Agora Web SDK 是通过 HTML 网页加载的 JavaScript 库。Agora Web SDK 库在网页浏览器中调用 API 建立连接,控制音视频通话和直播服务。

icon 自 v2.5.0 开始,Agora Web SDK API 参考可以在 Dash 平台下载。

如果需要打开摄像头,请务必使用 HTTPS 协议或者 localhost。

AgoraRTC 是 Agora Web SDK 中所有可调用方法的入口。

AgoraRTC 包含以下类:

描述
Client 提供 AgoraRTC 核心功能的 web 客户端对象。
ClientConfig 定义 createClient 创建的 Client 对象的属性。
Stream 设置通话中的本地或远程音视频流。
StreamSpec 定义 createStream 创建的 Stream 对象的属性。
LocalStreamStats 提供本地发布流的连接统计数据。
RemoteStreamStats 提供远端订阅流的连接统计数据。
LocalAudioStats 提供本地发布流的音频统计数据。
RemoteAudioStats 提供远端订阅流的音频统计数据。
LocalVideoStats 提供本地发布流的视频统计数据。
RemoteVideoStats 提供远端订阅流的视频统计数据。
TransportStats 提供与网关的连接统计数据。
SessionStats 提供与会话的连接统计数据。
NetworkQualityStats 提供网络质量评分。
LiveTranscoding 管理旁路推流转码的设置。
InjectStreamConfig 导入的在线媒体流的设置。
MediaDeviceInfo 提供媒体设备的信息。

Client 客户端对象

使用 Agora Web SDK 的第一步就是调用 createClient 创建客户端对象。

客户端对象指通话中的本地或远程用户,提供 AgoraRTC 的核心功能。下表列出 Client 的所有方法:

方法 描述
init 初始化客户端对象。
join 加入 AgoraRTC 频道。
leave 离开 AgoraRTC 频道。
publish 发布本地音视频流至 SD-RTN。
unpublish 取消发布本地音视频流。
subscribe 接收远端音视频流。
unsubscribe 取消接收远端音视频流。
setClientRole 设置直播场景的用户角色。
enableDualStream 开启双流模式。双流为视频大流和视频小流,其中视频大流指高分辨率、高码率的视频流,视频小流指低分辨率、低码率的视频流。
setLowStreamParameter 设置小流视频参数。如果你开启了双流模式,该方法设置小流的视频参数。
setRemoteVideoStreamType 设置视频大小流。
setStreamFallbackOption 设置音视频流回退策略。网络不理想的情况下,为保证通话质量,可以选择自动订阅视频小流或者仅订阅音频流。
disableDualStream 关闭双流模式。
enableAudioVolumeIndicator 启用说话者音量提示。该方法允许 SDK 定期返回频道内正在说话的远端用户及其音量。
startLiveStreaming 新建直播流。
setLiveTranscoding 设置直播转码。
stopLiveStreaming 停止并删除直播流。
addInjectStreamUrl 导入在线媒体流。
removeInjectStreamUrl 删除导入的在线媒体流。
setProxyServer 部署 Nginx 服务器。
setTurnServer 部署 TURN 服务器。
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 设置视频属性。
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.onStream.on 方法监听 ClientStream 方法触发的事件。

错误代码

错误代码意味着 SDK 遭遇不可恢复的错误,需要应用程序干预,例如打开摄像头失败会返回错误,应用程序需要提示用户不能使用摄像头。

错误代码 描述
STREAM_ALREADY_PUBLISHED / 重复 Publish
INVALID_LOCAL_STREAM / Stream 不合法
INVALID_OPERATION / 未加入频道,或重复加入频道
PUBLISH_STREAM_FAILED / Publish 失败
PEERCONNECTION_FAILED / P2P 连接断开
STREAM_NOT_YET_PUBLISHED / 尚未 Publish
UNPUBLISH_STREAM_FAILED / Unpublish 失败
INVALID_REMOTE_STREAM / 远端 Stream 不合法
SUBSCRIBE_STREAM_FAILED / Subscribe 失败
NO_SUCH_REMOTE_STREAM / 频道里没有这个 Remote 流
UNSUBSCRIBE_STREAM_FAILED / Unsubscribe 失败
INVALID_PARAMETER / 参数类型不正确
JOIN_TOO_FREQUENT / 加入频道过于频繁
IOS_NOT_SUPPORT / iOS Safari 不支持小流
STILL_ON_PUBLISHING / 无法在发流的过程中,打开或者关闭小流
ENABLE_DUALSTREAM_FAILED / 打开小流失败
SHARING_SCREEN_NOT_SUPPORT / 屏幕共享不支持小流
LOW_STREAM_ALREADY_PUBLISHED / 小流已经 Publish
HIGH_STREAM_NOT_VIDEO_TRACE / 无法获取大流的轨道
NOT_FIND_DEVICE_BY_LABEL / 无法找到大流的设备
DISABLE_DUALSTREAM_FAILED / 关闭小流失败
LOW_STREAM_NOT_YET_PUBLISHED / 小流没有 Publish
ERR_JOIN_CHANNEL_TIMEOUT 2002 加入频道超时
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 未激活
ERR_INVALID_UID 117 非法的 UID
ERR_DYNAMIC_KEY_EXPIRED 118 Channel Key 或者 Token 服务过期
ERR_STATIC_USE_DYNAMIC_KEY 119 静态厂商使用了动态 Key
ERR_DYNAMIC_USE_STATIC_KEY 120 动态厂商使用了静态 Key
K_TIMESTAMP_EXPIRED 2 Channel Key 或者 Token 服务过期
K_CHANNEL_PERMISSION_INVALID 3 无权利加入频道,具体解决办法请咨询频道管理员
K_CERTIFICATE_INVALID 4 App Certificate 无效
K_CHANNEL_NAME_EMPTY 5 频道名为空
K_CHANNEL_NOT_FOUND 6 未找到指定的频道
K_TICKET_INVALID 7 凭证无效
K_CHANNEL_CONFLICTED 8 频道有冲突
K_SERVICE_NOT_READY 9 无法提供服务
K_SERVICE_TOO_HEAVY 10 服务负载过大
K_UID_BANNED 14 UID 被禁用
K_IP_BANNED 15 IP 被禁用
K_CHANNEL_BANNED 16 频道被禁用

警告代码

警告代码意味着 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 用户申请延迟