API Reference for web - Class: CoreRTC

更新时间: 2023-10-23 16:45:52

# Class: CoreRTC

CoreRTC.CoreRTC

# Hierarchy

EnhancedEventEmitter

↳ CoreRTC

# Properties

# VERSION

VERSION: string = SDK_VERSION

Web SDK 的版本信息

# disableLogUpload

disableLogUpload: () => void = Logger.disableLogUpload

# Type declaration

(): void

关闭日志上传。日志上传默认是关闭状态，如果你调用了开启日志上传（enableLogUpload)，可以通过本方法停止上传日志。

# Returns

void

# enableLogUpload

enableLogUpload: () => void = Logger.enableLogUpload

# Type declaration

(): void

开启日志上传。开启后 SDK 的日志会上传到RTC服务器。日志上传功能默认为关闭状态，如果你需要开启此功能，请确保在所有方法之前调用本方法。

如果没有成功加入频道，则服务器上无法查看日志信息。

# Returns

void

# defaultMaxListeners

Static defaultMaxListeners: number

# Inherited from

EnhancedEventEmitter.defaultMaxListeners

# errorMonitor

Static Readonly errorMonitor: typeof errorMonitor

This symbol shall be used to install a listener for only monitoring 'error' events. Listeners installed using this symbol are called before the regular 'error' listeners are called.

Installing a listener using this symbol does not change the behavior once an 'error' event is emitted, therefore the process will still crash if no regular 'error' listener is installed.

# Inherited from

EnhancedEventEmitter.errorMonitor

# Global Callback Methods

# onCameraChanged

onCameraChanged(info): void

视频采集设备状态变化回调。

该回调提示有摄像头被添加或移除。

CoreRTC.onCameraChanged = (info) => {
  console.log("camera changed!", info.state, info.device);
};

deviceInfo: 设备信息，详见 See DeviceInfo.

# Parameters

Name	Type
`info`	`any`

# Returns

void

# onMicrophoneChanged

onMicrophoneChanged(info): void

音频采集设备状态变化回调。

该回调提示有麦克风被添加或移除。

CoreRTC.onMicrophoneChanged = (info) => {
  console.log("microphone changed!", info.state, info.device);
};

Parameters

deviceInfo: 设备信息，详见 See DeviceInfo.

# Parameters

Name	Type
`info`	`any`

# Returns

void

# onPlaybackDeviceChanged

onPlaybackDeviceChanged(info): void

音频播放设备状态变化回调。

该回调提示有音频播放设备被添加或移除。

CoreRTC.onPlaybackDeviceChanged = (info) => {
  console.log("speaker changed!", info.state, info.device);
};

Parameters

deviceInfo: 设备信息，详见 DeviceInfo.

# Parameters

Name	Type
`info`	`any`

# Returns

void

# Local Track Methods

# createCameraVideoTrack

createCameraVideoTrack(config?): Promise<LocalVideoTrack>

通过摄像头采集的视频创建一个视频轨道。

# Parameters

Name	Type	Description
`config?`	`CameraVideoTrackInitConfig`	采集视频的配置，包括采集设备、编码配置等。详见CameraVideoTrackInitConfig.

# Returns

Promise<LocalVideoTrack>

# createCustomAudioTrack

createCustomAudioTrack(config): LocalAudioTrack

创建一个自定义的音频轨道。

你可以使用这个方法将自己维护的 MediaStreamTrack (opens new window) 转换成一个可以用于 SDK 的音频轨道。

# Parameters

Name	Type	Description
`config`	`CustomAudioTrackInitConfig`	自定义音频的配置，详见 CustomAudioTrackInitConfig.

# Returns

LocalAudioTrack

# createCustomVideoTrack

createCustomVideoTrack(config): LocalVideoTrack

创建一个自定义的视频轨道。

你可以使用这个方法将自己维护的 MediaStreamTrack (opens new window) 转换成一个可以用于 SDK 的视频轨道。

