AgoraRtcEngineDelegate
AgoraRtcEngineDelegate 接口类用于 SDK 向 app 发送事件通知,app 通过继承该接口类的方法获取 SDK 的事件通知。
该接口类的所有方法都有缺省(空)实现, app 可以根据需要只继承关心的事件。
- 在回调方法中,app 不应该做耗时或者调用可能会引起阻塞的 API(如
sendMessage
),否则可能影响 SDK 的运行。 - SDK 不再捕获开发者在 AgoraRtcEngineDelegate 类回调中自行实现的代码逻辑中的异常。你需要自行处理该异常,否则异常出现时可能引起 app 崩溃。
activeSpeaker
监测到远端最活跃用户回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine activeSpeaker:(NSUInteger)speakerUid;
成功调用 enableAudioVolumeIndication 后,SDK 会持续监测音量最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。
- 如果远端最活跃用户一直是同一位用户,则 SDK 不会再次触发 activeSpeaker 回调。
- 如果远端最活跃用户有变化,则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。
参数
- engine
- AgoraRtcEngineKit 对象。
- speakerUid
- 远端最活跃用户的 ID。
didApiCallExecute
API 方法已执行回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didApiCallExecute:(NSInteger)error api:(NSString * _Nonnull)api result:(NSString * _Nonnull)result;
参数
- engine
- AgoraRtcEngineKit 对象。
- error
- 当方法调用失败时 SDK 返回的错误码。如果该方法调用成功,SDK 会返回 0。
- api
- SDK 执行的 API 方法。
- result
- SDK 调用 API 的结果。
rtcEngineDidAudioEffectFinish
本地音效文件播放已结束回调。
- (void)rtcEngineDidAudioEffectFinish:(AgoraRtcEngineKit * _Nonnull)engine soundId:(int)soundId;
当播放音效结束后,会触发该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。
rtcEngineLocalAudioMixingDidFinish
本地音乐文件播放已结束回调。
- (void)rtcEngineLocalAudioMixingDidFinish:(AgoraRtcEngineKit * _Nonnull)engine;
- 弃用:
- 请改用 audioMixingStateChanged。
当调用 startAudioMixing [2/2] 播放本地音乐文件结束后,会触发该回调。如果调用 startAudioMixing [2/2] 失败,会返回错误码 WARN_AUDIO_MIXING_OPEN_ERROR。
参数
- engine
- AgoraRtcEngineKit 对象。
audioMixingStateChanged
音乐文件的播放状态已改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioMixingStateChanged:(AgoraAudioMixingStateType)state reasonCode:(AgoraAudioMixingReasonCode)reasonCode;
该回调在音乐文件播放状态发生改变时触发,并报告当前的播放状态和错误码。
参数
- state
- 音乐文件播放状态。详见 AgoraAudioMixingStateType。
- reasonCode
- 错误码。详见 AgoraAudioMixingReasonCode。
didAudioPublishStateChange
音频发布状态改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didAudioPublishStateChange:(NSString * _Nonnull)channelId oldState:(AgoraStreamPublishState)oldState newState:(AgoraStreamPublishState)newState elapseSinceLastState:(int)elapseSinceLastState;
参数
- engine
- AgoraRtcEngineKit 对象。
- channelId
- 频道名。
- oldState
- 之前的发布状态,详见 AgoraStreamPublishState。
- newState
- 当前的发布状态,详见 AgoraStreamPublishState。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
audioQualityOfUid
远端声音质量回调。
- (void)audioQualityBlock:(void (^_Nullable)(NSUInteger uid, AgoraNetworkQuality quality, NSUInteger delay, NSUInteger lost))audioQualityBlock
- 弃用:
- 请改用 remoteAudioStats。
该回调描述远端用户在通话中的音频质量,针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播,该回调每 2 秒会被触发多次。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID,指定是谁发的音频流。
- quality
- 语音质量。详见 AgoraNetworkQuality。
- delay
- 音频包从发送端到接收端的延迟(毫秒),包括声音采样前处理、网络传输、网络抖动缓冲引起的延迟。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
didAudioRouteChanged
音频路由已发生变化回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioRouteChanged:(AgoraAudioOutputRouting)routing;
参数
- engine
- AgoraRtcEngineKit 对象。
- routing
-
当前的音频路由。详见 AgoraAudioOutputRouting。
didAudioSubscribeStateChange
音频订阅状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didAudioSubscribeStateChange:(NSString * _Nonnull)channelId uid:(unsigned int)uid oldState:(AgoraStreamSubscribeState)oldState newState:(AgoraStreamSubscribeState)newState elapseSinceLastState:(int)elapseSinceLastState;
参数
- engine
- AgoraRtcEngineKit 对象。
- channelId
- 频道名。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态,详见 AgoraStreamSubscribeState。
- newState
- 当前的订阅状态,详见 AgoraStreamSubscribeState。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
reportAudioVolumeIndicationOfSpeakers
用户音量提示回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine reportAudioVolumeIndicationOfSpeakers:(NSArray<AgoraRtcAudioVolumeInfo *> * _Nonnull)speakers totalVolume:(NSInteger)totalVolume;
该回调默认禁用,你可以通过 enableAudioVolumeIndication 开启。 开启后,只要频道内有发流用户,SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。每次会触发两个 reportAudioVolumeIndicationOfSpeakers 回调,一个报告本地发流用户的音量相关信息,另一个报告瞬时音量最高的远端用户(最多 3 位)的音量相关信息。
启用该功能后,如果有用户将自己静音(调用了 muteLocalAudioStream),SDK 会继续报告本地用户的音量提示回调。
瞬时音量最高的远端用户静音后 20 秒,远端的音量提示回调中将不再包含该用户;如果远端所有用户都将自己静音,20 秒后 SDK 停止报告远端用户的音量提示回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- speakers
- 用户音量信息,详见 AgoraRtcAudioVolumeInfo 数组。如果 speakers 为空,则表示远端用户不发流或没有远端用户。
- totalVolume
-
混音后的总音量,取值范围为 [0,255]。
- 在本地用户的回调中,totalVolume 为本地发流用户的音量。
- 在远端用户的回调中,totalVolume 为瞬时音量最高的远端用户(最多 3 位)混音后的总音量。 如果用户调用了 startAudioMixing [2/2],则 totalVolume 为音乐文件和用户声音的总音量。
cameraExposureDidChangedToRect
摄像头曝光区域已改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine cameraExposureDidChangedToRect:(CGRect)rect;
该回调是由本地用户调用 setCameraExposurePosition 方法改变曝光位置触发的。
参数
- engine
- AgoraRtcEngineKit 对象。
- rect
- 镜头内表示曝光的区域。
cameraFocusDidChangedToRect
相机对焦区域已改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine cameraFocusDidChangedToRect:(CGRect)rect;
该回调是由本地用户调用 setCameraFocusPositionInPreview 方法改变对焦位置触发的。
参数
- rect
- 镜头内表示对焦的区域。
- engine
- AgoraRtcEngineKit 对象。
rtcEngineCameraDidReady
摄像头就绪回调。
- (void)rtcEngineCameraDidReady:(AgoraRtcEngineKit * _Nonnull)engine;
- 弃用:
-
请改用 localVideoStateChangedOfState 中的 AgoraVideoLocalStateCapturing(1)。
该回调提示已成功打开摄像头,可以开始捕获视频。
参数
- engine
- AgoraRtcEngineKit 对象。
didReceiveChannelMediaRelayEvent
跨频道媒体流转发事件回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didReceiveChannelMediaRelayEvent:(AgoraChannelMediaRelayEvent)event;
参数
- engine
- AgoraRtcEngineKit 对象。
- event
-
跨频道媒体流转发事件码。详见 AgoraChannelMediaRelayEvent。
channelMediaRelayStateDidChange
跨频道媒体流转发状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine channelMediaRelayStateDidChange:(AgoraChannelMediaRelayState)state error:(AgoraChannelMediaRelayError)error;
当跨频道媒体流转发状态发生改变时,SDK 会触发该回调,并报告当前的转发状态以及相关的错误信息。
参数
- engine
- AgoraRtcEngineKit 对象。
- state
-
跨频道媒体流转发状态。详见 AgoraChannelMediaRelayState。
- code
-
跨频道媒体流转发出错的错误码。详见 AgoraChannelMediaRelayError。
didClientRoleChanged
直播场景下用户角色已切换回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChanged: (AgoraClientRole)oldRole newRole:(AgoraClientRole)newRole;
该回调是由本地用户在加入频道后调用 setClientRole [1/2] 改变用户角色触发的。
参数
- engine
- AgoraRtcEngineKit 对象。
- oldRole
- 切换前的角色:AgoraClientRole。
- newRole
- 切换后的角色:AgoraClientRole。
didClientRoleChangeFailed
直播场景下切换用户角色失败回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didClientRoleChangeFailed:(AgoraClientRoleChangeFailedReason)reason currentRole:(AgoraClientRole)currentRole;
直播场景下,本地用户加入频道后调用 setClientRole [1/2] 切换用户角色失败时,SDK 会触发该回调,报告切换失败的原因和当前的用户角色。
参数
- reason
- 切换用户角色失败的原因。详见 AgoraClientRoleChangeFailedReason。
- currentRole
- 当前用户角色。详见 AgoraClientRole。
rtcEngineConnectionDidBanned
网络连接已被服务器禁止回调。
- (void)rtcEngineConnectionDidBanned:(AgoraRtcEngineKit * _Nonnull)engine;
- 弃用:
- 请改用 connectionChangedToState。
参数
- engine
- AgoraRtcEngineKit 对象。
rtcEngineConnectionDidInterrupted
网络连接中断回调。
- (void)rtcEngineConnectionDidInterrupted:(AgoraRtcEngineKit * _Nonnull)engine;
- 弃用:
- 请改用 connectionChangedToState 回调。
- rtcEngineConnectionDidInterrupted 回调一定是发生在成功加入频道后,且 SDK 刚失去和服务器连接超过 4 秒时触发。
- rtcEngineConnectionDidLost 回调是无论是否成功加入频道,只要 10 秒内和服务器无法建立连接都会触发。
参数
- engine
- AgoraRtcEngineKit 对象。
rtcEngineConnectionDidLost
网络连接中断,且 SDK 无法在 10 秒内连接服务器回调。
- (void)rtcEngineConnectionDidLost:(AgoraRtcEngineKit * _Nonnull)engine;
SDK 在调用 joinChannelByToken [2/4] 后,无论是否加入成功,只要 10 秒和服务器无法连接就会触发该回调。如果 SDK 在断开连接后,20 分钟内还是没能重新加入频道,SDK 会停止尝试重连。
参数
- engine
- AgoraRtcEngineKit 对象。
connectionChangedToState
网络连接状态已改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine connectionStateChanged:(AgoraConnectionState)state reason:(AgoraConnectionChangedReason)reason;
该回调在网络连接状态发生改变的时候触发,并告知用户当前的网络连接状态和引起网络状态改变的原因。
参数
- engine
- AgoraRtcEngineKit 对象。
- state
-
当前网络连接状态。详见 AgoraConnectionState。
- reason
-
引起当前网络连接状态改变的原因。详见 AgoraConnectionChangedReason。
contentInspectResult
视频内容审核结果回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine contentInspectResult:(AgoraContentInspectResult)result;
调用 enableContentInspect 启用视频内容审核服务,并设置 AgoraContentInspectConfig 中的 type 为 AgoraContentInspectTypeModeration 后,SDK 会触发 contentInspectResult 回调,报告鉴黄结果。
参数
- result
- 鉴黄结果。详见 AgoraContentInspectResult。
didOccurEncryptionError
内置加密出错回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurEncryptionError:(AgoraEncryptionErrorType)errorType;
调用 enableEncryption 开启加密后, 如果发流端、收流端出现加解密出错,SDK 会触发该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- errorType
- 错误类型,详见 AgoraEncryptionErrorType。
didOccurError
发生错误回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurError:(AgoraErrorCode)errorCode;
该回调方法表示 SDK 运行时出现了网络或媒体相关的错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 app 干预或提示用户。
参数
- engine
- AgoraRtcEngineKit 对象。
- errorCode
- 错误码。详见 AgoraErrorCode。
facePositionDidChangeWidth
报告本地人脸检测结果。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine facePositionDidChangeWidth:(int)width previewHeight:(int)height faces:(NSArray<AgoraFacePositionInfo*>* _Nullable)faces NS_SWIFT_NAME(rtcEngine(_:facePositionDidChangeWidth:previewHeight:faces:));
enableFaceDetection(YES)
开启本地人脸检测后,你可以通过该回调实时获取以下人脸检测的信息:
- 摄像头采集的画面大小
- 人脸在 view 中的位置
- 人脸距设备屏幕的距离
其中,人脸距设备屏幕的距离由 SDK 通过摄像头采集的画面大小和人脸在 view 中的位置拟合计算得出。
- 当检测到摄像头前的人脸消失时,该回调会立刻触发;在无人脸的状态下,该回调触发频率会降低,以节省设备耗能。
- 当人脸距离设备屏幕过近时,SDK 不会触发该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- width
- 摄像头采集画面的宽度 (px)。
- hight
- 摄像头采集画面的高度 (px)。
- faces
- 检测到的人脸信息,详见 AgoraFacePositionInfo。检测到几张人脸,就会报告几个 AgoraFacePositionInfo 数组。数组长度可以为 0,表示没有检测到摄像头前出现人脸。
firstLocalAudioFramePublished
已发布本地音频首帧回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstLocalAudioFramePublished:(NSInteger)elapsed;
- 开启本地音频的情况下,调用 joinChannelByToken [2/4] 成功加入频道后。
- 调用
muteLocalAudioStream(
,再调用YES
)muteLocalAudioStream(
后。NO
) - 调用 disableAudio,再调用 enableAudio 后。
- 调用 pushExternalAudioFrameNSData 成功向 SDK 推送音频帧后。
参数
- engine
- AgoraRtcEngineKit 对象。
- elapsed
- 从调用 joinChannelByToken [2/4] 方法到触发该回调的时间间隔(毫秒)。
firstLocalVideoFramePublishedWithElapsed
已发布本地视频首帧回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstLocalVideoFramePublishedWithElapsed:(NSInteger)elapsed sourceType:(AgoraVideoSourceType)sourceType;
- 开启本地视频的情况下,调用 joinChannelByToken [2/4] 成功加入频道后。
- 调用 muteLocalVideoStream(
YES
),再调用 muteLocalVideoStream(NO
) 后。 - 调用 disableVideo,再调用 enableVideo 后。
- 调用 pushExternalVideoFrame 成功向 SDK 推送视频帧后。
参数
- engine
- AgoraRtcEngineKit 对象。
- sourceType
- 视频源的类型。详见 AgoraVideoSourceType。
- elapsed
- 从调用 joinChannelByToken [2/4] 方法到触发该回调的时间间隔(毫秒)。
firstRemoteAudioFrameOfUid
已接收远端音频首帧回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine firstRemoteAudioFrameOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed NS_SWIFT_NAME(rtcEngine(_:firstRemoteAudioFrameOfUid:elapsed:));
- 弃用:
- 请改用 remoteAudioStateChangedOfUid 。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 发送音频帧的远端用户的用户 ID。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 直至该回调触发的延迟,单位为毫秒。
firstRemoteAudioFrameDecodedOfUid
已解码远端音频首帧的回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine firstRemoteAudioFrameDecodedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;
- 弃用:
- 请改用 remoteAudioStateChangedOfUid 。
- 远端用户首次上线后发送音频。
- 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包,可能有如下原因:
- 远端用户离开频道
- 远端用户掉线
- 远端用户调用 muteLocalAudioStream 方法停止发送音频流
- 远端用户调用 disableAudio 方法关闭音频
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 远端用户 ID。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 直至该回调触发的延迟,单位为毫秒。
firstRemoteVideoDecodedOfUid
已接收到远端视频并完成解码回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstRemoteVideoDecodedOfUid:(NSUInteger)uid size:(CGSize)size elapsed:(NSInteger)elapsed;
- 远端用户首次上线后发送视频。
- 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括:
- 远端用户离开频道。
- 远端用户掉线。
- 远端用户调用 muteLocalVideoStream 方法停止发送本地视频流。
- 远端用户调用 disableVideo 方法关闭视频模块。
参数
- uid
- 用户 ID,指定是哪个用户的视频流。
- engine
- AgoraRtcEngineKit 对象。
- size
- 视频流尺寸。
- elapsed
- 从本地调用 joinChannelByToken [2/4] 开始到该回调触发的延迟(毫秒)。
firstRemoteVideoFrameOfUid
渲染器已接收首帧远端视频回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine firstRemoteVideoFrameOfUid:(NSUInteger)uid size:(CGSize)size elapsed:(NSInteger)elapsed;
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID,指定是哪个用户的视频流。
- size
- 视频流尺寸。
- elapsed
- 从本地调用 joinChannelByToken [2/4] 到发生此事件过去的时间(毫秒)。
didJoinChannel
成功加入频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;
该回调方法表示该客户端成功加入了指定的频道。
参数
- engine
- AgoraRtcEngineKit 对象。
- channel
- 频道名。
- uid
- 加入频道的用户 ID。
- elapsed
- 从本地调用 joinChannelByToken [2/4] 开始到发生此事件过去的时间(毫秒)。
lastmileProbeTestResult
通话前网络上下行 Last mile 质量探测报告回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine lastmileProbeTestResult:(AgoraLastmileProbeResult * _Nonnull)result;
在调用 startLastmileProbeTest 之后,SDK 会在约 30 秒内返回该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- result
- 上下行 Last mile 质量探测结果。 详见: AgoraLastmileProbeResult。
lastmileQuality
网络上下行 last mile 质量报告回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine lastmileQuality:(AgoraNetworkQuality)quality;
该回调描述本地用户在加入频道前的 last mile 网络探测的结果,其中 last mile 是指设备到 Agora 边缘服务器的网络状态。
加入频道前,调用 startLastmileProbeTest 之后,SDK 触发该回调报告本地用户在加入频道前的 last mile 网络探测的结果。
参数
- engine
- AgoraRtcEngineKit 对象。
- quality
- Last mile 网络质量。详见 AgoraNetworkQuality 。
didLeaveChannelWithStats
离开频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLeaveChannelWithStats:(AgoraChannelStats * _Nonnull)stats;
App 调用 leaveChannel [1/2] 方法时,SDK 提示 app 离开频道成功。在该回调方法中,app 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
- 通话的统计数据: AgoraChannelStats。
localAudioStateChanged
本地音频状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localAudioStateChanged:(AgoraAudioLocalState)state error:(AgoraAudioLocalError)error;
本地音频的状态发生改变时(包括本地麦克风采集状态和音频编码状态),SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时,该回调可以帮助你了解当前音频的状态以及出现故障的原因,方便你排查问题。
参数
- engine
- AgoraRtcEngineKit 对象。
- state
- 当前的本地音频状态。详见 AgoraAudioLocalState。
- error
- 本地音频出错原因。详见 AgoraAudioLocalError。
localAudioStats
通话中本地音频流的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localAudioStats:(AgoraRtcLocalAudioStats * _Nonnull)stats;
SDK 每 2 秒触发该回调一次。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
- 本地音频统计数据。详见 AgoraRtcLocalAudioStats。
didLocalUserRegisteredWithUserId
本地用户成功注册 User Account 回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLocalUserRegisteredWithUserId:(NSUInteger)uid userAccount:(NSString * _Nonnull)userAccount;
本地用户成功调用 registerLocalUserAccountWithAppID 方法注册用户 User Account,或调用 joinChannelByToken [4/4] 加入频道后,SDK 会触发该回调,并告知本地用户的 UID 和 User Account。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 本地用户的 ID。
- userAccount
- 本地用户的 User Account。
localVideoStateChangedOfState
本地视频状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localVideoStateChangedOfState:(AgoraVideoLocalState)state error:(AgoraLocalVideoStreamError)error sourceType:(AgoraVideoSourceType)sourceType;
本地视频的状态发生改变时,SDK 会触发该回调返回当前的本地视频状态。你可以通过该回调了解当前视频的状态以及出现故障的原因,方便排查问题。
AgoraVideoLocalStateFailed
,错误码为 AgoraLocalVideoStreamErrorCaptureFailure
:
- 应用退到后台,系统回收摄像头。
- 摄像头正常启动,但连续 4 秒都没有输出采集的视频。
摄像头输出采集的视频帧时,如果连续 15 帧中,所有视频帧都一样,SDK 触发 localVideoStateChangedOfState 回调,状态为 AgoraVideoLocalStateCapturing,错误码为 AgoraLocalVideoStreamErrorCaptureFailure。注意,帧重复检测仅针对分辨率大于 200 × 200、帧率大于等于 10 fps、码率小于 20 Kbps 的视频帧。
参数
- engine
- AgoraRtcEngineKit 对象。
- sourceType
- 视频源的类型。详见 AgoraVideoSourceType。
- state
-
本地视频状态,详见 AgoraVideoLocalState。
- error
-
本地视频出错原因,详见 AgoraLocalVideoStreamError。
localVideoStats
本地视频流统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine localVideoStats:(AgoraRtcLocalVideoStats * _Nonnull)stats sourceType:(AgoraVideoSourceType)sourceType;
该回调描述本地设备发送视频流的统计信息,每 2 秒触发一次。
参数
- engine
- AgoraRtcEngineKit 对象。
- sourceType
- 视频源的类型。详见 AgoraVideoSourceType。
- stats
- 本地视频流统计信息。详见 AgoraRtcLocalVideoStats。
rtcEngineMediaEngineDidLoaded
媒体引擎成功加载的回调。
- (void)rtcEngineMediaEngineDidLoaded:(AgoraRtcEngineKit * _Nonnull)engine;
参数
- engine
- AgoraRtcEngineKit 对象。
rtcEngineMediaEngineDidStartCall
媒体引擎成功启动的回调。
- (void)rtcEngineMediaEngineDidStartCall:(AgoraRtcEngineKit * _Nonnull)engine;
参数
- engine
- AgoraRtcEngineKit 对象。
networkQuality
通话中每个用户的网络上下行 last mile 质量报告回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine networkQuality:(NSUInteger)uid txQuality:(AgoraNetworkQuality)txQuality rxQuality:(AgoraNetworkQuality)rxQuality;
该回调描述每个用户在通话中的 last mile 网络状态,其中 last mile 是指设备到 Agora 边缘服务器的网络状态。
该回调每 2 秒触发一次。如果远端有多个用户,该回调每 2 秒会被触发多次。
Unknown
;用户不收流时,rxQuality 为 Unknown
。参数
- engine
- AgoraRtcEngineKit 对象。
- uid
-
用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。
- txQuality
- 该用户的上行网络质量,基于发送码率、上行丢包率、平均往返时延和网络抖动计算。 该值代表当前的上行网络质量,帮助判断是否可以支持当前设置的视频编码属性。 假设上行码率是 1000 Kbps,那么支持直播场景下 640 × 480 的分辨率、15 fps 的帧率没有问题,但是支持 1280 × 720 的分辨率就会有困难。 详见 AgoraNetworkQuality。
- rxQuality
- 该用户的下行网络质量,基于下行网络的丢包率、平均往返延时和网络抖动计算。详见 AgoraNetworkQuality。
networkTypeChangedToType
本地网络类型发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine networkTypeChanged:(AgoraNetworkType)type;
本地网络连接类型发生改变时,SDK 会触发该回调,并在回调中明确当前的网络连接类型。 你可以通过该回调获取正在使用的网络类型;当连接中断时,该回调能辨别引起中断的原因是网络切换还是网络条件不好。
参数
- engine
- AgoraRtcEngineKit 对象。
- type
-
本地网络连接类型。详见 AgoraNetworkType。
permissionError
获取设备权限出错回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine permissionError:(AgoraPermissionType)type;
无法获取设备权限时,SDK 会触发该回调,报告哪个设备的权限无法获取。
参数
- engine
- AgoraRtcEngineKit 对象。
- type
- 设备权限类型。详见 AgoraPermissionType。
didRejoinChannel
成功重新加入频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didRejoinChannel:(NSString * _Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger) elapsed;
有时候由于网络原因,客户端可能会和服务器失去连接,SDK 会进行自动重连,自动重连成功后触发此回调方法。
参数
- engine
- AgoraRtcEngineKit 对象。
- channel
- 频道名。
- uid
- 重新加入频道的用户 ID。
- elapsed
- 从调用 joinChannelByToken [1/4] 或 joinChannelByToken [2/4] 方法到触发该回调的时间间隔(毫秒)。
remoteAudioStateChangedOfUid
远端音频流状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteAudioStateChangedOfUid:(NSUInteger)uid state:(AgoraAudioRemoteState)state reason:(AgoraAudioRemoteReason)reason elapsed:(NSInteger)elapsed;
远端用户(通信场景)或主播(直播场景)的音频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端音频流状态。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 发生音频状态改变的远端用户 ID。
- state
- 远端音频流状态,详见 AgoraAudioRemoteState。
- reason
- 远端音频流状态改变的具体原因,详见 AgoraAudioRemoteReason。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 方法到发生本事件经历的时间,单位为毫秒。
remoteAudioStats
通话中远端音频流的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteAudioStats:(AgoraRtcRemoteAudioStats * _Nonnull)stats;
该回调针对每个发送音频流的远端用户/主播每 2 秒触发一次。如果远端有多个用户/主播发送音频流,该回调每 2 秒会被触发多次。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
- 接收到的远端音频统计数据,详见 AgoraRtcRemoteAudioStats。
audioTransportStatsOfUid
通话中远端音频流传输的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine audioTransportStatsOfUid:(NSUInteger)uid delay:(NSUInteger)delay lost:(NSUInteger)lost rxKBitRate:(NSUInteger)rxKBitRate;
- 弃用:
- 请改用 remoteAudioStats。
该回调描述远端用户通话中端到端的网络统计信息,通过音频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。通话中,当用户收到远端用户/主播发送的音频数据包后 ,会每 2 秒触发一次该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID,指定是哪个用户/主播的音频包。
- delay
- 音频包从发送端到接收端的延时(毫秒)。
- lost
- 音频包从发送端到接收端的丢包率 (%)。
- rxKBitrate
- 远端音频包的接收码率(Kbps)。
remoteVideoStateChangedOfUid
远端视频状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteVideoStateChangedOfUid:(NSUInteger)uid state:(AgoraVideoRemoteState)state reason:(AgoraVideoRemoteReason)reason elapsed:(NSInteger)elapsed;
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 发生视频状态改变的远端用户 ID。
- state
-
远端视频流状态,详见 AgoraVideoRemoteState。
- reason
-
远端视频流状态改变的具体原因,详见 AgoraVideoRemoteReason。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 方法到发生本事件经历的时间,单位为毫秒。
remoteVideoStats
通话中远端视频流的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine remoteVideoStats:(AgoraRtcRemoteVideoStats * _Nonnull)stats;
该回调描述远端用户在通话中端到端的视频流统计信息, 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播, 该回调每 2 秒会被触发多次。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
- 远端视频统计数据。详见 AgoraRtcRemoteVideoStats。
videoTransportStatsOfUid
通话中远端视频流传输的统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine videoTransportStatsOfUid:(NSUInteger)uid delay:(NSUInteger)delay lost:(NSUInteger)lost rxKBitRate:(NSUInteger)rxKBitRate;
- 弃用:
- 该回调已被废弃,请改用 remoteVideoStats。
该回调描述远端用户通话中端到端的网络统计信息,通过视频包计算,用客观的数据,如丢包、 网络延迟等,展示当前网络状态。
通话中,当用户收到远端用户/主播发送的视频数据包后,会每 2 秒触发一次该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID,指定是哪个用户/主播的视频包。
- delay
- 视频包从发送端到接收端的延时(毫秒)。
- lost
- 视频包从发送端到接收端的丢包率 (%)。
- rxKBitRate
- 远端视频包的接收码率(Kbps)。
rtcEngineRequestToken
Token 已过期回调。
- (void)rtcEngineRequestToken:(AgoraRtcEngineKit * _Nonnull)engine;
在通话过程中如果 Token 已失效,SDK 会触发该回调,提醒 app 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 joinChannelByToken [2/4] 重新加入频道。
参数
- engine
- AgoraRtcEngineKit 对象。
reportRtcStats
当前通话统计信息回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine reportRtcStats:(AgoraChannelStats * _Nonnull)stats;
SDK 定期向 App 报告当前通话的统计信息,每两秒触发一次。
参数
- engine
- AgoraRtcEngineKit 对象。
- stats
-
RTC 引擎统计数据,详见 AgoraChannelStats 。
rtmpStreamingEventWithUrl
旁路推流事件回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine rtmpStreamingEventWithUrl:(NSString* _Nonnull)url eventCode:(AgoraRtmpStreamingEvent)eventCode;
参数
- url
- 旁路推流 URL。
- eventCode
- 旁路推流事件码。详见 AgoraRtmpStreamingEvent。
rtmpStreamingChangedToState
旁路推流状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine rtmpStreamingChangedToState:(NSString* _Nonnull)url state:(AgoraRtmpStreamingState)state errCode:(AgoraRtmpStreamingErrorCode)errCode;
旁路推流状态发生改变时,SDK会触发该回调,并在回调中明确状态发生改变的 URL 地址及当前推流状态。该回调方便推流用户了解当前的推流状态;推流出错时,你可以通过返回的错误码了解出错的原因,方便排查问题。
参数
- engine
- AgoraRtcEngineKit 对象。
- url
-
推流状态发生改变的 URL 地址。
- state
- 当前的推流状态,详见 AgoraRtmpStreamingState。
- errCode
- 推流错误信息,详见 AgoraRtmpStreamingErrorCode。
snapshotTaken
视频截图结果回调。
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine snapshotTaken:(NSUInteger)uid filePath:(NSString* _Nonnull)filePath width:(NSInteger)width height:(NSInteger)height errCode:(NSInteger)errCode;
成功调用 takeSnapshot 后,SDK 触发该回调报告截图是否成功和获取截图的详情。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID。如果 uid 为 0,表示本地用户。
- filePath
- 截图的本地保存路径。
- width
- 图片宽度(px)。
- height
- 图片高度(px)。
- errCode
- 截图成功的提示或失败的原因。
- 0:截图成功。
- < 0: 截图失败。
- -1:写入文件失败或 JPEG 编码失败。
- -2:takeSnapshot 方法调用成功后 1 秒内没有发现指定用户的视频流。
- -3:takeSnapshot 方法调用过于频繁。
receiveStreamMessageFromUid
接收到对方数据流消息的回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine receiveStreamMessageFromUid:(NSUInteger)uid streamId:(NSInteger)streamId data:(NSData * _Nonnull)data;
该回调表示本地用户收到了远端用户调用 sendStreamMessage 方法发送的流消息。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 发送消息的用户 ID。
- streamId
- 接收到的消息的 Stream ID。
- data
- 接收到的数据。
didOccurStreamMessageErrorFromUid
接收对方数据流消息发生错误的回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOccurStreamMessageErrorFromUid:(NSUInteger)uid streamId:(NSInteger)streamId error:(NSInteger)error missed:(NSInteger)missed cached:(NSInteger)cached;
该回调表示本地用户未收到远端用户调用 sendStreamMessage 方法发送的流消息。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 发送消息的用户 ID。
- streamId
- 接收到的消息的 Stream ID。
- error
- 发生错误的错误码。
- missed
- 丢失的消息数量。
- cached
- 数据流中断时,后面缓存的消息数量。
tokenPrivilegeWillExpire
Token 服务将在30s内过期回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine tokenPrivilegeWillExpire:(NSString *_Nonnull)token;
在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒 app 更新 Token。
当收到该回调时,你需要重新在服务端生成新的 Token,然后调用 renewToken 将新生成的 Token 传给 SDK。
参数
- engine
- AgoraRtcEngineKit 对象。
- token
- 即将服务失效的 Token。
rtcEngineTranscodingUpdated
旁路推流转码设置已被更新回调。
- (void)rtcEngineTranscodingUpdated:(AgoraRtcEngineKit * _Nonnull)engine;
setLiveTranscoding 方法中的直播参数 AgoraLiveTranscoding 更新时,rtcEngineTranscodingUpdated 回调会被触发并向主播报告更新信息。
参数
- engine
- AgoraRtcEngineKit 对象。
uplinkNetworkInfoUpdate
上行网络信息变化回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine uplinkNetworkInfoUpdate:(AgoraUplinkNetworkInfo *_Nonnull)networkInfo;
只有当上行网络信息发生变化时,SDK 才会触发该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- networkInfo
- 上行网络信息,详见 AgoraUplinkNetworkInfo。
didLocalVideoEnabled
远端用户开/关本地视频采集回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didLocalVideoEnabled:(BOOL)enabled byUid:(NSUInteger)uid
该回调是由远端用户调用 enableLocalVideo 方法开启或关闭视频采集触发的。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID,提示是哪个用户的视频流。
- enabled
-
远端用户是否启用视频采集:
-
YES
: 该用户已启用视频功能。启用后,其他用户可以接收到该用户的视频流。 -
NO
: 该用户已关闭视频功能。关闭后,该用户仍然可以接收其他用户的视频流,但其他用户接收不到该用户的视频流。
-
didVideoEnabled
远端用户开/关视频模块回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didVideoEnabled:(BOOL)enabled byUid:(NSUInteger)uid
关闭视频功能是指该用户只能进行语音通话,不能显示、发送自己的视频,也不能接收、显示别人的视频。
该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 用户 ID,提示是哪个用户的视频流。
- enabled
-
-
YES
: 该用户已启用视频功能。 -
NO
: 该用户已关闭视频功能。
-
didUserInfoUpdatedWithUserId
远端用户信息已更新回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didUserInfoUpdatedWithUserId:(NSUInteger)uid userInfo:(AgoraUserInfo* _Nonnull)userInfo;
远端用户加入频道后, SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发该回调。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 远端用户 ID。
- userInfo
- 标识用户信息的 UserInfo 对象,包含用户 UID 和 User Account。详见 AgoraUserInfo 类。
didJoinedOfUid
远端用户(通信场景)/主播(直播场景)加入当前频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed;
- 通信场景下,该回调提示有远端用户加入了频道。如果加入之前,已经有其他用户在频道中了,新加入的用户也会收到这些已有用户加入频道的回调。
- 直播场景下,该回调提示有主播加入了频道。如果加入之前,已经有主播在频道中了,新加入的用户也会收到已有主播加入频道的回调。Agora 建议连麦主播不超过 17 人。
- 远端用户/主播调用 joinChannelByToken [2/4] 方法加入频道。
- 远端用户加入频道后将用户角色改变为主播。
- 远端用户/主播网络中断后重新加入频道。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 新加入频道的远端用户/主播 ID。
- elapsed
- 从本地用户调用 joinChannelByToken [2/4] 到该回调触发的延迟(毫秒)。
didAudioMuted
远端用户(通信场景)/主播(直播场景)停止或恢复发送音频流回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didAudioMuted:(BOOL)muted byUid:(NSUInteger)uid;
该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。
参数
- uid
- 用户 ID。
- muted
- 该用户是否静音:
YES
: 该用户已将音频静音。NO
: 该用户取消了音频静音。
didVideoMuted
远端用户取消或恢复发布视频流回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didVideoMuted:(BOOL)muted byUid:(NSUInteger)uid
当远端用户调用 muteLocalVideoStream 取消或恢复发布视频流时,SDK 会触发该回调向本地用户报告远端用户的发流状况。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 远端用户 ID。
- muted
- 远端用户是否取消发布视频流:
YES
: 取消发布视频流。NO
: 发布视频流。
didOfflineOfUid
远端用户(通信场景)/主播(直播场景)离开当前频道回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didOfflineOfUid:(NSUInteger)uid reason:(AgoraUserOfflineReason)reason;
- 正常离开:远端用户/主播会发送类似“再见”的消息。接收此消息后,判断用户离开频道。
- 超时掉线:在一定时间内(通信场景为 20 秒,直播场景稍有延时),用户没有收到对方的任何数据包,则判定为对方掉线。在网络较差的情况下,有可能会误报。我们建议使用 Agora 云信令 SDK 来做可靠的掉线检测。
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 离线用户或主播的用户 ID。
- reason
-
离线原因: AgoraUserOfflineReason。
didVideoPublishStateChange
视频发布状态改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didVideoPublishStateChange:(NSString * _Nonnull)channelId sourceType:(AgoraVideoSourceType)sourceType oldState:(AgoraStreamPublishState)oldState newState:(AgoraStreamPublishState)newState elapseSinceLastState:(int)elapseSinceLastState;
参数
- engine
- AgoraRtcEngineKit 对象。
- channelId
- 频道名。
- sourceType
- 视频源的类型。详见 AgoraVideoSourceType。
- oldState
- 之前的发布状态,详见 AgoraStreamPublishState。
- newState
- 当前的发布状态,详见 AgoraStreamPublishState。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。
videoSizeChangedOfUid
本地或远端视频大小和旋转信息发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine videoSizeChangedOfUid:(NSUInteger)uid size:(CGSize)size rotation:(NSInteger)rotation;
参数
- engine
- AgoraRtcEngineKit 对象。
- uid
- 图像尺寸和旋转信息发生变化的用户 ID(本地用户的 uid 为 0。此时视频为本地用户的视频预览)。
- size
- 视频流的尺寸。
- rotation
- 旋转信息,取值范围 [0,360)。
rtcEngineVideoDidStop
视频功能已停止回调。
- (void)rtcEngineVideoDidStop:(AgoraRtcEngineKit * _Nonnull)engine;
- 弃用:
- 请改用 localVideoStateChangedOfState 回调中的 AgoraVideoLocalStateStopped(0)。
App 如需在停止视频后对 view 做其他处理(比如显示其他画面),可以在这个回调中进行。
参数
- engine
- AgoraRtcEngineKit 对象。
didVideoSubscribeStateChange
视频订阅状态发生改变回调。
- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didVideoSubscribeStateChange:(NSString * _Nonnull)channelId uid:(unsigned int)uid oldState:(AgoraStreamSubscribeState)oldState newState:(AgoraStreamSubscribeState)newState elapseSinceLastState:(int)elapseSinceLastState;
参数
- engine
- AgoraRtcEngineKit 对象。
- channel
- 频道名。
- uid
- 远端用户的 ID。
- oldState
- 之前的订阅状态,详见 AgoraStreamSubscribeState。
- newState
- 当前的订阅状态,详见 AgoraStreamSubscribeState。
- elapseSinceLastState
- 两次状态变化时间间隔(毫秒)。