跨频道媒体流转发事件回调。
事件码,详见 ChannelMediaRelayEvent。
跨频道媒体流转发状态回调。
当跨频道媒体流转发状态发生改变时,SDK 会触发该回调,并报告当前的转发状态以及相关的错误信息。
回调会携带当前跨频道媒体流转发服务的状态 ChannelMediaRelayState,如果状态异常,相应的错误码可以通过 ChannelMediaRelayError 获取(比如 token 过期,重连失败等)。
跨频道媒体流转发服务的状态。
跨频道媒体流转发错误码。
SDK 与服务器的连接状态发生改变回调。
当前的连接状态。
如果 curState
为 "DISCONNECTED"
,这里表示断开连接的原因。
解密失败回调。
该回调表示用户在订阅过程中出现了解密失败,通常是由于和发布端设置的加密参数不一致导致的。详见 setEncryptionConfig。
SDK 监测到异常事件回调。
该回调报告频道内 SDK 监测出的异常事件。
异常事件不是错误,但是一般会引起通话质量问题。发生异常事件后,如果恢复正常,也会收到该回调。
每个异常事件都有对应的恢复事件。
异常事件见下表:
事件码 | 提示消息 | 异常 |
---|---|---|
1001 | FRAMERATE_INPUT_TOO_LOW | 视频采集帧率过低 |
1002 | FRAMERATE_SENT_TOO_LOW | 视频发送帧率过低 |
1003 | SEND_VIDEO_BITRATE_TOO_LOW | 视频发送码率过低 |
1005 | RECV_VIDEO_DECODE_FAILED | 接收视频解码失败 |
2001 | AUDIO_INPUT_LEVEL_TOO_LOW | 发送音量过低 |
2002 | AUDIO_OUTPUT_LEVEL_TOO_LOW | 接收音量过低 |
2003 | SEND_AUDIO_BITRATE_TOO_LOW | 音频发送码率过低 |
2005 | RECV_AUDIO_DECODE_FAILED | 接收音频解码失败 |
恢复事件详见下表:
事件码 | 提示消息 | 恢复 |
---|---|---|
3001 | FRAMERATE_INPUT_TOO_LOW_RECOVER | 视频采集帧率恢复正常 |
3002 | FRAMERATE_SENT_TOO_LOW_RECOVER | 视频发送帧率恢复正常 |
3003 | SEND_VIDEO_BITRATE_TOO_LOW_RECOVER | 视频发送码率恢复正常 |
3005 | RECV_VIDEO_DECODE_FAILED_RECOVER | 接收视频解码恢复正常 |
4001 | AUDIO_INPUT_LEVEL_TOO_LOW_RECOVER | 发送音量恢复正常 |
4002 | AUDIO_OUTPUT_LEVEL_TOO_LOW_RECOVER | 接收音量恢复正常 |
4003 | SEND_AUDIO_BITRATE_TOO_LOW_RECOVER | 音频发送码率恢复正常 |
4005 | RECV_AUDIO_DECODE_FAILED_RECOVER | 接收音频解码恢复正常 |
事件码,详细见上表。
提示消息。
发生异常或者恢复异常的用户 ID。
自从
4.4.0
成功调用 publish 后,SDK 会通过这个回调通知当前媒体流是否经云代理服务转发。
当前媒体流是否经云代理服务转发:
true
: 经云代理服务转发。false
: 没有经云代理服务转发。推流发生错误回调。
在调用 startLiveStreaming 成功开始推流后,推流中途发生错误时,会通过这个事件抛出。
你可以访问 err.code
来获取错误码字符串,下面列出可能出现的错误:
LIVE_STREAMING_INVALID_ARGUMENT
: 推流参数错误。LIVE_STREAMING_INTERNAL_SERVER_ERROR
: 推流服务器内部错误。LIVE_STREAMING_PUBLISH_STREAM_NOT_AUTHORIZED
: 推流 URL 被占用。LIVE_STREAMING_TRANSCODING_NOT_SUPPORTED
: 在非转码推流中调用了转码参数。LIVE_STREAMING_CDN_ERROR
: 推流的目标 CDN 出现错误导致推流失败。LIVE_STREAMING_INVALID_RAW_STREAM
: 推流超时,请确认目标流是否存在。发生错误的直播推流地址。
详细的错误信息。
推流发生警告回调。
在调用 startLiveStreaming 成功开始推流后,推流中途发生警告时,会通过这个事件抛出。
你可以访问 err.code
来获取警告码字符串,下面列举可能出现的警告:
LIVE_STREAMING_WARN_STREAM_NUM_REACH_LIMIT
: 推流超过 10 路流。LIVE_STREAMING_WARN_FAILED_LOAD_IMAGE
: 推流中的背景图片或者水印地址无法拉取。LIVE_STREAMING_WARN_FREQUENT_REQUEST
: 推流请求太频繁。发生警告的直播推流地址。
SDK 重新建立媒体连接(用于发布和订阅)结束的回调。
重新建立的媒体连接所对应的用户 ID。如果是本地 uid
说明是重新发布,如果是远端 uid
说明是重新订阅。
SDK 开始尝试重新建立媒体连接(用于发布和订阅)的回调。
重新建立的媒体连接所对应的用户 ID。如果是本地 uid
说明是重新发布,如果是远端 uid
说明是重新订阅。
网络上下行质量报告回调。
用户加入频道后,SDK 会每 2 秒触发一次该回调,报告本地用户当前的上行和下行网络质量。
我们推荐使用此回调来展示你的网络状态。
网络质量。
订阅的音视频流回退为音频流或恢复为音视频流回调。
如果在 setStreamFallbackOption 中将 fallbackType
设为 2,当下行网络环境不理想、仅接收远端音频流时,或当下行网络改善、恢复订阅音视频流时,会触发该回调。
远端流对应的用户 ID。
订阅流是回退还是恢复:
"fallback"
: 从音视频流回退为纯音频流。"recover"
: 从音频流恢复为音视频。注意事项:客户端输入在线媒体流功能即将停服。如果你尚未集成该功能,Agora 建议你不要使用。详见《部分服务下架计划》。
调用 addInjectStreamUrl 后,SDK 通过这个回调通知当前输入媒体流的状态。
当前的状态码。
输入媒体流的 UID。
输入媒体流的在线地址。
订阅的视频流类型发生改变回调。
视频流类型改变指视频大流(高码率、高分辨率)变为视频小流(低码率、低分辨率),或视频小流变为视频大流。
远端流对应的用户 ID。
改变后的视频流类型:
Token 已过期回调。
在 token 过期后,会收到该回调。
一般情况下,在收到该消息之后,应向服务端重新申请 token,并调用 join 方法传入新的 token 重新加入频道。
client.on("token-privilege-did-expire", async function(){
//进行重新申请 token 操作后
await client.renewToken(token);
});
Token 即将过期回调。
在 token 过期前 30 秒,会收到该回调。
在收到该回调之后,应向服务端重新申请 token,并调用 renewToken 方法传入新的 token。
client.on("token-privilege-will-expire", async function(){
//进行重新申请 token 操作后
await client.renewToken(token);
});
该回调用于和 Agora RTC Native SDK 互通时提示来自 Native SDK 的用户状态变化。
该事件仅用于和 Native 应用之间同步状态。
在大部分情况下,你只需要监听 user-published 和 user-unpublished 就可以完成订阅、取消订阅、展示远端用户是否打开了摄像头和麦克风等工作,无需特别关注实际用户状态的变化,SDK 会自动处理用户状态变化。
即使用户状态表示该用户的音视频流是活跃的,不一定意味着该用户可订阅。是否可订阅的唯一标志是收到 user-published 事件。
发生状态变化的用户的 ID。
当前状态。
远端用户或主播加入频道回调。
该回调在以下情况下会被触发:
加入频道的用户信息。
远端用户离线回调。
该回调通知 app 有远端用户离线,离线包括以下情况:
在直播场景中,只有角色为主播的用户会触发该回调。
离线的用户信息。
用户离线的原因。
"Quit"
: 用户调用了 leave 主动离开频道。"ServerTimeOut"
: 因过长时间收不到对方数据包,超时掉线。注意:由于 SDK 使用的是不可靠通道,也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线。"BecomeAudience"
: 用户角色从主播切换为观众。该回调通知远端用户发布了新的音频轨道或者视频轨道。
你可以在该回调中订阅并播放远端用户的音视频轨道。详见 subscribe 和 RemoteTrack.play。
如果用户加入频道时频道内已经有其他用户的音视频轨道,也会收到该回调报告已经存在的远端轨道。
client.on("user-published", async (user, mediaType) => {
await client.subscribe(user, mediaType);
if (mediaType === "video") {
console.log("subscribe video success");
user.videoTrack.play("xxx");
}
if (mediaType === "audio") {
console.log("subscribe audio success");
user.audioTrack.play();
}
})
远端用户信息。
远端用户发布的媒体类型。
"audio"
: 远端用户发布了音频轨道。"video"
: 远端用户发布了视频轨道。该回调通知远端用户取消发布了音频或视频轨道。
远端用户信息。
远端用户取消发布的媒体类型。
"audio"
: 远端用户取消发布了音频轨道。"video"
: 远端用户取消发布了视频轨道。报告频道内正在说话的远端用户及其音量的回调。
默认禁用。可以通过 enableAudioVolumeIndicator 方法开启;开启后,无论频道内是否有人说话,都会每两秒返回提示音量。
音量范围为 0 到 100 之间。通常在列表中音量大于 5 的用户为持续说话的人。
client.on("volume-indicator", function(result){
result.forEach(function(volume, index){
console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
});
});
当前加入的频道名称
如果本地用户没有加入频道,该属性值为 undefined
。
SDK 和 Agora 服务器的连接状态。
远端用户信息列表,包含频道中各个远端用户的用户 ID 和轨道信息。
如果本地用户没有加入频道,该列表为空。
本地用户的用户 ID。
如果本地用户没有加入频道,该属性值为 undefined
。
加入频道。
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话。
调用该方法加入频道时,本地会触发 AgoraRTCClient.on("connection-state-change") 回调。
通信场景下的用户和直播场景下的主播加入频道后,远端会触发 AgoraRTCClient.on("user-joined") 回调。
你的 Agora 项目的 App ID。
标识通话的频道名称,长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
用于鉴权的 token。
null
。标识用户的 ID。整数或字符串,ASCII 字符,需保证唯一性。如果不指定(或设为 null
),服务器会自动分配一个并在 Promise 中返回。
注意事项:
- 一个频道内的所有用户必须使用同样类型的
uid
,即必须都为整数或都为字符串。- 如果使用整数作为用户 ID,需为 32 位无符号整数。建议设置范围:0 到 (232-1)。
- 如果使用字符串作为用户 ID,长度不超过 255 个字符。
- 使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通,请确保 Native SDK 使用 User Account 加入频道。详见使用 String 型的用户名。
Promise 对象,包含本地用户的 ID。如果使用字符串作为用户 ID 加入频道,则返回对应的整型 uid。异步操作完成说明加入成功。
离开频道。
离开频道即挂断或退出通话。
调用该方法离开频道时,本地会触发 AgoraRTCClient.on("connection-state-change") 回调。
通信场景下的用户和直播场景下的主播离开频道后,远端会触发 AgoraRTCClient.on("user-left") 回调。
发布本地音视频轨道。
该方法将本地音视频轨道发布至频道中。
发布音视频轨道之后,远端会触发 AgoraRTCClient.on("user-published") 回调。
注意事项:
- 直播场景里,调用 setClientRole 将用户角色设为主播后才能调用该方法。
- 你可以多次调用该方法添加要发布的轨道。
- 一个
AgoraRTCClient
对象可以发布多个音频轨道,SDK 会自动混音,将多个音频轨道合并为一个音频轨道。Safari 12 之前的版本不支持发布多个音频轨道。- 一个
AgoraRTCClient
对象只能发布一个视频轨道。如果你想要更换视频轨道,例如已经发布了一个摄像头视频轨道,想要切换为屏幕共享视频轨道,你必须先取消发布。
通过 AgoraRTC.createMicrophoneAudioTrack / AgoraRTC.createCameraTrack 或其他方法创建的本地 Track 对象。
订阅远端用户的音视频轨道。
await client.subscribe(user,"audio");
user.audioTrack.play();
远端用户对象。
订阅的轨道媒体类型。
"video"
: 订阅指定用户发布的视频轨道。“audio”
: 订阅指定用户发布的音频轨道。订阅的异步操作完成后,返回远端轨道对象,该对象也会在 user.audioTrack 和 user.videoTrack 上更新, 之后直接调用 audioTrack.play 或 videoTrack.play 就可以播放了。
如果指定要订阅的音视频轨道不存在会抛出
TRACK_IS_NOT_PUBLISHED
错误。
取消发布本地音视频轨道。
取消发布音视频轨道之后,远端会触发 AgoraRTCClient.on("user-unpublished") 回调。
要取消发布的轨道。如果留空,会将所有发布过的音视频轨道取消发布。
取消订阅远端用户的音视频轨道。
远端用户对象。
取消订阅的轨道媒体类型。
"video"
: 仅取消订阅指定用户的视频轨道。“audio”
: 仅取消订阅指定用户的音频轨道。如果指定的音视频轨道不存在会抛出 TRACK_IS_NOT_SUBSCRIBED
错误。
开始跨频道媒体流转发。
调用该方法后,SDK 会触发以下回调:
state
为 3,code
为错误码。你可以尝试再次调用本方法。code
为 4.注意事项:
- 跨频道媒体流转发功能需要联系 sales@agora.io 开通。
- 该功能不支持 String 型 UID。
- 请在成功加入频道后调用该方法。
- 直播场景下,只有主播可以调用该方法。
- 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
client.startChannelMediaRelay(config).then(() => {
console.log("startChannelMediaRelay success");
}).catch(e => {
console.log("startChannelMediaRelay failed", e);
})
跨频道媒体流转发参数配置,详见 ChannelMediaRelayConfiguration。
Promise 对象。当 Promise resolve 后,表示成功开启了跨频道服务。
停止跨频道媒体流转发。
一旦停止转发,用户会退出所有的目标频道。
Promise 对象。当 Promise resolve 后,表示成功停止了跨频道服务。
更新媒体流转发的目标频道。
成功开始跨频道转发媒体流后,如果你希望添加或删除媒体流转发的目标频道,可以调用该方法。
注意事项:
- 请在 startChannelMediaRelay 后调用该方法,更新媒体流转发的频道。
- 跨频道媒体流转发最多支持 4 个目标频道。
跨频道媒体流转发参数配置,详见 ChannelMediaRelayConfiguration。
Promise 对象。当 Promise resolve 后,表示更新成功,否则更新失败。出错后跨频道媒体流转发状态会被重置,你需要调用 startChannelMediaRelay 重新开始跨频道媒体流转发。
关闭双流模式。
开启双流模式。
该方法为本地流开启双流模式。双流为视频大流和视频小流,其中视频大流指高分辨率、高码率的视频流,视频小流指低分辨率、低码率的视频流。
注意事项:
- Safari 浏览器不支持本方法。
- 移动端不支持大小流。
client.enableDualStream().then(() => {
console.log("Enable Dual stream success!");
}).catch(err => {
console.log(err);
})
设置小流视频属性。
如果你调用 enableDualStream 开启了双流模式,该方法设置小流的视频属性。
如果你不设置小流的视频属性,SDK 会根据你的视频流属性自动适配小流的视频属性。
注意事项:
- Firefox 浏览器上设置帧率不生效,浏览器会把帧率固定在 30 fps。
- 请在 publish 之前调用此方法。
- 由于设备和浏览器的限制,部分浏览器设置视频分辨率可能不会生效,这种情况下浏览器会自动调整分辨率,计费也将按照实际分辨率计算。
小流的视频属性。
设置订阅远端用户视频的类型(大小流)。
如果发送端开启了双流模式,该方法可以在接收端选择订阅大流还是小流。如果不设置,默认订阅大流。
该方法只可在发送端通过 enableDualStream 开启双流模式的情况下使用。
远端用户的 ID。
订阅的视频流类型,0 代表大流,1 代表小流,详见 RemoteStreamType。
设置远端用户音视频流回退策略。
该方法用于设置在弱网情况下订阅音视频流的回退策略。网络不理想的情况下,为保证通话质量,可以选择自动订阅视频小流(低分辨率、低码率视频流)或者仅订阅音频流。
开启自动回退之后,当订阅流从视频大流回退为视频小流或从视频小流恢复为视频大流时,本地会触发 AgoraRTCClient.on("stream-type-changed") 回调。当订阅流回退为音频流或从音频流恢复为音视频流时,本地会触发 AgoraRTCClient.on("stream-fallback") 回调。
该方法仅在发送端开启双流模式后生效。
远端用户的 UID
回退策略选项,详见 RemoteStreamFallbackType。
注意事项:客户端输入在线媒体流功能即将停服。如果你尚未集成该功能,Agora 建议你不要使用。详见《部分服务下架计划》。
输入在线媒体流。
该方法通过在服务端拉取视频流并发送到频道中,将正在播出的视频输入到正在进行的直播中。 可主要应用于赛事直播、多人看视频互动等直播场景。详见输入在线媒体流。
成功输入媒体流后,该流会出现在频道中,频道内所有用户都会收到 AgoraRTCClient.on("user-published") 和 AgoraRTCClient.on("user-joined") 回调,
其中 uid
为 666。
输入媒体流的状态会通过 AgoraRTCClient.on("stream-inject-status") 通知。
添加到直播中的视频流 HTTP/HTTPS 地址,ASCII 字符,字符串长度不得超过 1024 字节。支持 RTMP,HLS,HTTP-FLV 协议传输。
输入的在线媒体流的设置,详见 InjectStreamConfig。
注意事项:客户端输入在线媒体流功能即将停服。如果你尚未集成该功能,Agora 建议你不要使用。详见《部分服务下架计划》。
删除输入的在线媒体流。
该方法从直播中删除通过 addInjectStreamUrl 输入的在线媒体流。
删除后频道內所有用户都会收到 AgoraRTCClient.on("user-left") 和 AgoraRTCClient.on("user-unpublished") 回调。
直播转码的设置,详见 LiveStreamingTranscodingConfig。
将本地流发布到 CDN。
详见推流到 CDN。
注意事项:
- 该方法每次只能增加一路旁路推流地址。
- 移动端不支持推流到 CDN 功能。
await client.setLiveTranscoding(config);
await client.startLiveStreaming("rtmp://xxxx", true);
直播推流的地址,ASCII 字符。支持 RTMP 协议。
(可选) 是否启用直播转码。转码是指在旁路推流时对音视频流进行转码处理后,再推送到其他 RTMP 服务器,适用于频道内有多个主播,需要进行混流、合图的场景。如果设为 true
,需要在调用该方法前先调用 setLiveTranscoding。
true
: 启用转码,需要在调用该方法前先调用 setLiveTranscoding。false
: (默认)不启用转码,这种情况下需要保证当前用户正在发布。删除旁路推流地址。
该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
待删除的推流地址。
启用说话者音量提示。
该方法允许 SDK 定期报告正在说话的远端用户及其音量。
启用音量提示后,无论频道中有没有人说话,SDK 都会每两秒触发 AgoraRTCClient.on("volume-indicator") 回调。
client.enableAudioVolumeIndicator();
client.on("volume-indicator", volumes => {
volumes.forEach((volume, index) => {
console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
});
})
指定一个事件名,获取当前所有监听这个事件的回调函数。
事件名称。
自从
4.1.0
获取本地音频相关信息。
获取本地视频相关信息。
注意事项:iOS 上无法获取到
encodeDelay
字段。
获取当前通话的统计信息。
通话相关的统计信息。
自从
4.1.0
获取远端用户的音频相关信息。
自从
4.2.0
获取本地订阅的所有远端用户的上下行网络质量。
自从
4.1.0
获取远端用户的视频相关信息。
取消一个指定事件的监听。
指定事件的名称。
监听事件时传入的回调函数。
监听一个指定的事件,当事件触发时会调用传入的回调函数。
当监听后事件第一次触发时,该监听和回调函数就会被立刻移除,也就是只监听一次指定事件。
指定事件的名称。
传入的回调函数。
指定一个事件,取消其所有的监听。
指定事件的名称,如果没有指定事件,则取消所有事件的所有监听。
更新 token。
如果启用了 token 机制,过一段时间后 token 会失效。当收到 AgoraRTCClient.on("token-privilege-will-expire") 回调时, 调用该方法传入新的 token,否则 SDK 会无法和服务器建立连接。
新的 token。
自定义事件上报,用于将自定义的数据格式上报到 Agora 的数据中心。
- 目前支持 5s 内最多上报 20 条事件。
设置直播场景中(mode 设为 "live"
)的用户角色。
用户角色 (role) 确定用户在 SDK 层的权限,包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。用户角色有 "host"
(主播)和 `"audience"(观众)。主播既可发布轨道,也可订阅轨道;观众不能进行 publish 操作。直播场景中的用户角色默认为观众。如需发布音视频,必须先调用本方法切换角色为主播。
注意事项:
- 通信场景(mode 设为
"rtc"
)无法使用本方法,默认所有用户都是"host"
角色。- 如果在加入频道后调用该方法切换用户角色,远端会触发 AgoraRTCClient.on("user-joined") 或者 AgoraRTCClient.on("user-left") 回调。
- 如果已经调用了 publish,想要将用户角色切换为
"audience"
时,必须先调用 unpublish 取消发布后再调用本方法,否则会设置失败并抛出异常。
用户角色。
设置加密方案。
该方法用于设置 SDK 内置的加密算法和密钥,开启内置加密功能。
如果该方法设置错误,在发布或者订阅时会触发 AgoraRTCClient.on("crypt-error") 回调。
注意事项:
- 同一频道内的所有用户必须设置相同的加密算法和密钥才能进行通话。
- 该方法必须在加入频道前调用,否则加密不生效。
- 请勿在 CDN 推流场景中使用内置加密功能。
加密模式。
加密密钥。ASCII 字符。当用户设置的密码为弱密码时,SDK 会在控制台打印警告信息,提醒用户设置强密码,即密码必须满足以下要求:
云代理模式。
关闭云代理服务。
该方法必须在加入频道前或离开频道后调用。
提供音视频通话的核心功能,比如加入频道、发布和订阅音视频轨道等。
你可以通过 createClient 创建一个
AgoraRTCClient
对象。一个AgoraRTCClient
对象代表一个本地客户端。