# Parameters

Name	Type	Description
`config`	`CustomVideoTrackInitConfig`	自定义视频轨道的配置，详见 CustomAudioTrackInitConfig. > 自定义视频轨道无法设置具体的编码参数，只能通过 (config)CustomVideoTrackInitConfig 来设置发送码率。

# Returns

LocalVideoTrack

# createMicrophoneAudioTrack

createMicrophoneAudioTrack(config?): Promise<LocalAudioTrack>

通过麦克风采集的音频创建一个音频轨道。

# Parameters

Name	Type	Description
`config?`	`MicrophoneAudioTrackInitConfig`	麦克风采集音频的配置，包括采集设备、音频编码配置等，详见 MicrophoneAudioTrackInitConfig.

# Returns

Promise<LocalAudioTrack>

# createScreenVideoTrack

createScreenVideoTrack(config?, withAudio?): Promise<LocalVideoTrack | [LocalVideoTrack, LocalAudioTrack]>

创建用于屏幕共享的视频轨道。

# Parameters

Name	Type	Description
`config`	`ScreenVideoTrackInitConfig`	屏幕共享的视频配置，包括编码配置、采集配置等。
`withAudio?`	`"enable"` \| `"disable"` \| `"auto"`	屏幕共享时是否同时分享屏幕共享输入源的音频。 - `enable`: 分享音频。 - `disable`: （默认）不分享音频。 - `auto`: 根据浏览器是否支持决定是否分享音频。 > Note: > - 该功能仅支持 Windows 和 macOS 平台下的 Chrome 浏览器 74 及以上版本。 > - Windows 平台支持在共享整个屏幕和共享 Chrome 标签页时分享音频，不支持在共享应用窗口时分享音频。 macOS 平台仅支持在共享 Chrome 标签页时分享音频。 > - 设置了 withAudio 为 enable 后，还需要在屏幕共享的弹出框上，勾选分享音频才能真正生效。

# Returns

Promise<LocalVideoTrack | [LocalVideoTrack, LocalAudioTrack]>

如果 withAudio 设为 enable，返回包含屏幕共享视频轨道和一个音频轨道的列表。如果用户没有勾选 分享音频 ，SDK 会抛出错误。
如果 withAudio 设为 disable，返回屏幕共享的视频轨道。
如果 withAudio 设为 auto，在支持屏幕共享音频的浏览器上 SDK 会默认尝试分享音频。
- 如果用户勾选了 分享音频 ，会返回包含屏幕共享视频轨道和一个音频轨道的列表。
- 如果用户没有勾选 分享音频 ，只返回屏幕共享视频轨道。

# Media Devices Methods

# getCameras

getCameras(skipPermissionCheck?): Promise<MediaDeviceInfo[]>

该方法枚举可用的视频输入设备，比如摄像头。

调用成功后 SDK 会通过 MediaDeviceInfo (opens new window) 对象返回可用的视频输入设备。

调用本方法会暂时打开摄像头以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。

# Parameters

Name	Type	Description
`skipPermissionCheck?`	`boolean`	是否跳过权限检查。你可以通过将该参数设置成 true 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。 - `true`: 跳过权限检查。 - `false`: （默认）不跳过权限检查。

# Returns

Promise<MediaDeviceInfo[]>

# getDevices

getDevices(skipPermissionCheck?): Promise<MediaDeviceInfo[]>

该方法枚举可用的媒体输入和输出设备，比如麦克风、摄像头、耳机等。

调用成功后 SDK 会通过 MediaDeviceInfo (opens new window) 对象返回可用的媒体设备。

调用本方法会暂时打开摄像头和麦克风以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。

即使是对于同一设备，SDK 返回的 MediaDeviceInfo.deviceId 也可能会发生变化，例如用户清除 Cookie 后，deviceId 就会被重置。不建议基于 deviceId 开发业务逻辑。

getDevices().then(devices => {
console.log("first device id", devices[0].deviceId);
}).catch(e => {
console.log("get devices error!", e);
});

