Interface IAgoraRTC

Agora Web SDK 的入口。

Events

autoplay-failed

autoplay-failed(): void

自从 4.18.0
如果你需要更灵活地监听自动播放失败事件，推荐通过在 IAgoraRTC.on 方法中传入该回调来代替 onAutoplayFailed。

JavaScript
AgoraRTC.on("autoplay-failed", (info) => {
  console.log("Autoplay failed!", info.state, info.device);
});  

返回值

void

camera-changed

camera-changed(deviceInfo: DeviceInfo): void

自从 4.18.0
如果你需要更灵活地监听视频采集设备状态变化，推荐通过在 IAgoraRTC.on 方法中传入该回调来代替 onCameraChanged。

JavaScript
AgoraRTC.on("camera-changed", (info) => {
  console.log("Camera changed!", info.state, info.device);
});  

参数

参数名	类型	描述
deviceInfo	DeviceInfo	设备信息，详见 DeviceInfo。

返回值

void

microphone-changed

microphone-changed(deviceInfo: DeviceInfo): void

自从 4.18.0
如果你需要更灵活地监听麦克风设备变化，推荐通过在 IAgoraRTC.on 方法中传入该回调来代替 onMicrophoneChanged。

JavaScript
AgoraRTC.on("microphone-changed", (info) => {
  console.log("Microphone changed!", info.state, info.device);
});  

参数

参数名	类型	描述
deviceInfo	DeviceInfo	设备信息，详见 DeviceInfo。

返回值

void

playback-device-changed

playback-device-changed(deviceInfo: DeviceInfo): void

自从 4.18.0
如果你需要更灵活地监听音频播放设备变化，推荐通过在 IAgoraRTC.on 方法中传入该回调来代替 onPlaybackDeviceChanged。

JavaScript
AgoraRTC.on("playback-device-changed", (info) => {
  console.log("Playback device changed!", info.state, info.device);
});  

参数

参数名	类型	描述
deviceInfo	DeviceInfo	设备信息，详见 DeviceInfo。

返回值

void

security-policy-violation

security-policy-violation(): void

自从 4.18.0
如果你需要更灵活地监听触发 CSP 规则事件，推荐通过在 IAgoraRTC.on 方法中传入该回调来代替 onSecurityPolicyViolation。

JavaScript
AgoraRTC.on("security-policy-violation", (info) => {
  console.log("Security policy violation!", info.state, info.device);
});  

返回值

void

Global Callback Properties

Optional

onAudioAutoplayFailed

onAudioAutoplayFailed: undefined | function

音频轨道自动播放失败回调。
DEPRECATED
自 4.6.0 起废弃，请改用 onAutoplayFailed。
该回调在音频轨道自动播放失败的时候触发。如果短时间内有多个音频轨道对象都调用了 play，SDK 会触发多次 onAudioAutoplayFailed。
音频自动播放失败是浏览器的自动播放策略导致的，视频轨道的播放不受此影响。
在 Agora Web SDK 中，只要用户和页面发生过一次点击交互，就会自动解锁浏览器音频自动播放的限制，所以针对音频自动播放有两种解决方案：

如果不希望收到 onAudioAutoplayFailed 回调，就确保在调用 RemoteAudioTrack.play 和 LocalAudioTrack.play 之前用户已经和页面发生了点击交互。
如果无法保证在调用 RemoteAudioTrack.play 和 LocalAudioTrack.play 之前用户已经和页面发生点击交互，就监听 onAudioAutoplayFailed 回调，通过回调在页面上显示一个按钮引导用户点击。

注意

无论使用何种方案，只要浏览器启用了自动播放策略，都需要用户至少触发一次点击交互操作才能播放音频。随着用户使用某个页面的次数变多，浏览器会在这个页面上默认关闭自动播放策略，此时不需要任何交互也可以播放音频了，但是我们无法通过 JavaScript 去感知浏览器这个行为。

下面的示例代码演示了当检测到自动播放失败后的处理：在页面上动态显示一个按钮让用户点击。

