IAgoraRtcChannelEventHandler - 极速直播 (Legacy) - 文档中心

OnActiveSpeaker

监测到最活跃用户回调。

public virtual void OnActiveSpeaker(string channelId, uint uid)

成功调用 EnableAudioVolumeIndication 后，SDK 会持续监测音量最大的远端用户，并统计该用户被判断为音量最大者的次数。当前时间段内，该次数累积最多的远端用户为最活跃的用户。

当频道内用户数量大于或等于 2 且有活跃用户时，SDK 会触发该回调并报告最活跃用户的 uid。

如果最活跃用户一直是同一位用户，则 SDK 不会再次触发 OnActiveSpeaker 回调。
如果最活跃用户有变化，则 SDK 会再次触发该回调并报告新的最活跃用户的 uid。

参数

channelId: 频道 ID。
uid: 远端最活跃用户的 ID。

OnAudioPublishStateChanged

音频发布状态改变回调。

public virtual void OnAudioPublishStateChanged(string channelId, STREAM_PUBLISH_STATE oldState,
            STREAM_PUBLISH_STATE newState, int elapseSinceLastState)

参数

channelId: 频道 ID。
oldState: 之前的发布状态，详见 STREAM_PUBLISH_STATE。
newState: 当前的发布状态，详见 STREAM_PUBLISH_STATE。
elapseSinceLastState: 两次状态变化时间间隔（毫秒）。

OnAudioSubscribeStateChanged

音频订阅状态发生改变回调。

public virtual void OnAudioSubscribeStateChanged(string channelId, uint uid, STREAM_SUBSCRIBE_STATE oldState,
            STREAM_SUBSCRIBE_STATE newState, int elapseSinceLastState)

参数

channelId: 频道 ID。
uid: 远端用户的 ID。
oldState: 之前的订阅状态，详见 STREAM_SUBSCRIBE_STATE。
newState: 当前的订阅状态，详见 STREAM_SUBSCRIBE_STATE。
elapseSinceLastState: 两次状态变化时间间隔（毫秒）。

OnChannelError

报告 IAgoraRtcChannel 的错误码。

public virtual void OnChannelError(string channelId, int err, string msg)

参数

channelId: 频道 ID。
err: 错误码，详见错误码和警告码。
msg: 错误信息

OnChannelMediaRelayEvent

跨频道媒体流转发事件回调。

public virtual void OnChannelMediaRelayEvent(string channelId, CHANNEL_MEDIA_RELAY_EVENT code)

参数

channelId: 频道 ID。
code: 跨频道媒体流转发事件码。详见 CHANNEL_MEDIA_RELAY_EVENT。

OnChannelMediaRelayStateChanged

跨频道媒体流转发状态发生改变回调。

public virtual void OnChannelMediaRelayStateChanged(string channelId, CHANNEL_MEDIA_RELAY_STATE state,
            CHANNEL_MEDIA_RELAY_ERROR code)

当跨频道媒体流转发状态发生改变时，SDK 会触发该回调，并报告当前的转发状态以及相关的错误信息。

参数

channelId: 频道 ID。
state: 跨频道媒体流转发状态。详见 CHANNEL_MEDIA_RELAY_STATE。
code: 跨频道媒体流转发出错的错误码。详见 CHANNEL_MEDIA_RELAY_ERROR。

OnChannelWarning

报告 IAgoraRtcChannel 的警告码。

public virtual void OnChannelWarning(string channelId, int warn, string msg)

参数

channelId: 频道 ID。
warn: 警告码，详见错误码和警告码。
msg: 警告信息

OnClientRoleChanged

直播场景下用户角色切换成功回调。

public virtual void OnClientRoleChanged(string channelId, CLIENT_ROLE_TYPE oldRole, CLIENT_ROLE_TYPE newRole)

直播场景下，本地用户加入频道后调用 SetClientRole [2/2] 成功改变用户角色时，例如主播切换为观众，或观众切换为主播，SDK 会触发该回调，报告切换前和切换后的角色。

参数

channelId: 频道 ID。
oldRole: 切换前的角色：CLIENT_ROLE_TYPE。
newRole: 切换后的角色：CLIENT_ROLE_TYPE。

OnConnectionLost

网络连接中断，且 SDK 无法在 10 秒内连接服务器回调。

public virtual void OnConnectionLost(string channelId)

SDK 在调用 JoinChannel 后无论是否加入成功，只要 10 秒和服务器无法连接就会触发该回调。

参数

channelId: 频道 ID。

OnConnectionStateChanged

网络连接状态已改变回调。

public virtual void OnConnectionStateChanged(string channelId, CONNECTION_STATE_TYPE state,
            CONNECTION_CHANGED_REASON_TYPE reason)

