AgoraRtcEngineDelegate Protocol Reference

Conforms to NSObject
Declared in AgoraRtcEngineKit.h

Overview

AgoraRtcEngineDelegate 接口类采用 Delegate 方法用于向 App 发送回调通知。

SDK 会通过代理方法 AgoraRtcEngineDelegate 向 App 上报一些运行时的事件。从 1.1 版本开始,SDK 使用 Delegate 代替原有的部分 Block 回调。 原有的 Block 回调被标为废弃,目前仍然可以使用,但是建议用相应的 Delegate 方法代替。如果同一个回调 Block 和 Delegate 方法都有定义,则 SDK 只回调 Block 方法。

核心事件回调

– rtcEngine:didOccurWarning:

发生警告回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didOccurWarning:(AgoraWarningCode)warningCode

Parameters

engine

AgoraRtcEngineKit 对象

warningCode

AgoraWarningCode

Discussion

该回调方法表示 SDK 运行时出现了(网络或媒体相关的)警告。通常情况下,SDK 上报的警告信息 App 可以忽略,SDK 会自动恢复。比如和服务器失去连接时,SDK 可能会上报 AgoraWarningCodeOpenChannelTimeout(106) 警告,同时自动尝试重连。

详细的警告代码,见 AgoraWarningCode

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didOccurError:

发生错误回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didOccurError:(AgoraErrorCode)errorCode

Parameters

engine

AgoraRtcEngineKit 对象

errorCode

AgoraErrorCode

Discussion

该回调方法表示 SDK 运行时出现了(网络或媒体相关的)错误。通常情况下,SDK 上报的错误意味着 SDK 无法自动恢复,需要 App 干预或提示用户。 比如启动通话失败时,SDK 会上报 AgoraErrorCodeStartCall = 1002 错误。App 可以提示用户启动通话失败,并调用 leaveChannel 退出频道。

详细的错误代码,见 AgoraErrorCode

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didApiCallExecute:api:result:

API 方法已执行回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didApiCallExecute:(NSInteger)error api:(NSString *_Nonnull)api result:(NSString *_Nonnull)result

Parameters

engine

AgoraRtcEngineKit 对象

error

错误码。如果方法调用失败,会返回错误码 (AgoraErrorCode)。

api

SDK 所调用的 API

result

SDK 调用 API 的调用结果

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didJoinChannel:withUid:elapsed:

加入频道回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didJoinChannel:(NSString *_Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

channel

频道名称

uid

用户ID。 如果在joinChannelByToken方法中指定了 uid,它会返回指定的 ID; 如果没有,它将返回由声网服务器自动分配的 ID。

elapsed

从调用joinChannelByToken开始到发生此事件过去的时间(ms)。

Discussion

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didRejoinChannel:withUid:elapsed:

重新加入频道回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didRejoinChannel:(NSString *_Nonnull)channel withUid:(NSUInteger)uid elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

channel

频道名称

uid

用户ID。 如果在joinChannelByToken方法中指定了 uid,它会返回指定的 ID; 如果没有,它将返回由声网服务器自动分配的 ID。

elapsed

从开始重连到重连成功的时间(ms)。

Discussion

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didLeaveChannelWithStats:

已离开频道回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didLeaveChannelWithStats:(AgoraChannelStats *_Nonnull)stats

Parameters

engine

AgoraRtcEngineKit 对象

stats

通话相关的统计信息:AgoraChannelStats

Discussion

当用户调用 leaveChannel 离开频道后,SDK 会触发该回调。在该回调方法中,App 可以得到此次通话的总通话时长、SDK 收发数据的流量等信息。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didRegisteredLocalUser:withUid:

本地用户成功注册 User Account 回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didRegisteredLocalUser:(NSString *_Nonnull)userAccount withUid:(NSUInteger)uid

Parameters

engine

AgoraRtcEngineKit 对象

userAccount

本地用户的 User Account

uid

本地用户的 UID

Discussion

本地用户成功调用 registerLocalUserAccount 方法注册用户 User Account 或调用 joinChannelByUserAccount 加入频道后,SDK 会触发该回调,并告知本地用户的 UID 和 User Account。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didUpdatedUserInfo:withUid:

远端用户信息已更新回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didUpdatedUserInfo:(AgoraUserInfo *_Nonnull)userInfo withUid:(NSUInteger)uid

Parameters

engine

AgoraRtcEngineKit 对象

userInfo

标识用户信息的 AgoraUserInfo 对象,包含用户 UID 和 User Account

uid

用户的 UID

Discussion

远端用户加入频道后, SDK 会获取到该用户的 UID 和 User Account,然后缓存一个包含了用户 UID 和 User Account 的映射表,并在本地触发该回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didClientRoleChangeFailed:currentRole:

直播场景下切换用户角色失败回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didClientRoleChangeFailed:(AgoraClientRoleChangeFailedReason)reason currentRole:(AgoraClientRole)currentRole

Parameters

engine

AgoraRtcEngineKit 对象

reason

切换用户角色失败的原因。详见 AgoraClientRoleChangeFailedReason

currentRole

当前的用户角色。详见 AgoraClientRole

Availability

v3.7.0

直播场景下,本地用户加入频道后调用 setClientRole 切换用户角色失败时,SDK 会触发该回调,报告切换失败的原因和当前的用户角色。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didClientRoleChanged:newRole:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didClientRoleChanged:(AgoraClientRole)oldRole newRole:(AgoraClientRole)newRole

Parameters

engine

AgoraRtcEngineKit 对象

oldRole

切换前的角色

newRole

切换后的角色

Discussion

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didJoinedOfUid:elapsed:

远端用户/主播加入回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

uid

新加入频道的远端用户/主播 ID。如果 joinChannelByToken 中指定了 uid,则此处返回该 ID;否则使用声网服务器自动分配的 ID。

elapsed

从本地用户加入频道 joinChannelByTokenjoinChannelByUserAccount 开始到发生此事件过去的时间(ms)。

Discussion

userJoinedBlock

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

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

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

Note:

直播场景下,

  • 主播间能相互收到新主播加入频道的回调,并能获得该主播的 uid
  • 观众也能收到新主播加入频道的回调,并能获得该主播的 uid
  • 当 Web 端加入直播频道时,只要 Web 端有推流,SDK 会默认该 Web 端为主播,并触发该回调

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didOfflineOfUid:reason:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didOfflineOfUid:(NSUInteger)uid reason:(AgoraUserOfflineReason)reason

Parameters

engine

AgoraRtcEngineKit 对象

uid

离线的用户 ID。

reason

离线原因,详见 AgoraUserOfflineReason

Discussion

userOfflineBlock

提示有远端用户/主播离开了频道(或掉线)。用户离开频道有两个原因,即正常离开和超时掉线:

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:connectionChangedToState:reason:

网络连接状态已改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine connectionChangedToState:(AgoraConnectionStateType)state reason:(AgoraConnectionChangedReason)reason

Parameters

engine

AgoraRtcEngineKit 对象

state

当前的网络连接状态,详见 AgoraConnectionStateType

reason

引起网络连接状态发生改变的原因,详见 AgoraConnectionChangedReason

Discussion

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:networkTypeChangedToType:

本地网络类型发生改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine networkTypeChangedToType:(AgoraNetworkType)type

Parameters

engine

AgoraRtcEngineKit 对象

type

网络连接类型,详见 AgoraNetworkType

Discussion

本地网络连接类型发生改变时,SDK 会触发该回调,并在回调中明确当前的网络连接类型。

你可以通过该回调获取正在使用的网络类型;当连接终端时,该回调能辨别引起中断的原因是网络切换还是网络条件不好。

Declared In

AgoraRtcEngineKit.h

– rtcEngineConnectionDidLost:

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

- (void)rtcEngineConnectionDidLost:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

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

rtcEngineConnectionDidInterrupted 回调的区别是:

如果 SDK 在断开连接后,20 分钟内还是没能重新加入频道,SDK 会停止尝试重连。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:tokenPrivilegeWillExpire:

Token 服务即将过期回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine tokenPrivilegeWillExpire:(NSString *_Nonnull)token

Parameters

engine

AgoraRtcEngineKit 对象

token

即将服务失效的 Token

Discussion

在调用 joinChannelByToken 时如果指定了 Token,由于 Token 具有一定的时效,在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发该回调,提醒应用程序更新 Token。 当收到该回调时,用户需要重新在服务端生成新的 Token,然后调用 renewToken 将新生成的 Token 传给 SDK。

Declared In

AgoraRtcEngineKit.h

– rtcEngineRequestToken:

Token 过期回调

- (void)rtcEngineRequestToken:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

在调用 joinChannelByToken joinChannelByToken:channelId:info:uid:joinSuccess:]) 时如果指定了 Token,由于 Token 具有一定的时效,在通话过程中 SDK 可能由于网络原因和服务器失去连接,重连时可能需要新的 Token。 该回调通知 App 需要生成新的 Token,然后调用 joinChannelByToken,使用新的 Token 重新加入频道。

