Interface IAgoraRTC

EventsCopy Anchor Link

audio-context-state-changedCopy Anchor Link

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

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

autoplay-failedCopy Anchor Link

autoplay-failed(): void

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

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

camera-changedCopy Anchor Link

camera-changed(deviceInfo: DeviceInfo): void

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

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

microphone-changedCopy Anchor Link

microphone-changed(deviceInfo: DeviceInfo): void

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

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

playback-device-changedCopy Anchor Link

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

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

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

security-policy-violationCopy Anchor Link

security-policy-violation(): void

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

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

Global Callback PropertiesCopy Anchor Link

onAudioAutoplayFailedCopy Anchor Link

onAudioAutoplayFailed: function

音频轨道自动播放失败回调。

deprecatedCopy Anchor Link

自 4.6.0 起废弃，请改用 onAutoplayFailed。

该回调在音频轨道自动播放失败的时候触发。如果短时间内有多个音频轨道对象都调用了 play，SDK 会触发多次 onAudioAutoplayFailed。

音频自动播放失败是浏览器的自动播放策略导致的，视频轨道的播放不受此影响。

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

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

无论使用何种方案，只要浏览器启用了自动播放策略，都需要用户至少触发一次点击交互操作才能播放音频。随着用户使用某个页面的次数变多，浏览器会在这个页面上默认关闭自动播放策略，此时不需要任何交互也可以播放音频了，但是我们无法通过 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 这个对象防止创建重复的按钮对象。

Type declarationCopy Anchor Link

(): void

onAutoplayFailedCopy Anchor Link

onAutoplayFailed: function

音频或视频轨道自动播放失败回调。

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

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

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

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

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

Type declarationCopy Anchor Link

(): void

onCameraChangedCopy Anchor Link

onCameraChanged: function

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

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

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

Parameters

• deviceInfo：设备信息，详见 DeviceInfo。

Type declarationCopy Anchor Link

(deviceInfo: DeviceInfo): void

onMicrophoneChangedCopy Anchor Link

onMicrophoneChanged: function

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

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

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

Parameters

• deviceInfo：设备信息，详见 DeviceInfo。

Type declarationCopy Anchor Link

(deviceInfo: DeviceInfo): void

onPlaybackDeviceChangedCopy Anchor Link

onPlaybackDeviceChanged: function

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

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

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

Parameters

• deviceInfo：设备信息，详见 DeviceInfo。

Type declarationCopy Anchor Link

(deviceInfo: DeviceInfo): void

onSecurityPolicyViolationCopy Anchor Link

onSecurityPolicyViolation: function

触发 CSP 规则回调。

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

Type declarationCopy Anchor Link

(event: SecurityPolicyViolationEvent): void

Other PropertiesCopy Anchor Link

VERSIONCopy Anchor Link

VERSION: string

Agora Web SDK 的版本信息。

Agora Core MethodsCopy Anchor Link

createClientCopy Anchor Link

createClient(config: ClientConfig): IAgoraRTCClient

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

Local Track MethodsCopy Anchor Link

createBufferSourceAudioTrackCopy Anchor Link

createBufferSourceAudioTrack(config: BufferSourceAudioTrackInitConfig): Promise<IBufferSourceAudioTrack>

通过音频文件或者 AudioBuffer 对象创建一个音频轨道。

该方法支持本地和在线音频文件。音频文件支持以下音频格式：

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

createCameraVideoTrackCopy Anchor Link

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

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

createCustomAudioTrackCopy Anchor Link

createCustomAudioTrack(config: CustomAudioTrackInitConfig): ILocalAudioTrack

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

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

createCustomVideoTrackCopy Anchor Link

createCustomVideoTrack(config: CustomVideoTrackInitConfig): ILocalVideoTrack

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

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

createMicrophoneAndCameraTracksCopy Anchor Link

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

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

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

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

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

createMicrophoneAudioTrackCopy Anchor Link

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

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

createScreenVideoTrackCopy Anchor Link

createScreenVideoTrack [1/3]Copy Anchor Link

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

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

createScreenVideoTrack [2/3]Copy Anchor Link

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

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

createScreenVideoTrack [3/3]Copy Anchor Link

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

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

Logger MethodsCopy Anchor Link

disableLogUploadCopy Anchor Link

disableLogUpload(): void

关闭日志上传。

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

enableLogUploadCopy Anchor Link

enableLogUpload(): void

开启日志上传。开启后 SDK 的日志会上传到声网的服务器。

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

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

setLogLevelCopy Anchor Link

setLogLevel(level: number): void

设置 SDK 的日志输出级别。

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

Media Devices MethodsCopy Anchor Link

getCamerasCopy Anchor Link

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

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

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

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

getDevicesCopy Anchor Link

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

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

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

getElectronScreenSourcesCopy Anchor Link

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 });
})()

getMicrophonesCopy Anchor Link

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

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

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

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

getPlaybackDevicesCopy Anchor Link

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

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

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

• Chrome、Firefox、Edge 浏览器上支持该方法。Safari 支持情况如下：macOS 上的 Safari 18.4 及以上版本支持该方法；iOS 上的 Safari 26 及以上版本支持该方法。
• 调用本方法会暂时打开麦克风以触发浏览器的媒体设备权限申请。在 Chrome 67+ 和 Firefox 70+ 浏览器上，没有媒体设备权限时无法获取到准确的设备信息。

Other MethodsCopy Anchor Link

checkAudioTrackIsActiveCopy Anchor Link

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

检测音频轨道是否活跃。

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

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

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);
});

checkSystemRequirementsCopy Anchor Link

checkSystemRequirements(): boolean

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

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

checkVideoTrackIsActiveCopy Anchor Link

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

检测视频轨道是否活跃。

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

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

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);
});

createChannelMediaRelayConfigurationCopy Anchor Link

createChannelMediaRelayConfiguration(): IChannelMediaRelayConfiguration

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

getListenersCopy Anchor Link

getListeners(event: string): Function[]

Inherited from EventEmitter.getListeners

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

getSupportedCodecCopy Anchor Link

getSupportedCodec(): Promise<object>

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

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

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

offCopy Anchor Link

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

Inherited from EventEmitter.off

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

onCopy Anchor Link

on [1/6]Copy Anchor Link

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

Overrides EventEmitter.on

on [2/6]Copy Anchor Link

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

Overrides EventEmitter.on

on [3/6]Copy Anchor Link

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

Overrides EventEmitter.on

on [4/6]Copy Anchor Link

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

Overrides EventEmitter.on

on [5/6]Copy Anchor Link

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

Overrides EventEmitter.on

on [6/6]Copy Anchor Link

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

Overrides EventEmitter.on

onceCopy Anchor Link

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

Inherited from EventEmitter.once

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

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

preloadCopy Anchor Link

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

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

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

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

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

processExternalMediaAECCopy Anchor Link

processExternalMediaAEC(element: HTMLMediaElement): void

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

在多个用户同时播放一个媒体文件的场景中，例如一起看电影，如果用户 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>

registerExtensionsCopy Anchor Link

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

注册插件。

removeAllListenersCopy Anchor Link

removeAllListeners(event?: string): void

Inherited from EventEmitter.removeAllListeners

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

resumeAudioContextCopy Anchor Link

resumeAudioContext(): void

恢复音视频播放。

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

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

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

setAreaCopy Anchor Link

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

设置访问区域。

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

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

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

startLastmileProbeTestCopy Anchor Link

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

在通话前对客户端与边缘节点之间的网络质量进行检测。