# Parameters

Name	Type	Description
`skipPermissionCheck?`	`boolean`	是否跳过权限检查。你可以通过将该参数设置成 true 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。 - `true`: 跳过权限检查。 - `false`: （默认）不跳过权限检查。

# Returns

Promise<MediaDeviceInfo[]>

# getMicrophones

getMicrophones(skipPermissionCheck?): Promise<MediaDeviceInfo[]>

该方法枚举可用的音频输入设备，比如麦克风。

调用成功后 SDK 会通过 MediaDeviceInfo (opens new window) 对象返回可用的音频输入设备。

调用本方法会暂时打开麦克风以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。

# Parameters

Name	Type	Description
`skipPermissionCheck?`	`boolean`	是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。 - `true`: 跳过权限检查。 - `false`: （默认）不跳过权限检查。

# Returns

Promise<MediaDeviceInfo[]>

# getPlaybackDevices

getPlaybackDevices(skipPermissionCheck?): Promise<MediaDeviceInfo[]>

该方法枚举可用的音频播放设备，比如扬声器。

调用成功后 SDK 会通过 MediaDeviceInfo (opens new window) 对象返回可用的音频播放设备。

调用本方法会暂时打开麦克风以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。

# Parameters

Name	Type	Description
`skipPermissionCheck?`	`boolean`	是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。 - `true`: 跳过权限检查。 - `false`:（默认）不跳过权限检查。

# Returns

Promise<MediaDeviceInfo[]>

# Other Methods

# addListener

addListener(event, listener): CoreRTC

# Parameters

Name	Type
`event`	`string` \| `symbol`
`listener`	(...`args`: `any`[]) => `void`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.addListener

# checkAudioTrackIsActive

checkAudioTrackIsActive(track, timeOut?): Promise<unknown>

检测音频轨道是否活跃。

SDK 通过检测指定时间范围内音量是否发生变化来判断音频轨道是否活跃。

建议通过此方法在开始通话前对音频输入设备进行可用性检测。你可以将麦克风采集到的音频轨道作为参数传入该方法，判断麦克风是否正常运行。

注意事项：

极为安静的环境下可能检测失败，所以建议在使用此方法的时候提示用户发出声响。

当音频轨道被 mute 时，会返回 false。

不建议频繁调用此方法。

const audioTrack = await CoreRTC.createMicrophoneAudioTrack({ microphoneId });
CoreRTC.checkAudioTrackIsActive(audioTrack).then(result => {
  console.log(`${ microphoneLabel } is ${ result ? "available" : "unavailable" }`);
}).catch(e => {
  console.log("check audio track error!", e);
});

# Parameters

Name	Type	Default value	Description
`track`	`LocalAudioTrack`	`undefined`	需要进行检测的本地或远端音频轨道。
`timeOut`	`number`	`5000`	-

# Returns

Promise<unknown>

Whether 传入该方法的音频轨道中的音量大小是否发生了变化：

true: 音量大小有变化。对于麦克风音频轨道，说明音频采集设备采集到了声音。
false: 音量大小未变化，说明音频采集设备没有采集到声音，或自定义音频轨道中没有音量变化，或音频轨道被 mute。

# checkSystemRequirements

checkSystemRequirements(): boolean

检查 SDK 对正在使用的浏览器的适配情况。该方法必须在创建客户端对象 createClient 之前调用。

# Returns

boolean

true: 支持。
false: 不支持。

# checkVideoTrackIsActive

checkVideoTrackIsActive(videoTrack, timeout?): Promise<boolean>

检测视频轨道是否活跃。

SDK 通过检测指定时间范围内视频图像是否发生变动来判断视频轨道是否活跃。

建议通过此方法在开始通话前对视频输入设备进行可用性检测。你可以将摄像头采集到的视频轨道作为参数传入该方法，判断摄像头是否正常运行。

注意事项:

当视频轨道被 mute 时，会返回 false。

不建议频繁调用此方法。

const videoTrack = await CoreRTC.createCameraVideoTrack({ cameraId });
CoreRTC.checkVideoTrackIsActive(videoTrack).then(result => {
  console.log(`${ cameraLabel } is ${ result ? "available" : "unavailable" }`);
}).catch(e => {
  console.log("check video track error!", e);
});

# Parameters

Name	Type	Description
`videoTrack`	`MediaStreamTrack`	-
`timeout?`	`number`	视频轨道检测的超时时间，单位为毫秒，默认 5,000 毫秒。

# Returns

Promise<boolean>

传入该方法的视频轨道中的图像是否发生了变动：

true: 视频画面发生变动。对于摄像头视频轨道，说明视频采集设备采集到了画面。
false: 视频画面未变动，说明视频采集设备异常或被完全遮挡，或视频轨道被 mute。

# createBufferSourceAudioTrack

createBufferSourceAudioTrack(config): Promise<BufferSourceAudioTrack>

# Parameters

Name	Type	Description
`config`	`BufferSourceAudioTrackInitConfig`	通过音频文件或者 AudioBuffer 对象创建一个音频轨道该方法支持本地和在线音频文件。音频文件支持以下音频格式： - MP3 - AAC 浏览器支持的其他音频格式

# Returns

Promise<BufferSourceAudioTrack>

# createMicrophoneAndCameraTracks

createMicrophoneAndCameraTracks(audioConfig?, videoConfig?): Promise<(MicrophoneAudioTrack | CameraVideoTrack)[]>

同时创建麦克风音频轨道和摄像头视频轨道。

通过麦克风采集的音频创建一个音频轨道，同时通过摄像头采集的视频创建一个视频轨道。

调用该方法和分别调用 createMicrophoneAudioTrack 以及 createCameraVideoTrack 的区别是：

调用该方法会同时要求麦克风和摄像头的授权，用户只需授权一次。

分别创建音频轨道和视频轨道需要用户分别对麦克风和摄像头进行授权，也就是说用户需要授权两次。

# Parameters

Name	Type	Description
`audioConfig?`	`MicrophoneAudioTrackInitConfig`	采集音频的配置，包括采集设备、编码配置等。
`videoConfig?`	`CameraVideoTrackInitConfig`	采集视频的配置，包括采集设备、编码配置等。

# Returns

Promise<(MicrophoneAudioTrack | CameraVideoTrack)[]>

# emit

emit(event, ...args): boolean

# Parameters

Name	Type
`event`	`string` \| `symbol`
`...args`	`any`[]

# Returns

boolean

# Inherited from

EnhancedEventEmitter.emit

# eventNames

eventNames(): (string | symbol)[]

# Returns

(string | symbol)[]

# Inherited from

EnhancedEventEmitter.eventNames

# getMaxListeners

getMaxListeners(): number

# Returns

number

# Inherited from

EnhancedEventEmitter.getMaxListeners

# getSupportedCodec

getSupportedCodec(): Promise<{ audio: string[] ; video: string[] }>

获取 SDK 对当前浏览器支持的编解码格式。

调用该方法会返回服务与当前浏览器同时支持的编解码格式。目前而言，视频仅支持 H.264 格式，音频仅支持 OPUS 格式。

CoreRTC.getSupportedCodec().then(result => {
console.log(`Supported video codec: ${result.video.join(",")}`);
console.log(`Supported audio codec: ${result.audio.join(",")}`);
});

# Returns

Promise<{ audio: string[] ; video: string[] }>

A 调用该方法会返回一个 Promise 对象，在 .then(function(result){}) 回调中，result 包含以下属性：

video: 数组类型，支持的视频编解码格式。可能含有 "H264"
audio: 数组类型，支持的音频编解码格式。可能含有 "OPUS"

# listenerCount

listenerCount(event): number

# Parameters

Name	Type
`event`	`string` \| `symbol`

