Interface IAgoraRTC

Agora Web SDK 的入口。

Events

audio-context-state-changed

audio-context-state-changed(currState: AudioContextState | "interrupted", prevState: AudioContextState | "interrupted" | undefined): void

自从

4.20.0

音频上下文 (Audio Context) 状态发生改变回调。该回调中的 "interrupted" 状态当前只会在 iOS 上触发。

参数

参数名	描述
currState: AudioContextState \| "interrupted"	当前的状态，取值如下： `AudioContextState`：枚举值的含义详见 BaseAudioContext.state。 `"interrupted"`：App 的音视频播放被微信通话或系统电话打断。你可以调用 resumeAudioContext 方法恢复音视频播放。
prevState: AudioContextState \| "interrupted" \| undefined	之前的状态，取值如下： `AudioContextState`：枚举值的含义详见 BaseAudioContext.state。 `"interrupted"`：App 的音视频播放被微信通话或系统电话打断。 `undefined`：无先前状态。

返回值

void

autoplay-failed

autoplay-failed(): void

自从

4.18.0

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

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。

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。

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。

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。

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

返回值

void

Global Callback Properties

Optional

onAudioAutoplayFailed

onAudioAutoplayFailed: 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: 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: function

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

注意

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

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

Parameters

deviceInfo：设备信息，详见 DeviceInfo。

Optional

onMicrophoneChanged

onMicrophoneChanged: function

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

注意

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

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

Parameters

deviceInfo：设备信息，详见 DeviceInfo。

Optional

onPlaybackDeviceChanged

onPlaybackDeviceChanged: function

自从

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

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

Parameters

deviceInfo：设备信息，详见 DeviceInfo。

Optional

onSecurityPolicyViolation

onSecurityPolicyViolation: 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`: 根据浏览器是否支持决定是否分享音频。注意事项：该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见浏览器兼容性和已知问题。关于各操作系统平台的浏览器版本及功能支持的补充说明如下：在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。设置了 `withAudio` 为 `enable` 后，还需要在屏幕共享的弹出框上，勾选分享音频才能真正生效。

config: ScreenVideoTrackInitConfig

屏幕共享的视频配置，包括编码配置、采集配置等。

withAudio: "enable"

屏幕共享时是否同时分享屏幕共享输入源的音频。

enable: 分享音频。
disable: （默认）不分享音频。
auto: 根据浏览器是否支持决定是否分享音频。
注意事项：
- 该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见浏览器兼容性和已知问题。
- 关于各操作系统平台的浏览器版本及功能支持的补充说明如下：
  - 在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。
  - 在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。
  - 在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。
- 设置了 withAudio 为 enable 后，还需要在屏幕共享的弹出框上，勾选分享音频才能真正生效。

返回值

Promise<[ILocalVideoTrack, ILocalAudioTrack]>

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

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

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

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

参数

参数名描述

参数名	描述
config: ScreenVideoTrackInitConfig	屏幕共享的视频配置，包括编码配置、采集配置等。
withAudio: "disable"	屏幕共享时是否同时分享屏幕共享输入源的音频。 `enable`: 分享音频。 `disable`: （默认）不分享音频。 `auto`: 根据浏览器是否支持决定是否分享音频。注意事项：该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见浏览器兼容性和已知问题。关于各操作系统平台的浏览器版本及功能支持的补充说明如下：在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。设置了 `withAudio` 为 `enable` 后，还需要在屏幕共享的弹出框上，勾选分享音频才能真正生效。

config: ScreenVideoTrackInitConfig

屏幕共享的视频配置，包括编码配置、采集配置等。

withAudio: "disable"

屏幕共享时是否同时分享屏幕共享输入源的音频。

enable: 分享音频。
disable: （默认）不分享音频。
auto: 根据浏览器是否支持决定是否分享音频。
注意事项：
- 该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见浏览器兼容性和已知问题。
- 关于各操作系统平台的浏览器版本及功能支持的补充说明如下：
  - 在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。
  - 在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。
  - 在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。
- 设置了 withAudio 为 enable 后，还需要在屏幕共享的弹出框上，勾选分享音频才能真正生效。

返回值

Promise<ILocalVideoTrack>

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

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`: 根据浏览器是否支持决定是否分享音频。注意事项：该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见浏览器兼容性和已知问题。关于各操作系统平台的浏览器版本及功能支持的补充说明如下：在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。设置了 `withAudio` 为 `enable` 后，还需要在屏幕共享的弹出框上，勾选分享音频才能真正生效。