该回调在网络连接状态发生改变的时候触发，并告知用户当前的网络连接状态和引起网络状态改变的原因。

参数

channelId: 频道 ID。
state: 当前网络连接状态。详见 CONNECTION_STATE_TYPE。
reason: 引起当前网络连接状态改变的原因。详见 CONNECTION_CHANGED_REASON_TYPE。

OnJoinChannelSuccess

成功加入频道回调。

public virtual void OnJoinChannelSuccess(string channelId, uint uid, int elapsed)

该回调方法表示该客户端成功加入了指定的频道。

参数

channelId: 频道 ID。
uid: 用户 ID。如果 JoinChannel 中指定了用户 ID，则此处返回该 ID；否则使用声网服务器自动分配的 ID。
elapsed: 从 JoinChannel 开始到发生此事件过去的时间（毫秒）。

OnMetadataReceived

接收端已收到 Metadata。

public virtual void OnMetadataReceived(Metadata metadata)

参数

metadata: 接收到的媒体附属信息。详见 Metadata。

OnLeaveChannel

离开频道回调。

public virtual void OnLeaveChannel(string channelId, RtcStats stats)

调用 LeaveChannel 方法离开频道后，SDK 会出发该回调提示 app 用户已成功离开频道。在该回调中，app 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。

参数

channelId: 频道 ID。
stats: 通话的统计数据: RtcStats。

OnLocalPublishFallbackToAudioOnly

本地发布流已回退为音频流回调。

public virtual void OnLocalPublishFallbackToAudioOnly(string channelId, bool isFallbackOrRecover)

如果你调用了 SetLocalPublishFallbackOption 接口并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY ，当上行网络环境不理想、本地发布的媒体流回退为音频流时，或当上行网络改善、媒体流恢复为音视频流时，会触发该回调。

注意：如果本地发流已回退为音频流，远端的 App 上会收到 OnUserMuteVideo 的回调事件。

参数

channelId

频道 ID。

isFallbackOrRecover

true: 由于网络环境不理想，本地发布的媒体流已回退为音频流。
false: 由于网络环境改善，发布的音频流已恢复为音视频流。

OnNetworkQuality

通话中每个用户的网络上下行 last mile 质量报告回调。

public virtual void OnNetworkQuality(string channelId, uint uid, int txQuality, int rxQuality)

该回调描述每个用户在通话中的 last mile 网络状态，其中 last mile 是指设备到声网边缘服务器的网络状态。

该回调每 2 秒触发一次。如果远端有多个用户，该回调每 2 秒会被触发多次。

参数

channelId

频道 ID。

uid

用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。

当 uid 为 0 时，返回的是本地用户的网络质量。

txQuality

该用户的上行网络质量，基于发送码率、上行丢包率、平均往返时延和网络抖动计算。该值代表当前的上行网络质量，帮助判断是否可以支持当前设置的视频编码属性。假设上行码率是 1000 Kbps，那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题，但是支持 1280 × 720 的分辨率就会有困难。详见 QUALITY_TYPE。

rxQuality

该用户的下行网络质量，基于下行网络的丢包率、平均往返延时和网络抖动计算。详见 QUALITY_TYPE。

OnProxyConnected

代理连接状态回调。

public virtual void OnProxyConnected(string channelId, uint uid, PROXY_TYPE proxyType, string localProxyIp, int elapsed)

通过该回调你可以监听 SDK 连接代理的状态。例如，当用户调用 SetCloudProxy 设置代理并成功加入频道后， SDK 会触发该回调报告用户 ID、连接的代理类型和从调用 JoinChannel 到触发该回调经过的时间等。

参数

channelId: 频道 ID。
uid: 用户 ID
proxyType: 连接上的代理类型。详见 CLOUD_PROXY_TYPE
localProxyIp: 本地代理的 IP 地址。当 proxyType 的值不为 3 时，该参数的值为空。
elapsed: 从调用 JoinChannel [1/2] 到 SDK 触发该回调的经过的时间（毫秒）。

OnReadyToSendMetadata

发送端已准备好发送 Metadata。

public virtual bool OnReadyToSendMetadata(Metadata metadata)
        {
            return true;
        }

当 SDK 准备好发送 Metadata 时，会触发该回调。收到该回调后，你可以调用 SendMetadata 发送媒体附属信息。

参数

metadata: 媒体附属信息。详见 Metadata。

OnRejoinChannelSuccess

成功重新加入频道回调。

public virtual void OnRejoinChannelSuccess(string channelId, uint uid, int elapsed)

有时候由于网络原因，客户端可能会和服务器失去连接，SDK 会进行自动重连，自动重连成功后触发此回调方法。

参数

