IRtcEngineEventHandler
IRtcEngineEventHandler 接口类用于 SDK 向 app 发送事件通知,app 通过继承该接口类的方法获取 SDK 的事件通知。
该接口类的所有方法都有缺省(空)实现, app 可以根据需要只继承关心的事件。
- 在回调方法中,app 不应该做耗时或者调用可能会引起阻塞的 API(如
sendMessage
),否则可能影响 SDK 的运行。 - SDK 不再捕获开发者在 IRtcEngineEventHandler 类回调中自行实现的代码逻辑中的异常。你需要自行处理该异常,否则异常出现时可能引起 app 崩溃。
onActiveSpeaker
监测到远端最活跃用户回调。
public void onActiveSpeaker(int uid) {}
成功调用 enableAudioVolumeIndication 后,SDK 会持续监测音量最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。
- 如果远端最活跃用户一直是同一位用户,则 SDK 不会再次触发 onActiveSpeaker 回调。
- 如果远端最活跃用户有变化,则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。
参数
- uid
- 远端最活跃用户的 ID。
onApiCallExecuted
API 方法已执行回调。
public void onApiCallExecuted(int error, String api, String result) {}
参数
- error
- 当方法调用失败时 SDK 返回的错误码。如果该方法调用成功,SDK 会返回 0。
- api
- SDK 执行的 API 方法。
- result
- SDK 调用 API 的结果。
onAudioEffectFinished
本地音效文件播放已结束回调。
public void onAudioEffectFinished(int soundId) {}
当播放音效结束后,会触发该回调。
参数
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。
onAudioMixingFinished
本地音乐文件播放已结束回调。
public void onAudioMixingFinished() {}
- 弃用:
- 请改用 onAudioMixingStateChanged。
当调用 startAudioMixing [2/2] 播放本地音乐文件结束后,会触发该回调。如果调用 startAudioMixing [2/2] 失败,会返回错误码 WARN_AUDIO_MIXING_OPEN_ERROR。
onAudioMixingStateChanged
音乐文件的播放状态已改变回调。
public void onAudioMixingStateChanged(int state, int reasonCode);
该回调在音乐文件播放状态发生改变时触发,并报告当前的播放状态和错误码。
参数
- state
- 音乐文件播放状态。
- AUDIO_MIXING_STATE_PLAYING (710): 音乐文件正常播放。
- AUDIO_MIXING_STATE_PAUSED (711): 音乐文件暂停播放。
- AUDIO_MIXING_STATE_STOPPED (713): 音乐文件停止播放。
- AUDIO_MIXING_STATE_FAILED (714): 音乐文件报错。SDK 会在 errorCode 参数中返回具体的报错原因。
- reasonCode
- 错误码。
- AUDIO_MIXING_REASON_OK(0): 正常。
- AUDIO_MIXING_REASON_CAN_NOT_OPEN (701): 音乐文件打开出错。
- AUDIO_MIXING_REASON_TOO_FREQUENT_CALL (702): 音乐文件打开太频繁。
- AUDIO_MIXING_REASON_INTERRUPTED_EOF (703): 音乐文件播放异常中断。
- AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED(721): 音乐文件完成一次循环播放。
- AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETEDD(723): 音乐文件完成所有循环播放。
- AUDIO_MIXING_REASON_STOPPED_BY_USER(724): 成功调用 pauseAudioMixing 暂停播放音乐文件。
onAudioPublishStateChanged
音频发布状态改变回调。
public void onAudioPublishStateChanged(String channel, STREAM_PUBLISH_STATE oldState, STREAM_PUBLISH_STATE newState, int elapseSinceLastState) {}
参数
- channel
- 频道名。
- oldState
- 之前的发布状态,详见 STREAM_PUBLISH_STATE。
- newState
- 当前的发布状态,详见 STREAM_PUBLISH_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
onAudioQuality
远端声音质量回调。
public void onAudioQuality(int uid, int quality, short delay, short lost) {}
- 弃用:
- 请改用 onRemoteAudioStats。
该回调描述远端用户在通话中的音频质量,针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播,该回调每 2 秒会被触发多次。
参数
- uid
- 用户 ID,指定是谁发的音频流。
- quality
- 语音质量。
- QUALITY_UNKNOWN (0):质量未知。
- QUALITY_EXCELLENT (1):质量极好。
- QUALITY_GOOD (2):用户主观感觉和极好差不多,但码率可能略低于极好。
- QUALITY_POOR (3):用户主观感受有瑕疵但不影响沟通。
- QUALITY_BAD (4):勉强能沟通但不顺畅。
- QUALITY_VBAD (5):网络质量非常差,基本不能沟通。
- QUALITY_DOWN (6):网络连接断开,完全无法沟通。
- delay
- 音频包从发送端到接收端的延迟(毫秒),包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
onAudioRouteChanged
音频路由已发生变化回调。
public void onAudioRouteChanged(int routing) {}
参数
- routing
-
当前的音频路由:
- AUDIO_ROUTE_DEFAULT (-1):使用默认的音频路由。
- AUDIO_ROUTE_HEADSET (0):音频路由为带麦克风的耳机。
- AUDIO_ROUTE_EARPIECE (1):音频路由为听筒。
- AUDIO_ROUTE_HEADSETNOMIC (2):音频路由为不带麦克风的耳机。
- AUDIO_ROUTE_SPEAKERPHONE (3):音频路由为设备自带的扬声器。
- AUDIO_ROUTE_LOUDSPEAKER (4):(暂不支持)音频路由为外接的扬声器。
- AUDIO_ROUTE_BLUETOOTH (5):音频路由为蓝牙耳机。
onAudioSubscribeStateChanged
音频订阅状态发生改变回调。
public void onAudioSubscribeStateChanged( String channel, int uid, int oldState, int newState, int elapseSinceLastState) {}
参数
- channel
- 频道名。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态。
- SUB_STATE_IDLE (0): 加入频道后的初始订阅状态。
- SUB_STATE_NO_SUBSCRIBED (1): 订阅失败。可能是因为:
- 远端用户:
- 调用 muteLocalAudioStream(
true
) 或 muteLocalVideoStream(true
) 停止发送本地媒体流。 - 调用 disableAudio 或 disableVideo 关闭本地音频或视频模块。
- 调用 enableLocalAudio(false) 或 enableLocalVideo(false) 关闭本地音频或视频采集。
- 用户角色为观众。
- 调用 muteLocalAudioStream(
- 本地用户调用以下方法停止接收远端媒体流:
- 调用 muteRemoteAudioStream(true)、 muteAllRemoteAudioStreams(true) 停止接收远端音频流。
- 调用 muteRemoteVideoStream(true)、 muteAllRemoteVideoStreams(true) 停止接收远端视频流。
- 远端用户:
- SUB_STATE_SUBSCRIBING (2): 正在订阅。
- SUB_STATE_SUBSCRIBED (3): 收到了远端流,订阅成功。
- newState
- 当前的订阅状态。
- SUB_STATE_IDLE (0): 加入频道后的初始订阅状态。
- SUB_STATE_NO_SUBSCRIBED (1): 订阅失败。可能是因为:
- 远端用户:
- 调用 muteLocalAudioStream(
true
) 或 muteLocalVideoStream(true
) 停止发送本地媒体流。 - 调用 disableAudio 或 disableVideo 关闭本地音频或视频模块。
- 调用 enableLocalAudio(
false
) 或 enableLocalVideo(false
) 关闭本地音频或视频采集。 - 用户角色为观众。
- 调用 muteLocalAudioStream(
- 本地用户调用以下方法停止接收远端媒体流:
- 调用 muteRemoteAudioStream(
true
)、 muteAllRemoteAudioStreams(true
) 停止接收远端音频流。 - 调用 muteRemoteVideoStream(
true
)、 muteAllRemoteVideoStreams(true
) 停止接收远端视频流。
- 调用 muteRemoteAudioStream(
- 远端用户:
- SUB_STATE_SUBSCRIBING (2): 正在订阅。
- SUB_STATE_SUBSCRIBED (3): 收到了远端流,订阅成功。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
onAudioVolumeIndication
用户音量提示回调。
public void onAudioVolumeIndication(AudioVolumeInfo[] speakers, int totalVolume) {}
该回调默认禁用,你可以通过 enableAudioVolumeIndication 开启。 开启后,只要频道内有发流用户,SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 onAudioVolumeIndication 回调。每次会触发两个 onAudioVolumeIndication 回调,一个报告本地发流用户的音量相关信息,另一个报告瞬时音量最高的远端用户(最多 3 位)的音量相关信息。
启用该功能后,如果有用户将自己静音(调用了 muteLocalAudioStream),SDK 会继续报告本地用户的音量提示回调。
瞬时音量最高的远端用户静音后 20 秒,远端的音量提示回调中将不再包含该用户;如果远端所有用户都将自己静音,20 秒后 SDK 停止报告远端用户的音量提示回调。
参数
- speakers
- 用户音量信息,详见 AudioVolumeInfo 数组。如果 speakers 为空,则表示远端用户不发流或没有远端用户。
- totalVolume
-
混音后的总音量,取值范围为 [0,255]。
- 在本地用户的回调中,totalVolume 为本地发流用户的音量。
- 在远端用户的回调中,totalVolume 为瞬时音量最高的远端用户(最多 3 位)混音后的总音量。 如果用户调用了 startAudioMixing [2/2],则 totalVolume 为音乐文件和用户声音的总音量。
onCameraExposureAreaChanged
摄像头曝光区域已改变回调。
public void onCameraExposureAreaChanged(Rect rect) {}
该回调是由本地用户调用 setCameraExposurePosition 方法改变曝光位置触发的。
参数
- rect
- 镜头内表示曝光的区域。
onCameraFocusAreaChanged
相机对焦区域已改变回调。
public void onCameraFocusAreaChanged(Rect rect) {}
该回调是由本地用户调用 setCameraFocusPositionInPreview 方法改变对焦位置触发的。
参数
- rect
- 镜头内表示对焦的区域。
onCameraReady
摄像头就绪回调。
public void onCameraReady() {}
- 弃用:
-
请改用 onLocalVideoStateChanged 中的 LOCAL_VIDEO_STREAM_STATE_CAPTURING(1)。
该回调提示已成功打开摄像头,可以开始捕获视频。
onChannelMediaRelayEvent
跨频道媒体流转发事件回调。
public void onChannelMediaRelayEvent(int code) {}
参数
- code
-
跨频道媒体流转发事件码:
- RELAY_EVENT_NETWORK_DISCONNECTED(0):网络中断导致用户与服务器连接断开。
- RELAY_EVENT_NETWORK_CONNECTED(1):用户与服务器建立连接。
- RELAY_EVENT_PACKET_JOINED_SRC_CHANNEL(2):用户已加入源频道。
- RELAY_EVENT_PACKET_JOINED_DEST_CHANNEL(3):用户已加入目标频道。
- RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL(4):SDK 开始向目标频道发送数据包。
- RELAY_EVENT_PACKET_RECEIVED_VIDEO_FROM_SRC(5):服务器收到了目标频道发送的视频流。
- RELAY_EVENT_PACKET_RECEIVED_AUDIO_FROM_SRC(6):服务器收到了目标频道发送的音频流
- RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL(7):目标频道已更新。
- RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_REFUSED(8):内部原因导致目标频道更新失败。
- RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_NOT_CHANGE(9):目标频道未发生改变,即目标频道更新失败。
- RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL_IS_NULL(10):目标频道名为
NULL
。 - RELAY_EVENT_VIDEO_PROFILE_UPDATE(11):视频属性已发送至服务器。
- RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(12):暂停向目标频道转发媒体流成功。
- RELAY_EVENT_PAUSE_SEND_PACKET_TO_DEST_CHANNEL_FAILED(13):暂停向目标频道转发媒体流失败。
- RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_SUCCESS(14):恢复向目标频道转发媒体流成功。
- RELAY_EVENT_RESUME_SEND_PACKET_TO_DEST_CHANNEL_FAILED(15):恢复向目标频道转发媒体流失败。
onChannelMediaRelayStateChanged
跨频道媒体流转发状态发生改变回调。
public void onChannelMediaRelayStateChanged(int state, int code) {}
当跨频道媒体流转发状态发生改变时,SDK 会触发该回调,并报告当前的转发状态以及相关的错误信息。
参数
- state
-
跨频道媒体流转发状态:
- RELAY_STATE_IDLE (0):SDK 正在初始化。
- RELAY_STATE_CONNECTING (1):SDK 尝试跨频道。
- RELAY_STATE_RUNNING (2):源频道主播成功加入目标频道。
- RELAY_STATE_FAILURE (3):发生异常,详见 code 中提示的错误信息。
- code
-
跨频道媒体流转发出错的错误码:
- RELAY_OK (0):一切正常。
- RELAY_ERROR_SERVER_ERROR_RESPONSE (1):服务器回应出错。
- RELAY_ERROR_SERVER_NO_RESPONSE (2):服务器无回应。你可以调用 leaveChannel [1/2] 方法离开频道。该错误也可能是由于当前的 App ID 未开启跨频道连麦导致的。你可以联系技术支持申请开通跨频道连麦。
- RELAY_ERROR_NO_RESOURCE_AVAILABLE (3):SDK 无法获取服务,可能是因为服务器资源有限导致。
- RELAY_ERROR_FAILED_JOIN_SRC (4):发起跨频道转发媒体流请求失败。
- RELAY_ERROR_FAILED_JOIN_DEST (5):接受跨频道转发媒体流请求失败。
- RELAY_ERROR_FAILED_PACKET_RECEIVED_FROM_SRC (6):服务器接收跨频道转发媒体流失败。
- RELAY_ERROR_FAILED_PACKET_SENT_TO_DEST (7):服务器发送跨频道转发媒体流失败。
- RELAY_ERROR_SERVER_CONNECTION_LOST (8):SDK 因网络质量不佳与服务器断开。你可以调用 leaveChannel [1/2] 方法离开当前频道。
- RELAY_ERROR_INTERNAL_ERROR (9):服务器内部出错。
- RELAY_ERROR_SRC_TOKEN_EXPIRED (10):源频道的 Token 已过期。
- RELAY_ERROR_DEST_TOKEN_EXPIRED (11):目标频道的 Token 已过期。
onClientRoleChanged
直播场景下用户角色已切换回调。
public void onClientRoleChanged(int oldRole, int newRole) {}
该回调是由本地用户在加入频道后调用 setClientRole [1/2] 改变用户角色触发的。
参数
- oldRole
- 切换前的角色:
- CLIENT_ROLE_BROADCASTER (1):主播。
- CLIENT_ROLE_AUDIENCE (2):观众。
- newRole
- 切换后的角色:
- CLIENT_ROLE_BROADCASTER (1):主播。
- CLIENT_ROLE_AUDIENCE (2):观众。
onClientRoleChangeFailed
直播场景下切换用户角色失败回调。
public void onClientRoleChangeFailed(int reason, int currentRole) {}
直播场景下,本地用户加入频道后调用 setClientRole [1/2] 切换用户角色失败时,SDK 会触发该回调,报告切换失败的原因和当前的用户角色。
参数
- reason
- 切换用户角色失败的原因。
- CLIENT_ROLE_CHANGE_FAILED_TOO_MANY_BROADCASTERS(1): 频道内主播人数达到上限。
注: 该枚举仅在开启 128 人功能后报告。主播人数的上限根据开启 128 人功能时实际配置的人数而定。
- CLIENT_ROLE_CHANGE_FAILED_NOT_AUTHORIZED(2): 请求被服务端拒绝。建议提示用户重新尝试切换用户角色。
- CLIENT_ROLE_CHANGE_FAILED_REQUEST_TIME_OUT(3): 请求超时。建议提示用户检查网络连接状况后重新尝试切换用户角色。
- CLIENT_ROLE_CHANGE_FAILED_CONNECTION_FAILED(4): 网络连接断开。可根据 onConnectionStateChanged 报告的 reason,排查网络连接失败的具体原因。
- CLIENT_ROLE_CHANGE_FAILED_TOO_MANY_BROADCASTERS(1): 频道内主播人数达到上限。
- currentRole
- 当前用户角色。
- CLIENT_ROLE_BROADCASTER(1): 主播。主播可以发流也可以收流。
- CLIENT_ROLE_AUDIENCE(2): 观众。观众只能收流不能发流。
onConnectionBanned
onConnectionInterrupted
网络连接中断回调。
public void onConnectionInterrupted() {}
- 弃用:
- 请改用 onConnectionStateChanged 回调。
- onConnectionInterrupted 回调一定是发生在成功加入频道后,且 SDK 刚失去和服务器连接超过 4 秒时触发。
- onConnectionLost 回调是无论是否成功加入频道,只要 10 秒内和服务器无法建立连接都会触发。
onConnectionLost
网络连接中断,且 SDK 无法在 10 秒内连接服务器回调。
public void onConnectionLost() {}
SDK 在调用 joinChannel [2/2] 后,无论是否加入成功,只要 10 秒和服务器无法连接就会触发该回调。如果 SDK 在断开连接后,20 分钟内还是没能重新加入频道,SDK 会停止尝试重连。
onConnectionStateChanged
网络连接状态已改变回调。
public void onConnectionStateChanged(int state, int reason) {}
该回调在网络连接状态发生改变的时候触发,并告知用户当前的网络连接状态和引起网络状态改变的原因。
参数
- state
-
当前网络连接状态。
- CONNECTION_STATE_DISCONNECTED (1):网络连接断开。
- CONNECTION_STATE_CONNECTING (2):建立网络连接中。
- CONNECTION_STATE_CONNECTED (3):网络已连接。
- CONNECTION_STATE_RECONNECTING (4):重新建立网络连接中 。
- CONNECTION_STATE_FAILED (5):网络连接失败 。
- reason
-
- CONNECTION_CHANGED_CONNECTING (0):建立网络连接中 。
- CONNECTION_CHANGED_JOIN_SUCCESS (1):成功加入频道 。
- CONNECTION_CHANGED_INTERRUPTED (2):网络连接中断 。
- CONNECTION_CHANGED_BANNED_BY_SERVER (3):网络连接被服务器禁止 。
- CONNECTION_CHANGED_JOIN_FAILED (4):加入频道失败 。
- CONNECTION_CHANGED_LEAVE_CHANNEL (5):离开频道 。
- CONNECTION_CHANGED_INVALID_APP_ID (6):不是有效的 APP ID。请更换有效的 APP ID 重新加入频道 。
- CONNECTION_CHANGED_INVALID_CHANNEL_NAME (7):不是有效的频道名。请更换有效的频道名重新加入频道。
- CONNECTION_CHANGED_INVALID_TOKEN (8):生成的 Token 无效。一般有以下原因:
- 在控制台上启用了 App Certificate,但加入频道未使用 Token。当启用了 App Certificate,必须使用 Token。
- 在调用 joinChannel [1/2] 加入频道时指定的 uid 与生成 Token 时传入的 uid 不一致。
- CONNECTION_CHANGED_TOKEN_EXPIRED (9):当前使用的 Token 过期,不再有效,需要重新在你的服务端申请生成 Token 。
- CONNECTION_CHANGED_REJECTED_BY_SERVER (10):此用户被服务器禁止 。
- CONNECTION_CHANGED_SETTING_PROXY_SERVER (11):由于设置了代理服务器,SDK 尝试重连 。
- CONNECTION_CHANGED_RENEW_TOKEN (12):更新 Token 引起网络连接状态改变 。
- CONNECTION_CHANGED_CLIENT_IP_ADDRESS_CHANGED (13):客户端 IP 地址变更,可能是由于网络类型,或网络运营商的 IP 或端口发生改变引起 。
- CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT (14):SDK 和服务器连接保活超时,进入自动重连状态 。
- CONNECTION_CHANGED_REJOIN_SUCCESS (15):重新加入频道成功。
- CONNECTION_CHANGED_LOST (16):SDK 和服务器失去连接 。
- CONNECTION_CHANGED_ECHO_TEST (17):连接状态变化由回声测试引起。
onEncryptionError
内置加密出错回调。
public void onEncryptionError(int errorType) {}
调用 enableEncryption 开启加密后, 如果发流端、收流端出现加解密出错,SDK 会触发该回调。
参数
- errorType
- 错误类型。
- ENCRYPTION_ERROR_INTERNAL_FAILURE (0): 内部原因。
- ENCRYPTION_ERROR_DECRYPTION_FAILURE (1): 解密错误。请确保接收端和发送端使用的加密模式或密钥一致。
- ENCRYPTION_ERROR_ENCRYPTION_FAILURE (2): 加密错误。
onError
发生错误回调。
public void onError(int err) {}
该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 app 干预或提示用户。
参数
- err
- 错误码。
onFacePositionChanged
报告本地人脸检测结果。
public void onFacePositionChanged( int imageWidth, int imageHeight, AgoraFacePositionInfo[] faceRectArr) {}
enableFaceDetection(true)
开启本地人脸检测后,你可以通过该回调实时获取以下人脸检测的信息:
- 摄像头采集的画面大小
- 人脸在 view 中的位置
- 人脸距设备屏幕的距离
其中,人脸距设备屏幕的距离由 SDK 通过摄像头采集的画面大小和人脸在 view 中的位置拟合计算得出。
- 当检测到摄像头前的人脸消失时,该回调会立刻触发;在无人脸的状态下,该回调触发频率会降低,以节省设备耗能。
- 当人脸距离设备屏幕过近时,SDK 不会触发该回调。
- Android 平台上,人脸距设备屏幕的距离(distance)值有一定误差,请不要用它进行精确计算。
参数
- imageWidth
- 摄像头采集画面的宽度 (px)。
- imageHeight
- 摄像头采集画面的高度 (px)。
- faceRectArr
- 检测到的人脸信息,详见 AgoraFacePositionInfo。检测到几张人脸,就会报告几个 AgoraFacePositionInfo 数组。数组长度可以为 0,表示没有检测到摄像头前出现人脸。
onFirstLocalAudioFramePublished
已发布本地音频首帧回调。
public void onFirstLocalAudioFramePublished(int elapsed) {}
- 开启本地音频的情况下,调用 joinChannel [2/2] 成功加入频道后。
- 调用
muteLocalAudioStream(
,再调用true
)muteLocalAudioStream(
后。false
) - 调用 disableAudio,再调用 enableAudio 后。
- 调用 pushExternalAudioFrame [2/2] 成功向 SDK 推送音频帧后。
参数
- elapsed
- 从调用 joinChannel [2/2] 方法到触发该回调的时间间隔(毫秒)。
onFirstLocalVideoFrame
已显示本地视频首帧回调。
public void onFirstLocalVideoFrame( Constants.VideoSourceType source, int width, int height, int elapsed) {}
本地视频首帧显示在本地视图上时,SDK 会触发此回调。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- width
- 本地渲染视频的宽 (px) 。
- height
- 本地渲染视频的高 (px)。
- elapsed
- 从调用 joinChannel [2/2] 到发生此事件过去的时间(毫秒)。如果在 joinChannel [2/2] 前调用了 startPreview [1/2] ,则是从 startPreview [1/2] 到发生此事件过去的时间。
onFirstLocalVideoFramePublished
已发布本地视频首帧回调。
public void onFirstLocalVideoFramePublished(Constants.VideoSourceType source, int elapsed) {}
- 开启本地视频的情况下,调用 joinChannel [2/2] 成功加入频道后。
- 调用 muteLocalVideoStream(
true
),再调用 muteLocalVideoStream(false
) 后。 - 调用 disableVideo,再调用 enableVideo 后。
- 调用 pushExternalVideoFrame [1/2] 成功向 SDK 推送视频帧后。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- elapsed
- 从调用 joinChannel [2/2] 方法到触发该回调的时间间隔(毫秒)。
onFirstRemoteAudioFrame
已接收远端音频首帧回调。
public void onFirstRemoteAudioFrame(int uid, int elapsed) { }
- 弃用:
- 请改用 onRemoteAudioStateChanged 。
参数
- uid
- 发送音频帧的远端用户的用户 ID。
- elapsed
- 从本地用户调用 joinChannel [2/2] 直至该回调触发的延迟,单位为毫秒。
onFirstRemoteAudioDecoded
已解码远端音频首帧的回调。
public void onFirstRemoteAudioDecoded(int uid, int elapsed) { }
- 弃用:
- 请改用 onRemoteAudioStateChanged 。
- 远端用户首次上线后发送音频。
- 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包,可能有如下原因:
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 muteLocalAudioStream 方法停止发送音频流
- 远端用户调用 disableAudio 方法关闭音频
参数
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用 joinChannel [2/2] 直至该回调触发的延迟,单位为毫秒。
onFirstRemoteVideoDecoded
已接收到远端视频并完成解码回调。
public void onFirstRemoteVideoDecoded(int uid, int width, int height, int elapsed) {}
- 远端用户首次上线后发送视频。
- 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括:
- 远端用户离开频道。
- 远端用户掉线。
- 远端用户调用 muteLocalVideoStream 方法停止发送本地视频流。
- 远端用户调用 disableVideo 方法关闭视频模块。
参数
- uid
- 用户 ID,指定是哪个用户的视频流。
- width
- 视频流宽(px)。
- height
- 视频流高(px)。
- elapsed
- 从本地调用 joinChannel [2/2] 开始到该回调触发的延迟(毫秒)。
onFirstRemoteVideoFrame
渲染器已接收首帧远端视频回调。
public void onFirstRemoteVideoFrame(int uid, int width, int height, int elapsed) {}
参数
- uid
- 用户 ID,指定是哪个用户的视频流。
- width
- 视频流宽(px)。
- height
- 视频流高(px)。
- elapsed
- 从本地调用 joinChannel [2/2] 到发生此事件过去的时间(毫秒)。
onJoinChannelSuccess
成功加入频道回调。
public void onJoinChannelSuccess(String channel, int uid, int elapsed) {}
该回调方法表示该客户端成功加入了指定的频道。
参数
- channel
- 频道名。
- uid
- 加入频道的用户 ID。
- elapsed
- 从本地调用 joinChannel [2/2] 开始到发生此事件过去的时间(毫秒)。
onLastmileProbeResult
通话前网络上下行 Last mile 质量探测报告回调。
public void onLastmileProbeResult(LastmileProbeResult result) {}
在调用 startLastmileProbeTest 之后,SDK 会在约 30 秒内返回该回调。
参数
- result
- 上下行 Last mile 质量探测结果。 详见: LastmileProbeResult。
onLastmileQuality
网络上下行 last mile 质量报告回调。
public void onLastmileQuality(int quality) {}
该回调描述本地用户在加入频道前的 last mile 网络探测的结果,其中 last mile 是指设备到 Agora 边缘服务器的网络状态。
加入频道前,调用 startLastmileProbeTest 之后,SDK 触发该回调报告本地用户在加入频道前的 last mile 网络探测的结果。
参数
- quality
- Last mile 网络质量。
- QUALITY_UNKNOWN (0):质量未知。
- QUALITY_EXCELLENT (1):质量极好。
- QUALITY_GOOD (2):用户主观感觉和极好差不多,但码率可能略低于极好。
- QUALITY_POOR (3):用户主观感受有瑕疵但不影响沟通。
- QUALITY_BAD (4):勉强能沟通但不顺畅。
- QUALITY_VBAD (5):网络质量非常差,基本不能沟通。
- QUALITY_DOWN (6):网络连接断开,完全无法沟通。
onLeaveChannel
离开频道回调。
public void onLeaveChannel(RtcStats stats) {}
App 调用 leaveChannel [1/2] 方法时,SDK 提示 app 离开频道成功。在该回调方法中,app 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。
参数
- stats
- 通话的统计数据: RtcStats。
onLocalAudioStateChanged
本地音频状态发生改变回调。
public void onLocalAudioStateChanged(int state, int error) {}
本地音频的状态发生改变时(包括本地麦克风采集状态和音频编码状态),SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时,该回调可以帮助你了解当前音频的状态以及出现故障的原因,方便你排查问题。
参数
- state
- 当前的本地音频状态。
- LOCAL_AUDIO_STREAM_STATE_STOPPED (0): 本地音频默认初始状态。
- LOCAL_AUDIO_STREAM_STATE_RECORDING (1): 本地音频采集设备启动成功。
- LOCAL_AUDIO_STREAM_STATE_ENCODING (2): 本地音频首帧编码成功。
- LOCAL_AUDIO_STREAM_STATE_FAILED (3): 本地音频启动失败。
- error
- 本地音频出错原因。
- LOCAL_AUDIO_STREAM_ERROR_OK 0: 本地音频状态正常。
- LOCAL_AUDIO_STREAM_ERROR_FAILURE 1: 本地音频出错原因不明确。建议提示用户尝试重新加入频道。
- LOCAL_AUDIO_STREAM_ERROR_DEVICE_NO_PERMISSION 2: 没有权限启动本地音频采集设备。请提示用户开启权限。
- LOCAL_AUDIO_STREAM_ERROR_DEVICE_BUSY 3: 本地音频采集设备已经在使用中。请提示用户检查麦克风是否被其他应用占用。麦克风空闲约 5 秒后本地音频采集会自动恢复,你也可以在麦克风空闲后尝试重新加入频道。
- LOCAL_AUDIO_STREAM_ERROR_RECORD_FAILURE 4: 本地音频采集失败。
- LOCAL_AUDIO_STREAM_ERROR_ENCODE_FAILURE 5: 本地音频编码失败。
- LOCAL_AUDIO_STREAM_ERROR_INTERRUPTED 8: 本地音频采集被系统来电、Siri、闹钟中断。如需恢复本地音频采集,请用户中止电话、Siri、闹钟。
onLocalAudioStats
通话中本地音频流的统计信息回调。
public void onLocalAudioStats(LocalAudioStats stats) {}
SDK 每 2 秒触发该回调一次。
参数
- stats
- 本地音频统计数据。详见 LocalAudioStats。
onLocalUserRegistered
本地用户成功注册 User Account 回调。
public void onLocalUserRegistered(int uid, String userAccount) {}
本地用户成功调用 registerLocalUserAccount 方法注册用户 User Account,或调用 joinChannelWithUserAccount [2/2] 加入频道后,SDK 会触发该回调,并告知本地用户的 UID 和 User Account。
参数
- uid
- 本地用户的 ID。
- userAccount
- 本地用户的 User Account。
onLocalVideoStateChanged
本地视频状态发生改变回调。
public void onLocalVideoStateChanged(Constants.VideoSourceType source, int state, int error) { super.onLocalVideoStateChanged(source, state, error); mCallbackObj = new Object[] {source, state, error}; }
本地视频的状态发生改变时,SDK 会触发该回调返回当前的本地视频状态。你可以通过该回调了解当前视频的状态以及出现故障的原因,方便排查问题。
LOCAL_VIDEO_STREAM_STATE_FAILED
,错误码为 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE
:
- 应用退到后台,系统回收摄像头。
- 摄像头正常启动,但连续 4 秒都没有输出采集的视频。
摄像头输出采集的视频帧时,如果连续 15 帧中,所有视频帧都一样,SDK 触发 onLocalVideoStateChanged 回调,状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING,错误码为 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE。注意,帧重复检测仅针对分辨率大于 200 × 200、帧率大于等于 10 fps、码率小于 20 Kbps 的视频帧。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- state
-
- LOCAL_VIDEO_STREAM_STATE_STOPPED (0): 本地视频默认初始状态。
- LOCAL_VIDEO_STREAM_STATE_CAPTURING (1): 本地视频采集设备启动成功。
- LOCAL_VIDEO_STREAM_STATE_ENCODING (2): 本地视频首帧编码成功。
- LOCAL_VIDEO_STREAM_STATE_FAILED (3): 本地视频启动失败。
- error
-
- LOCAL_VIDEO_STREAM_ERROR_OK (0): 本地视频状态正常。
- LOCAL_VIDEO_STREAM_ERROR_FAILURE (1): 出错原因不明确。
- LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY (3): 本地视频采集设备正在使用中。请提示用户检查摄像头是否被其他应用占用。
- LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE (4): 本地视频采集失败。请提示用户检查视频采集设备是否正常工作,检查摄像头是否被其他应用占用,或者尝试重新加入频道。
- Android 9 及以上版本,app 切后台一段时间后,系统收回相机权限。
- Android 6 及以上版本,如果相机被第三方应用占用,且未被及时释放。如果一段时间后,相机被释放,则 SDK会再次出发该回调,并报告
state
为CAPTURING
,error
为ERROR_OK
。
- LOCAL_VIDEO_STREAM_ERROR_ENCODE_FAILURE (5):本地视频编码失败。
- LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND (8):找不到本地视频采集设备。需检查摄像头是否与设备正常连接、摄像头是否正常工作,或者尝试重新加入频道。
onLocalVideoStats
本地视频流统计信息回调。
public void onLocalVideoStats(Constants.VideoSourceType source, LocalVideoStats stats) {}
该回调描述本地设备发送视频流的统计信息,每 2 秒触发一次。
参数
- source
- 视频源的类型。详见 VideoSourceType。
- stats
- 本地视频流统计信息。详见 LocalVideoStats。
onMediaEngineLoadSuccess
媒体引擎成功加载的回调。
public void onMediaEngineLoadSuccess() {}
onMediaEngineStartCallSuccess
媒体引擎成功启动的回调。
public void onMediaEngineStartCallSuccess() {}
onNetworkQuality
通话中每个用户的网络上下行 last mile 质量报告回调。
public void onNetworkQuality(int uid, int txQuality, int rxQuality) {}
该回调描述每个用户在通话中的 last mile 网络状态,其中 last mile 是指设备到 Agora 边缘服务器的网络状态。
该回调每 2 秒触发一次。如果远端有多个用户,该回调每 2 秒会被触发多次。
UNKNOWN
;用户不收流时,rxQuality 为 UNKNOWN
。参数
- uid
-
用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。
- txQuality
- 该用户的上行网络质量,基于发送码率、上行丢包率、平均往返时延和网络抖动计算。 该值代表当前的上行网络质量,帮助判断是否可以支持当前设置的视频编码属性。 假设上行码率是 1000 Kbps,那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题,但是支持 1280 × 720 的分辨率就会有困难。
- QUALITY_UNKNOWN (0):质量未知。
- QUALITY_EXCELLENT (1):质量极好。
- QUALITY_GOOD (2):用户主观感觉和极好差不多,但码率可能略低于极好。
- QUALITY_POOR (3):用户主观感受有瑕疵但不影响沟通。
- QUALITY_BAD (4):勉强能沟通但不顺畅。
- QUALITY_VBAD (5):网络质量非常差,基本不能沟通。
- QUALITY_DOWN (6):网络连接断开,完全无法沟通。
- rxQuality
- 该用户的下行网络质量,基于下行网络的丢包率、平均往返延时和网络抖动计算。
- QUALITY_UNKNOWN (0):质量未知。
- QUALITY_EXCELLENT (1):质量极好。
- QUALITY_GOOD (2):用户主观感觉和极好差不多,但码率可能略低于极好。
- QUALITY_POOR (3):用户主观感受有瑕疵但不影响沟通。
- QUALITY_BAD (4):勉强能沟通但不顺畅。
- QUALITY_VBAD (5):网络质量非常差,基本不能沟通。
- QUALITY_DOWN (6):网络连接断开,完全无法沟通。
onNetworkTypeChanged
本地网络类型发生改变回调。
public void onNetworkTypeChanged(int type) {}
本地网络连接类型发生改变时,SDK 会触发该回调,并在回调中明确当前的网络连接类型。你可以通过该回调获取正在使用的网络类型;当连接中断时,该回调能辨别引起中断的原因是网络切换还是网络条件不好。
参数
- type
-
网络连接类型:
- NETWORK_TYPE_UNKNOWN (-1):网络连接类型未知。
- NETWORK_TYPE_DISCONNECTED (0):网络连接已断开。
- NETWORK_TYPE_LAN (1):网络类型为 LAN。
- NETWORK_TYPE_WIFI (2):网络类型为 Wi-Fi(包含热点)。
- NETWORK_TYPE_MOBILE_2G (3):网络类型为 2G 移动网络。
- NETWORK_TYPE_MOBILE_3G (4):网络类型为 3G 移动网络。
- NETWORK_TYPE_MOBILE_4G (5):网络类型为 4G 移动网络。
- NETWORK_TYPE_MOBILE_5G (6):网络类型为 5G 移动网络。
onPermissionError
获取设备权限出错回调。
public void onPermissionError(int permission) {}
无法获取设备权限时,SDK 会触发该回调,报告哪个设备的权限无法获取。
参数
- permission
- 设备权限类型。
- RECORD_AUDIO (0): 音频采集设备的权限。
- CAMERA (1): 摄像头权限。
onProxyConnected
代理连接状态回调。
public void onProxyConnected( String channel, int uid, int proxyType, String localProxyIp, int elapsed) {}
通过该回调你可以监听 SDK 连接代理的状态。例如,当用户调用 setCloudProxy 设置代理并成功加入频道后, SDK 会触发该回调报告用户 ID、连接的代理类型和从调用 joinChannel [1/2] 到触发该回调经过的时间等。
参数
- channel
- 频道名称。
- uid
- 用户 ID
- proxyType
- 连接上的代理类型。
- PROXY_TYPE_NONE_PROXY (0): 预留参数,暂不支持。
- PROXY_TYPE_UDP_CLOUD_PROXY (1): UDP 协议的云代理,即 Force UDP 云代理模式。在该模式下,SDK 始终通过 UDP 协议传输数据。
- PROXY_TYPE_TCP_CLOUD_PROXY (2): TCP(加密)协议的云代理,即 Force TCP 云代理模式。在该模式下,SDK 始终通过 TLS 443 传输数据。
- PROXY_TYPE_LOCAL_PROXY (3): 预留参数,暂不支持。
- PROXY_TYPE_TCP_AUTO_FALLBACK (4): 自动模式。在该模式下,SDK 优先连接 SD-RTN™,如果连接失败,自动切换为 TLS 443。
- localProxyIp
- 预留参数,暂不支持。
- elapsed
- 从调用 joinChannel [1/2] 到 SDK 触发该回调的经过的时间(毫秒)。
onRejoinChannelSuccess
成功重新加入频道回调。
public void onRejoinChannelSuccess(String channel, int uid, int elapsed) {}
有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。
参数
- channel
- 频道名。
- uid
- 重新加入频道的用户 ID。
- elapsed
- 从调用 joinChannel [1/2] 或 joinChannel [2/2] 方法到触发该回调的时间间隔(毫秒)。
onRemoteAudioStateChanged
远端音频流状态发生改变回调。
public void onRemoteAudioStateChanged(int uid, int state, int reason, int elapsed) {}
远端用户(通信场景)或主播(直播场景)的音频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端音频流状态。
参数
- uid
- 发生音频状态改变的远端用户 ID。
- state
- 远端音频流状态。
- REMOTE_AUDIO_STATE_STOPPED (0): 远端音频默认初始状态。在 REMOTE_AUDIO_REASON_LOCAL_MUTED、REMOTE_AUDIO_REASON_REMOTE_MUTED 或 REMOTE_AUDIO_REASON_REMOTE_OFFLINE 的情况下,会报告该状态。
- REMOTE_AUDIO_STATE_STARTING (1): 本地用户已接收远端音频首包。
- REMOTE_AUDIO_STATE_DECODING (2): 远端音频流正在解码,正常播放。在 REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY、REMOTE_AUDIO_REASON_LOCAL_UNMUTED 或 REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED 的情况下, 会报告该状态。
- REMOTE_AUDIO_STATE_FROZEN (3): 远端音频流卡顿。在 REMOTE_AUDIO_REASON_NETWORK_CONGESTION的情况下,会报告该状态。
- REMOTE_AUDIO_STATE_FAILED (4): 远端音频流播放失败。在 REMOTE_VIDEO_STATE_REASON_INTERNAL 的情况下,会报告该状态。
- reason
- 远端音频流状态改变的具体原因。
- REMOTE_AUDIO_REASON_INTERNAL (0): 音频状态发生改变时,会报告该原因。
- REMOTE_AUDIO_REASON_NETWORK_CONGESTION (1): 网络阻塞。
- REMOTE_AUDIO_REASON_NETWORK_RECOVERY (2): 网络恢复正常。
- REMOTE_AUDIO_REASON_LOCAL_MUTED (3): 本地用户停止接收远端音频流或本地用户禁用音频模块。
- REMOTE_AUDIO_REASON_LOCAL_UNMUTED (4): 本地用户恢复接收远端音频流或本地用户启动音频模块。
- REMOTE_AUDIO_REASON_REMOTE_MUTED (5): 远端用户停止发送音频流或远端用户禁用音频模块。
- REMOTE_AUDIO_REASON_REMOTE_UNMUTED (6): 远端用户恢复发送音频流或远端用户启用音频模块。
- REMOTE_AUDIO_REASON_REMOTE_OFFLINE (7): 远端用户离开频道。
- elapsed
- 从本地用户调用 joinChannel [2/2] 方法到发生本事件经历的时间,单位为毫秒。
onRemoteAudioStats
通话中远端音频流的统计信息回调。
public void onRemoteAudioStats(RemoteAudioStats stats) {}
该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流,该回调每 2 秒会被触发多次。
参数
- stats
- 接收到的远端音频统计数据,详见 RemoteAudioStats。
onRemoteAudioTransportStats
通话中远端音频流传输的统计信息回调。
public void onRemoteAudioTransportStats(int uid, int delay, int lost, int rxKBitRate) {}
- 弃用:
- 请改用 onRemoteAudioStats。
该回调描述远端用户通话中端到端的网络统计信息,通过音频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。通话中,当用户收到远端用户/主播发送的音频数据包后 ,会每 2 秒触发一次该回调。
参数
- uid
- 用户 ID,指定是哪个用户/主播的音频包。
- delay
- 音频包从发送端到接收端的延时(毫秒)。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
- rxKBitrate
- 远端音频包的接收码率(Kbps)。
onRemoteVideoStateChanged
远端视频状态发生改变回调。
public void onRemoteVideoStateChanged(int uid, int state, int reason, int elapsed) {}
参数
- uid
- 发生视频状态改变的远端用户 ID。
- state
-
远端视频流状态:
- REMOTE_VIDEO_STATE_STOPPED(0):远端视频默认初始状态。在
REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3)
、REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5)
、REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7)
或REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8)
的情况下,会报告该状态。 - REMOTE_VIDEO_STATE_STARTING(1):本地用户已接收远端视频首包。
- REMOTE_VIDEO_STATE_PLAYING(2):远端视频流正常解码播放。在
REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY(2)
、REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4)
、REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6)
或REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9)
的情况下,会报告该状态。 - REMOTE_VIDEO_STATE_FROZEN(3):远端视频流卡顿。在
REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1)
的情况下,会报告该状态。 - REMOTE_VIDEO_STATE_FAILED(4):远端视频流播放失败。在
REMOTE_VIDEO_STATE_REASON_INTERNAL(0)
的情况下,会报告该状态。
- REMOTE_VIDEO_STATE_STOPPED(0):远端视频默认初始状态。在
- reason
-
远端视频流状态改变的具体原因:
- REMOTE_VIDEO_STATE_REASON_INTERNAL(0):内部原因。
- REMOTE_VIDEO_STATE_REASON_NETWORK_CONGESTION(1):网络阻塞。
- REMOTE_VIDEO_STATE_REASON_NETWORK_RECOVERY(2):网络恢复正常。
- REMOTE_VIDEO_STATE_REASON_LOCAL_MUTED(3):本地用户停止接收远端视频流或本地用户禁用视频模块。
- REMOTE_VIDEO_STATE_REASON_LOCAL_UNMUTED(4):本地用户恢复接收远端视频流或本地用户启动视频模块。
- REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5):远端用户停止发送视频流或远端用户禁用视频模块。
- REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6):远端用户恢复发送视频流或远端用户启用视频模块。
- REMOTE_VIDEO_STATE_REASON_REMOTE_OFFLINE(7):远端用户离开频道。
- REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK(8):远端视频流已回退为音频流。
- REMOTE_VIDEO_STATE_REASON_AUDIO_FALLBACK_RECOVERY(9):回退的远端音频流恢复为视频流。
- elapsed
- 从本地用户调用 joinChannel [2/2] 方法到发生本事件经历的时间,单位为毫秒。
onRemoteVideoStats
通话中远端视频流的统计信息回调。
public void onRemoteVideoStats(RemoteVideoStats stats) {}
该回调描述远端用户在通话中端到端的视频流统计信息, 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播, 该回调每 2 秒会被触发多次。
参数
- stats
- 远端视频统计数据。详见 RemoteVideoStats。
onRemoteVideoTransportStats
通话中远端视频流传输的统计信息回调。
public void onRemoteVideoTransportStats(int uid, int delay, int lost, int rxKBitRate) {}
- 弃用:
- 该回调已被废弃,请改用 onRemoteVideoStats。
该回调描述远端用户通话中端到端的网络统计信息,通过视频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。
通话中,当用户收到远端用户/主播发送的视频数据包后,会每 2 秒触发一次该回调。
参数
- uid
- 用户 ID,指定是哪个用户/主播的视频包。
- delay
- 视频包从发送端到接收端的延时(毫秒)。
- lost
- 视频包从发送端到接收端的丢包率 (%)。
- rxKBitRate
- 远端视频包的接收码率(Kbps)。
onRequestToken
Token 已过期回调。
public void onRequestToken() {}
在通话过程中如果 Token 已失效,SDK 会触发该回调,提醒 app 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 joinChannel [2/2] 重新加入频道。
参数
onRtcStats
当前通话统计信息回调。
public void onRtcStats(RtcStats stats) {}
SDK 定期向 App 报告当前通话的统计信息,每两秒触发一次。
参数
- stats
-
RTC 引擎统计数据,详见 RtcStats 。
onRtmpStreamingEvent
旁路推流事件回调。
public void onRtmpStreamingEvent(String url, int event) {}
参数
- url
- 旁路推流 URL。
- event
- 旁路推流事件码。
- RTMP_STREAMING_EVENT_FAILED_LOAD_IMAGE (1): 旁路推流时,添加背景图或水印出错。
- RTMP_STREAMING_EVENT_URL_ALREADY_IN_USE (2): 该推流 URL 已用于推流。如果你想开始新的推流,请使用新的推流 URL。
- RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT (3): 功能不支持。
- RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN (4): 预留参数。
onRtmpStreamingStateChanged
旁路推流状态发生改变回调。
public void onRtmpStreamingStateChanged(String url, int state, int errCode) {}
旁路推流状态发生改变时,SDK会触发该回调,并在回调中明确状态发生改变的 URL 地址及当前推流状态。该回调方便推流用户了解当前的推流状态;推流出错时,你可以通过返回的错误码了解出错的原因,方便排查问题。
参数
- url
-
推流状态发生改变的 URL 地址。
- state
- 当前的推流状态:
- RTMP_STREAM_PUBLISH_STATE_IDLE (0):推流未开始或已结束。
- RTMP_STREAM_PUBLISH_STATE_CONNECTING (1):正在连接 Agora 推流服务器和 CDN 服务器。
- RTMP_STREAM_PUBLISH_STATE_RUNNING (2):推流正在进行。成功推流后,会返回该状态。
- RTMP_STREAM_PUBLISH_STATE_RECOVERING (3):正在恢复推流。当 CDN 出现异常,或推流短暂中断时,SDK 会自动尝试恢复推流,并返回该状态。
- 如成功恢复推流,则进入状态 RTMP_STREAM_PUBLISH_STATE_RUNNING(2)。
- 如服务器出错或 60 秒内未成功恢复,则进入状态 RTMP_STREAM_PUBLISH_STATE_FAILURE(4)。如果觉得 60 秒太长,也可以主动调用 startRtmpStreamWithTranscoding/startRtmpStreamWithoutTranscoding 和 stopRtmpStream 方法尝试重连。
- RTMP_STREAM_PUBLISH_STATE_FAILURE (4):推流失败。失败后,你可以通过返回的错误码排查错误原因,也可以重新尝试推流。
- RTMP_STREAM_PUBLISH_STATE_DISCONNECTING (5):SDK 正在与 Agora 推流服务器和 CDN 服务器断开连接。当你调用 stopRtmpStream 方法正常结束推流时,SDK 会依次报告推流状态为 RTMP_STREAM_PUBLISH_STATE_DISCONNECTING、RTMP_STREAM_PUBLISH_STATE_IDLE。
- errCode
- 推流错误信息。
- RTMP_STREAM_PUBLISH_ERROR_OK (0):推流成功。
- RTMP_STREAM_PUBLISH_ERROR_INVALID_ARGUMENT (1):参数无效。请检查输入参数是否正确。
- RTMP_STREAM_PUBLISH_ERROR_ENCRYPTED_STREAM_NOT_ALLOWED (2):推流已加密,不能推流。
- RTMP_STREAM_PUBLISH_ERROR_CONNECTION_TIMEOUT (3):推流超时未成功。可尝试重新推流。
- RTMP_STREAM_PUBLISH_ERROR_INTERNAL_SERVER_ERROR (4):推流服务器出现错误。请尝试重新推流。
- RTMP_STREAM_PUBLISH_ERROR_RTMP_SERVER_ERROR (5):CDN 服务器出现错误。
- RTMP_STREAM_PUBLISH_ERROR_TOO_OFTEN (6):预留参数。
- RTMP_STREAM_PUBLISH_ERROR_REACH_LIMIT (7):单个主播的推流地址数目达到上限 10。请先停止对一些非必要地址的推流。
- RTMP_STREAM_PUBLISH_ERROR_NOT_AUTHORIZED (8):主播操作不属于自己的流。例如更新其他主播的流参数、停止其他主播的流。请检查 App 逻辑。
- RTMP_STREAM_PUBLISH_ERROR_STREAM_NOT_FOUND (9):服务器未找到这个流。
- RTMP_STREAM_PUBLISH_ERROR_FORMAT_NOT_SUPPORTED (10):推流地址格式有错误。请检查推流地址格式是否正确。
- RTMP_STREAM_PUBLISH_ERROR_NOT_BROADCASTER (11):用户角色不是主播,该用户无法使用推流功能。请检查你的应用代码逻辑。
- RTMP_STREAM_PUBLISH_ERROR_TRANSCODING_NO_MIX_STREAM (13):非转码推流情况下,调用了 updateRtmpTranscoding 或 setLiveTranscoding 方法更新转码属性。请检查你的应用代码逻辑。
- RTMP_STREAM_PUBLISH_ERROR_NET_DOWN (14):主播的网络出错。
- RTMP_STREAM_PUBLISH_ERROR_INVALID_APPID (15):你的 App ID 没有使用 Agora 推流服务的权限。
- RTMP_STREAM_UNPUBLISH_ERROR_OK (100):推流已正常结束。当你调用 stopRtmpStream 结束推流后,SDK 会返回该值。
onSnapshotTaken
视频截图结果回调。
public void onSnapshotTaken(int uid, String filePath, int width, int height, int errCode) {}
成功调用 takeSnapshot 后,SDK 触发该回调报告截图是否成功和获取截图的详情。
参数
- uid
- 用户 ID。如果 uid 为 0,表示本地用户。
- filePath
- 截图的本地保存路径。
- width
- 图片宽度(px)。
- height
- 图片高度(px)。
- errCode
- 截图成功的提示或失败的原因。
- 0:截图成功。
- < 0: 截图失败。
- -1:写入文件失败或 JPEG 编码失败。
- -2:takeSnapshot 方法调用成功后 1 秒内没有发现指定用户的视频流。
- -3:takeSnapshot 方法调用过于频繁。
onStreamMessage
接收到对方数据流消息的回调。
public void onStreamMessage(int uid, int streamId, byte[] data) {}
该回调表示本地用户收到了远端用户调用 sendStreamMessage 方法发送的流消息。
参数
- uid
- 发送消息的用户 ID。
- streamId
- 接收到的消息的 Stream ID。
- data
- 接收到的数据。
onStreamMessageError
接收对方数据流消息发生错误的回调。
public void onStreamMessageError(int uid, int streamId, int error, int missed, int cached) {}
该回调表示本地用户未收到远端用户调用 sendStreamMessage 方法发送的流消息。
参数
- uid
- 发送消息的用户 ID。
- streamId
- 接收到的消息的 Stream ID。
- error
- 发生错误的错误码。
- missed
- 丢失的消息数量。
- cached
- 数据流中断时,后面缓存的消息数量。
onTokenPrivilegeWillExpire
Token 服务将在30s内过期回调。
public void onTokenPrivilegeWillExpire(String token) {}
在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒 app 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 renewToken 将新生成的 Token 传给 SDK。
参数
- token
- 即将服务失效的 Token。
onTranscodingUpdated
旁路推流转码设置已被更新回调。
public void onTranscodingUpdated() {}
setLiveTranscoding 方法中的直播参数 LiveTranscoding 更新时,onTranscodingUpdated 回调会被触发并向主播报告更新信息。
onUplinkNetworkInfoUpdated
上行网络信息变化回调。
public void onUplinkNetworkInfoUpdated(UplinkNetworkInfo info) {}
只有当上行网络信息发生变化时,SDK 才会触发该回调。
参数
- info
- 上行网络信息,详见 UplinkNetworkInfo。
onUserEnableLocalVideo
远端用户开/关本地视频采集回调。
public void onUserEnableLocalVideo(int uid, boolean enabled) {}
该回调是由远端用户调用 enableLocalVideo 方法开启或关闭视频采集触发的。
参数
- uid
- 用户 ID,提示是哪个用户的视频流。
- enabled
-
远端用户是否启用视频采集:
-
true
: 该用户已启用视频功能。启用后,其他用户可以接收到该用户的视频流。 -
false
: 该用户已关闭视频功能。关闭后,该用户仍然可以接收其他用户的视频流,但其他用户接收不到该用户的视频流。
-
onUserEnableVideo
远端用户开/关视频模块回调。
public void onUserEnableVideo(int uid, boolean enabled) {}
关闭视频功能是指该用户只能进行语音通话,不能显示、发送自己的视频,也不能接收、显示别人的视频。
该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。
参数
- uid
- 用户 ID,提示是哪个用户的视频流。
- enabled
-
-
true
: 该用户已启用视频功能。 -
false
: 该用户已关闭视频功能。
-
onUserInfoUpdated
远端用户信息已更新回调。
public void onUserInfoUpdated(int uid, UserInfo userInfo) {}
远端用户加入频道后, SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发该回调。
参数
- uid
- 远端用户 ID。
- userInfo
- 标识用户信息的 UserInfo 对象,包含用户 UID 和 User Account。详见 UserInfo 类。
onUserJoined
远端用户(通信场景)/主播(直播场景)加入当前频道回调。
public void onUserJoined(int uid, int elapsed) {}
- 通信场景下,该回调提示有远端用户加入了频道。如果加入之前,已经有其他用户在频道中了,新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下,该回调提示有主播加入了频道。如果加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。Agora 建议连麦主播不超过 17 人。
- 远端用户/主播调用 joinChannel [2/2] 方法加入频道。
- 远端用户加入频道后将用户角色改变为主播。
- 远端用户/主播网络中断后重新加入频道。
参数
- uid
- 新加入频道的远端用户/主播 ID。
- elapsed
- 从本地用户调用 joinChannel [2/2] 到该回调触发的延迟(毫秒)。
onUserMuteAudio
远端用户(通信场景)/主播(直播场景)停止或恢复发送音频流回调。
public void onUserMuteAudio(int uid, boolean muted) {}
该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。
参数
- uid
- 用户 ID。
- muted
- 该用户是否静音:
true
: 该用户已将音频静音。false
: 该用户取消了音频静音。
onUserMuteVideo
远端用户取消或恢复发布视频流回调。
public void onUserMuteVideo(int uid, boolean muted) {}
当远端用户调用 muteLocalVideoStream 取消或恢复发布视频流时,SDK 会触发该回调向本地用户报告远端用户的发流状况。
参数
- uid
- 远端用户 ID。
- muted
- 远端用户是否取消发布视频流:
true
: 取消发布视频流。false
: 发布视频流。
onUserOffline
远端用户(通信场景)/主播(直播场景)离开当前频道回调。
public void onUserOffline(int uid, int reason) {}
- 正常离开:远端用户/主播会发送类似“再见”的消息。接收此消息后,判断用户离开频道。
- 超时掉线:在一定时间内(通信场景为 20 秒,直播场景稍有延时),用户没有收到对方的任何数据包,则判定为对方掉线。在网络较差的情况下,有可能会误报。我们建议使用 Agora 云信令 SDK 来做可靠的掉线检测。
参数
- uid
- 离线用户或主播的用户 ID。
- reason
-
远端用户(通信场景)或主播(直播场景)下线的原因:
- USER_OFFLINE_QUIT(0):用户主动离开。此时离开频道的用户会发送一个类似“再见”的消息。收到该消息是,SDK 判定该用户、 离开频道。
- USER_OFFLINE_DROPPED(1):因过长时间收不到对方数据包,SDK 判定该远端用户超时掉线。注意:在网络连接不稳定时,该判定 可能会有误。我们建议使用 Agora 实时消息 SDK 来做可靠的掉线检测。
- USER_OFFLINE_BECOME_AUDIENCE(2):用户的角色从主播切换为观众。
onVideoPublishStateChanged
视频发布状态改变回调。
public void onVideoPublishStateChanged(Constants.VideoSourceType source, String channel, int oldState, int newState, int elapseSinceLastState) {}
参数
- channel
- 频道名。
- source
- 视频源的类型。详见 VideoSourceType。
- oldState
- 之前的发布状态,详见 STREAM_PUBLISH_STATE。
- newState
- 当前的发布状态,详见 STREAM_PUBLISH_STATE。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
onVideoSizeChanged
本地或远端视频大小和旋转信息发生改变回调。
public void onVideoSizeChanged(int uid, int width, int height, int rotation) {}
参数
- uid
- 图像尺寸和旋转信息发生变化的用户 ID(本地用户的 uid 为 0。此时视频为本地用户的视频预览)。
- width
- 视频流的宽度(像素)。
- height
- 视频流的高度(像素)。
- rotation
- 旋转信息,取值范围 [0,360)。
onVideoStopped
视频功能已停止回调。
public void onVideoStopped() {}
- 弃用:
- 请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED(0)。
App 如需在停止视频后对 view 做其他处理(比如显示其他画面),可以在这个回调中进行。
onVideoSubscribeStateChanged
视频订阅状态发生改变回调。
public void onVideoSubscribeStateChanged( String channel, int uid, int oldState, int newState, int elapseSinceLastState) {}
参数
- channel
- 频道名。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态。
- SUB_STATE_IDLE (0): 加入频道后的初始订阅状态。
- SUB_STATE_NO_SUBSCRIBED (1): 订阅失败。可能是因为:
- 远端用户:
- 调用 muteLocalAudioStream(
true
) 或 muteLocalVideoStream(true
) 停止发送本地媒体流。 - 调用 disableAudio 或 disableVideo 关闭本地音频或视频模块。
- 调用 enableLocalAudio(false) 或 enableLocalVideo(false) 关闭本地音频或视频采集。
- 用户角色为观众。
- 调用 muteLocalAudioStream(
- 本地用户调用以下方法停止接收远端媒体流:
- 调用 muteRemoteAudioStream(true)、 muteAllRemoteAudioStreams(true) 停止接收远端音频流。
- 调用 muteRemoteVideoStream(true)、 muteAllRemoteVideoStreams(true) 停止接收远端视频流。
- 远端用户:
- SUB_STATE_SUBSCRIBING (2): 正在订阅。
- SUB_STATE_SUBSCRIBED (3): 收到了远端流,订阅成功。
- newState
- 当前的订阅状态。
- SUB_STATE_IDLE (0): 加入频道后的初始订阅状态。
- SUB_STATE_NO_SUBSCRIBED (1): 订阅失败。可能是因为:
- 远端用户:
- 调用 muteLocalAudioStream(
true
) 或 muteLocalVideoStream(true
) 停止发送本地媒体流。 - 调用 disableAudio 或 disableVideo 关闭本地音频或视频模块。
- 调用 enableLocalAudio(false) 或 enableLocalVideo(false) 关闭本地音频或视频采集。
- 用户角色为观众。
- 调用 muteLocalAudioStream(
- 本地用户调用以下方法停止接收远端媒体流:
- 调用 muteRemoteAudioStream(true)、 muteAllRemoteAudioStreams(true) 停止接收远端音频流。
- 调用 muteRemoteVideoStream(true)、 muteAllRemoteVideoStreams(true) 停止接收远端视频流。
- 远端用户:
- SUB_STATE_SUBSCRIBING (2): 正在订阅。
- SUB_STATE_SUBSCRIBED (3): 收到了远端流,订阅成功。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。