Agora Web API Reference
声网已经推出下一代 Agora Web SDK (Agora Web SDK NG)，优化了 SDK 的内部架构，提高了 SDK 的可用性。Agora Web SDK NG 基于 Typescript 开发，并使用 Promise 来管理异步操作，提供了更灵活更易用的 API 方案。Agora Web SDK NG 当前处于 Beta 阶段，点击此处抢先体验，如有问题，可直接提交 Issue。
Agora Web SDK 是通过 HTML 网页加载的 JavaScript 库。Agora Web SDK 库在网页浏览器中调用 API 建立连接，控制音视频通话和直播服务。
Agora Web SDK 支持所有的主流浏览器，详见浏览器支持。如果你的使用场景中有移动设备，推荐阅读移动端使用 Agora Web SDK。
自 v2.5.0 开始，Agora Web SDK API 参考可以在 Dash 平台下载。
请务必使用 HTTPS 协议或者 localhost，否则会报错 MEDIA_NOT_SUPPORT。
AgoraRTC 是 Agora Web SDK 中所有可调用方法的入口。
AgoraRTC 包含以下方法:
| 方法 | 描述 |
|---|---|
| createClient | 创建客户端。 |
| createStream | 创建音视频流对象。 |
| getDevices | 获取可用的媒体输入/输出设备。 |
| getSupportedCodec | 获取支持的编解码格式。 |
| checkSystemRequirements | 检查 Web SDK 是否适配当前浏览器。 |
Client 客户端对象
使用 Agora Web SDK 的第一步就是调用 createClient 创建客户端对象。
为方便问题调查，我们建议你在创建客户端对象之前先调用 enableLogUpload 打开日志上传功能。
客户端对象指通话中的本地或远程用户，提供 AgoraRTC 的核心功能。下表列出 Client 的所有方法：
| 方法 | 描述 |
|---|---|
| init | 初始化客户端对象。 |
| off | 取消事件绑定。 |
| join | 加入 AgoraRTC 频道。 |
| leave | 离开 AgoraRTC 频道。 |
| publish | 发布本地音视频流至 SD-RTN。 |
| unpublish | 取消发布本地音视频流。 |
| subscribe | 接收远端音视频流。 |
| unsubscribe | 取消接收远端音视频流。 |
| setClientRole | 设置直播场景的用户角色。 |
| enableDualStream | 开启双流模式。双流为视频大流和视频小流，其中视频大流指高分辨率、高码率的视频流，视频小流指低分辨率、低码率的视频流。 |
| setLowStreamParameter | 设置小流视频参数。如果你开启了双流模式，该方法设置小流的视频参数。 |
| setRemoteVideoStreamType | 设置视频大小流。 |
| setStreamFallbackOption | 设置音视频流回退策略。网络不理想的情况下，为保证通话质量，可以选择自动订阅视频小流或者仅订阅音频流。 |
| disableDualStream | 关闭双流模式。 |
| enableAudioVolumeIndicator | 启用说话者音量提示。该方法允许 SDK 定期返回频道内正在说话的远端用户及其音量。 |
| startLiveStreaming | 新建直播流。 |
| setLiveTranscoding | 设置直播转码。 |
| stopLiveStreaming | 停止并删除直播流。 |
| addInjectStreamUrl | 导入在线媒体流。 |
| removeInjectStreamUrl | 删除导入的在线媒体流。 |
| startChannelMediaRelay | 开始跨频道媒体流转发。 |
| updateChannelMediaRelay | 更新媒体流转发的频道。 |
| stopChannelMediaRelay | 停止跨频道媒体流转发。 |
| startProxyServer | 开启云代理服务。 |
| stopProxyServer | 关闭云代理服务。 |
| setEncryptionSecret | 设置 AES 加密密码。 |
| setEncryptionMode | 设置 AES 加密方案。 |
| renewToken | 更新 Token。 |
| renewChannelKey | 更新 Channel Key。 |
| getSystemStats | 获取系统信息。 |
| getRecordingDevices | 枚举音频输入设备，如麦克风。 |
| getPlayoutDevices | 枚举音频输出设备，如扬声器。 |
| getCameras | 枚举视频输入设备，如摄像头。 |
| getRemoteAudioStats | 获取远端订阅的音频统计数据。 |
| getLocalAudioStats | 获取本地发布的音频统计数据。 |
| getRemoteVideoStats | 获取远端订阅的视频统计数据。 |
| getLocalVideoStats | 获取本地发布的视频统计数据。 |
| getTransportStats | 获取本地客户端与网关的连接状况的统计数据。 |
| getSessionStats | 获取本地客户端与会话的连接状况的统计数据。 |
| getConnectionState | 获取 SDK 与服务器的连接状态。 |
Stream 音视频流对象
音视频流对象指通话中的本地或远程音视频流，提供对音视频流的设置。下表列出 Stream 的所有方法：
| 方法 | 描述 |
|---|---|
| init | 初始化音视频流对象。 |
| play | 播放音视频流。 |
| stop | 停止播放音视频流。 |
| isPlaying | 检查音视频流是否在播放状态。 |
| close | 关闭音视频输入设备，如摄像头。 |
| unmuteAudio | 启用音频轨道。 |
| muteAudio | 禁用音频轨道。 |
| hasAudio | 获取音频 flag。 |
| getAudioLevel | 获取当前音量。 |
| getAudioTrack | 获取音视频流中的音频轨道。 |
| getVideoTrack | 获取音视频流中的视频轨道。 |
| replaceTrack | 替换本地流中的音视频轨道。 |
| addTrack | 将音视频轨道添加到音视频流。 |
| removeTrack | 从音视频流中移除音视频轨道。 |
| setAudioProfile | 设置音频属性。 |
| setAudioVolume | 调节播放订阅流的音量大小。 |
| setAudioOutput | 设置音频输出设备，可以在麦克风和扬声器之间切换。 |
| switchDevice | 切换媒体输入设备，比如麦克风和摄像头。 |
| unmuteVideo | 启用视频轨道。 |
| muteVideo | 禁用视频轨道。 |
| hasVideo | 获取视频 flag。 |
| setVideoProfile | 设置视频属性。 |
| setVideoEncoderConfiguration | 自定义视频编码配置。 |
| setBeautyEffectOptions | 设置美颜效果选项。 |
| setScreenProfile | 设置屏幕共享中的屏幕属性。 |
| startAudioMixing | 开始播放伴奏。 |
| stopAudioMixing | 停止播放伴奏。 |
| pauseAudioMixing | 暂停播放伴奏。 |
| resumeAudioMixing | 恢复播放伴奏。 |
| adjustAudioMixingVolume | 调节伴奏音量。 |
| getAudioMixingDuration | 获取伴奏时长。 |
| getAudioMixingCurrentPosition | 获取伴奏播放进度。 |
| setAudioMixingPosition | 设置伴奏音频文件的播放位置。可以根据实际情况播放文件，而不是非得从头到尾播放一个文件。 |
| playEffect | 播放指定音效文件。 |
| stopEffect | 停止播放指定音效文件。 |
| pauseEffect | 暂停播放指定音效文件。 |
| resumeEffect | 恢复播放指定音效文件。 |
| setVolumeOfEffect | 实时调整播放音效文件音量。 |
| preloadEffect | 预加载指定音效文件。 |
| unloadEffect | 释放指定音效文件。 |
| getEffectsVolume | 获取所有音效文件播放音量。 |
| setEffectsVolume | 设置所有音效文件播放音量。 |
| stopAllEffects | 停止播放所有音效文件。 |
| pauseAllEffects | 暂停播放所有音效文件。 |
| resumeAllEffects | 恢复播放所有音效文件。 |
| getId | 获取音视频流 ID。 |
| getStats | 获取连接统计数据。 |
事件
通过 Client.on 和 Stream.on 方法监听 Client 和 Stream 方法触发的事件。
错误码
以下为 SDK 可能抛出的错误，参考下表进行处理。
| 错误码 | 描述 | 解决方法 |
|---|---|---|
| STREAM_ALREADY_PUBLISHED | 重复发布流。 | 调用 unpublish 然后再重新调用 publish。 |
| INVALID_LOCAL_STREAM | 本地 Stream 对象不合法。 | 请确认 publish 中传入的为 createStream 方法创建的 Stream 对象，并且已成功调用 Stream.init 进行初始化。 |
| INVALID_OPERATION | 未加入频道，或重复加入频道。 | 请确认已在频道内，没有加入失败或者网络连接断开导致离开频道。你可以通过 getConnectionState 获取当前连接状态。 |
| PUBLISH_STREAM_FAILED | 发布流失败。 | 调用 unpublish 然后再重新调用 publish。 |
| PEERCONNECTION_FAILED | P2P 连接断开。 | 调用 unpublish 然后再重新调用 publish。 |
| STREAM_NOT_YET_PUBLISHED | 尚未发布流。 | 请确保在 publish 调用成功以后再调用 unpublish，并检查是否重复调用了 unpublish。 |
| INVALID_REMOTE_STREAM | 远端 Stream 对象不合法。 | 请确认 subscribe 中传入的为 stream-added 事件中取出来的 Stream 对象。 |
| NO_SUCH_REMOTE_STREAM | 频道里没有这个远端流。 | 在收到 stream-added 事件以后再订阅远端流。在网络断开和退出频道以后也会出现这种情况，可以尝试重新加入频道。 |
| INVALID_PARAMETER | 参数类型不正确。 | 可以在浏览器控制台打印的日志中查看具体的错误参数。 |
| UID_CONFLICT | 与频道中其他用户 uid 重复。 |
该错误是由于在同一个浏览器窗口，两个不同的 Client 使用相同的 uid 和 cname 加入频道导致的。请确保一个频道中每个用户的 uid 是唯一的。 |
| IOS_NOT_SUPPORT | iOS Safari 不支持双流模式。 | 请勿在 iOS 环境下开启双流模式。 |
| STILL_ON_PUBLISHING | 无法在发布流的过程中开启或关闭双流模式。 | 在 publish 调用成功后再开启/关闭双流模式。 |
| ENABLE_DUALSTREAM_FAILED | 打开双流模式失败。 | 尝试再次调用 enableDualStream 开启双流模式。如果多次尝试失败可能是因为设备环境不支持双流模式。 |
| SHARING_SCREEN_NOT_SUPPORT | 屏幕共享不支持小流。 | 请勿在使用屏幕共享的时候开启双流模式。 |
| HIGH_STREAM_NOT_VIDEO_TRACE | 开启双流模式时无法获取视频大流的轨道。 | 用 Stream.hasVideo 检查发布的流中是否包含视频轨道。 |
| DISABLE_DUALSTREAM_FAILED | 关闭小流失败。 | 尝试再次调用 disableDualStream 关闭双流模式。如果多次尝试失败可能是因为没有开启双流模式。 |
以下为浏览器控制台打印的错误。
| 错误码 | 描述 |
|---|---|
| ERR_JOIN_CHANNEL_TIMEOUT(2002) | 加入频道超时。 |
| ERR_JOIN_BY_MULTI_IP(2004) | 当前网络存在多出口 IP。该错误码可以忽略，SDK 会自动重连。 |
| ERR_FAILED(1) | 一般性的错误 (没有明确归类的错误原因)。 |
| ERR_INVALID_VENDOR_KEY(101) | App ID 无效。 |
| ERR_INVALID_CHANNEL_NAME(102) | 指定的频道名无效。 |
| ERR_DYNAMIC_KEY_TIMEOUT(109) | Channel Key 或者 Token 授权过期。生成动态密钥后需要在一天内使用，超过一天后使用会出现该错误。 |
| ERR_NO_AUTHORIZED(110) | Channel Key 或者 Token 无效。 |
| ERR_NO_ACTIVE_STATUS(116) | 使用的 App ID 对应的 Agora 项目未激活。 |
| ERR_INVALID_UID(117) | 非法的 UID。 |
| ERR_DYNAMIC_KEY_EXPIRED(118) | （SDK 2.9.0 以前版本）Channel Key 或者 Token 服务过期。 |
| ERR_STATIC_USE_DYNAMIC_KEY(119) | 静态厂商使用了动态密钥。一般是由于使用的 App ID 对应的 Agora 项目未启用 App Certificate，却试图使用 Token 加入频道引起。 |
| ERR_DYNAMIC_USE_STATIC_KEY(120) | 动态厂商使用了静态密钥。一般是由于使用的 App ID 对应的 Agora 项目已经启用 App Certificate，加入频道时却没有传入 Token 引起。 |
| K_TIMESTAMP_EXPIRED(2) | (SDK 2.9.0 及以后版本）Channel Key 或者 Token 服务过期。 |
警告码
警告码意味着 SDK 遇到问题，但有可能恢复，警告码仅起告知作用，一般情况下应用程序可以忽略警告码。
| 警告码 | 值 | 描述 |
|---|---|---|
| WARN_NO_AVAILABLE_CHANNEL | 103 | 没有可用的频道资源。可能是因为服务端没法分配频道资源。 |
| WARN_LOOKUP_CHANNEL_TIMEOUT | 104 | 查找频道超时。在加入频道时 SDK 先要查找指定的频道，出现该警告一般是因为网络太差，连接不到服务器。 |
| WARN_LOOKUP_CHANNEL_REJECTED | 105 | 查找频道请求被服务器拒绝。服务器可能没有办法处理这个请求或请求是非法的。 |
| WARN_OPEN_CHANNEL_TIMEOUT | 106 | 打开频道超时。查找到指定频道后，SDK 接着打开该频道，超时一般是因为网络太差，连接不到服务器。 |
| WARN_OPEN_CHANNEL_REJECTED | 107 | 打开频道请求被服务器拒绝。服务器可能没有办法处理该请求或该请求是非法的。 |
| WARN_REQUEST_DEFERRED | 108 | 用户申请延迟。 |