channelId: 频道 ID。
uid: 重新加入频道的用户 ID。
elapsed: 从本地开始重连到发生此事件过去的时间（毫秒）。

OnRemoteAudioStateChanged

远端音频流状态发生改变回调。

public virtual void OnRemoteAudioStateChanged(string channelId, uint uid, REMOTE_AUDIO_STATE state,
            REMOTE_AUDIO_STATE_REASON reason, int elapsed)

远端用户（通信场景）或主播（直播场景）的音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。

注意：频道内的用户（通信场景）或主播（直播场景）人数超过 17 人时，该回调可能不准确。

参数

channelId: 频道 ID。
uid: 发生音频状态改变的远端用户 ID。
state: 远端音频流状态，详见 REMOTE_AUDIO_STATE。
reason: 远端音频流状态改变的具体原因，详见 REMOTE_AUDIO_STATE_REASON。
elapsed: 从本地用户调用 JoinChannel 方法到发生本事件经历的时间，单位为 ms。

OnRemoteAudioStats

通话中远端音频流的统计信息回调。

public virtual void OnRemoteAudioStats(string channelId, RemoteAudioStats stats)

该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流，该回调每 2 秒会被触发多次。

参数

channelId: 频道 ID。
stats: 接收到的远端音频统计数据，详见 RemoteAudioStats。

OnRemoteSubscribeFallbackToAudioOnly

远端订阅流已回退为音频流回调。

public virtual void OnRemoteSubscribeFallbackToAudioOnly(string channelId, uint uid, bool isFallbackOrRecover)

如果你调用了 SetRemoteSubscribeFallbackOption 并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY，当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。

注意：远端订阅流因弱网环境不能同时满足音视频而回退为小流时，你可以使用 OnRemoteVideoStats 来监控远端视频大小流的切换。

参数

channelId

频道 ID。

uid

远端用户的用户 ID。

isFallbackOrRecover

true: 由于网络环境不理想，远端订阅流已回退为音频流；
false: 由于网络环境改善，订阅的音频流已恢复为音视频流。

OnRemoteVideoStateChanged

远端视频状态发生改变回调。

public virtual void OnRemoteVideoStateChanged(string channelId, uint uid, REMOTE_VIDEO_STATE state,
            REMOTE_VIDEO_STATE_REASON reason, int elapsed)

注意：频道内的用户（通信场景）或主播（直播场景）人数超过 17 人时，该回调可能不准确。

参数

channelId: 频道 ID。
uid: 发生视频状态改变的远端用户 ID。
state: 远端视频流状态，详见 REMOTE_VIDEO_STATE。
reason: 远端视频流状态改变的具体原因，详见 REMOTE_VIDEO_STATE_REASON。
elapsed: 从本地用户调用 JoinChannel 方法到发生本事件经历的时间，单位为 ms。

OnRemoteVideoStats

通话中远端视频流的统计信息回调。

public virtual void OnRemoteVideoStats(string channelId, RemoteVideoStats stats)

该回调描述远端用户在通话中端到端的视频流统计信息，针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播，该回调每 2 秒会被触发多次。

参数

channelId: 频道 ID。
stats: 远端视频统计数据。详见 RemoteVideoStats。

OnRequestToken

Token 已过期回调。

public virtual void OnRequestToken(string channelId)

在通话过程中如果 Token 已失效，SDK 会触发该回调，提醒 app 更新 Token。

当收到该回调时，你需要重新在服务端生成新的 Token，然后调用 JoinChannel 重新加入频道。

参数

channelId: 频道 ID。

OnRtcStats

当前通话统计信息回调。

public virtual void OnRtcStats(string channelId, RtcStats stats)

SDK 定期向 App 报告当前通话的统计信息，每两秒触发一次。

参数

channelId: 频道 ID。
stats: RTC 引擎统计数据，详见 RtcStats 。

OnRtmpStreamingEvent

旁路推流事件回调。

public virtual void OnRtmpStreamingEvent(string channelId, string url, RTMP_STREAMING_EVENT eventCode)

参数

channelId: 频道 ID。
url: 旁路推流 URL。
eventCode: 旁路推流事件码。详见 RTMP_STREAMING_EVENT。

OnRtmpStreamingStateChanged

旁路推流状态发生改变回调。

public virtual void OnRtmpStreamingStateChanged(string channelId, string url, RTMP_STREAM_PUBLISH_STATE state,
            RTMP_STREAM_PUBLISH_ERROR errCode)

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_TYPE。

OnStreamMessage

接收到对方数据流消息的回调。

public virtual void OnStreamMessage(string channelId, uint uid, int streamId, byte[] data, uint length)

该回调表示本地用户收到了远端用户调用 SendStreamMessage 方法发送的流消息。