JavaScript
let isAudioAutoplayFailed = false;
 AgoraRTC.onAudioAutoplayFailed = () => {
  if (isAudioAutoplayFailed) return;
  isAudioAutoplayFailed = true;
  const btn = document.createElement("button");
  btn.innerText = "Click me to resume the audio playback";
  btn.onClick = () => {
    isAudioAutoplayFailed = false;
    btn.remove();
  };
  document.body.append(btn);
};  

注意

需要注意的是，短时间内可能会有多个音频轨道对象都调用了 play，此时会触发多次 onAudioAutoplayFailed。示例代码中通过 isAudioAutoplayFailed 这个对象防止创建重复的按钮对象。

Optional

onAutoplayFailed

onAutoplayFailed: undefined | function

音频或视频轨道自动播放失败回调。
自从 4.6.0
SDK 在音频或视频轨道自动播放失败时触发该回调。

音频自动播放失败是由浏览器的自动播放策略导致的。
在大部分浏览器中，纯视频不受到自动播放策略的限制，但是在低电量模式下的 iOS Safari 浏览器中以及开启自定义自动播放限制的 iOS WKWebView 中（如 iOS 微信浏览器），纯视频的自动播放也会受到限制。

在 Agora Web SDK 中，只要用户和页面发生过一次点击交互，就会自动解锁浏览器音频或视频的自动播放限制，所以针对自动播放有两种解决方案：

如果不希望收到 onAutoplayFailed 回调，就确保在调用 RemoteTrack.play 和 LocalTrack.play 之前用户已经和页面发生了点击交互。
如果无法保证在调用 RemoteTrack.play 和 LocalTrack.play 之前用户已经和页面发生点击交互，就监听 onAutoplayFailed 回调，通过回调在页面上显示一个按钮引导用户点击。

注意

无论使用何种方案，只要浏览器启用了自动播放策略，都需要用户至少触发一次点击交互操作才能播放音频或视频。随着用户使用某个页面的次数变多，浏览器会在这个页面上默认关闭自动播放策略，此时不需要任何交互也可以播放音频和视频了，但是我们无法通过 JavaScript 去感知浏览器这个行为。

下面的示例代码演示了当检测到自动播放失败后的处理：在页面上动态显示一个按钮让用户点击。

