设置旁路直播的属性
设置旁路直播的输出码流的码率。默认值为 500 Kbps。正整数,取值范围为 [1,10000000]。
设置旁路直播的输出码流的帧率。默认值为 15 fps。正整数,取值范围为 [1,10000]。
设置旁路直播的输出码流的高度。默认值为 640。正整数,取值范围为 [1,10000]。
设置合图的推流地址,默认为 null
, ASCII 字符,字符串长度大于 0 小于 256 字节。
设置旁路直播的输出码流的宽度。默认值为 360。正整数,取值范围为 [1,10000]。
关闭双流模式
该方法关闭双流模式。
方法调用成功时执行的回调函数
方法调用失败时执行的回调函数,常见的错误如下:
启用说话者音量提示
该方法允许 SDK 定期返回正在说话的远端用户及其音量。
启用该方法后,无论频道中有没有人说话,SDK 都会每两秒触发 "volume-indicator"
回调返回音量提示。
Note
在同一台设备上开多个通话页面可能会导致该功能不准或失效。
开启双流模式
该方法在 Publish 端,即发送端,开启双流模式。该方法建议在加入频道(Client.join)后调用。
双流为视频大流和视频小流,其中视频大流指高分辨率、高码率的视频流,视频小流指低分辨率、低码率的视频流。
建议不要对双流进行 track 操作(包括 addTrack/removeTrack/replaceTrack),否则会导致大流和小流的表现不一致。
方法调用成功时执行的回调函数
方法调用失败时执行的回调函数,常见的错误如下:
获取 SDK 与服务器的连接状态
调用该方法会返回 SDK 与服务器的连接状态。
SDK 与服务器的连接状态,共有以下 4 种:
DISCONNECTED
:连接断开。该状态表示 SDK 处于以下任一阶段:CONNECTING
:正在连接中。在调用 Client.join 或者连接中断自动重连的时候为此状态。CONNECTED
:已连接。该状态表示用户已经加入频道,可以在频道内发布或订阅媒体流。DISCONNECTING
:正在断开连接。在调用 Client.leave 的时候为此状态。获取本地发布流的音频统计数据
该方法获取发布流的音频统计数据,包括音频编码类型、采样率、码率等。
Note
stream-published
事件后进行统计,可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。包含本地发布流的音频统计数据的回调。
获取本地发布流的视频统计数据
该方法获取本地发布流的视频统计数据,包括视频分辨率、视频码率、视频帧率等。
Note
stream-published
事件后进行统计,可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。包含本地发布流的视频统计数据。
获取系统网络信息
DEPRECATED
该方法自 2.5.1 起废弃,请使用 getTransportStats 获取网络信息。
该方法可获取浏览器本地网络信息。
目前仅提供网络类型信息,详见 NetworkType。
Note
该功能仅支持 Chrome 61+ ,且无法保证兼容性,详见网络状况 API。
包含系统网络信息的回调。
获取远端订阅流的音频统计数据
该方法获取订阅流的音频统计数据,包括音频解码类型、丢包率、码率等。
Note
stream-subscribed
事件后进行统计,可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。包含远端订阅流的音频统计数据的回调。
获取远端订阅流的视频统计数据
该方法获取远端订阅流的视频统计数据,包括丢包率、视频码率、视频帧率等。
Note
stream-subscribed
事件后进行统计,可能耗费 0-3 秒时间返回。你可以循环调用该方法获取数据。包含远端订阅流的视频统计数据的回调。
获取与会话的连接状况统计数据
该方法获取与会话的连接状况统计数据。
Note
包含会话状况统计数据的回调。
包含系统信息的回调。
获取与网关的连接状况统计数据
该方法获取与网关的连接状况的统计数据。
Note
包含与网关的连接状况的统计数据的回调。
初始化客户端对象
使用该方法初始化客户端对象。
传入你的项目的 App ID。ASCII 字符,字符串长度大于 0 小于 256 字节。
方法调用成功时执行的回调函数
方法调用失败时执行的回调函数,常见的错误如下:
"BAD_ENVIRONMENT"
: 不支持当前使用的浏览器。加入 AgoraRTC 频道
该方法让用户加入 AgoraRTC 频道。
调用该方法加入频道时,本地会触发 Client.on("connected")
和 Client.on("connection-state-change")
回调;通信场景下的用户和直播场景下的主播加入频道后,远端会触发 Client.on("peer-online")
回调。
null
。标识通话频道的字符串,长度在 64 字节以内的字符串。以下为支持的字符集范围(共89个字符):
指定用户的 ID。整数或字符串,ASCII 字符,需保证唯一性。如果不指定(即设为 null
)或设为 0
,服务器会自动分配一个,并在 onSuccess
回调方法中返回。
Note
uid
,即必须都为整数或都为字符串。(选填)你想要传入的附加信息。一般可设置为空,或频道相关信息。该信息不会传递给频道内的其他用户。
方法调用成功时执行的回调函数,返回值代表用户身份的 uid(整型)。如果使用字符串作为用户 ID 加入频道,则返回对应的整型 uid。
方法调用失败时执行的回调函数,常见的错误如下:
"INVALID_OPERATION"
: 当前无法加入频道,通常是因为重复调用了 Client.join
。"UID_CONFLICT"
: 当前 Client 的 uid
和频道中其他 Client 的 uid
冲突。"ERR_REPEAT_JOIN"
: 当前 Client 已经加入了频道。"SOCKET_ERROR"
: 加入频道过程中和 Agora 服务器断开连接。"CANNOT_MEET_AREA_DEMAND"
: 由于用户在指定的访问区域外,导致无法建立连接。例如,假设你将 ClientConfig.areaCode 设为 [AgoraRTC.AREAS.CHINA]
,位于日本的用户尝试加入频道时就会发生此错误。如果你没有设置 ClientConfig.areaCode
,SDK 默认会同时请求多个区域的服务器并择优进行连接,因此在用户加入频道时控制台日志可能也会打印该错误。这种情况你可以忽略该错误码。离开 AgoraRTC 频道
该方法让用户离开 AgoraRTC 频道。
调用该方法离开频道时,本地会触发 Client.on("connection-state-change")
回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 Client.on("peer-leave")
回调。
方法调用成功时执行的回调函数
方法调用失败时执行的回调函数,可能的错误如下:
leave
或者当前没有完成加入频道取消事件绑定
该方法用于移除通过 Client.on()
绑定的事件。
要移除的事件名称
要移除的函数变量名
发布本地音视频流
该方法将本地音视频流发布至 SD-RTN。
发布音视频流之后,本地会触发 Client.on("stream-published")
回调;远端会触发 Client.on("stream-added")
回调。
Note
在直播场景里,调用该方法的用户即为主播。
本地音视频流对象
方法调用失败时执行的回调函数, 可能的错误如下:
stream
已经发布。stream
格式非法。rejoin
事件,等重连成功后再次调用 publish
。更新 Channel Key
该方法更新 Channel Key。如果启用了 Channel Key 机制,过一段时间后密钥会失效。 当 onFailure
回调报告 DYNAMIC_KEY_TIMEOUT
时,调用该 API 以更新 Channel Key,否则 SDK 会无法和服务器建立连接。
指定新的 Channel Key
方法调用成功时执行的回调函数
方法调用失败时执行的回调函数,常见的错误如下:
更新 Token
该方法更新 Token。如果启用了 Token 机制,过一段时间后密钥会失效。 当收到 onTokenPrivilegeWillExpire
或 onTokenPrivilegeDidExpire
消息时,调用该 API 以更新 Token,否则 SDK 会无法和服务器建立连接。
指定新的 Token
设置用户角色
本方法仅适用于直播场景。
直播场景下,可以调用本方法设置用户角色。
在加入频道前,用户可以通过本方法设置自己的角色。
在加入频道后,用户可以通过本方法切换角色:
host
角色,调用 unpublish 的时候会自动切换为 audience
角色。audience
,会自动进行 unpublish。如果你在加入频道后调用该方法切换用户角色,切换成功后,本地会触发 Client.on("client-role-changed")
回调;远端会触发 Client.on("peer-online")
或者 Client.on("peer-leave")
回调。
Note
通信场景(mode 设置为 rtc
)无法使用本方法,默认所有用户都是 host
角色。
用户角色:
"audience"
:观众,默认角色,只能接收音视频流,无法发布。"host"
:主播,可以发布和接收音视频流。设置内置加密方案
该方法和 setEncryptionSecret 搭配使用,可以开启内置加密功能,需要在加入频道前调用。
同一频道内的所有用户必须设置相同的加密方案、密钥和盐值才能进行通话。
Note
Client.on("crypt-error")
回调。加密模式,包含以下几种:
"aes-128-xts"
: 128 位 AES 加密,XTS 模式。"aes-256-xts"
: 256 位 AES 加密,XTS 模式。"aes-128-ecb"
: 128 位 AES 加密,ECB 模式。"aes-128-gcm"
: 128 位 AES 加密,GCM 模式。"aes-256-gcm"
: 256 位 AES 加密,GCM 模式。"sm4-128-ecb"
: 128 位国密 SM4 加密,ECB 模式。"aes-128-gcm2"
: 128 位 AES 加密,GCM 模式,加盐。"aes-256-gcm2"
: 256 位 AES 加密,GCM 模式,加盐。"none"
: 不加密。盐值。当加密模式为 "aes-128-gcm2"
或 "aes-256-gcm2"
时有效。Agora 推荐你在服务端使用 OpenSSL 生成盐值,详见媒体流加密。
设置内置加密密钥
该方法和 setEncryptionMode 搭配使用,可以开启内置加密功能,需要在加入频道前调用。
同一频道内的所有用户应设置相同的密钥。如果未指定密钥,则无法激活加密功能。
Note
Client.on("crypt-error")
回调。加密密钥。ASCII 字符,字符串长度大于 0 小于 256 字节。当终端用户设置的密码为弱密码时,SDK 会在控制台打印警告信息,提醒用户设置强密码,即密码必须包含大写字母、小写字母、数字和特殊字符,以及长度至少 8 位。Agora 推荐你在服务端使用 OpenSSL 生成密钥,详见媒体流加密。
设置直播推流转码
调用该方法更新转码设置后本地会触发 Client.on("liveTranscodingUpdated")
回调。
Note
直播转码的设置,详见 LiveTranscoding。
设置小流视频属性
如果你调用 Client.enableDualStream 开启了双流模式,可以调用该方法设置小流的视频属性。
如果你不调用该方法,SDK 会使用默认的小流视频属性:分辨率(宽 × 高)160 × 120,码率 50 Kbps,帧率 15 fps。
Note
小流的视频属性。
小流视频帧的码率。
正整数,取值范围为 [1,10000000],单位为 Kbps。默认值 50。
小流视频帧的帧率。
正整数,取值范围为 [1,10000],单位为 fps。默认值 15。
小流视频帧的高度。正整数,取值范围为 [1,10000]。
width
和 height
参数互相绑定,只有两个都填才有效,否则视为缺省,SDK 会自动设为 120。
小流视频帧的宽度。正整数,取值范围为 [1,10000]。
width
和 height
参数互相绑定,只有两个都填才有效,否则视为缺省,SDK 会自动设为 160。
部署代理服务器
Agora Web SDK 还提供 startProxyServer 方法支持云代理服务,详见使用云代理。
Note
你的代理服务器域名。ASCII 字符,字符串长度大于 0 小于 256 字节。详见 ClientConfig.proxyServer。
设置视频大小流
如果发送端选择发送视频双流 (大流或小流),该方法可以在订阅端选择接收大流还是小流。如果不设置,订阅端默认接收大流。
远端视频流对象
设置远端视频流大小。视频流类型如下:
设置音视频流回退策略
该接口用于设置订阅端在弱网情况下音视频流的回退策略。网络不理想的情况下,为保证通话质量,可以选择自动订阅视频小流(低分辨率、低码率视频流)或者仅订阅音频流。
开启自动回退之后,当订阅流从视频大流回退为视频小流或从视频小流恢复为视频大流时,本地会触发 Client.on("stream-type-changed")
回调。当订阅流回退为音频流或从音频流恢复为音视频流时,本地会触发 Client.on("stream-fallback")
回调。
Note
该方法只可在发送端通过 enableDualStream 开启双流模式的情况下使用。
远端音视频流对象
回退选项:
由 TurnServer 对象组成的数组,支持传入多组 TURN 服务器设置。
开始跨频道媒体流转发
自从
3.0.0
该方法可用于实现跨频道媒体流转发。
调用该方法后,SDK 会触发以下回调:
Client.on("channel-media-relay-state")
,报告当前的跨频道媒体流转发状态和错误码。state
为 2,code
为 0。state
为 3,code
为错误码。你可以尝试再次调用本方法。Client.on("channel-media-relay-event")
,报告跨频道媒体流转发相关的事件。code
为 4,表示 SDK 开始向目标频道发送数据包。Note
跨频道媒体流转发参数配置,详见 ChannelMediaRelayConfiguration。
媒体流转发是否成功的回调。
null
:媒体流转发成功。新建直播流
该方法新建直播流。详见推流到 CDN。
推流开始后本地会触发 Client.on("liveStreamingStarted")
回调。如果推流失败会触发 Client.on("liveStreamingFailed")
回调。
Note
(必选项)直播推流的地址。 ASCII 字符,字符串长度不得超过 1024 字节。
(非必选项) 是否启用直播转码。如果设为 true
(启用转码),需先调用 setLiveTranscoding。
停止跨频道媒体流转发
自从
3.0.0
一旦停止转发,用户会退出所有的目标频道。
调用该方法会触发 Client.on("channel-media-relay-state")
回调。
state
为 0。state
为 3,code
错误码可能为 2 或 8,一般是在网络较差的情况下,退出的消息发送不成功导致的。你可以调用 Client.leave 离开频道来停止跨频道媒体流转发。停止跨频道媒体流转发是否成功的回调。
null
:停止跨频道媒体流转发成功。删除直播流
该方法停止并删除直播流。推流停止后本地会触发 Client.on("liveStreamingStopped")
回调。
直播推流的地址。ASCII 字符,字符串长度不得超过 1024 字节。
订阅远端音视频流
该方法从服务器端接收远端音视频流。
订阅远端音视频流之后,本地会触发 Client.on("stream-subscribed")
回调。
如果订阅流中包含音频,还会触发 Client.on("first-audio-frame-decode")
回调;如果订阅流中包含视频,还会触发 Client.on("first-video-frame-decode")
回调。
远端音视频流对象
设置是否接收视频或音频。
Note
video
和 audio
不可同时设为 false
。如果想取消订阅流,请调用 Client.unsubscribe 方法。options
设为 null
,否则会收到SAFARI_NOT_SUPPORTED_FOR_TRACK_SUBSCRIPTION
错误。设置是否接收音频数据。
true
:(默认)接收音频数据。false
:不接收音频数据。设置是否接收视频数据。
true
:(默认)接收视频数据。false
:不接收视频数据。方法调用失败时执行的回调函数,以下列举一些常见的错误:
取消发布本地音视频流
该方法取消发布本地音视频流。
取消发布音视频流之后,本地会触发 Client.on("stream-unpublished")
回调,远端会触发 Client.on("stream-removed")
回调。
Note
直播场景中,主播取消发布流之后用户角色会自动切换为观众,远端还会触发 Client.on("peer-leave")
回调。
本地音视频流对象
方法调用失败时执行的回调函数,以下列举一些可能的错误:
stream
还没有发布。stream
格式非法。取消订阅远端音视频流
该方法取消接收远端音视频流。
远端音视频流对象
方法调用失败时执行的回调函数,常见的错误如下:
stream
对象格式非法。更新媒体流转发的目标频道
自从
3.0.0
成功开始跨频道转发媒体流后,如果你希望添加或删除媒体流转发的目标频道,可以调用该方法。
调用该方法后,SDK 会触发 Client.on("channel-media-relay-event")
回调。
code
为 7。code
为 8,同时还会触发 Client.on("channel-media-relay-state")
回调,其中 state
为 3。出错后跨频道媒体流转发状态会被重置,你需要调用 startChannelMediaRelay 重新开始跨频道媒体流转发。Note
跨频道媒体流转发参数配置,详见 ChannelMediaRelayConfiguration。
更新目标频道是否成功的回调。
null
:更新目标频道成功。
Client 接口提供音视频通话的核心功能,例如加入频道、发布和订阅音视频流等。
你可以通过 createClient 创建 Client 对象。一个 Client 对象代表一个本地客户端。