参数

channelId: 频道 ID。
uid: 发送消息的用户 ID。
streamId: 接收到的消息的 Stream ID。
data: 接收到的数据。
length: 数据长度，单位为字节。

OnStreamMessageError

接收对方数据流消息发生错误的回调。

public virtual void OnStreamMessageError(string channelId, uint uid, int streamId, int code, int missed,
            int cached)

该回调表示本地用户未收到远端用户调用 SendStreamMessage 方法发送的流消息。

参数

channelId: 频道 ID。
uid: 发送消息的用户 ID。
streamId: 接收到的消息的 Stream ID。
code: 发生错误的错误码。
missed: 丢失的消息数量。
cached: 数据流中断时，后面缓存的消息数量。

OnTokenPrivilegeWillExpire

Token 服务将在30s内过期回调。

public virtual void OnTokenPrivilegeWillExpire(string channelId, string token)

在通话过程中如果 Token 即将失效，SDK 会提前 30 秒触发该回调，提醒 app 更新 Token。当收到该回调时，你需要重新在服务端生成新的 Token，然后调用 RenewToken 将新生成的 Token 传给 SDK。

参数

channelId: 频道 ID。
token: 即将服务失效的 Token。

OnTranscodingUpdated

旁路推流转码设置已被更新回调。

public virtual void OnTranscodingUpdated(string channelId)

SetLiveTranscoding 方法中的直播参数 LiveTranscoding 更新时，OnTranscodingUpdated 回调会被触发并向主播报告更新信息。

注意：首次调用 SetLiveTranscoding 方法设置转码参数 LiveTranscoding 时，不会触发此回调。

OnUserJoined

远端用户（通信场景）/主播（直播场景）加入当前频道回调。

public virtual void OnUserJoined(string channelId, uint uid, int elapsed)

通信场景下，该回调提示有远端用户加入了频道。如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
直播场景下，该回调提示有主播加入了频道。如果加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。声网建议连麦主播不超过 17 人。

该回调在如下情况下会被触发：

远端用户/主播调用 JoinChannel 方法加入频道
远端用户加入频道后将用户角色改变为主播
远端用户/主播网络中断后重新加入频道

参数

channelId: 频道 ID。
uid: 新加入频道的远端用户/主播 ID。
elapsed: 从本地用户调用 JoinChannel 到该回调触发的延迟（毫秒)。

OnUserOffline

远端用户（通信场景）/主播（直播场景）离开当前频道回调。

public virtual void OnUserOffline(string channelId, uint uid, USER_OFFLINE_REASON_TYPE reason)

用户离开频道有两个原因：

正常离开：远端用户/主播会发送类似“再见”的消息。接收此消息后，判断用户离开频道。
超时掉线：在一定时间内（通信场景为 20 秒，直播场景稍有延时），用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。我们建议使用声网云信令 SDK 来做可靠的掉线检测。

参数

channelId: 频道 ID。
uid: 离线用户或主播的用户 ID。
reason: 离线原因: USER_OFFLINE_REASON_TYPE。

OnVideoPublishStateChanged

视频发布状态改变回调。

public virtual void OnVideoPublishStateChanged(string channelId, STREAM_PUBLISH_STATE oldState,
            STREAM_PUBLISH_STATE newState, int elapseSinceLastState)

参数

channelId: 频道 ID。
oldState: 之前的发布状态，详见 STREAM_PUBLISH_STATE。
newState: 当前的发布状态，详见 STREAM_PUBLISH_STATE。
elapseSinceLastState: 两次状态变化时间间隔（毫秒）。

OnVideoSizeChanged

本地或远端视频大小和旋转信息发生改变回调。

public virtual void OnVideoSizeChanged(string channelId, uint uid, int width, int height, int rotation)

参数

channelId: 频道 ID。
uid: 图像尺寸和旋转信息发生变化的用户的用户 ID（本地用户的 uid 为 0）。
width: 视频流的宽度（像素）。
height: 视频流的高度（像素）。
rotation: 旋转信息，取值范围 [0,360)。

OnVideoSubscribeStateChanged

视频订阅状态发生改变回调。

public virtual void OnVideoSubscribeStateChanged(string channelId, uint uid, STREAM_SUBSCRIBE_STATE oldState,
            STREAM_SUBSCRIBE_STATE newState, int elapseSinceLastState)

参数

channelId: 频道 ID。
uid: 远端用户的 ID。
oldState: 之前的订阅状态，详见 STREAM_SUBSCRIBE_STATE。
newState: 当前的订阅状态，详见 STREAM_SUBSCRIBE_STATE。
elapseSinceLastState: 两次状态变化时间间隔（毫秒）。