JavaScript
AgoraRTC.onAutoplayFailed = () => {
  const btn = document.createElement("button");
  btn.innerText = "Click me to resume the audio/video playback";
  btn.onClick = () => {
    btn.remove();
  };
  document.body.append(btn);  

注意

由于自动播放失败后在用户通过手势点击恢复播放之前，onAutoplayFailed 只会触发一次，因此在业务代码中不需要像 onAudioAutoplayFailed 回调一样维护 isAutoplayFailed 状态。

Optional

onCameraChanged

onCameraChanged: undefined | function

视频采集设备状态变化回调。
该回调提示有摄像头被添加或移除。

注意

注意事项：当该回调提示有设备被添加时，如果该设备是虚拟设备，可能无法采集到音频或视频。

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

Parameters

deviceInfo：设备信息，详见 DeviceInfo。

Optional

onMicrophoneChanged

onMicrophoneChanged: undefined | function

音频采集设备状态变化回调。
该回调提示有麦克风被添加或移除。

注意

注意事项：当该回调提示有设备被添加时，如果该设备是虚拟设备，可能无法采集到音频或视频。

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

Parameters

deviceInfo：设备信息，详见 DeviceInfo。

Optional

onPlaybackDeviceChanged

onPlaybackDeviceChanged: undefined | function

自从 4.1.0
音频播放设备状态变化回调。
该回调提示有音频播放设备被添加或移除。

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

Parameters

deviceInfo：设备信息，详见 DeviceInfo。

Optional

onSecurityPolicyViolation

onSecurityPolicyViolation: undefined | function

自从 4.15.0
触发 CSP 规则回调。
当声网服务相关的资源加载或请求发送因为触发浏览器的 CSP（Content Security Policy，内容安全策略）规则而失败时，SDK 会触发该回调。收到该回调后，请及时调整你的 CSP 设置，确保能正常体验声网的服务。

Other Properties

VERSION

VERSION: string

Agora Web SDK 的版本信息。

Agora Core Methods

createClient

createClient(config: ClientConfig): IAgoraRTCClient

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

参数

参数名	类型	描述
config	ClientConfig	客户端的配置，包括通话场景、编码格式等，默认使用 `vp8` 编码，`rtc` 通话场景。详见 ClientConfig。

返回值

IAgoraRTCClient

Local Track Methods

createBufferSourceAudioTrack

createBufferSourceAudioTrack(config: BufferSourceAudioTrackInitConfig): Promise<IBufferSourceAudioTrack>

通过音频文件或者 AudioBuffer 对象创建一个音频轨道。
该方法支持本地和在线音频文件。音频文件支持以下音频格式：

MP3
AAC
浏览器支持的其他音频格式

参数

参数名	类型	描述
config	BufferSourceAudioTrackInitConfig	通过该配置指定文件路径、缓存策略和编码配置。

返回值

Promise<IBufferSourceAudioTrack>

createCameraVideoTrack

createCameraVideoTrack(config?: CameraVideoTrackInitConfig): Promise<ICameraVideoTrack>

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

参数

参数名	类型	描述
config	CameraVideoTrackInitConfig	采集视频的配置，包括采集设备、编码配置等。详见 CameraVideoTrackInitConfig。

返回值

Promise<ICameraVideoTrack>

createCustomAudioTrack

createCustomAudioTrack(config: CustomAudioTrackInitConfig): ILocalAudioTrack

创建一个自定义的音频轨道。
你可以使用这个方法将自己维护的 MediaStreamTrack 转换成一个可以用于 SDK 的音频轨道。

参数

参数名	类型	描述
config	CustomAudioTrackInitConfig	自定义音频的配置，详见 CustomAudioTrackInitConfig。

返回值

ILocalAudioTrack

createCustomVideoTrack

createCustomVideoTrack(config: CustomVideoTrackInitConfig): ILocalVideoTrack

创建一个自定义的视频轨道。
你可以使用这个方法将自己维护的 MediaStreamTrack 转换成一个可以用于 SDK 的视频轨道。

参数

参数名	类型	描述
config	CustomVideoTrackInitConfig	自定义视频轨道的配置，详见 CustomVideoTrackInitConfig。自 v4.17.1 起，自定义视频轨道配置 config 除了支持设置码率，还支持设置分辨率和帧率。

返回值

ILocalVideoTrack

createMicrophoneAndCameraTracks

createMicrophoneAndCameraTracks(audioConfig?: MicrophoneAudioTrackInitConfig, videoConfig?: CameraVideoTrackInitConfig): Promise<[IMicrophoneAudioTrack, ICameraVideoTrack]>

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

注意

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

调用该方法会同时要求麦克风和摄像头的授权，用户只需授权一次。
分别创建音频轨道和视频轨道需要用户分别对麦克风和摄像头进行授权，也就是说用户需要授权两次。

参数

参数名	类型	描述
audioConfig	MicrophoneAudioTrackInitConfig	采集音频的配置，包括采集设备、编码配置等。
videoConfig	CameraVideoTrackInitConfig	采集视频的配置，包括采集设备、编码配置等。

返回值

Promise<[IMicrophoneAudioTrack, ICameraVideoTrack]>

createMicrophoneAudioTrack

createMicrophoneAudioTrack(config?: MicrophoneAudioTrackInitConfig): Promise<IMicrophoneAudioTrack>

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

参数

参数名	类型	描述
config	MicrophoneAudioTrackInitConfig	麦克风采集音频的配置，包括采集设备、音频编码配置等，详见 MicrophoneAudioTrackInitConfig。

返回值

Promise<IMicrophoneAudioTrack>

createScreenVideoTrack

createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio: "enable"): Promise<[ILocalVideoTrack, ILocalAudioTrack]>

createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio: "enable"): Promise<[ILocalVideoTrack, ILocalAudioTrack]>

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

参数

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

返回值

Promise<[ILocalVideoTrack, ILocalAudioTrack]>

createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio: "disable"): Promise<ILocalVideoTrack>

createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio: "disable"): Promise<ILocalVideoTrack>

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

参数

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

返回值

Promise<ILocalVideoTrack>

createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio?: "enable" | "disable" | "auto"): Promise<[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack>

createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio?: "enable" | "disable" | "auto"): Promise<[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack>

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

参数

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

返回值

Promise<[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack>

Logger Methods

disableLogUpload

disableLogUpload(): void

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

返回值

void

enableLogUpload

enableLogUpload(): void

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

注意

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

返回值

void

setLogLevel

setLogLevel(level: number): void

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

参数

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

返回值

void

Media Devices Methods

getCameras

getCameras(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>

该方法枚举可用的视频输入设备，比如摄像头。
调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的视频输入设备。

注意

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

参数

参数名	类型	描述
skipPermissionCheck	undefined \| false \| true	是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。 `true`: 跳过权限检查。 `false`:（默认）不跳过权限检查。

返回值

Promise<MediaDeviceInfo[]>

getDevices

getDevices(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>

该方法枚举可用的媒体输入和输出设备，比如麦克风、摄像头、耳机等。调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的媒体设备。

注意

注意事项：

调用本方法会暂时打开摄像头和麦克风以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。
即使是对于同一设备，SDK 返回的 MediaDeviceInfo.deviceId 也可能会发生变化，例如用户清除 Cookie 后，deviceId 就会被重置。因此，声网不建议基于 deviceId 开发业务逻辑。

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

参数

参数名	类型	描述
skipPermissionCheck	undefined \| false \| true	是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。 `true`: 跳过权限检查。 `false`:（默认）不跳过权限检查。

返回值

Promise<MediaDeviceInfo[]>

getElectronScreenSources

getElectronScreenSources(type?: ScreenSourceType): Promise<ElectronDesktopCapturerSource[]>

在 Electron 环境下获取屏幕共享源。
调用成功后 SDK 会返回一组 ElectronDesktopCapturerSource 对象。

注意

如果你的 Electron 运行环境开启了 contextIsolation 配置，调用此方法会报错。你需要自己使用 contextBridge.exposeInMainWorld 来获取视频源 id。

JavaScript
// preload.js
const {
  contextBridge, desktopCapturer
} = require("electron");
contextBridge.exposeInMainWorld(
  "electronDesktopCapturer", {
    getSources: async (...args) => {
      const sources = await desktopCapturer.getSources(...args);
      return sources;
    }
  }
);
// renderer.js
(async () => {
  sources = await window.electronDesktopCapturer.getSources(["window", "screen"]);
  const source = sources[0];   // just for example ,you shuould make an UI for user to select the exact source.
  const screenVideoTrack = await AgoraRTC.createScreenVideoTrack({ electronScreenSourceId: source.id });
})()  

参数

参数名	类型	描述
type	ScreenSourceType	需要获取的共享源类型（窗口/应用/屏幕），详见 ScreenSourceType。如果为空则获取所有可以获取的共享源。

返回值

Promise<ElectronDesktopCapturerSource[]>

getMicrophones

getMicrophones(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>

该方法枚举可用的音频输入设备，比如麦克风。
调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的音频输入设备。

注意

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

参数

参数名	类型	描述
skipPermissionCheck	undefined \| false \| true	是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。 `true`: 跳过权限检查。 `false`:（默认）不跳过权限检查。

返回值

Promise<MediaDeviceInfo[]>

getPlaybackDevices

getPlaybackDevices(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>

自从 4.1.0
该方法枚举可用的音频播放设备，比如扬声器。
调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的音频播放设备。

注意

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

参数

参数名	类型	描述
skipPermissionCheck	undefined \| false \| true	是否跳过权限检查。你可以通过将该参数设置成 `true` 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。 `true`: 跳过权限检查。 `false`:（默认）不跳过权限检查。

返回值

Promise<MediaDeviceInfo[]>

Other Methods

checkAudioTrackIsActive

checkAudioTrackIsActive(track: ILocalAudioTrack | IRemoteAudioTrack, timeout?: undefined | number): Promise<boolean>

检测音频轨道是否活跃。
SDK 通过检测指定时间范围内音量是否发生变化来判断音频轨道是否活跃。
声网建议通过此方法在开始通话前对音频输入设备进行可用性检测。你可以将麦克风采集到的音频轨道作为参数传入该方法，判断麦克风是否正常运行。

注意

注意事项：

极为安静的环境下可能检测失败，所以声网建议你在使用此方法的时候提示用户发出声响。
当音频轨道被 mute 时，会返回 false。
不建议频繁调用此方法。

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

参数

参数名	类型	描述
track	ILocalAudioTrack \| IRemoteAudioTrack	需要进行检测的本地或远端音频轨道。
timeout	undefined \| number	音频轨道检测的超时时间，单位为毫秒，默认 5,000 毫秒。

返回值

Promise<boolean>

checkSystemRequirements

checkSystemRequirements(): boolean

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

返回值

boolean

checkVideoTrackIsActive

checkVideoTrackIsActive(track: ILocalVideoTrack | IRemoteVideoTrack, timeout?: undefined | number): Promise<boolean>

检测视频轨道是否活跃。
SDK 通过检测指定时间范围内视频图像是否发生变动来判断视频轨道是否活跃。
声网建议通过此方法在开始通话前对视频输入设备进行可用性检测。你可以将摄像头采集到的视频轨道作为参数传入该方法，判断摄像头是否正常运行。

注意

注意事项：

当视频轨道被 mute 时，会返回 false。
不建议频繁调用此方法。

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

参数

参数名	类型	描述
track	ILocalVideoTrack \| IRemoteVideoTrack	需要进行检测的本地或远端视频轨道。
timeout	undefined \| number	视频轨道检测的超时时间，单位为毫秒，默认 5,000 毫秒。

返回值

Promise<boolean>

createChannelMediaRelayConfiguration

createChannelMediaRelayConfiguration(): IChannelMediaRelayConfiguration

创建跨频道媒体流转发的配置对象。

返回值

IChannelMediaRelayConfiguration

getListeners

getListeners(event: string): Function[]

指定一个事件名，获取当前所有监听这个事件的回调函数。

参数

参数名	类型	描述
event	string	事件名称。

返回值

Function[]

getSupportedCodec

getSupportedCodec(): Promise<object>

获取 Agora Web SDK 对当前浏览器支持的编解码格式。
调用该方法会返回声网服务与当前浏览器同时支持的编解码格式。目前而言，视频支持 VP8 及 H.264 格式，音频支持 OPUS 格式。

注意

注意事项：

该方法支持所有浏览器。对于不支持 WebRTC 或无法识别的浏览器环境，编解码列表返回为空。
返回的音视频编码为浏览器通过 SDP 声称的编码类型，为参考值。
目前部分安卓手机 H.264 与其他平台 H.264 存在无法互通或单通问题，对于这部分机型推荐使用 VP8 编码格式。

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

返回值

Promise<object>

off

off(event: string, listener: Function): void

取消一个指定事件的监听。

参数

参数名	类型	描述
event	string	指定事件的名称。
listener	Function	监听事件时传入的回调函数。

返回值

void

on

on(event: "camera-changed", listener: typeof event_camera_changed): void

on(event: "camera-changed", listener: typeof event_camera_changed): void

自从 4.18.0

参数

参数名	类型	描述
event	"camera-changed"	事件名称。
listener	typeof event_camera_changed	详见 event_camera_changed。

返回值

void

on(event: "microphone-changed", listener: typeof event_microphone_changed): void

on(event: "microphone-changed", listener: typeof event_microphone_changed): void

自从 4.18.0

参数

参数名	类型	描述
event	"microphone-changed"	事件名称。
listener	typeof event_microphone_changed	详见 event_microphone_changed。

返回值

void

on(event: "playback-device-changed", listener: typeof event_playback_device_changed): void

on(event: "playback-device-changed", listener: typeof event_playback_device_changed): void

自从 4.18.0

参数

参数名	类型	描述
event	"playback-device-changed"	事件名称。
listener	typeof event_playback_device_changed	详见 event_playback_device_changed。

返回值

void

on(event: "autoplay-failed", listener: typeof event_autoplay_failed): void

on(event: "autoplay-failed", listener: typeof event_autoplay_failed): void

自从 4.18.0

参数

参数名	类型	描述
event	"autoplay-failed"	事件名称。
listener	typeof event_autoplay_failed	详见 event_autoplay_failed。

返回值

void

on(event: "security-policy-violation", listener: typeof event_security_policy_violation): void

on(event: "security-policy-violation", listener: typeof event_security_policy_violation): void

自从 4.18.0

参数

参数名	类型	描述
event	"security-policy-violation"	事件名称。
listener	typeof event_security_policy_violation	详见 event_security_policy_violation。

返回值

void

once

once(event: string, listener: Function): void

监听一个指定的事件，当事件触发时会调用传入的回调函数。
当监听后事件第一次触发时，该监听和回调函数就会被立刻移除，也就是只监听一次指定事件。

参数

参数名	类型	描述
event	string	指定事件的名称。
listener	Function	传入的回调函数。

返回值

void

processExternalMediaAEC

processExternalMediaAEC(element: HTMLMediaElement): void

自从 4.5.0
对本地播放的音频启用回声消除。
在多个用户同时播放一个媒体文件的场景中，例如一起看电影，如果用户 A 在 Chrome 浏览器上通过 HTMLMediaElement 使用扬声器播放媒体文件，扬声器播放的声音会和人声一起被 SDK 采集，因此其他用户会听到自己本地播放的媒体音频以及用户 A 发送的媒体音频，从而产生回声。针对这种情况，你可以调用 processExternalMediaAEC 方法传入 HTMLMediaElement，对本地播放的媒体进行回声消除，提升音频体验。

JavaScript
<audio crossOrigin="anonymous" src="http://www.test.com/test.mp3" id="audioDom"></audio>
<script>
  const element = document.getElementById("audioDom");
  AgoraRTC.processExternalMediaAEC(element);
</script>  

注意

注意事项：如果本地播放的媒体元素的地址是跨域地址，必须设置 HTMLMediaElement 中的 crossOrigin 属性为 "anonymous" 以允许跨域媒体被重采集。

参数

参数名	类型	描述
element	HTMLMediaElement	需要进行回声消除的媒体元素，详见 HTMLMediaElement。

返回值

void

registerExtensions

registerExtensions(extensions: IExtension<any>[]): void

自从 4.10.0
注册插件。
声网当前支持以下插件：

参数

参数名	类型	描述
extensions	IExtension<any>[]	插件实例。

返回值

void

removeAllListeners

removeAllListeners(event?: undefined | string): void

指定一个事件，取消其所有的监听。

参数

参数名	类型	描述
event	undefined \| string	指定事件的名称，如果没有指定事件，则取消所有事件的所有监听。

返回值

void

setArea

setArea(area: AREAS[] | object): void

自从 4.2.0
设置访问区域。
该功能为高级设置，适用于有访问安全限制的场景。
默认情况下，SDK 会就近选择声网服务器进行连接。设置访问区域之后，SDK 只会连接到指定区域内的声网服务器。

JavaScript
// 指定仅访问北美的服务器。
AgoraRTC.setArea({
  areaCode:"NORTH_AMERICA"
})  

参数

参数名	类型	描述
area	AREAS[] \| object	服务器的访问区域。区域码详见 AREAS。你可以设置 `areaCode` 参数指定单个访问区域。

返回值

void

Events

autoplay-failed

返回值​

camera-changed

参数​

返回值​

microphone-changed

参数​

返回值​

playback-device-changed

参数​

返回值​

security-policy-violation

返回值​

Global Callback Properties

onAudioAutoplayFailed

onAutoplayFailed

onCameraChanged

onMicrophoneChanged

onPlaybackDeviceChanged

onSecurityPolicyViolation

Other Properties

VERSION

Agora Core Methods

createClient

参数​

返回值​

Local Track Methods

createBufferSourceAudioTrack

参数​

返回值​

createCameraVideoTrack

参数​

返回值​

createCustomAudioTrack

参数​

返回值​

createCustomVideoTrack

参数​

返回值​

createMicrophoneAndCameraTracks

参数​

返回值​

createMicrophoneAudioTrack

参数​

返回值​

createScreenVideoTrack

参数​

返回值​

参数​

返回值​

参数​

返回值​

Logger Methods

disableLogUpload

返回值​

enableLogUpload

返回值​

setLogLevel

参数​

返回值​

Media Devices Methods

getCameras

参数​

返回值​

getDevices

参数​

返回值​

getElectronScreenSources

参数​

返回值​

getMicrophones

参数​

返回值​

getPlaybackDevices

参数​

返回值​

Other Methods

checkAudioTrackIsActive

参数​

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值