AgoraRtcChannel 回调
AgoraRtcChannel.on 监听和报告指定频道的事件和数据。
ACTIVE_SPEAKER
监测到最活跃用户回调。
on( evt: ChannelEvents.ACTIVE_SPEAKER, cb: (channelId: string, uid: number) => void ): this;
成功调用 enableAudioVolumeIndication 后,SDK 会持续监测音量最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。
- 如果最活跃用户一直是同一位用户,则 SDK 不会再次触发 ACTIVE_SPEAKER 回调。
- 如果最活跃用户有变化,则 SDK 会再次触发该回调并报告新的最活跃用户的 uid。
参数
- channelId
- 频道 ID。
- uid
- 远端最活跃用户的 ID。
AUDIO_PUBLISH_STATE_CHANGED
音频发布状态改变回调。
on( evt: ChannelEvents.AUDIO_PUBLISH_STATE_CHANGED, cb: ( channelId: string, oldState: STREAM_PUBLISH_STATE, newState: STREAM_PUBLISH_STATE, elapseSinceLastState: number ) => void ): this;
- 自从
- v3.1.0
参数
- channelId
- 频道 ID。
- oldState
- 之前的发布状态,详见 STREAM_PUBLISH_STATE。
- newState
- 当前的发布状态,详见 STREAM_PUBLISH_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
AUDIO_SUBSCRIBE_STATE_CHANGED
音频订阅状态发生改变回调。
on( evt: ChannelEvents.AUDIO_SUBSCRIBE_STATE_CHANGED, cb: ( channelId: string, uid: number, oldState: STREAM_SUBSCRIBE_STATE, newState: STREAM_SUBSCRIBE_STATE, elapseSinceLastState: number ) => void ): this;
- 自从
- v3.1.0
参数
- channelId
- 频道 ID。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态,详见 STREAM_SUBSCRIBE_STATE。
- newState
- 当前的订阅状态,详见 STREAM_SUBSCRIBE_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
CHANNEL_ERROR
报告 AgoraRtcChannel 的错误码。
on( evt: ChannelEvents.CHANNEL_ERROR, cb: (channelId: string, err: number, msg: string) => void ): this;
参数
- channelId
- 频道 ID。
- err
- 错误码,详见错误码和警告码。
- msg
- 错误信息
CHANNEL_MEDIA_RELAY_EVENT
跨频道媒体流转发事件回调。
on( evt: ChannelEvents.CHANNEL_MEDIA_RELAY_EVENT, cb: (channelId: string, code: CHANNEL_MEDIA_RELAY_EVENT) => void ): this;
参数
- channelId
- 频道 ID。
- code
- 跨频道媒体流转发事件码。详见 CHANNEL_MEDIA_RELAY_EVENT 。
CHANNEL_MEDIA_RELAY_STATE_CHANGED
跨频道媒体流转发状态发生改变回调。
on( evt: ChannelEvents.CHANNEL_MEDIA_RELAY_STATE_CHANGED, cb: ( channelId: string, state: CHANNEL_MEDIA_RELAY_STATE, code: CHANNEL_MEDIA_RELAY_ERROR ) => void ): this;
当跨频道媒体流转发状态发生改变时,SDK 会触发该回调,并报告当前的转发状态以及相关的错误信息。
参数
- channelId
- 频道 ID。
- state
- 跨频道媒体流转发状态。详见 CHANNEL_MEDIA_RELAY_STATE 。
- code
- 跨频道媒体流转发出错的错误码。详见 CHANNEL_MEDIA_RELAY_ERROR 。
CHANNEL_WARNING
报告 AgoraRtcChannel 的警告码。
on( evt: ChannelEvents.CHANNEL_WARNING, cb: (channelId: string, warn: number, msg: string) => void ): this;
参数
- channelId
- 频道 ID。
- warn
- 警告码,详见错误码和警告码。
- msg
- 警告信息
CLIENT_ROLE_CHANGED
直播场景下用户角色已切换回调。
on( evt: ChannelEvents.CLIENT_ROLE_CHANGED, cb: ( channelId: string, oldRole: CLIENT_ROLE_TYPE, newRole: CLIENT_ROLE_TYPE ) => void ): this;
该回调由本地用户在加入频道后调用 setClientRole 改变用户角色触发的。
参数
- channelId
- 频道 ID。
- oldRole
- 切换前的角色: CLIENT_ROLE_TYPE。
- newRole
- 切换后的角色: CLIENT_ROLE_TYPE。
CONNECTION_LOST
网络连接中断,且 SDK 无法在 10 秒内连接服务器回调。
on(evt: ChannelEvents.CONNECTION_LOST, cb: (channelId: string) => void): this;
SDK 在调用 joinChannel 后无论是否加入成功,只要 10 秒和服务器无法连接就会触发该回调。
参数
- channelId
- 频道 ID。
CONNECTION_STATE_CHANGED
网络连接状态已改变回调。
on( evt: ChannelEvents.CONNECTION_STATE_CHANGED, cb: ( channelId: string, state: CONNECTION_STATE_TYPE, reason: CONNECTION_CHANGED_REASON_TYPE ) => void ): this;
该回调在网络连接状态发生改变的时候触发,并告知用户当前的网络连接状态和引起网络状态改变的原因。
参数
- channelId
- 频道 ID。
- state
- 当前网络连接状态。详见 CONNECTION_STATE_TYPE。
- reason
- 引起当前网络连接状态改变的原因。详见 CONNECTION_CHANGED_REASON_TYPE。
JOIN_CHANNEL_SUCCESS
成功加入频道回调。
on( evt: ChannelEvents.JOIN_CHANNEL_SUCCESS, cb: (channelId: string, uid: number, elapsed: number) => void ): this;
该回调方法表示该客户端成功加入了指定的频道。
参数
- channelId
- 频道 ID。
- uid
- 用户 ID。如果 joinChannel 中指定了用户 ID,则此处返回该 ID;否则使用 Agora 服务器自动分配的 ID。
- elapsed
- 从 joinChannel 开始到发生此事件过去的时间(毫秒)。
LEAVE_CHANNEL
离开频道回调。
on( evt: ChannelEvents.LEAVE_CHANNEL, cb: (channelId: string, stats: RtcStats) => void ): this;
调用 leaveChannel 方法离开频道后,SDK 会出发该回调提示 app 用户已成功离开频道。在该回调中,app 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。
参数
- channelId
- 频道 ID。
- stats
- 通话的统计数据: RtcStats。
METADATA_RECEIVED
NETWORK_QUALITY
通话中每个用户的网络上下行 last mile 质量报告回调。
on( evt: ChannelEvents.NETWORK_QUALITY, cb: ( channelId: string, uid: number, txquality: QUALITY_TYPE, rxquality: QUALITY_TYPE ) => void ): this;
该回调描述每个用户在通话中的 last mile 网络状态,其中 last mile 是指设备到 Agora 边缘服务器的网络状态。
该回调每 2 秒触发一次。如果远端有多个用户,该回调每 2 秒会被触发多次。
参数
- channelId
- 频道 ID。
- uid
- 用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。当 uid 为 0 时,返回的是本地用户的网络质量。
- txQuality
- 该用户的上行网络质量,基于发送码率、上行丢包率、平均往返时延和网络抖动计算。该值代表当前的上行网络质量,帮助判断是否可以支持当前设置的视频编码属性。假设上行码率是 1000 Kbps,那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题,但是支持 1280 × 720 的分辨率就会有困难。详见 QUALITY_TYPE。
- rxQuality
- 该用户的下行网络质量,基于下行网络的丢包率、平均往返延时和网络抖动计算。详见 QUALITY_TYPE。
READY_TO_SEND_METADATA
发送端已准备好发送 Metadata。
on( evt: ChannelEvents.READY_TO_SEND_METADATA, cb: (metadata: Metadata) => void ): this;
当 SDK 准备好发送 Metadata 时,会触发该回调。收到该回调后,你可以调用 sendMetadata 发送媒体附属信息。
参数
- metadata
- 媒体附属信息。详见 Metadata。
REJOIN_CHANNEL_SUCCESS
成功重新加入频道回调。
on( evt: ChannelEvents.REJOIN_CHANNEL_SUCCESS, cb: (channelId: string, uid: number, elapsed: number) => void ): this;
有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。
参数
- channelId
- 频道 ID。
- uid
- 重新加入频道的用户 ID。
- elapsed
- 从本地开始重连到发生此事件过去的时间(毫秒)。
REMOTE_AUDIO_STATE_CHANGED
远端音频流状态发生改变回调。
on( evt: ChannelEvents.REMOTE_AUDIO_STATE_CHANGED, cb: ( channelId: string, uid: number, state: REMOTE_AUDIO_STATE, reason: REMOTE_AUDIO_STATE_REASON, elapsed: number ) => void ): this;
- 自从
- v2.9.0
远端用户(通信场景)或主播(直播场景)的音频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端音频流状态。
参数
- channelId
- 频道 ID。
- uid
- 发生音频状态改变的远端用户 ID。
- state
- 远端音频流状态,详见 REMOTE_AUDIO_STATE。
- reason
- 远端音频流状态改变的具体原因,详见 REMOTE_AUDIO_STATE_REASON。
- elapsed
- 从本地用户调用 joinChannel 方法到发生本事件经历的时间,单位为 ms。
REMOTE_AUDIO_STATS
通话中远端音频流的统计信息回调。
on( evt: ChannelEvents.REMOTE_AUDIO_STATS, cb: (channelId: string, stats: RemoteAudioStats) => void ): this;
该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流,该回调每 2 秒会被触发多次。
参数
- channelId
- 频道 ID。
- stats
- 接收到的远端音频统计数据,详见 RemoteAudioStats。
REMOTE_SUBSCRIBE_FALLBACK_TO_AUDIO_ONLY
远端订阅流已回退为音频流回调。
on( evt: ChannelEvents.REMOTE_SUBSCRIBE_FALLBACK_TO_AUDIO_ONLY, cb: (channelId: string, uid: number, isFallbackOrRecover: boolean) => void ): this;
如果你调用了 setRemoteSubscribeFallbackOption 接口并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY,当下行网络环境不理想、仅接收远端音频流时,或当下行网络改善、恢复订阅音视频流时,会触发该回调。
参数
- channelId
- 频道 ID。
- uid
- 远端用户的用户 ID。
- isFallbackOrRecover
-
true
: 由于网络环境不理想,远端订阅流已回退为音频流;false
: 由于网络环境改善,订阅的音频流已恢复为音视频流。
REMOTE_VIDEO_STATE_CHANGED
远端视频状态发生改变回调。
on( evt: ChannelEvents.REMOTE_VIDEO_STATE_CHANGED, cb: ( channelId: string, uid: number, state: REMOTE_VIDEO_STATE, reason: REMOTE_VIDEO_STATE_REASON, elapsed: number ) => void ): this;
- 自从
- v2.9.0
参数
- channelId
- 频道 ID。
- uid
- 发生视频状态改变的远端用户 ID。
- state
- 远端视频流状态,详见 REMOTE_VIDEO_STATE。
- reason
- 远端视频流状态改变的具体原因,详见 REMOTE_VIDEO_STATE_REASON。
- elapsed
- 从本地用户调用 joinChannel 方法到发生本事件经历的时间,单位为 ms。
REMOTE_VIDEO_STATS
通话中远端视频流的统计信息回调。
on( evt: ChannelEvents.REMOTE_VIDEO_STATS, cb: (channelId: string, stats: RemoteVideoStats) => void ): this;
该回调描述远端用户在通话中端到端的视频流统计信息, 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播, 该回调每 2 秒会被触发多次。
参数
- channelId
- 频道 ID。
- stats
- 远端视频统计数据。详见 RemoteVideoStats。
REQUEST_TOKEN
Token 已过期回调。
on(evt: ChannelEvents.REQUEST_TOKEN, cb: (channelId: string) => void): this;
在通话过程中如果 Token 已失效,SDK 会触发该回调,提醒 app 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 joinChannel 重新加入频道。
参数
- channelId
- 频道 ID。
RTC_STATS
当前通话统计信息回调。
on( evt: ChannelEvents.RTC_STATS, cb: (channelId: string, stats: RtcStats) => void ): this;
SDK 定期向 App 报告当前通话的统计信息,每两秒触发一次。
参数
- channelId
- 频道 ID。
- stats
-
RTC 引擎统计数据,详见 RtcStats 。
RTMP_STREAMING_EVENT
RTMP/RTMPS 推流事件回调。
on( evt: ChannelEvents.RTMP_STREAMING_EVENT, cb: ( channelId: string, url: string, eventCode: RTMP_STREAMING_EVENT ) => void ): this;
- 自从
- v3.1.0
参数
- channelId
- 频道 ID。
- url
- RTMP/RTMPS 推流 URL。
- eventCode
- RTMP/RTMPS 推流事件码。详见 RTMP_STREAMING_EVENT。
RTMP_STREAMING_STATE_CHANGED
RTMP/RTMPS 推流状态发生改变回调。
on( evt: ChannelEvents.RTMP_STREAMING_STATE_CHANGED, cb: ( channelId: string, url: string, state: RTMP_STREAM_PUBLISH_STATE, errCode: RTMP_STREAM_PUBLISH_ERROR ) => void ): this;
该回调返回本地用户调用 addPublishStreamUrl 或 removePublishStreamUrl 方法的结果。RTMP/RTMPS 推流状态发生改变时,SDK 会触发该回调,并在回调中明确状态发生改变的 URL 地址及当前推流状态。该回调方便推流用户了解当前的推流状态;推流出错时,你可以通过返回的错误码了解出错的原因,方便排查问题。
参数
- channelId
- 频道 ID。
- url
- 推流状态发生改变的 URL 地址。
- state
- 当前的推流状态,详见 RTMP_STREAM_PUBLISH_STATE 。当推流状态为 RTMP_STREAM_PUBLISH_STATE_FAILURE (4) 时,你可以在 errorCode 参数中查看返回的错误信息。
- errCode
- 推流错误信息,详见 RTMP_STREAM_PUBLISH_ERROR 。
STREAM_INJECTED_STATUS
输入在线媒体流状态回调。
on( evt: ChannelEvents.STREAM_INJECTED_STATUS, cb: ( channelId: string, url: string, uid: number, status: INJECT_STREAM_STATUS ) => void ): this;
参数
- channelId
- 频道 ID。
- url
- 在线媒体流的地址。
- uid
- 用户 ID。
- status
- 输入的在线媒体流状态: INJECT_STREAM_STATUS 。
STREAM_MESSAGE
接收到对方数据流消息的回调。
on( evt: ChannelEvents.STREAM_MESSAGE, cb: (channelId: string, uid: number, streamId: number, data: string) => void ): this;
该回调表示本地用户收到了远端用户调用 sendStreamMessage 方法发送的流消息。
参数
- channelId
- 频道 ID。
- uid
- 发送消息的用户 ID。
- streamId
- 接收到的消息的 Stream ID。
- data
- 接收到的数据。
STREAM_MESSAGE_ERROR
接收对方数据流消息发生错误的回调。
on( evt: ChannelEvents.STREAM_MESSAGE_ERROR, cb: ( channelId: string, uid: number, streamId: number, code: number, missed: number, cached: number ) => void ): this;
该回调表示本地用户未收到远端用户调用 sendStreamMessage 方法发送的流消息。
参数
- channelId
- 频道 ID。
- uid
- 发送消息的用户 ID。
- streamId
- 接收到的消息的 Stream ID。
- code
- 发生错误的错误码。详见错误码和警告码。
- missed
- 丢失的消息数量。
- cached
- 数据流中断时,后面缓存的消息数量。
TOKEN_PRIVILEGE_WILL_EXPIRE
Token 服务将在30s内过期回调。
on( evt: ChannelEvents.TOKEN_PRIVILEGE_WILL_EXPIRE, cb: (channelId: string, token: string) => void ): this;
在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒 app 更新 Token。当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 renewToken 将新生成的 Token 传给 SDK。
参数
- channelId
- 频道 ID。
- token
- 即将服务失效的 Token。
TRANSCODING_UPDATED
旁路推流转码设置已被更新回调。
on( evt: ChannelEvents.TRANSCODING_UPDATED, cb: (channelId: string) => void ): this;
setLiveTranscoding 方法中的直播参数 LiveTranscoding 更新时,TRANSCODING_UPDATED 回调会被触发并向主播报告更新信息。
参数
- channelId
- 频道 ID。
USER_JOINED
远端用户(通信场景)/主播(直播场景)加入当前频道回调。
on( evt: ChannelEvents.USER_JOINED, cb: (channelId: string, uid: number, elapsed: number) => void ): this;
- 通信场景下,该回调提示有远端用户加入了频道。如果加入之前,已经有其他用户在频道中了,新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下,该回调提示有主播加入了频道。如果加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。Agora 建议连麦主播不超过 17 人。
- 远端用户/主播调用 joinChannel 方法加入频道
- 远端用户加入频道后调用 setClientRole 将用户角色改变为主播
- 远端用户/主播网络中断后重新加入频道
- 主播通过调用 addInjectStreamUrl 方法成功输入在线媒体流
参数
- channelId
- 频道 ID。
- uid
- 新加入频道的远端用户/主播 ID。
- elapsed
- 从本地用户调用 joinChannel 到该回调触发的延迟(毫秒)。
USER_OFFLINE
远端用户(通信场景)/主播(直播场景)离开当前频道回调。
on( evt: ChannelEvents.USER_OFFLINE, cb: ( channelId: string, uid: number, reason: USER_OFFLINE_REASON_TYPE ) => void ): this;
- 正常离开:远端用户/主播会发送类似“再见”的消息。接收此消息后,判断用户离开频道。
- 超时掉线:在一定时间内(通信场景为 20 秒,直播场景稍有延时),用户没有收到对方的任何数据包,则判定为对方掉线。在网络较差的情况下,有可能会误报。我们建议使用 Agora 云信令 SDK 来做可靠的掉线检测。
参数
- channelId
- 频道 ID。
- uid
- 离线用户或主播的用户 ID。
- reason
- 离线原因: USER_OFFLINE_REASON_TYPE。
VIDEO_PUBLISH_STATE_CHANGED
视频发布状态改变回调。
on( evt: ChannelEvents.VIDEO_PUBLISH_STATE_CHANGED, cb: ( channelId: string, oldState: STREAM_PUBLISH_STATE, newState: STREAM_PUBLISH_STATE, elapseSinceLastState: number ) => void ): this;
- 自从
- v3.1.0
参数
- channelId
- 频道 ID。
- oldState
- 之前的发布状态,详见 STREAM_PUBLISH_STATE。
- newState
- 当前的发布状态,详见 STREAM_PUBLISH_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
VIDEO_SIZE_CHANGED
本地或远端视频大小和旋转信息发生改变回调。
on( evt: ChannelEvents.VIDEO_SIZE_CHANGED, cb: ( channelId: string, uid: number, width: number, height: number, rotation: number ) => void ): this;
参数
- channelId
- 频道 ID。
- uid
- 图像尺寸和旋转信息发生变化的用户的用户 ID(本地用户的 uid 为 0)。
- width
- 视频流的宽度(像素)。
- height
- 视频流的高度(像素)。
- rotation
- 旋转信息,取值范围 [0,360)。
VIDEO_SUBSCRIBE_STATE_CHANGED
视频订阅状态发生改变回调。
on( evt: ChannelEvents.VIDEO_SUBSCRIBE_STATE_CHANGED, cb: ( channelId: string, uid: number, oldState: STREAM_SUBSCRIBE_STATE, newState: STREAM_SUBSCRIBE_STATE, elapseSinceLastState: number ) => void ): this;
- 自从
- v3.1.0
参数
- channelId
- 频道 ID。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态,详见 STREAM_SUBSCRIBE_STATE。
- newState
- 当前的订阅状态,详见 STREAM_SUBSCRIBE_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。