config: ScreenVideoTrackInitConfig

屏幕共享的视频配置，包括编码配置、采集配置等。

withAudio: "enable" | "disable" | "auto"

屏幕共享时是否同时分享屏幕共享输入源的音频。

enable: 分享音频。
disable: （默认）不分享音频。
auto: 根据浏览器是否支持决定是否分享音频。
注意事项：
- 该功能仅适用于支持 Web SDK 的浏览器桌面端，不支持移动端。具体支持列表详见浏览器兼容性和已知问题。
- 关于各操作系统平台的浏览器版本及功能支持的补充说明如下：
  - 在 macOS 平台上，Chrome 74 及以上版本支持音视频共享，仅支持在共享 Chrome 标签页时分享音频。Firefox 和 Safari 14 及以上版本支持窗口和屏幕共享，不支持分享音频。
  - 在 Windows 平台上，Chrome 74 及以上版本和 Edge 支持在共享屏幕和浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。Firefox 支持窗口和屏幕共享，不支持分享音频。
  - 在 ChromeOS 平台上，Chrome 支持在共享屏幕和共享浏览器标签页时分享音频，不支持在共享应用窗口时分享音频。
- 设置了 withAudio 为 enable 后，还需要在屏幕共享的弹出框上，勾选分享音频才能真正生效。

返回值

Promise<[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack>

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

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 级别的日志信息。

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?: boolean): Promise<MediaDeviceInfo[]>

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

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

注意

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

参数

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

返回值

Promise<MediaDeviceInfo[]>

getDevices

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

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

注意

注意事项：

调用本方法会暂时打开摄像头和麦克风以触发浏览器的媒体设备权限申请。在 Chrome 67+，Firefox 70+ 以及 Safari 12+ 等浏览器上没有媒体设备权限时，无法准确获取到设备信息。
即使是对于同一设备，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);
});

参数

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

返回值

Promise<MediaDeviceInfo[]>

getElectronScreenSources

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

在 Electron 环境下获取屏幕共享源。

调用成功后 SDK 会返回一组 ElectronDesktopCapturerSource 对象。

注意

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

// 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?: boolean): Promise<MediaDeviceInfo[]>

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

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

注意

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

参数

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

返回值

Promise<MediaDeviceInfo[]>

getPlaybackDevices

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

自从

4.1.0

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

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

注意

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

参数

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

返回值

Promise<MediaDeviceInfo[]>

Other Methods

checkAudioTrackIsActive

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

检测音频轨道是否活跃。

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

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

注意

注意事项：

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

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: number	音频轨道检测的超时时间，单位为毫秒，默认 5,000 毫秒。

返回值

Promise<boolean>

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

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

checkSystemRequirements

checkSystemRequirements(): boolean

检查 Agora Web SDK 对正在使用的浏览器的适配情况。

该方法必须在创建客户端对象 createClient 之前调用。

返回值

boolean

是否支持当前浏览器。

true: 支持。
false: 不支持。

checkVideoTrackIsActive

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

检测视频轨道是否活跃。

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

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

注意

注意事项：

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

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: number	视频轨道检测的超时时间，单位为毫秒，默认 5,000 毫秒。

返回值

Promise<boolean>

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

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

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 编码格式。

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

返回值

Promise<object>

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

video: 数组类型，支持的视频编解码格式。可能含有 "H264"、"VP8" 两种取值，或为空数组。
audio: 数组类型，支持的音频编解码格式。可能含有 "OPUS"，或为空数组。

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

