Agora Web SDK 是通过 HTML 网页加载的 JavaScript 库。Agora Web SDK 库在网页浏览器中调用 API 建立连接,控制音视频通话和直播服务。
自 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 | 提供媒体设备的信息。 |
使用 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 的所有方法:
方法 | 描述 |
---|---|
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.on 和 Stream.on 方法监听 Client 和 Stream 方法触发的事件。
错误代码意味着 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 | 用户申请延迟 |