Declared In

AgoraRtcEngineKit.h

媒体事件回调

– rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:

用户音量提示回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine reportAudioVolumeIndicationOfSpeakers:(NSArray<AgoraRtcAudioVolumeInfo*> *_Nonnull)speakers totalVolume:(NSInteger)totalVolume

Parameters

engine

AgoraRtcEngineKit 对象。

speakers

用户音量信息,详见 AgoraRtcAudioVolumeInfo 数组。

如果 speakers 为空,则表示远端用户不发流或没有远端用户。

totalVolume

混音后的总音量,取值范围为 [0,255]。

  • 在本地用户的回调中,totalVolume 为本地发流用户的音量。
  • 在远端用户的回调中,totalVolume 为瞬时音量最高的远端用户(最多 3 位)混音后的总音量。

如果用户调用了 startAudioMixing,则 totalVolume 为音乐文件 和用户声音的总音量。

Discussion

audioVolumeIndicationBlock 相同。

该回调默认禁用,你可以通过 enableAudioVolumeIndication 开启。 开启后,只要频道内有发流用户,SDK 会在加入频道后按 enableAudioVolumeIndication 中设置的时间间隔触发 reportAudioVolumeIndicationOfSpeakers 回调。每次会触发两个 reportAudioVolumeIndicationOfSpeakers 回调,一个报告本地发流用户的音量相关信息,另一个报告瞬时音量最高的远端 用户(最多 3 位)的音量相关信息。

Note: 如果有用户将自己静音(调用了 muteLocalAudioStream ),SDK 行为会受如下影响:

  • 本地用户静音后 SDK 立即停止报告本地用户的音量提示回调。
  • 瞬时音量最高的远端用户静音后 20 秒,远端的音量提示回调中将不再包含该用户;如果远端所有用户都将自己静音,20 秒后 SDK 停止报告远端用户的音量提示回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:reportLocalVoicePitchFrequency:

报告本地用户的语音音调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine reportLocalVoicePitchFrequency:(NSInteger)pitchInHz

Parameters

engine

AgoraRtcEngineKit 对象。

pitchInHz

本地用户的语音音调,单位为 Hz。

Availability

v3.7.0

开启本地音频采集并调用 enableLocalVoicePitchCallback 后,SDK 会按 enableLocalVoicePitchCallback 中设置的时间间隔触发本回调,报告本地用户的语音音调。

Discussion

Note: 启用该功能后,如果用户关闭了本地音频采集,例如,调用了 enableLocalAudio(NO) ,SDK 会停止发送本回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:reportAudioDeviceTestVolume:volume:

音频设备测试回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine reportAudioDeviceTestVolume:(AgoraAudioDeviceTestVolumeType)volumeType volume:(NSInteger)volume

Parameters

engine

AgoraRtcEngineKit 对象。

volumeType

音量类型。详见 AgoraAudioDeviceTestVolumeType

volume

音量大小,范围为 [0,255]。

Availability

v3.6.2

成功调用 startRecordingDeviceTeststartPlaybackDeviceTeststartAudioDeviceLoopbackTest 方法开启音频设备测试后,SDK 会按设置的时间间隔触发本回调,报告被测试音频设备的音量信息。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:activeSpeaker:

监测到远端最活跃用户回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine activeSpeaker:(NSUInteger)speakerUid

Parameters

engine

AgoraRtcEngineKit 对象。

speakerUid

远端最活跃用户的 ID。

Discussion

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

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

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:firstLocalAudioFramePublished:

已发布本地音频首帧回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine firstLocalAudioFramePublished:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

elapsed

从调用 joinChannelByToken 方法到触发该回调的时间间隔(毫秒)。

Availability

v3.1.0

SDK 会在以下时机触发该回调:

Declared In

AgoraRtcEngineKit.h

– rtcEngine:firstLocalVideoFrameWithSize:elapsed:

已显示本地视频首帧的回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine firstLocalVideoFrameWithSize:(CGSize)size elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

size

本地渲染的视频尺寸(宽度和高度)

elapsed

从本地用户调用joinChannelByToken到发生此事件过去的时间(ms)。

如果在joinChannelByToken前调用了startPreview,是从 startPreview 到发生此事件过去的时间。

Discussion

第一帧本地视频显示时,触发此回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:firstLocalVideoFramePublished:

已发布本地视频首帧回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine firstLocalVideoFramePublished:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

elapsed

从调用 joinChannelByToken 方法到触发该回调的时间间隔(毫秒)。

Availability

v3.1.0

SDK 会在以下时机触发该回调:

Declared In

AgoraRtcEngineKit.h

– rtcEngine:videoSizeChangedOfUid:size:rotation:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine videoSizeChangedOfUid:(NSUInteger)uid size:(CGSize)size rotation:(NSInteger)rotation

Parameters

engine

AgoraRtcEngineKit 对象

uid

图像尺寸和旋转信息发生变化的用户的用户 ID(本地用户的 uid 为 0)