on(event: "audio-context-state-changed", listener: typeof event_audio_context_state_changed): void

on(event: "audio-context-state-changed", listener: typeof event_audio_context_state_changed): void

自从: 4.20.0

参数

参数名	描述
event: "audio-context-state-changed"	事件名称。
listener: typeof event_audio_context_state_changed	详见 event_audio_context_state_changed。

返回值

void

once

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

监听一个指定的事件，当事件触发时会调用传入的回调函数。

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

参数

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

返回值

void

preload

preload(appid: string, channel: string, token: string | null, uid?: UID | null): Promise<void>

使用appid、channel、token、uid 预加载频道。

调用该方法可以减少观众频繁切换频道时加入频道的时间，从而缩短观众听到主播首帧音频以及看到首帧画面的耗时，提升观众端的视频体验。

如果当前频道已经成功预加载，观众加入、离开频道后如需再次加入该频道，只要预加载时传入的 Token 仍在有效期内，则无需重新预加载。

注意

预加载的有效时间只有两分钟。
为了保护页面性能，此方法采取一次性尽力而为的策略，无法保证一定成功。但预加载失败不会影响观众正常加入频道，也不会增加加入频道的耗时。
系统最多缓存 10 条最新的不同预加载数据。
目前此方法不支持通过 proxy 代理进行转发。

参数

参数名	描述
appid: string	你的声网项目的 App ID。
channel: string	标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）: 26 个小写字母 a-z。 26 个大写字母 A-Z。 10 个数字 0-9。空格。 "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "\|", "~", ","。
token: string \| null	用于鉴权的 token。如果你的项目没有开启 token 鉴权，这里填 `null`。安全要求不高: 你可以使用控制台生成的临时 token，详见获取 RTC 临时 Token。安全要求高：传入从你的服务端获得的正式 token，详见使用 Token 鉴权。
uid: UID \| null	标识用户的 ID。整数或字符串，ASCII 字符，需保证唯一性。如果不指定或设为 `null`，服务器会自动分配一个整数型 uid。如果使用整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (2³²-1)。如果使用字符串作为用户 ID，长度不超过 255 个字符。为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。注意事项：一个频道内的所有用户必须使用同样类型的 `uid`，即必须都为整数或都为字符串。使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通，请确保 Native SDK 使用 User Account 加入频道。详见使用 String 型的用户名。为保证水晶球数据的准确性，建议自行指定 `uid` 并保证唯一性。

返回值

Promise<void>

processExternalMediaAEC

processExternalMediaAEC(element: HTMLMediaElement): void

自从

4.5.0

对本地播放的音频启用回声消除。

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

<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?: string): void

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

参数

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

返回值

void

resumeAudioContext

resumeAudioContext(): void

恢复音视频播放。

在某些版本的 iOS 设备上，App 通话被微信通话或系统电话打断后有概率无法自动恢复。你可以调用该方法恢复 App 通话。

声网推荐你通过 IAgoraRTC.on 监听 "audio-context-state-changed" 事件，并在回调函数 event_audio_context_state_changed 中进行以下处理：

当状态变为 "interrupted" 时，弹窗提示用户 App 通话被打断，需要点击按钮恢复通话。用户点击按钮后，调用 resumeAudioContext。
当状态变为 "running" 时，关闭弹窗。

返回值

void

setArea

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

自从

4.2.0

设置访问区域。

该功能为高级设置，适用于有访问安全限制的场景。

默认情况下，SDK 会就近选择声网服务器进行连接。设置访问区域之后，SDK 只会连接到指定区域内的声网服务器。

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

参数

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

返回值

void

Events​

audio-context-state-changed

参数​

返回值​

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

参数​

返回值​

Events

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

Global Callback Properties

Other Properties

Agora Core Methods

参数

返回值

Local Track Methods

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

Logger Methods

返回值

返回值

参数

返回值

Media Devices Methods

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

Other Methods

参数

返回值

返回值

参数

返回值

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数