# Returns

number

# Inherited from

EnhancedEventEmitter.listenerCount

# listeners

listeners(event): Function[]

# Parameters

Name	Type
`event`	`string` \| `symbol`

# Returns

Function[]

# Inherited from

EnhancedEventEmitter.listeners

# off

off(event, listener): CoreRTC

# Parameters

Name	Type
`event`	`string` \| `symbol`
`listener`	(...`args`: `any`[]) => `void`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.off

# on

on(event, listener): CoreRTC

# Parameters

Name	Type
`event`	`string` \| `symbol`
`listener`	(...`args`: `any`[]) => `void`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.on

# once

once(event, listener): CoreRTC

# Parameters

Name	Type
`event`	`string` \| `symbol`
`listener`	(...`args`: `any`[]) => `void`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.once

# prependListener

prependListener(event, listener): CoreRTC

# Parameters

Name	Type
`event`	`string` \| `symbol`
`listener`	(...`args`: `any`[]) => `void`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.prependListener

# prependOnceListener

prependOnceListener(event, listener): CoreRTC

# Parameters

Name	Type
`event`	`string` \| `symbol`
`listener`	(...`args`: `any`[]) => `void`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.prependOnceListener

# rawListeners

rawListeners(event): Function[]

# Parameters

Name	Type
`event`	`string` \| `symbol`

# Returns

Function[]

# Inherited from

EnhancedEventEmitter.rawListeners

# removeAllListeners

removeAllListeners(event?): CoreRTC

# Parameters

Name	Type
`event?`	`string` \| `symbol`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.removeAllListeners

# removeListener

removeListener(event, listener): CoreRTC

# Parameters

Name	Type
`event`	`string` \| `symbol`
`listener`	(...`args`: `any`[]) => `void`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.removeListener

# safeEmit

safeEmit(event, ...args): boolean

# Parameters

Name	Type
`event`	`string`
`...args`	`any`[]

# Returns

boolean

# Inherited from

EnhancedEventEmitter.safeEmit

# safeEmitAsPromise

safeEmitAsPromise(event, ...args): Promise<any>

# Parameters

Name	Type
`event`	`string`
`...args`	`any`[]

# Returns

Promise<any>

# Inherited from

EnhancedEventEmitter.safeEmitAsPromise

# setLogLevel

setLogLevel(level): void

设置 SDK 的日志输出级别。选择一个级别，你就可以看到在该级别及该级别以上所有级别的日志信息。

# Parameters

Name	Type	Description
`level`	`number`	SDK 日志输出级别。按照输出日志最全到最少排列： - 0: DEBUG。输出所有的 SDK 日志。 - 1: INFO。输出 INFO、WARNING 和 ERROR 级别的日志。 - 2: WARNING。输出 WARNING 和 ERROR 级别的日志。 - 3: ERROR。输出 ERROR 级别的日志。 - 4: NONE。不输出日志。例如，如果你输入代码 `CoreRTC.setLogLevel(1);`，就可以看到 INFO，WARNING 和 ERROR 级别的日志信息。

# Returns

void

# setMaxListeners

setMaxListeners(n): CoreRTC

# Parameters

Name	Type
`n`	`number`

# Returns

CoreRTC

# Inherited from

EnhancedEventEmitter.setMaxListeners

# listenerCount

Static listenerCount(emitter, event): number

deprecated since v4.0.0

# Parameters

Name	Type
`emitter`	`EventEmitter`
`event`	`string` \| `symbol`

# Returns

number

# Inherited from

EnhancedEventEmitter.listenerCount

# {@link Client} Methods

# createClient

createClient(config): Client

创建一个客户端对象用于通话/直播管理，通常来说这是使用 SDK 的第一步。

客户端的配置，包括通话场景、编码格式等

# Parameters

Name	Type	Description
`config`	`ClientConfig`	客户端的配置，包括通话场景、编码格式等。详见 ClientConfig

# Returns

Client