size

新的视频尺寸

rotation

旋转信息 (0 到 360)

Declared In

AgoraRtcEngineKit.h

– rtcEngine:remoteVideoStateChangedOfUid:state:reason:elapsed:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine remoteVideoStateChangedOfUid:(NSUInteger)uid state:(AgoraVideoRemoteState)state reason:(AgoraVideoRemoteStateReason)reason elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

uid

发生视频状态改变的远端用户 ID。

state

远端视频流状态。详见 AgoraVideoRemoteState

reason

远端视频流状态改变的具体原因。详见 AgoraVideoRemoteStateReason

elapsed

从本地用户调用 joinChannel 方法到发生本事件经历的时间,单位为 ms。

Discussion

Note: 当频道内的用户(通信场景)或主播(直播场景)的人数超过 17 时,该回调可能不准确。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:superResolutionEnabledOfUid:enabled:reason:

报告超分辨率功能是否成功开启。(beta 功能)

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine superResolutionEnabledOfUid:(NSUInteger)uid enabled:(BOOL)enabled reason:(AgoraSuperResolutionStateReason)reason

Parameters

engine

AgoraRtcEngineKit 对象。

uid

远端用户 ID。

enabled

是否对远端视频成功开启超分辨率:

  • YES: 成功开启超分辨率。
  • NO: 未成功开启超分辨率。
reason

超分辨率功能未成功开启的原因,详见 AgoraSuperResolutionStateReason

Availability

v3.5.1

调用 enableRemoteSuperResolution 后, SDK 触发该回调报告超分辨率是否成功开启。如果未成功开启,请通过 reason 排查问题。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:virtualBackgroundSourceEnabled:reason:

报告虚拟背景是否成功开启。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine virtualBackgroundSourceEnabled:(BOOL)enabled reason:(AgoraVirtualBackgroundSourceStateReason)reason

Parameters

engine

AgoraRtcEngineKit 对象。

enabled

是否已成功开启虚拟背景:

  • YES: 成功开启虚拟背景。
  • NO: 未成功开启虚拟背景。
reason

虚拟背景开启出错的原因或开启成功的提示。 详见 AgoraVirtualBackgroundSourceStateReason

Availability

自 v3.4.5 起支持 macOS 平台,自 v3.5.0 起支持 iOS 平台。

调用 enableVirtualBackground 后,SDK 触发该回调报告虚拟背景是否成功开启。

Discussion

Note: 如果虚拟背景中自定义的背景图为 PNG、JPG 格式的图片, 该回调的触发时机会延迟到图片读取完毕。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:snapshotTaken:uid:filePath:width:height:errCode:

视频截图结果回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine snapshotTaken:(NSString *_Nonnull)channel uid:(NSUInteger)uid filePath:(NSString *_Nonnull)filePath width:(NSInteger)width height:(NSInteger)height errCode:(NSInteger)errCode

Parameters

engine

AgoraRtcEngineKit

channel

频道名。

uid

用户 ID。如果 uid 为 0,表示本地用户。

filePath

截图的本地保存路径。

width

图片宽度(px)。

height

图片高度(px)。

errCode

截图成功的提示或失败的原因:

  • 0: 截图成功。
  • < 0: 截图失败。

    • -1: 写入文件失败或 JPEG 编码失败。
    • -2: takeSnapshot 方法调用成功后 1 秒内没有发现指定用户的视频流。

Availability

v3.5.2

成功调用 takeSnapshot 后,SDK 触发该回调报告截图是否成功和获取截图的详情。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:localVideoStateChange:error:

本地视频状态发生改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine localVideoStateChange:(AgoraLocalVideoStreamState)state error:(AgoraLocalVideoStreamError)error

Parameters

engine

AgoraRtcEngineKit 对象。

state

本地视频状态,详见 AgoraLocalVideoStreamState

error

本地视频出错原因,详见 AgoraLocalVideoStreamError

Discussion

本地视频的状态发生改变时,SDK 会触发该回调返回当前的本地视频状态。

SDK 会在如下情况触发 localVideoStateChange(AgoraLocalVideoStreamStateFailed, AgoraLocalVideoStreamErrorCaptureFailure) 回调:

  • 应用退到后台,系统回收摄像头。
  • 摄像头正常启动,但连续 4 秒都没有输出采集的视频。

摄像头输出采集的视频帧时,如果连续 15 帧中,所有视频帧都一样,SDK 触发 localVideoStateChange(AgoraLocalVideoStreamStateCapturing, AgoraLocalVideoStreamErrorCaptureFailure) 回调。 注意:帧重复检测仅针对分辨率大于 200 × 200,帧率大于等于 10 fps,码率小于 20 Kbps 的视频帧。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine remoteAudioStateChangedOfUid:(NSUInteger)uid state:(AgoraAudioRemoteState)state reason:(AgoraAudioRemoteStateReason)reason elapsed:(NSInteger)elapsed

Parameters

engine

详见 AgoraRtcEngineKit

uid

发生音频状态改变的远端用户 ID。

state

远端音频流状态。详见 AgoraAudioRemoteState

reason

远端音频流状态改变的具体原因。详见 AgoraAudioRemoteStateReason

elapsed

从本地用户调用 joinChannel 方法到发生本事件经历的时间,单位为 ms。

Discussion

远端用户/主播音频状态发生改变时,SDK 会触发该回调向本地用户报告当前的远端音频流状态。

Note: 当频道内的用户(通信场景)或主播(直播场景)的人数超过 17 时,该回调可能不准确。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:localAudioStateChange:error:

本地音频状态发生改变回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine localAudioStateChange:(AgoraAudioLocalState)state error:(AgoraAudioLocalError)error

Parameters

engine

详见 AgoraRtcEngineKit

state

当前的本地音频状态。详见 AgoraAudioLocalState

error

本地音频出错原因。详见 AgoraAudioLocalError

Discussion

本地音频的状态发生改变时(包括本地音频采集状态和音频编码状态),SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时,该回调可以帮助你了解当前音频的状态以及出现故障的原因,方便你排查问题。

Note: 当状态为 AgoraAudioLocalStateFailed(3) 时,你可以在 error 参数中查看返回的错误信息。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:firstRemoteVideoFrameOfUid:size:elapsed:

已显示远端视频首帧回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine firstRemoteVideoFrameOfUid:(NSUInteger)uid size:(CGSize)size elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

uid

远端用户 ID

size

视频尺寸(宽和高)

elapsed

从本地用户调用joinChannelByToken到发生此事件过去的时间(ms)。

Discussion

firstRemoteVideoFrameBlock。提示第一帧远端视频显示在视图上。 App 可在此调用中获知出图时间(elapsed)。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didAudioPublishStateChange:oldState:newState:elapseSinceLastState:

音频发布状态改变回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didAudioPublishStateChange:(NSString *_Nonnull)channel oldState:(AgoraStreamPublishState)oldState newState:(AgoraStreamPublishState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState

Parameters

engine

AgoraRtcEngineKit 对象。

channel

频道名。

oldState

之前的发布状态,详见 AgoraStreamPublishState

newState

当前的发布状态,详见 AgoraStreamPublishState

elapseSinceLastState

两次状态变化时间间隔(毫秒)。

Availability

v3.1.0

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didVideoPublishStateChange:oldState:newState:elapseSinceLastState:

视频发布状态改变回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didVideoPublishStateChange:(NSString *_Nonnull)channel oldState:(AgoraStreamPublishState)oldState newState:(AgoraStreamPublishState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState

Parameters

engine

AgoraRtcEngineKit 对象。

channel

频道名。

oldState

之前的发布状态,详见 AgoraStreamPublishState

newState

当前的发布状态,详见 AgoraStreamPublishState

elapseSinceLastState

两次状态变化时间间隔(毫秒)。

Availability

v3.1.0

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didAudioSubscribeStateChange:withUid:oldState:newState:elapseSinceLastState:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didAudioSubscribeStateChange:(NSString *_Nonnull)channel withUid:(NSUInteger)uid oldState:(AgoraStreamSubscribeState)oldState newState:(AgoraStreamSubscribeState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState

Parameters

engine

AgoraRtcEngineKit 对象。

channel

频道名。

uid

远端用户的 ID。

oldState

之前的订阅状态,详见 AgoraStreamSubscribeState

newState

当前的订阅状态,详见 AgoraStreamSubscribeState

elapseSinceLastState

两次状态变化时间间隔(毫秒)。

Availability

v3.1.0

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didVideoSubscribeStateChange:withUid:oldState:newState:elapseSinceLastState:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didVideoSubscribeStateChange:(NSString *_Nonnull)channel withUid:(NSUInteger)uid oldState:(AgoraStreamSubscribeState)oldState newState:(AgoraStreamSubscribeState)newState elapseSinceLastState:(NSInteger)elapseSinceLastState

Parameters

engine

AgoraRtcEngineKit 对象。

channel

频道名。

uid

远端用户的 ID。

oldState

之前的订阅状态,详见 AgoraStreamSubscribeState

newState

当前的订阅状态,详见 AgoraStreamSubscribeState

elapseSinceLastState

两次状态变化时间间隔(毫秒)。

Availability

v3.1.0

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didAudioMuted:byUid:

远端用户音频静音回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didAudioMuted:(BOOL)muted byUid:(NSUInteger)uid

Parameters

engine

AgoraRtcEngineKit 对象

muted

该用户是否静音:

  • YES: 静音
  • NO: 取消静音
uid

远端用户 ID

Discussion

该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。

Note: 当频道内的用户(通信场景)或主播(直播场景)的人数超过 17 时,该回调可能不准确。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didVideoMuted:byUid:

远端用户取消或恢复发布视频流回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didVideoMuted:(BOOL)muted byUid:(NSUInteger)uid

Parameters

engine

AgoraRtcEngineKit 对象

muted

远端用户是否取消发布视频流:

  • Yes: 取消发布视频流
  • No: 发布视频流
uid

远端用户 UID

Discussion

userMuteVideoBlock

当远端用户调用 muteLocalVideoStream 取消或恢复发布视频流时,SDK 会触发该回调向本地用户报告远端用户的发流状况。

Note: 当频道内的用户(通信场景)或主播(直播场景)的人数超过 17 时,该回调可能不准确。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didProxyConnected:withUid:proxyType:localProxyIp:elapsed:

代理连接状态回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didProxyConnected:(NSString *_Nonnull)channel withUid:(NSUInteger)uid proxyType:(AgoraProxyType)proxyType localProxyIp:(NSString *_Nonnull)localProxyIp elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象。

channel

频道名称。

uid

用户 ID。

proxyType

连接上的代理类型。详见 AgoraProxyType

localProxyIp

本地代理的 IP 地址。当 proxyType 的值不为 3 时,该参数的值为空。

elapsed

从调用 joinChannelByToken 到 SDK 触发该回调的经过的时间(毫秒)。

Availability

v3.6.2

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didVideoEnabled:byUid:

远端用户启用/关闭视频回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didVideoEnabled:(BOOL)enabled byUid:(NSUInteger)uid

Parameters

engine

AgoraRtcEngineKit 对象

enabled

是否启用了视频功能

  • YES: 该用户已启用了视频功能。启用后,该用户可以进行视频通话或直播。
  • NO: 该用户已关闭了视频功能。关闭后,该用户只能进行语音通话或直播,不能显示、发送自己的视频,也不能接收、显示别人的视频。
uid

远端用户 UID

Discussion

提示有远端用户启用/关闭了视频功能。关闭视频功能是指该用户只能进行语音直播,不能显示、发送自己的视频,也不能接收、显示别人的视频。

该回调是由远端用户调用 enableVideodisableVideo 方法开启或关闭视频模块触发的。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didLocalVideoEnabled:byUid:

远端用户启用/关闭本地视频回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didLocalVideoEnabled:(BOOL)enabled byUid:(NSUInteger)uid

Parameters

engine

AgoraRtcEngineKit 对象

enabled

是否启用了视频功能

  • YES: 该用户已启用本地视频功能。启用后,远端用户可以接收到该用户的视频流。
  • NO: 该用户已关闭视频功能。关闭后,该用户仍然可以接收远端用户的视频流,但远端用户接收不到该用户的视频流。
uid

远端用户 UID

Discussion

提示有远端用户启用/关闭了本地视频功能。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:firstRemoteVideoDecodedOfUid:size:elapsed:

已完成远端视频首帧解码回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine firstRemoteVideoDecodedOfUid:(NSUInteger)uid size:(CGSize)size elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

uid

远端用户 ID

size

视频流尺寸(宽度和高度)

elapsed

从本地用户调用 joinChannelByToken到发生此事件过去的时间(ms)。

Discussion

你还可以使用 remoteVideoStateChangedOfUid 回调的 AgoraVideoRemoteStateStarting(1) 和 AgoraVideoRemoteStateDecoding(2)。

本地收到远端第一个视频帧并解码成功后,会触发该回调。有两种情况:

  • 远端用户首次上线后发送视频
  • 远端用户视频离线再上线发送视频。视频离线指本地在 15 秒内没有收到视频包,可能有如下原因:

    • 远端用户离开频道
    • 远端用户掉线
    • 远端用户停止发送视频流(调用了 muteLocalVideoStream
    • 远端用户关闭视频(调用了 disableVideo

firstRemoteVideoDecodedBlock

Declared In

AgoraRtcEngineKit.h

音视频流回退事件回调

– rtcEngine:didLocalPublishFallbackToAudioOnly:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didLocalPublishFallbackToAudioOnly:(BOOL)isFallbackOrRecover

Parameters

engine

AgoraRtcEngineKit 对象

isFallbackOrRecover
  • YES: 由于网络环境不理想,本地发布的媒体流已回退为音频流
  • NO: 由于网络环境改善,发布的音频流已恢复为音视频流

Discussion

Note:

如果本地推流已回退为音频流,远端的 App 上会收到 didVideoMuted 的回调事件。

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didRemoteSubscribeFallbackToAudioOnly:byUid:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didRemoteSubscribeFallbackToAudioOnly:(BOOL)isFallbackOrRecover byUid:(NSUInteger)uid

Parameters

engine

AgoraRtcEngineKit 对象

isFallbackOrRecover

回退为音频流或恢复为音视频流:

  • YES: 由于网络环境不理想,远端订阅流已回退为音频流
  • NO: 由于网络环境改善,订阅的音频流已恢复为音视频流
uid

远端用户ID

Discussion

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

Note:

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

Declared In

AgoraRtcEngineKit.h

人脸检测事件回调

– rtcEngine:facePositionDidChangeWidth:previewHeight:faces:

报告本地人脸检测结果。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine facePositionDidChangeWidth:(int)width previewHeight:(int)height faces:(NSArray<AgoraFacePositionInfo*> *_Nullable)faces

Parameters

engine

AgoraRtcEngineKit 对象。

width

摄像头采集画面的宽度 (px)。

height

摄像头采集画面的高度 (px)。

faces

检测到的人脸信息,详见 AgoraFacePositionInfo

检测到几张人脸,就会报告几个 AgoraFacePositionInfo 数组。数组长度可以为 0,表示没有检测到摄像头前出现人脸。

Discussion

自从: v3.0.1.

调用 enableFaceDetection(YES) 开启本地人脸检测后,你可以通过该回调实时获取以下人脸检测的信息:

  • 摄像头采集的画面大小
  • 人脸在 View 中的位置
  • 人脸距设备屏幕的距离,该值由 SDK 通过摄像头采集的画面大小和人脸在 View 中的位置拟合计算得出。

Note

  • 该回调仅适用于 iOS 平台。
  • 当检测到摄像头前没有人脸时,该回调触发频率会降低,以节省设备耗能。
  • 当人脸距离设备屏幕过近时,SDK 不会触发该回调。

Declared In

AgoraRtcEngineKit.h

媒体设备事件回调

– rtcEngine:device:type:stateChanged:

设备状态改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine device:(NSString *_Nonnull)deviceId type:(AgoraMediaDeviceType)deviceType stateChanged:(NSInteger)state

Parameters

engine

AgoraRtcEngineKit 对象

deviceId

设备ID

deviceType

设备类型,详见 AgoraMediaDeviceType

state

设备状态:

  • 0: 设备插入,但未使用。
  • 1: 视频设备被拔出。
  • 8: 音频设备被拔出。

Discussion

Warning: 该回调仅适用于 macOS 平台。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didAudioRouteChanged:

音频路由已发生变化回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didAudioRouteChanged:(AgoraAudioOutputRouting)routing

Parameters

engine

AgoraRtcEngineKit 对象

routing

当前的音频路由: AgoraAudioOutputRouting

Discussion

当音频路由发生变化时,SDK 会触发此回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:cameraFocusDidChangedToRect:

摄像头对焦区域已改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine cameraFocusDidChangedToRect:(CGRect)rect

Parameters

engine

AgoraRtcEngineKit 对象

rect

镜头内表示对焦区域的长方形

Discussion

该回调仅适用于 iOS 平台。

该回调表示摄像头的对焦区域发生了改变。

该回调是由本地用户调用 setCameraFocusPositionInPreview 方法改变对焦位置触发的。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:cameraExposureDidChangedToRect:

摄像头曝光区域已改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine cameraExposureDidChangedToRect:(CGRect)rect

Parameters

engine

AgoraRtcEngineKit 对象

rect

镜头内表示曝光的区域

Discussion

该回调仅适用于 iOS 平台。

该回调是由本地用户调用 setCameraExposurePosition 方法改变曝光位置触发的。

Declared In

AgoraRtcEngineKit.h

统计数据事件回调

– rtcEngine:reportRtcStats:

当前通话统计回调。 该回调在通话或直播中每两秒触发一次。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine reportRtcStats:(AgoraChannelStats *_Nonnull)stats

Parameters

engine

AgoraRtcEngineKit 对象

stats

通话相关的数据统计信息,详见 AgoraChannelStats

Declared In

AgoraRtcEngineKit.h

– rtcEngine:lastmileQuality:

通话前网络上下行 last mile 质量报告回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine lastmileQuality:(AgoraNetworkQuality)quality

Parameters

engine

AgoraRtcEngineKit 对象

quality

网络上下行质量,基于上下行网络的丢包率和抖动计算,探测结果主要反映上行网络的状态。详见 AgoraNetworkQuality

Discussion

该回调描述本地用户在加入频道前的 last mile 网络探测的结果,其中 last mile 是指设备到声网边缘服务器的网络状态。

在调用 enableLastmileTest 之后,该回调每 2 秒触发一次。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:networkQuality:txQuality:rxQuality:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine networkQuality:(NSUInteger)uid txQuality:(AgoraNetworkQuality)txQuality rxQuality:(AgoraNetworkQuality)rxQuality

Parameters

engine

AgoraRtcEngineKit 对象

uid

用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。当 uid 为 0 时,返回的是本地用户的网络质量。

txQuality

该用户的上行网络质量。基于上行视频的发送码率、上行丢包率、平均往返时延和网络抖动计算。该值代表当前的上行网络质量,帮助判断是否可以支持当前设置的视频编码属性。

假设上行码率是 500 Kbps,那么支持 480 x 480 的分辨率、30 fps 的帧率没有问题,但是支持 1280 x 720 的分辨率就会有困难。详见 AgoraNetworkQuality

rxQuality

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

Discussion

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

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

Note: 用户不发流时,txQualityUnknown ;用户不收流时,rxQualityUnknown

Declared In

AgoraRtcEngineKit.h

– rtcEngine:wlAccMessage:action:wlAccMsg:

报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine wlAccMessage:(AgoraWlAccReason)reason action:(AgoraWlAccAction)action wlAccMsg:(NSString *_Nonnull)wlAccMsg

Parameters

engine

AgoraRtcEngineKit 对象

reason

Wi-Fi 连接质量不佳的原因。详见 AgoraWlAccReason

action

改善 Wi-Fi 连接质量的操作建议。详见 AgoraWlAccAction

wlAccMsg

根据 action 的值提供的详细帮助信息:

  • actionAgoraWlAccSuggestActionCloseToWIFI,该参数的值为 nil
  • actionAgoraWlAccSuggestActionConnectSSID,该参数的值为推荐用户连接的网络名称(SSID)。
  • actionAgoraWlAccSuggestActionCheck5G,该参数的值为开启路由器 5G 频道的操作步骤的链接。
  • actionAgoraWlAccSuggestActionModifySSID,该参数的值为修改网络名称(SSID)的操作步骤的链接。

Availability

v3.6.2

调用 enableWirelessAccelerate(YES) 开启 Wi-Fi 加速功能后,当 Wi-Fi 连接质量不佳时,SDK 会触发该回调,报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

Discussion

Note: 声网强烈建议你在 app 中展示将该回调报告的 actionwlAccMsg,提示用户采取网络优化措施,以获得更好的音视频体验。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:wlAccStats:averageStats:

报告 Wi-Fi 加速效果。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine wlAccStats:(AgoraWlAccStats *_Nonnull)currentStats averageStats:(AgoraWlAccStats *_Nonnull)averageStats

Parameters

engine

AgoraRtcEngineKit 对象

currentStats

当前的 Wi-Fi 加速效果。详见 AgoraWlAccStats

averageStats

自加入频道后平均的 Wi-Fi 加速效果。详见 AgoraWlAccStats

Availability

v3.6.2

调用 enableWirelessAccelerate(YES) 开启 Wi-Fi 加速功能后,SDK 每隔两秒触发一次该回调,报告当前的 Wi-Fi 加速效果和自加入频道后平均的 Wi-Fi 加速效果。Wi-Fi 加速效果用端到端延时、丢包率和音视频卡顿率三个指标下降的百分比来衡量。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:lastmileProbeTestResult:

通话前网络质量探测报告回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine lastmileProbeTestResult:(AgoraLastmileProbeResult *_Nonnull)result

Parameters

engine

AgoraRtcEngineKit 对象

result

上下行 last mile 质量探测结果,详见 AgoraLastmileProbeResult

Discussion

通话前网络上下行 last mile 质量探测报告回调。在调用 startLastmileProbeTest 之后,SDK 会在约 30 秒内返回该回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:localVideoStats:

本地视频流统计信息回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine localVideoStats:(AgoraRtcLocalVideoStats *_Nonnull)stats

Parameters

engine

AgoraRtcEngineKit 对象

stats

本地视频的统计信息: AgoraRtcLocalVideoStats

Discussion

localVideoStatBlock。报告更新本地视频统计信息,该回调方法每两秒触发一次。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:localAudioStats:

通话中本地音频流的统计信息回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine localAudioStats:(AgoraRtcLocalAudioStats *_Nonnull)stats

Parameters

engine

详见 AgoraRtcEngineKit

stats

本地音频统计数据。详见 AgoraRtcLocalAudioStats

Discussion

该回调描述本地设备发送音频流的统计信息。SDK 每 2 秒触发该回调一次。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:remoteVideoStats:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine remoteVideoStats:(AgoraRtcRemoteVideoStats *_Nonnull)stats

Parameters

engine

AgoraRtcEngineKit 对象

stats

远端视频统计数据,详细定义见 AgoraRtcRemoteVideoStats

Discussion

该回调描述远端用户在通话中端到端的视频流统计信息,针对每个远端用户/主播每 2 秒触发一次。

如果远端同时存在多个用户/主播,该回调每 2 秒会被触发多次。

videoTransportStatsOfUid 相比,该回调为视频引擎统计,贴近用户最终主观感受。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:remoteAudioStats:

通话中远端音频流的统计信息回调,用于取代 audioQualityOfUid

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine remoteAudioStats:(AgoraRtcRemoteAudioStats *_Nonnull)stats

Parameters

engine

AgoraRtcEngineKit 对象。

stats

远端音频统计数据,详细定义见 AgoraRtcRemoteAudioStats

Discussion

该回调描述远端用户在通话中端到端的音频流统计信息,针对每个远端用户/主播每 2 秒触发一次。

如果远端同时存在多个用户/主播,该回调每 2 秒会被触发多次。

audioTransportStatsOfUid 回调相比,该回调更贴近用户的主观感受。

比如,当网络发生丢包时,因 FEC(Forward Error Correction,向前纠错码)或重传恢复,最终的音频丢帧率不高,则可以认为整个质量较好。

Declared In

AgoraRtcEngineKit.h

音频播放事件回调

– rtcEngineLocalAudioMixingDidFinish:

本地音乐文件播放已结束回调

- (void)rtcEngineLocalAudioMixingDidFinish:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

本地用户调用 startAudioMixing 播放音乐文件音乐结束后,会触发该回调。如果调用 startAudioMixing 失败,会在 didOccurWarning 回调里,返回警告代码 AgoraWarningCodeAudioMixingOpenError。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:localAudioMixingStateDidChanged:reason:

本地用户的音乐文件播放状态已改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine localAudioMixingStateDidChanged:(AgoraAudioMixingStateCode)state reason:(AgoraAudioMixingReasonCode)reason

Parameters

engine

AgoraRtcEngineKit 对象。

state

当前音乐文件播放状态,详见 AgoraAudioMixingStateCode

reason

音乐文件播放状态改变的原因,详见 AgoraAudioMixingReasonCode

Discussion

该回调在音乐文件播放状态发生改变时触发,并报告当前的播放状态和播放状态改变的原因。

Note: 通过 startAudioMixing 播放在线音乐文件时,如果遇到网络情况较差,localAudioMixingStateDidChanged 回调报告 AgoraAudioMixingStatePlaying 的时刻可能与用户听到音乐的时刻不同。因为 SDK 会在解码第一帧音频帧后触发该回调报告 Playing 状态,但在弱网情况下,SDK 无法稳定地接收在线音频包,因此音乐播放不稳定,用户主观感受到的音频开始播放的时刻可能比音频首帧解码的时刻更晚。

Declared In

AgoraRtcEngineKit.h

– rtcEngineRemoteAudioMixingDidStart:

远端音乐文件播放已开始回调

- (void)rtcEngineRemoteAudioMixingDidStart:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

当远端有用户调用 startAudioMixing 播放音乐文件音乐,会触发该回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngineRemoteAudioMixingDidFinish:

远端音乐文件播放已结束回调

- (void)rtcEngineRemoteAudioMixingDidFinish:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Declared In

AgoraRtcEngineKit.h

– rtcEngineDidAudioEffectFinish:soundId:

本地音效文件播放已结束回调

- (void)rtcEngineDidAudioEffectFinish:(AgoraRtcEngineKit *_Nonnull)engine soundId:(NSInteger)soundId

Parameters

engine

AgoraRtcEngineKit 对象

soundId

自行设定的音效 ID,需保证唯一性。

Discussion

当调用 playEffect 播放音效结束后,会触发该回调。

Declared In

AgoraRtcEngineKit.h

CDN 旁路推流事件回调

– rtcEngine:rtmpStreamingChangedToState:state:errorCode:

RTMP/RTMPS 推流状态发生改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine rtmpStreamingChangedToState:(NSString *_Nonnull)url state:(AgoraRtmpStreamingState)state errorCode:(AgoraRtmpStreamingErrorCode)errorCode

Parameters

engine

AgoraRtcEngineKit 对象。

url

推流状态发生改变的 URL 地址。

state

当前的推流状态,详见 AgoraRtmpStreamingState

errorCode

具体的推流错误信息,详见 AgoraRtmpStreamingErrorCode

Discussion

RTMP/RTMPS 推流状态发生改变时,SDK 会触发该回调,并在回调中明确状态发生改变的 URL 地址及当前推流状态。

该回调方便推流用户了解当前的推流状态;推流出错时,你可以通过返回的错误码了解出错的原因,方便排查问题。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:rtmpStreamingEventWithUrl:eventCode:

RTMP/RTMPS 推流事件回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine rtmpStreamingEventWithUrl:(NSString *_Nonnull)url eventCode:(AgoraRtmpStreamingEvent)eventCode

Parameters

engine

AgoraRtcEngineKit 对象。

url

RTMP/RTMPS 推流 URL。

eventCode

RTMP/RTMPS 推流事件码。详见 AgoraRtmpStreamingEvent

Availability

v3.1.0

Declared In

AgoraRtcEngineKit.h

– rtcEngineTranscodingUpdated:

旁路推流设置被更新回调

- (void)rtcEngineTranscodingUpdated:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

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

Note: 首次调用 setLiveTranscoding 方法设置转码参数 LiveTranscoding 时,不会触发此回调。

Declared In

AgoraRtcEngineKit.h

数据流事件回调

– rtcEngine:receiveStreamMessageFromUid:streamId:data:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine receiveStreamMessageFromUid:(NSUInteger)uid streamId:(NSInteger)streamId data:(NSData *_Nonnull)data

Parameters

engine

AgoraRtcEngineKit 对象

uid

用户ID

streamId

数据流 ID

data

接收到的数据

Discussion

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didOccurStreamMessageErrorFromUid:streamId:error:missed:cached:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didOccurStreamMessageErrorFromUid:(NSUInteger)uid streamId:(NSInteger)streamId error:(NSInteger)error missed:(NSInteger)missed cached:(NSInteger)cached

Parameters

engine

AgoraRtcEngineKit 对象

uid

用户 ID

streamId

数据流 ID

error

错误代码: AgoraErrorCode

missed

丢失的消息数量

cached

数据流中断时,后面缓存的消息数量

Discussion

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

Declared In

AgoraRtcEngineKit.h

其他回调

– rtcEngine:didRequestAudioFileInfo:error:

音频文件信息回调。

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didRequestAudioFileInfo:(AgoraRtcAudioFileInfo *_Nonnull)info error:(AgoraAudioFileInfoError)error

Parameters

engine

AgoraRtcEngineKit 对象。

info

音频文件信息。详见 AgoraRtcAudioFileInfo

error

信息获取状态。详见 AgoraAudioFileInfoError

Availability

v3.5.1

成功调用 getAudioFileInfo 后, SDK 会触发该回调并报告音频文件的路径、时长等信息。

Declared In

AgoraRtcEngineKit.h

– rtcEngineMediaEngineDidLoaded:

媒体引擎成功加载的回调

- (void)rtcEngineMediaEngineDidLoaded:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Declared In

AgoraRtcEngineKit.h

– rtcEngineMediaEngineDidStartCall:

媒体引擎成功启动的回调

- (void)rtcEngineMediaEngineDidStartCall:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Declared In

AgoraRtcEngineKit.h

– rtcEngine:channelMediaRelayStateDidChange:error:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine channelMediaRelayStateDidChange:(AgoraChannelMediaRelayState)state error:(AgoraChannelMediaRelayError)error

Parameters

engine

AgoraRtcEngineKit 对象。

state

跨频道媒体流转发状态 AgoraChannelMediaRelayState

error

跨频道媒体流转发出错的错误码 AgoraChannelMediaRelayError

Discussion

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

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didReceiveChannelMediaRelayEvent:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didReceiveChannelMediaRelayEvent:(AgoraChannelMediaRelayEvent)event

Parameters

engine

AgoraRtcEngineKit 对象。

event

跨频道媒体流转发事件码 AgoraChannelMediaRelayEvent

Discussion

该回调报告跨频道媒体流转发过程中发生的事件。

Declared In

AgoraRtcEngineKit.h

已废弃回调

– rtcEngine:firstLocalAudioFrame:

已发送本地音频首帧的回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine firstLocalAudioFrame:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

elapsed

从本地用户调用joinChannelByToken开始到发生此事件过去的时间(ms)。

Discussion

Deprecated 该回调自 v3.1.0 废弃,请改用 firstLocalAudioFramePublished 回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:firstRemoteAudioFrameOfUid:elapsed:

已接收远端音频首帧的回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine firstRemoteAudioFrameOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

uid

远端用户 ID

elapsed

从本地用户调用joinChannelByToken到发生此事件的时间(ms)。

Discussion

Deprecated 自 v3.0.0 起废弃。请改用 remoteAudioStateChangedOfUid 中的 AgoraAudioRemoteStateStarting(1)

Declared In

AgoraRtcEngineKit.h

– rtcEngine:firstRemoteAudioFrameDecodedOfUid:elapsed:

已解码远端音频首帧的回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine firstRemoteAudioFrameDecodedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed

Parameters

engine

AgoraRtcEngineKit 对象

uid

远端用户 ID

elapsed

从本地用户调用 joinChannelByToken 直至该回调触发的延迟,单位为毫秒。

Discussion

Deprecated 自 v3.0.0 起废弃。请改用 remoteAudioStateChangedOfUid 回调中的 AgoraAudioRemoteStateDecoding(2)

SDK 完成远端音频首帧解码,并发送给音频模块用以播放时,会触发此回调。有两种情况:

  • 远端用户首次上线后发送音频
  • 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包,可能有如下原因:

    • 远端用户离开频道
    • 远端用户掉线
    • 远端用户停止发送音频流(调用了 muteLocalAudioStream
    • 远端用户关闭音频(调用了 disableAudio

Declared In

AgoraRtcEngineKit.h

– rtcEngine:streamPublishedWithUrl:errorCode:

开启旁路推流的结果回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine streamPublishedWithUrl:(NSString *_Nonnull)url errorCode:(AgoraErrorCode)errorCode

Parameters

engine

AgoraRtcEngineKit 对象

url

主播推流地址或输入的外部音视频流地址

errorCode

常见的错误码如下,详情见 AgoraErrorCode

  • AgoraErrorCodeNoError(0):推流成功
  • AgoraErrorCodeFailed(1):推流失败
  • AgoraErrorCodeInvalidArgument(2):参数错误,如果你在调用 addPublishStreamUrl 前没有调用 setLiveTranscoding 配置 AgoraLiveTranscoding ,会导致此错误。
  • AgoraErrorCodeTimedOut(10):推流超时未成功
  • AgoraErrorCodeAlreadyInUse(19):推流地址已经在推流
  • AgoraErrorCodeEncryptedStreamNotAllowedPublish(130):推流已加密不能推流
  • AgoraErrorCodePublishStreamCDNError(151):CDN 相关错误。请调用 removePublishStreamUrl 方法删除原来的推流地址,然后调用 addPublishStreamUrl 方法重新推流到新地址。
  • AgoraErrorCodePublishStreamNumReachLimit(152):单个主播的推流地址数目达到上限 10。请删掉一些不用的推流地址再增加推流地址。
  • AgoraErrorCodePublishStreamNotAuthorized(153):操作不属于主播自己的流,例如更新其他主播的流参数、停止其他主播的流。请检查 App 逻辑。
  • AgoraErrorCodePublishStreamInternalServerError(154):推流服务器出现错误。请调用 addPublishStreamUrl 重新推流。
  • AgoraErrorCodePublishStreamFormatNotSuppported(156):推流地址格式有错误。请检查推流地址格式是否正确。

Discussion

Deprecated 自 v3.0.0 起废弃。请改用 rtmpStreamingChangedToState 回调。

返回 addPublishStreamUrl 方法的调用结果。如果调用不成功,你可以在 errorCode 参数中查看详细的错误信息。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:streamUnpublishedWithUrl:

停止旁路推流的结果回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine streamUnpublishedWithUrl:(NSString *_Nonnull)url

Parameters

engine

AgoraRtcEngineKit 对象

url

主播停止推流的地址

Discussion

Deprecated 自 v3.0.0 起废弃。请改用 rtmpStreamingChangedToState 回调。

返回 removePublishStreamUrl 方法的调用结果。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:audioTransportStatsOfUid:delay:lost:rxKBitRate:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioTransportStatsOfUid:(NSUInteger)uid delay:(NSUInteger)delay lost:(NSUInteger)lost rxKBitRate:(NSUInteger)rxKBitRate

Parameters

engine

AgoraRtcEngineKit 对象

uid

用户 ID,指定是哪个用户/主播的音频包

delay

音频包从发送端到接收端的延时(毫秒)

lost

音频包从发送端到接收端的丢包率(%)

rxKBitRate

远端音频包的接收码率(Kbps)

Discussion

Deprecated 自 v2.9.0 起废弃。请改用 remoteAudioStats 回调。

该回调描述远端用户通话中端到端的网络统计信息,通过音频包计算,用客观的数据,如丢包、网络延迟等,展示当前网络状态。

通话中,当用户收到远端用户/主播发送的音频数据包后,会每 2 秒触发一次该回调。

remoteAudioStats 回调相比,该回调以数据展示当前网络状态,因此更客观。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:videoTransportStatsOfUid:delay:lost:rxKBitRate:

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

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine videoTransportStatsOfUid:(NSUInteger)uid delay:(NSUInteger)delay lost:(NSUInteger)lost rxKBitRate:(NSUInteger)rxKBitRate

Parameters

engine

AgoraRtcEngineKit 对象

uid

用户 ID,指定是哪个用户/主播的视频包

delay

视频包从发送端到接收端的延时(毫秒)

lost

视频包从发送端到接收端 800 ms 内的丢包率(%)

rxKBitRate

远端视频包的接收码率(Kbps)

Discussion

Deprecated 自 v2.9.0 起废弃。请改用 remoteVideoStats 回调。

该回调描述远端用户通话中端到端的网络统计信息,通过视频包计算,用客观的数据,如丢包、网络延迟等,展示当前网络状态。

通话中,当用户收到远端用户/主播发送的视频数据包后,会每 2 秒触发一次该回调。

remoteVideoStats 回调相比,该回调以数据展示当前网络状态,因此更客观。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:didMicrophoneEnabled:

麦克风状态已改变回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine didMicrophoneEnabled:(BOOL)enabled

Parameters

engine

AgoraRtcEngineKit 对象

enabled
  • YES: 麦克风已启用
  • NO: 麦克风已禁用

Discussion

Deprecated 自 v2.9.0 起废弃。请改用 localAudioStateChange 回调的 AgoraAudioLocalStateStopped(0) 或 AgoraAudioLocalStateRecording(1)。

该回调是由本地用户调用 enableLocalAudio 方法开启或关闭本地音频采集触发的。

Declared In

AgoraRtcEngineKit.h

– rtcEngineConnectionDidInterrupted:

网络连接中断回调

- (void)rtcEngineConnectionDidInterrupted:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

Deprecated 自 v2.3.2 起废弃。请改用 connectionChangedToState 回调中的 AgoraConnectionStateReconnecting(4)AgoraConnectionChangedInterrupted(2)

SDK 在和服务器建立连接后,失去了网络连接超过 4 秒,会触发该回调。在触发事件后,SDK 会主动重连服务器,所以该事件可以用于 UI 提示。

rtcEngineConnectionDidLost 回调的区别是:

如果 SDK 在断开连接后,20 分钟内还是没能重新加入频道,SDK 会停止尝试重连。

Declared In

AgoraRtcEngineKit.h

– rtcEngineConnectionDidBanned:

连接已被禁止回调

- (void)rtcEngineConnectionDidBanned:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

Deprecated 自 v2.3.2 起废弃。请改用 connectionChangedToState 回调中的 AgoraConnectionStateFailed(5)AgoraConnectionChangedBannedByServer(3)

当你被服务端禁掉连接的权限时,会触发该回调。

Declared In

AgoraRtcEngineKit.h

– rtcEngine:audioQualityOfUid:quality:delay:lost:

远端音频质量回调

- (void)rtcEngine:(AgoraRtcEngineKit *_Nonnull)engine audioQualityOfUid:(NSUInteger)uid quality:(AgoraNetworkQuality)quality delay:(NSUInteger)delay lost:(NSUInteger)lost

Parameters

engine

AgoraRtcEngineKit 对象。

uid

用户 ID,指定是谁发的音频流。

quality

语音质量,详见 AgoraNetworkQuality

delay

音频包从发送端到接收端的延迟(毫秒)。包括音频采样前处理、网络传输、网络抖动缓冲引起的延迟。

lost

音频包从发送端到接收端的丢包率(%)

Discussion

Deprecated 自 v2.3.2 起废弃。请改用 remoteAudioStats 回调。

audioQualityBlock

该回调描述远端用户在通话中的音频质量,针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播,该回调每 2 秒会被触发多次。

See Also

Declared In

AgoraRtcEngineKit.h

– rtcEngineCameraDidReady:

摄像头就绪回调

- (void)rtcEngineCameraDidReady:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

Deprecated 从 v2.4.1 起废弃。请改用 localVideoStateChange 回调 state 参数中的 AgoraLocalVideoStreamStateCapturing(1)。

cameraReadyBlock。提示已成功打开摄像头,可以开始捕获视频。

Declared In

AgoraRtcEngineKit.h

– rtcEngineVideoDidStop:

视频功能停止回调

- (void)rtcEngineVideoDidStop:(AgoraRtcEngineKit *_Nonnull)engine

Parameters

engine

AgoraRtcEngineKit 对象

Discussion

Deprecated 从 v2.4.1 起废弃。请改用 localVideoStateChange 回调 state 参数中的 AgoraLocalVideoStreamStateStopped(0)。

提示视频功能已停止。 App 如需在停止视频后对 view 做其他处理(比如显示其他画面),可以在这个回调中进行。

Declared In

AgoraRtcEngineKit.h