Protocol

ZegoApiCalledEventHandler

Declared in ZegoExpressEventHandler.h

方法

onApiCalledResult:funcName:info:

- (void)onApiCalledResult:(int) errorCode funcName:(NSString *) funcName info:(NSString *) info;

方法执行结果回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
funcName	NSString *	函数名。
info	NSString *	错误的详细信息。

详情

通过 [setApiCalledCallback] 开启监听时，会通过本回调回调所有方法的执行的结果。

通知时机：在开发者调用 SDK 方法时，回调该方法的执行结果。

支持版本：2.3.0 及以上。
使用限制：无。
注意事项：建议在开发、测试阶段监听并处理本回调，在上线后关闭对本回调的监听。

ZegoAudioDataHandler

Declared in ZegoExpressEventHandler.h

方法

onCapturedAudioData:dataLength:param:

- (void)onCapturedAudioData:(const unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param;

获取本地麦克风采集到的音频数据的回调.

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	const unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。

详情

在非自定义采集模式下，SDK 会负责麦克风的声音采集工作，但是开发者可能也需要拿到 SDK 采集到的音源数据，通过这个回调可以获取。

通知时机：在调用 [setAudioDataHandler] 设置了监听本回调的前提下，调用 [startAudioDataObserver] 设置了掩码 0b01 即 1 << 0 之后，且处于推流状态才会触发此回调。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作。

onPlaybackAudioData:dataLength:param:

- (void)onPlaybackAudioData:(const unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param;

获取 SDK 播放的音频数据的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	const unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。

详情

此函数会回调全部要播放的音频混合后的数据。如果需开发者需要对全部要播放的音频混合后的数据进行处理，就可以用这个回调。

通知时机：在调用 [setAudioDataHandler] 设置了监听本回调的前提下，调用 [startAudioDataObserver] 设置了掩码 0b10 即 1 << 1 之后，且处于 SDK 音视频引擎启动时(预览/推流/拉流)才会触发此回调。

支持版本：1.1.0 及以上。
使用限制：播放版权音乐时，该回调会被默认禁用，若有需要，请联系 ZEGO 技术支持。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作，在非拉流状态的引擎启动状态且未使用媒体播放器播放媒体文件状态时，回调的音频数据是静音的音频数据。

onMixedAudioData:dataLength:param:

- (void)onMixedAudioData:(const unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param;

获取 SDK 播放的音频数据和本地麦克风采集到的音频数据的回调，该音频数据是经过 SDK 混合之后的数据。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	const unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。

详情

SDK 播放的音频数据与本地麦克风采集到的数据在送到扬声器之前进行混合，并通过此函数回调出来。

通知时机：在调用 [setAudioDataHandler] 设置了监听本回调的前提下，调用 [startAudioDataObserver] 设置了掩码 0x04 之后，且处于推流或拉流状态才会触发此回调。

支持版本：1.1.0 及以上。
使用限制：播放版权音乐时，该回调会被默认禁用，若有需要，请联系 ZEGO 技术支持。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作。

onPlayerAudioData:dataLength:param:streamID:

- (void)onPlayerAudioData:(const unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param streamID:(NSString *) streamID;

获取 SDK 每条拉流的音频数据的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	const unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。
streamID	NSString *	对应的流 ID。

详情

此函数会回调每条拉流单独对应的数据,不同于[onPlaybackAudioData],后者是所有拉流的混合数据。如果开发者需要对某条拉流的数据单独进行处理，就可以用这个回调。

通知时机：在调用 [setAudioDataHandler] 设置了监听本回调的前提下，调用 [startAudioDataObserver] 设置了掩码 0x08 即 1 << 3 之后，且处于 SDK 音视频引擎启动拉流时才会触发此回调。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作。

ZegoAudioEffectPlayerEventHandler

Declared in ZegoExpressEventHandler.h

方法

audioEffectPlayer:audioEffectID:playStateUpdate:errorCode

- (void)audioEffectPlayer:(ZegoAudioEffectPlayer *)audioEffectPlayer audioEffectID:(unsigned int)audioEffectID playStateUpdate:(ZegoAudioEffectPlayState)state errorCode:(int)errorCode;

音效播放状态回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
audioEffectPlayer	ZegoAudioEffectPlayer *	触发此次回调的音效播放器实例。
audioEffectID	unsigned int	触发此次回调的音效资源的 ID。
state	ZegoAudioEffectPlayState	音效的播放状态。
errorCode	int	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html

详情

当音效播放器的某条音效的播放状态改变时会触发此回调。

通知时机：当音效的播放状态变化时会触发这个回调。

支持版本：1.16.0 及以上。
使用限制：无。

ZegoAudioMixingHandler

Declared in ZegoExpressEventHandler.h

方法

onAudioMixingCopyData:

- (ZegoAudioMixingData *)onAudioMixingCopyData:(unsigned int) expectedDataLength;

混音数据回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
expectedDataLength	unsigned int	期望开发者传入 SDK 的混音数据长度。

详情

往 SDK 中拷贝混音 PCM 数据，用于将开发者提供的音频数据混到推流的音频数据中。需要和 [enableAudioMixing] 结合使用。

业务场景：当开发者有需要往推流的音频中混入自己的歌曲、音效等音频数据时，可以使用此功能。
通知时机：需要在 [createEngine] 之后，调用 [enableAudioMixing] 开启混音功能，且通过 [setAudioMixingHandler] 设置了混音回调处理器才会触发本回调函数。

支持版本：1.9.0 及以上。
使用限制：支持 16k 32k 44.1k 48k 的采样率、单声道或双声道、16位深的 PCM 音频数据。
注意事项：本回调为高频回调，为保证混音质量，请勿在本回调中做耗时操作。

返回值

开发者提供的期望混入推流中的音频数据。

ZegoCustomAudioProcessHandler

Declared in ZegoExpressEventHandler.h

方法

onProcessCapturedAudioData:dataLength:param:timestamp:

- (void)onProcessCapturedAudioData:(unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param timestamp:(double) timestamp;

自定义音频处理本地采集 PCM 音频帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。
timestamp	double	音频帧时间戳，当启动采集时从 0 开始计时，单位为毫秒。

详情

在此回调中可以收到自定义音频处理本地采集的 PCM 音频帧，开发者可对音频帧数据进行修改，同时可以修改声道数、采样率。返回的时间戳可用于数据同步，如歌词等。如果需要经过耳返后的数据，请使用 [onProcessCapturedAudioDataAfterUsedHeadphoneMonitor] 回调。

通知时机：需要先调用 [enableCustomAudioCaptureProcessing] 开启功能后，并且在调用 [startPreview] 或 [startPublishingStream] 后，才会触发本回调函数。

支持版本：2.13.0 及以上。
使用限制：无。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作。

onProcessCapturedAudioDataAfterUsedHeadphoneMonitor:dataLength:param:timestamp:

- (void)onProcessCapturedAudioDataAfterUsedHeadphoneMonitor:(unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param timestamp:(double) timestamp;

自定义音频处理本地采集使用耳返后的 PCM 音频帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	unsigned char * _Nonnull	PCM 格式的音频数据
dataLength	unsigned int	数据的长度
param	ZegoAudioFrameParam *	音频帧参数
timestamp	double	音频帧时间戳，当启动采集时从 0 开始计时，单位为毫秒。

详情

在此回调中可以收到自定义音频处理本地采集经耳返后的 PCM 音频帧，开发者可对音频帧数据进行修改，同时可以修改声道数、采样率。返回的时间戳可用于数据同步，如歌词等。

通知时机：需要先调用 [enableCustomAudioCaptureProcessingAfterHeadphoneMonitor] 开启功能后，并且在调用 [startPreview] 或 [startPublishingStream] 后，才会触发本回调函数。

支持版本：2.13.0 及以上。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作。

onAlignedAudioAuxData:dataLength:param:

- (void)onAlignedAudioAuxData:(const unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param;

与伴奏对齐的音频混音数据回调

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	const unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。

详情

在此回调中可以收到与伴奏对齐后的音频混音数据，开发者可以进行本地录制。

通知时机：需要先调用 [enableAlignedAudioAuxData] 开启抛出对齐的音频混音数据功能，并且在调用 [startPublishingStream] 或 [startRecordingCapturedData] 后，才会触发本回调函数。

支持版本：2.22.0 及以上。
使用限制：若要从此回调中获取媒体播放器的音频混音数据，媒体播放器需要调用 [enableAux]、[start]。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作，且该回调中数据不允许修改。

onBeforeAudioPrepAudioData:dataLength:param:

- (void)onBeforeAudioPrepAudioData:(const unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param;

SDK 内部音频前处理前的音频数据回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	const unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。

详情

在此回调中可以收到 SDK 内部音频前处理前的音频数据。

通知时机：需要先调用 [enableBeforeAudioPrepAudioData] 开启抛出 SDK 内部音频前处理前的音频数据功能，并且在调用 [startPublishingStream] 后，才会触发本回调函数。

支持版本：3.11.0 及以上。
使用限制：无。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作，且该回调中数据不允许修改。

onProcessRemoteAudioData:dataLength:param:streamID:timestamp:

- (void)onProcessRemoteAudioData:(unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param streamID:(NSString *) streamID timestamp:(double) timestamp;

自定义音频处理远端拉流 PCM 音频帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度
param	ZegoAudioFrameParam *	音频帧参数。
streamID	NSString *	对应的流 ID。
timestamp	double	音频帧时间戳，当启动采集时从 0 开始计时，单位为毫秒。

详情

在此回调中可以收到自定义音频处理远端拉流 PCM 音频帧，开发者可对音频帧数据进行修改，同时可以修改声道数、采样率。返回的时间戳可用于数据同步，如歌词等。

通知时机：需要先调用 [enableCustomAudioRemoteProcessing] 开启功能后，并且在调用 [startPlayingStream] 后，才会触发本回调函数。

支持版本：2.13.0 及以上。
使用限制：无。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作。

onProcessPlaybackAudioData:dataLength:param:timestamp:

- (void)onProcessPlaybackAudioData:(unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoAudioFrameParam *) param timestamp:(double) timestamp;

自定义音频处理 SDK 播放音频的 PCM 音频帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	unsigned char * _Nonnull	PCM 格式的音频数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。
timestamp	double	音频帧时间戳，以开启采集从 0 开始计时，单位为毫秒（当有且仅有一路流的时候才有效）。

详情

在此回调中可以收到自定义音频处理 SDK 播放音频的 PCM 音频帧，开发者可对音频帧数据进行修改，同时可以修改声道数、采样率。返回的时间戳可用于数据同步，如歌词等。

通知时机：需要先调用 [enableCustomAudioPlaybackProcessing] 开启功能后，并且在调用 [startPublishingStream], [startPlayingStream], [startPreview], [createMediaPlayer] 或 [createAudioEffectPlayer] 后，才会触发本回调函数。

支持版本：2.13.0 及以上。
使用限制：无。
注意事项：本回调为高频回调，请勿在本回调中做耗时操作。

ZegoCustomVideoCaptureHandler

Declared in ZegoExpressEventHandler.h

方法

onStart:

- (void)onStart:(ZegoPublishChannel) channel;

自定义视频采集开始的通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道。

详情

SDK 通知将要开始采集视频帧，收到该回调后向 SDK 发送的视频帧数据才有效。

业务场景：直播非摄像头采集的数据。例如本地视频文件播放、屏幕分享、游戏直播等。
通知时机：调用 [startPreview] 或 [startPublishingStream] 成功之后。
相关回调：自定义视频采集结束通知 [onCaptureStop]。
相关接口：可调用 [setCustomVideoCaptureHandler] 设置自定义视频采集回调。

支持版本：1.1.0 及以上。
注意事项：收到该回调后向 SDK 发送的视频帧数据才有效。

onStop:

- (void)onStop:(ZegoPublishChannel) channel;

自定义视频采集结束的通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道。

详情

SDK 通知将要结束采集视频帧。

业务场景：直播非摄像头采集的数据。例如本地视频文件播放、屏幕分享、游戏直播等。
通知时机：调用 [stopPreview] 或 [stopPublishingStream] 成功之后。
相关回调：自定义视频采集开始通知 [onCaptureStart]。
相关接口：可调用 [setCustomVideoCaptureHandler] 设置自定义视频采集回调。

支持版本：1.1.0 及以上。
注意事项：如果开启自定义采集后同时调用 [startPreview] 和 [startPublishingStream] 开启预览和推流，则应该调用 [stopPreview] 和 [stopPublishingStream] 停止预览和推流后才会触发该回调。

onEncodedDataTrafficControl:channel:

- (void)onEncodedDataTrafficControl:(ZegoTrafficControlInfo *) trafficControlInfo channel:(ZegoPublishChannel) channel;

自定义视频采集时检测到网络变化，通知开发者需要做流量控制，根据SDK的推荐参数调整编码配置。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
trafficControlInfo	ZegoTrafficControlInfo *	流控参数。
channel	ZegoPublishChannel	推流通道。

详情

使用自定义视频采集时，SDK 检测到网络变化，通知开发者需要做流量控制，根据SDK的推荐参数调整编码配置。由于自定义采集传输已编码数据的情况下，SDK 无法得知外部的编码配置，因此流控操作需要开发者自行完成。SDK 会根据当前的网络情况，将视频配置的推荐值通知到开发者，开发者需要自行对编码器配置进行修改，以保证视频传输的流畅性。

业务场景：直播非摄像头采集的数据。例如本地视频文件播放、屏幕分享、游戏直播等。
通知时机：自定义视频采集过程中发生网络状态变化，需要做流量控制时。
相关接口：可调用 [setCustomVideoCaptureHandler] 设置自定义视频采集回调。

支持版本：1.14.0 及以上。
注意事项：请不要在此回调中执行耗时操作，比如大文件读写，若需执行耗时操作，请切换线程。

ZegoCustomVideoProcessHandler

Declared in ZegoExpressEventHandler.h

方法

onStart:

- (void)onStart:(ZegoPublishChannel) channel;

SDK 通知开发者将要开始进行视频前处理。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道。

详情

开启自定义视频前处理时，SDK 通知开发者将要开始进行视频前处理，推荐在此回调中进行其他资源（比如美颜 SDK）的初始化。

业务场景：开发者自行采集视频数据或获取到 SDK 采集的视频数据后，若 SDK 自带的基础美颜和水印功能无法满足开发者需求时（例如美颜效果无法达到预期），可以结合 ZegoEffects SDK 对视频进行一些特殊处理，例如美颜、添加挂件等，该过程即为自定义视频前处理。
通知时机：开启自定义视频前处理，调用 [startPreview] 或 [startPublishingStream] 成功之后。
相关回调：自定义视频前处理结束通知 [onStop]。
相关接口：可调用 [setCustomVideoProcessHandler] 函数设置自定义视频前处理回调。

支持版本：2.2.0 及以上。

onStop:

- (void)onStop:(ZegoPublishChannel) channel;

SDK 通知开发者停止进行视频前处理。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道。

详情

开启自定义视频前处理时，SDK 通知开发者将要结束视频前处理，推荐在此回调中进行其他资源（比如美颜 SDK）的销毁。

业务场景：开发者自行采集视频数据或获取到 SDK 采集的视频数据后，若 SDK 自带的基础美颜和水印功能无法满足开发者需求时（例如美颜效果无法达到预期），可以结合 ZegoEffects SDK 对视频进行一些特殊处理，例如美颜、添加挂件等，该过程即为自定义视频前处理。
通知时机：如果开启自定义采集后同时调用 [startPreview] 开启预览和 [startPublishingStream] 开启推流，则应该调用 [stopPreview] 停止预览和 [stopPublishingStream] 停止推流后才会触发该回调。
相关回调：自定义视频前处理开始通知 [onStart]。
相关接口：可调用 [setCustomVideoProcessHandler] 函数设置自定义视频前处理回调。

支持版本：2.2.0 及以上。

onCapturedUnprocessedCVPixelBuffer:timestamp:channel:

- (void)onCapturedUnprocessedCVPixelBuffer:(CVPixelBufferRef) buffer timestamp:(CMTime) timestamp channel:(ZegoPublishChannel) channel;

当获取到 [CVPixelBuffer] 类型的原始视频数据时回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
buffer	CVPixelBufferRef	要向 SDK 发送的 CVPixelBuffer 类型视频帧数据。
timestamp	CMTime	该视频帧的时间戳。
channel	ZegoPublishChannel	推流通道。

详情

开启自定义视频前处理时，调用 [setCustomVideoProcessHandler] 设置回调后，SDK 收到原始视频数据并回调给开发者。当开发者处理完原始图像之后，必须调用 [sendCustomVideoProcessedCVPixelbuffer] 将处理后数据传回 SDK 中，否则会导致丢帧现象。

业务场景：开发者自行采集视频数据或获取到 SDK 采集的视频数据后，若 SDK 自带的基础美颜和水印功能无法满足开发者需求时（例如美颜效果无法达到预期），可以结合 ZegoEffects SDK 对视频进行一些特殊处理，例如美颜、添加挂件等，该过程即为自定义视频前处理。
通知时机：开启自定义视频前处理，SDK 采集到原始视频数据时。
平台差异：仅在 iOS/macOS 平台生效。

支持版本：2.2.0 及以上。
使用限制：当调用 [enableCustomVideoProcessing] 开启自定义视频前处理且 config 的 bufferType 传入 [ZegoVideoBufferTypeCVPixelBuffer] 或 [ZegoVideoBufferTypeNV12CVPixelBuffer] 时，此接口生效。

ZegoCustomVideoRenderHandler

Declared in ZegoExpressEventHandler.h

方法

onCapturedVideoFrameRawData:dataLength:param:flipMode:channel:

- (void)onCapturedVideoFrameRawData:(unsigned char * _Nonnull * _Nonnull) data dataLength:(unsigned int *) dataLength param:(ZegoVideoFrameParam *) param flipMode:(ZegoVideoFlipMode) flipMode channel:(ZegoPublishChannel) channel;

开启自定义视频渲染时，本地预览采集的原始视频帧数据回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	unsigned char * _Nonnull * _Nonnull	原始视频帧数据（例：RGBA 只需考虑 data[0]，I420 需考虑 data[0,1,2]）。
dataLength	unsigned int *	数据的长度（例：RGBA 只需考虑 dataLength[0]，I420 需考虑 dataLength[0,1,2]）。
param	ZegoVideoFrameParam *	视频帧参数。
flipMode	ZegoVideoFlipMode	视频帧翻转模式。
channel	ZegoPublishChannel	推流通道。

详情

使用自定义视频渲染时，SDK 回调本地预览采集的原始视频帧数据，由开发者自行渲染。

业务场景：使用了跨平台界面框架或游戏引擎；需要获取 SDK 采集或拉流的视频帧数据进行特殊处理。
通知时机：开启本地预览后，SDK 采集到本地预览视频帧数据时。
相关接口：可调用 [setCustomVideoRenderHandler] 设置自定义视频渲染回调。

支持版本：1.1.0 及以上。

onRemoteVideoFrameRawData:dataLength:param:streamID:

- (void)onRemoteVideoFrameRawData:(unsigned char * _Nonnull * _Nonnull) data dataLength:(unsigned int *) dataLength param:(ZegoVideoFrameParam *) param streamID:(NSString *) streamID;

开启自定义视频渲染时，远端拉流原始视频帧数据回调，通过 streamID 区分不同的流。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	unsigned char * _Nonnull * _Nonnull	原始视频帧数据（例：RGBA 只需考虑 data[0]，I420 需考虑 data[0,1,2]）。
dataLength	unsigned int *	数据的长度（例：RGBA 只需考虑 dataLength[0]，I420 需考虑 dataLength[0,1,2]）。
param	ZegoVideoFrameParam *	视频帧参数。
streamID	NSString *	拉流的流 ID。

详情

开启自定义视频渲染时，SDK 回调远端拉流原始视频帧数据，通过 streamID 区分不同的流，由开发者自行渲染。

业务场景：使用了跨平台界面框架或游戏引擎；需要获取 SDK 采集或拉流的视频帧数据进行特殊处理。
通知时机：开始拉流后，SDK 收到远端拉流视频帧数据时。
相关接口：可调用 [setCustomVideoRenderHandler] 设置自定义视频渲染回调。

支持版本：1.1.0 及以上。

onCapturedVideoFrameCVPixelBuffer:param:flipMode:channel:

- (void)onCapturedVideoFrameCVPixelBuffer:(CVPixelBufferRef) buffer param:(ZegoVideoFrameParam *) param flipMode:(ZegoVideoFlipMode) flipMode channel:(ZegoPublishChannel) channel;

自定义视频渲染本地预览视频帧 CVPixelBuffer 数据回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
buffer	CVPixelBufferRef	封装为 CVPixelBufferRef 的视频帧数据。
param	ZegoVideoFrameParam *	视频帧参数。
flipMode	ZegoVideoFlipMode	视频帧翻转模式。
channel	ZegoPublishChannel	推流通道。

详情

当调用 [enableCustomVideoRender] 开启自定义视频渲染并且指定数据类型为 [CVPixelBuffer] 时，将通过此函数回调本地预览视频帧 CVPixelBufferRef 数据。

业务场景：需要获取 SDK 采集的视频帧数据进行特殊处理的场景，例如使用了跨平台 UI 框架、游戏引擎等。
通知时机：调用 [startPreview] 开始预览后，SDK 采集到本地预览视频帧数据时回调。
相关接口：可调用 [setCustomVideoRenderHandler] 设置自定义视频渲染回调。
平台差异：仅 iOS / macOS 专有。

支持版本：1.1.0 及以上。

onRemoteVideoFrameCVPixelBuffer:param:streamID:

- (void)onRemoteVideoFrameCVPixelBuffer:(CVPixelBufferRef) buffer param:(ZegoVideoFrameParam *) param streamID:(NSString *) streamID;

自定义视频渲染远端拉流视频帧 CVPixelBuffer 数据回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
buffer	CVPixelBufferRef	封装为 CVPixelBufferRef 的视频帧数据。
param	ZegoVideoFrameParam *	视频帧参数。
streamID	NSString *	拉流的流 ID。

详情

当使用 [enableCustomVideoRender] 开启自定义视频渲染并且指定数据类型为 [CVPixelBuffer] 时，远端拉流 CVPixelBuffer 格式视频帧数据回调，通过 streamID 区分不同的流，视频数据由开发者自行渲染。

业务场景：需要获取 SDK 远端拉流的视频帧数据进行特殊处理的场景，例如使用了跨平台 UI 框架、游戏引擎等。
通知时机：调用 [startPlayingStream] 开始拉流后，SDK 收到远端拉流视频帧数据时回调。
相关接口：可调用 [setCustomVideoRenderHandler] 设置自定义视频渲染回调。
平台差异：仅 iOS / macOS 专有。

支持版本：1.1.0 及以上。

onRemoteVideoFrameEncodedData:dataLength:param:referenceTimeMillisecond:streamID:

- (void)onRemoteVideoFrameEncodedData:(unsigned char * _Nonnull) data dataLength:(unsigned int) dataLength param:(ZegoVideoEncodedFrameParam *) param referenceTimeMillisecond:(unsigned long long) referenceTimeMillisecond streamID:(NSString *) streamID;

自定义视频渲染远端拉流视频帧未解码数据回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	unsigned char * _Nonnull	视频帧的编码数据。
dataLength	unsigned int	数据的长度。
param	ZegoVideoEncodedFrameParam *	视频帧参数。
referenceTimeMillisecond	unsigned long long	视频帧的索引时间，UNIX 时间戳，单位为毫秒。
streamID	NSString *	拉流的流 ID。

详情

当使用 [enableCustomVideoRender] 开启自定义视频渲染并且指定数据类型为 [EncodedData] 时，远端拉流未解码视频帧数据回调，通过 streamID 区分不同的流，视频数据由开发者自行渲染。详情描述：开启自定义视频渲染时，远端拉流视频帧编码后的数据回调，通过 streamID 区分不同的流，由开发者自行渲染。

通知时机：开始拉流后，SDK 收到远端拉流视频帧数据时。
相关接口：可调用 [setCustomVideoRenderHandler] 设置自定义视频渲染回调。

支持版本：1.10.0 及以上。

ZegoDataRecordEventHandler

Declared in ZegoExpressEventHandler.h

方法

onCapturedDataRecordStateUpdate:errorCode:config:channel:

- (void)onCapturedDataRecordStateUpdate:(ZegoDataRecordState) state errorCode:(int) errorCode config:(ZegoDataRecordConfig *) config channel:(ZegoPublishChannel) channel;

本地录制的状态更新回调，当录制过程状态变化时触发。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoDataRecordState	文件录制状态。
errorCode	int	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
config	ZegoDataRecordConfig *	录制配置对象。
channel	ZegoPublishChannel	推流通道。

详情

本地录制的状态更新回调，当录制过程状态变化时触发。

业务场景：开发者应根据此回调来判断文件录制的状态或者进行 UI 的提示等。
通知时机：调用 [startRecordingCapturedData] 后，当录制过程状态变化时触发。

支持版本：1.10.0 及以上。
使用限制：无。

onCapturedDataRecordProgressUpdate:config:channel:

- (void)onCapturedDataRecordProgressUpdate:(ZegoDataRecordProgress *) progress config:(ZegoDataRecordConfig *) config channel:(ZegoPublishChannel) channel;

录制进度更新回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
progress	ZegoDataRecordProgress *	文件录制过程进度，开发者可以此对用户界面进行 UI 的提示等。
config	ZegoDataRecordConfig *	录制配置对象。
channel	ZegoPublishChannel	推流通道。

详情

本地录制的进度更新回调，录制过程中定时触发。

业务场景：开发者可以此对用户界面进行 UI 的提示等。
通知时机：调用 [startRecordingCapturedData] 后，如果配置了需要回调，录制过程中定时触发。

支持版本：1.10.0 及以上。
使用限制：无。

ZegoEventHandler

Declared in ZegoExpressEventHandler.h

方法

onDebugError:funcName:info:

- (void)onDebugError:(int) errorCode funcName:(NSString *) funcName info:(NSString *) info;

调试错误信息回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
funcName	NSString *	函数名。
info	NSString *	错误的详细信息。

详情

调用 SDK 函数出现异常时，会通过该回调提示详细的异常信息。

业务场景：开发者在集成 SDK 的开发、测试阶段，可以通过本回调中的详细异常信息快速定位问题。
通知时机：在 SDK 出现异常时通知开发者。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：无。

onEngineStateUpdate:

- (void)onEngineStateUpdate:(ZegoEngineState) state;

音视频引擎状态更新的回调通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoEngineState	音视频引擎状态。

详情

音视频引擎状态更新的回调通知，当启用音视频功能时，比如预览、推流、本地媒体播放器、原始音频数据获取等，音视频引擎会进入开始状态，当退出房间或停用所有音视频功能时，音视频引擎会进入停止状态。

通知时机：开发者调用了相关函数改变了音视频引擎的状态。例如：1. 调用了ZegoExpressEngine的 [startPreview]、[stopPreview]、[startPublishingStream]、[startPlayingStream]、[startAudioDataObserver] 等函数。2. 调用了 MediaPlayer 的相关函数等。3. 调用了 [logoutRoom] 函数。4.调用了 RealTimeSequentialDataManager 的相关接口等。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项： 1. 开发者调用 [destroyEngine] 时，由于 SDK 的资源被完全释放，并不会触发此通知。 2. 如无特殊需要，开发者可以不必关注本回调。

onRecvExperimentalAPI:

- (void)onRecvExperimentalAPI:(NSString *) content;

实验性 API 回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
content	NSString *	回调的内容，JSON 字符串格式。

详情

接收实验性 API 回调，请在 ZEGO 技术支持的帮助下使用此功能。

支持版本：2.7.0 及以上。

onFatalError:

- (void)onFatalError:(int) errorCode;

发生致命性错误的回调通知，SDK功能无法正常使用。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	错误码。

详情

发生致命性错误的回调通知。

通知时机：当 APP 开启了禁止域外 IP 访问的限制，当前客户端处于域外，就会触发。

支持版本：3.6.0 及以上。
使用限制：无。
注意事项：无。

onRoomStateUpdate:errorCode:extendedData:roomID:

- (void)onRoomStateUpdate:(ZegoRoomState) state errorCode:(int) errorCode extendedData:(nullable NSDictionary *) extendedData roomID:(NSString *) roomID;

房间状态变化通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoRoomState	变化后的房间状态。
errorCode	int	错误码，详情请参考常见错误码。
extendedData	nullable NSDictionary *	状态更新附带的扩展信息。当房间登录成功时，可通过"room_session_id" key 获取每一次音视频通信唯一的 RoomSessionID，标识房间内首个用户发起音视频通信到最后一个用户结束通信的持续通信。可用于通话质量评分、通话问题诊断等场景中。
roomID	NSString *	房间 ID，最大长度为 128 字节的字符串。

详情

当房间的连接状态改变时触发该回调，并通知改变的原因。2.18.0 及以上版本推荐使用 onRoomStateChanged 回调来替代 onRoomStateUpdate 回调监听房间状态变化。

业务场景：开发者可以通过这个回调来判断房间内当前用户的状态。
通知时机： 1. 开发者调用 [loginRoom]、[logoutRoom]、[switchRoom] 函数时会收到此通知。

用户设备的网络情况变化时也可能收到此通知 (SDK 在断线时会自动重新登录房间，详情请参考 SDK 是否支持断线重连机制。

相关接口：[loginRoom]、[logoutRoom]、[switchRoom]。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：若长时间处于正在请求连接状态（ZegoRoomStateConnecting），一般是因为用户端网络不稳定导致。

onRoomStateChanged:errorCode:extendedData:roomID:

- (void)onRoomStateChanged:(ZegoRoomStateChangedReason) reason errorCode:(int) errorCode extendedData:(NSDictionary *) extendedData roomID:(NSString *) roomID;

房间状态变化通知，包含具体的状态变化原因。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
reason	ZegoRoomStateChangedReason	房间状态变化原因。
errorCode	int	错误码，详情请参考常用错误码文档 https://doc-zh.zego.im/zh/4378.html
extendedData	NSDictionary *	状态更新附带的扩展信息。当房间登录成功时，可通过 "room_session_id" key 获取每一次音视频通信唯一的 RoomSessionID，标识房间内首个用户发起音视频通信到最后一个用户结束通信的持续通信。可用于通话质量评分、通话问题诊断等场景中。
roomID	NSString *	房间 ID，最大长度为 128 字节的字符串。

详情

当房间的连接状态改变时触发该回调，并通知改变的原因。2.18.0 及以上版本推荐使用 onRoomStateChanged 回调来替代 onRoomStateUpdate 回调监听房间状态变化。

业务场景：开发者可以通过这个回调来判断房间内当前用户的状态。
通知时机： 1. 开发者调用房间相关函数 (参考 "相关接口") 时会收到此通知。 2. 用户设备的网络情况变化时也可能收到此通知 (SDK 在断线时会自动重新登录房间，详情请参考 https://doc-zh.zego.im/faq/reconnect )。
相关接口：[loginRoom], [logoutRoom], [switchRoom]

支持版本：2.18.0 及以上。
使用限制：无。
注意事项：若长时间处于正在请求连接状态 [ZegoRoomStateConnecting]，一般是因为用户端网络不稳定导致。

onRoomUserUpdate:userList:roomID:

- (void)onRoomUserUpdate:(ZegoUpdateType) updateType userList:(NSArray<ZegoUser *> *) userList roomID:(NSString *) roomID;

房间内其他用户增加或减少的回调通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
updateType	ZegoUpdateType	更新类型（添加/删除）。
userList	NSArray<ZegoUser >	当前房间内变更的用户列表。
roomID	NSString *	用户已登录的房间 ID，最大长度为 128 字节的字符串。

详情

当房间内有其他用户上线或下线时，导致房间内用户列表发生变化，会通过本回调通知开发者。

业务场景：开发者可以通过这个回调来实时更新房间内的用户列表展示。
通知时机： 1. 用户首次登录房间时，如果房间内有其他用户，SDK 会触发 "updateType" 为 [ZegoUpdateTypeAdd] 的回调通知，此时 "userList" 为房间内的其他用户。 2. 用户已在房间内，如果有其他用户通过 [loginRoom]、[switchRoom] 函数登录到本房间，SDK 会触发 "updateType" 为 [ZegoUpdateTypeAdd] 的回调通知。 3. 用户已在房间内，有其他用户通过 [logoutRoom]、[switchRoom] 函数登出本房间，SDK 会触发 "updateType" 为 [ZegoUpdateTypeDelete] 的回调通知。 4. 用户已在房间内，如果有其他用户从服务端被踢出本房间，SDK 会触发 "updateType" 为 [ZegoUpdateTypeDelete] 的回调通知。
相关接口：[loginRoom]、[logoutRoom]、[switchRoom]。

支持版本：1.1.0 及以上。
使用限制：调用 [loginRoom] 登录房间时设置 [ZegoRoomConfig] 参数中的 "isUserStatusNotify" 属性为 "true" 时，才会接收到这个回调通知。如果开发者需要使用在回调通知中处理相关业务，请确保每个登录的用户都将 "isUserStatusNotify" 设置为 "true"。

onRoomOnlineUserCountUpdate:roomID:

- (void)onRoomOnlineUserCountUpdate:(int) count roomID:(NSString *) roomID;

房间内当前在线用户数量回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
count	int	当前在线用户数量。
roomID	NSString *	用户已登录的房间 ID，最大长度为 128 字节的字符串。

详情

此方法会通知用户当前房间内的在线人数。

业务场景：开发者可根据此回调来来展示当前房间内的在线人数。
通知时机：登录房间成功后。

支持版本：1.7.0 及以上。
使用限制：无。
注意事项：1. 此函数 30 秒回调一次。2. 因设计如此，当房间内用户超过 500 后，对房间内在线人数的统计会有一些误差。

onRoomStreamUpdate:streamList:extendedData:roomID:

- (void)onRoomStreamUpdate:(ZegoUpdateType) updateType streamList:(NSArray<ZegoStream *> *) streamList extendedData:(nullable NSDictionary *) extendedData roomID:(NSString *) roomID;

相同房间内其他用户推的流增加或减少的通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
updateType	ZegoUpdateType	更新类型（添加/删除）。
streamList	NSArray<ZegoStream >	更新的流列表。
extendedData	nullable NSDictionary *	流更新附带的扩展信息。收到流删除通知时，开发者可将该字符串转为 json 对象得到 stream_delete_reason 字段，该字段为流删除原因的数组，stream_delete_reason[].code 字段可能为如下值：1（用户主动停止推流）； 2（用户心跳超时）； 3（用户重复登录）； 4（用户被踢出）； 5（用户断线）； 6（被服务端移除）。
roomID	NSString *	用户已登录的房间 ID，最大长度为 128 字节的字符串。

详情

当房间内有其他用户开始推流或停止推流时，导致房间内流列表发生变化，会通过本回调通知开发者。

业务场景：开发者可根据此回调来判断指定房间内其他用户是否新增推流或停止推流，并根据情况选择调用 [startPlayingStream] 主动拉流或调用[stopPlayingStream] 停止拉流，同时也可以变更拉流的 UI 控件。
通知时机： 1. 用户首次登录房间时，如果房间内其他用户正在推流，SDK 会触发 updateType 为 [ZegoUpdateTypeAdd] 的回调通知，此时 "streamList" 为已存在的流列表。 2. 用户已在房间内，如果有其他用户新增推流，SDK 会触发 "updateType" 为 [ZegoUpdateTypeAdd] 的回调通知。 3. 用户已在房间内，如果有其他用户停止推流，SDK 会触发 "updateType" 为 [ZegoUpdateTypeDelete] 的回调通知。 4. 用户已在房间内，如果有其他用户退出房间，SDK 会触发 "updateType" 为 [ZegoUpdateTypeDelete] 的回调通知。

支持版本：1.1.0 及以上。
使用限制：无。

onRoomStreamExtraInfoUpdate:roomID:

- (void)onRoomStreamExtraInfoUpdate:(NSArray<ZegoStream *> *) streamList roomID:(NSString *) roomID;

房间内流附加信息更新通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamList	NSArray<ZegoStream >	流附加信息更新的流列表。
roomID	NSString *	用户已登录的房间 ID，最大长度为 128 字节的字符串。

详情

房间内流附加信息更新时所有房间内用户会收到通知。

业务场景：用户可通过流附加信息与流生命周期一致的特性实现一些业务功能。
通知时机：当相同房间内一个正在推流的用户更新了流的附加信息时，相同房间内的其他用户会收到该回调。
相关接口：推流用户可以通过 [setStreamExtraInfo] 设置流附加信息。

支持版本：1.1.0 及以上。
使用限制：无。
注意事项：不同于流 ID 在推流过程中不可修改，流附加信息可以在对应流 ID 的生命周期中更新。

onRoomExtraInfoUpdate:roomID:

- (void)onRoomExtraInfoUpdate:(NSArray<ZegoRoomExtraInfo *> *) roomExtraInfoList roomID:(NSString *) roomID;

房间附加信息更新通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
roomExtraInfoList	NSArray<ZegoRoomExtraInfo >	更新的房间附加信息列表。
roomID	NSString *	用户已登录的房间 ID，最大长度为 128 字节的字符串。

详情

房间附加信息更新后，除更新房间附加信息的用户外，房间内所有用户会收到通知。

业务场景：为房间附加信息。
通知时机：当相同房间内其他用户更新了房间附加信息时，相同房间内的其他用户会收到该回调。
相关接口：用户可以通过 [setRoomExtraInfo] 更新房间附加信息。

支持版本：1.1.0 及以上。
使用限制：无。

onRoomTokenWillExpire:roomID:

- (void)onRoomTokenWillExpire:(int) remainTimeInSecond roomID:(NSString *) roomID;

房间 Token 鉴权将要过期的回调通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
remainTimeInSecond	int	token 过期前的剩余时间。
roomID	NSString *	用户已登录的房间 ID，最大长度为 128 字节的字符串。

详情

房间 Token 鉴权将要过期的回调通知，请用户通过 [renewToken] 函数更新房间 Token 鉴权。

业务场景：为了防止炸麦场景，需要对登录房间、推流等操作进行鉴权控制，提高安全性。
通知时机：在 Token 过期前 30 秒，SDK 会通过 onRoomTokenWillExpire 回调发出通知。
相关接口：当开发者收到此回调后，可通过 [renewToken] 来更新 token 鉴权信息。

支持版本：2.8.0 及以上。
使用限制：无。
注意事项：Token 中包含用户的房间权限、推流权限、有效时间等重要信息，详情请参考 https://doc-zh.zego.im/article/10360 。

onPublisherStateUpdate:errorCode:extendedData:streamID:

- (void)onPublisherStateUpdate:(ZegoPublisherState) state errorCode:(int) errorCode extendedData:(nullable NSDictionary *) extendedData streamID:(NSString *) streamID;

推流状态回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoPublisherState	推流状态。
errorCode	int	推流状态变更对应的错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
extendedData	nullable NSDictionary *	状态更新附带的扩展信息，包含CDN拉流地址。
streamID	NSString *	推流的流 ID。

详情

在调用推流接口 [startPublishingStream] 成功后，可以通过该回调函数获取推流状态变更的通知。开发者可根据 state 参数是否在 [正在请求推流状态] 来大体判断用户的推流网络情况。

相关回调：在调用拉流接口 [startPlayingStream] 成功后，可以通过回调函数 [onPlayerStateUpdate] 获取拉流状态变更的通知。开发者可根据 state 参数是否在 [正在请求拉流状态] 来大体判断用户的拉流网络情况。

支持版本：1.1.0 及以上。
注意事项：参数 [extendedData] 为状态更新附带的扩展信息。若使用 ZEGO 的 CDN 内容分发网络，在推流成功后，该参数的内容的键为 [flv_url_list]、[rtmp_url_list]、[hls_url_list]，分别对应 flv、rtmp、hls 协议的拉流 URL。

onPublisherQualityUpdate:streamID:

- (void)onPublisherQualityUpdate:(ZegoPublishStreamQuality *) quality streamID:(NSString *) streamID;

推流质量回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
quality	ZegoPublishStreamQuality *	推流质量，包含了音视频帧率、码率、RTT 等值。
streamID	NSString *	推流的流 ID。

详情

在调用推流接口 [startPublishingStream] 成功后默认3秒(该时间如果需要变更，请联系 ZEGO 技术支持配置)会收到此回调，通过该回调可以获取推送的音视频流的采集帧率，码率，RTT，丢包率等质量数据。开发者可根据此函数的质量参数实时监控推送的音视频流的健康情况，以便在设备 UI 界面上实时展示上行网络状况。

相关回调：当调用拉流接口 [startPlayingStream] 成功后每3秒会收到回调 [onPlayerQualityUpdate]，开发者可根据拉取的音视频流的帧率，码率，RTT，丢包率等质量数据，实时监控拉取流的健康情况。

支持版本：1.1.0 及以上。
注意事项：若开发者不清楚该回调函数的各个参数应该如何使用，可以只关注其中的 [quality] 参数的 [level] 字段，这是 SDK 内部根据质量参数计算的一个描述上行网络的综合值。

onPublisherCapturedAudioFirstFrame

- (void)onPublisherCapturedAudioFirstFrame;

音频采集首帧回调接口。

Declared in ZegoExpressEventHandler.h

SDK 启动麦克风采集到第一帧音频数据时会收到此回调。若未收到该回调,说明音频采集设备被占用或异常。

通知时机：SDK内部的音视频模块的引擎启动时，SDK 会去采集本机设备的音频数据，此时会收到该回调。
相关回调：通过回调函数[onPublisherCapturedVideoFirstFrame] 判断 SDK 是否真正采集到了视频数据，通过回调[onPublisherRenderVideoFirstFrame] 判断 SDK 是否渲染完了采集到的第一帧视频数据。

支持版本：1.1.0 及以上。

onPublisherCapturedVideoFirstFrame:

- (void)onPublisherCapturedVideoFirstFrame:(ZegoPublishChannel) channel;

视频采集首帧回调接口。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

SDK 启动摄像头采集到第一帧视频数据时会收到此回调。若未收到该回调，说明视频采集设备被占用或异常。

通知时机：SDK 内部的音视频模块的引擎启动时，SDK 会去采集本机设备的视频数据，此时会收到该回调。
相关回调：通过回调函数 [onPublisherCapturedAudioFirstFrame] 判断 SDK 是否真的采集到音频数据，通过回调 [onPublisherRenderVideoFirstFrame] 判断 SDK 是否渲染完采集到的第一帧视频数据。

支持版本：1.1.0 及以上。

onPublisherSendAudioFirstFrame:

- (void)onPublisherSendAudioFirstFrame:(ZegoPublishChannel) channel;

推流端音频发送首帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道，如果只推一路音频流，可以不关注该参数。

详情

调用推流函数 [startPublishingStream] 成功后，SDK 发出第一帧音频数据时会收到此回调。开发者可根据该回调判断 SDK 是否真的发出音频数据，若未收到该回调，说明音频发送异常。

通知时机：在未调用推流函数 [startPublishingStream] 的情况下，首次推流 SDK 会收到该回调。
相关回调：调用推流函数 [startPublishingStream] 成功后, 通过回调函数 [onPublisherCapturedVideoFirstFrame] 判断 SDK 是否真的采集到视频数据，通过回调 [onPublisherRenderVideoFirstFrame] 判断 SDK 是否渲染完采集到的第一帧视频数据。

支持版本：3.5.0 及以上。

onPublisherSendVideoFirstFrame:

- (void)onPublisherSendVideoFirstFrame:(ZegoPublishChannel) channel;

推流端视频发送首帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道，如果只推一路视频流，可以不关注该参数。

详情

调用推流函数 [startPublishingStream] 成功后，SDK 发出第一帧视频数据时会收到此回调。开发者可根据该回调判断 SDK 是否真的发出视频数据，若未收到该回调，说明视频发送异常。

通知时机：在未调用推流函数 [startPublishingStream] 的情况下，首次推流 SDK 会收到该回调。
相关回调：调用推流函数 [startPublishingStream] 成功后, 通过回调函数 [onPublisherCapturedAudioFirstFrame] 判断 SDK 是否真的采集到音频数据，通过回调 [onPublisherRenderVideoFirstFrame] 判断 SDK 是否渲染完采集到的第一帧视频数据。

支持版本：3.5.0 及以上。

onPublisherRenderVideoFirstFrame:

- (void)onPublisherRenderVideoFirstFrame:(ZegoPublishChannel) channel;

推流端视频渲染首帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

SDK 渲染完采集到的第一帧视频数据时会收到此回调，该接口为预览渲染，自定义视频采集内部预览才有首帧回调，如果不是 SDK 渲染没有此回调。

相关回调：调用推流函数 [startPublishingStream] 成功后, 通过回调函数 [onPublisherCapturedAudioFirstFrame] 判断 SDK 是否真的采集到音频数据，通过回调 [onPublisherCapturedVideoFirstFrame] 判断 SDK 是否真的采集到视频数据。

支持版本：2.4.0 及以上。

onPublisherVideoSizeChanged:channel:

- (void)onPublisherVideoSizeChanged:(CGSize) size channel:(ZegoPublishChannel) channel;

采集视频大小变更回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
size	CGSize	视频采集分辨率
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

当在未推流 [startPublishingStream] 或未预览 [startPreview] 的情况下，首次推流或首次预览，即 SDK 内部的音视频模块的引擎启动时，会去采集本机设备的视频数据，此时采集分辨率会改变。

通知时机：推流 [startPublishingStream] 成功后，在推流中途如果有改变视频采集分辨率发生变化将会收到此回调。
业务场景：开发者可以根据此回调来去除本地预览的 UI 的遮盖等类似操作。也可以根据该回调的分辨率来动态调整预览视图的比例等。

支持版本：1.1.0 及以上。
注意事项：外部采集时通知的是编码分辨率大小变化，会受到流控影响。

onPublisherRelayCDNStateUpdate:streamID:

- (void)onPublisherRelayCDNStateUpdate:(NSArray<ZegoStreamRelayCDNInfo *> *) infoList streamID:(NSString *) streamID;

添加/删除转推 CDN 地址状态回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
infoList	NSArray<ZegoStreamRelayCDNInfo >	当前 CDN 正在转推的信息列表。
streamID	NSString *	推流的流 ID。

详情

开发者可根据该回调判断转推 CDN 的音视频流是否正常，若不正常根据异常原因进一步定位转推 CDN 的音视频流异常的原因，以及做对应的容灾策略。

通知时机：在 ZEGO RTC 服务器将音视频流转推到 CDN 后，如果 CDN 转推状态发生变化，例如出现转推停止或转推重试，将会收到此回调。

支持版本：1.1.0 及以上。
注意事项：若对异常的原因不了解，可联系 ZEGO 技术人员分析具体异常的原因。

onPublisherVideoEncoderChanged:toCodecID:channel:

- (void)onPublisherVideoEncoderChanged:(ZegoVideoCodecID) fromCodecID toCodecID:(ZegoVideoCodecID) toCodecID channel:(ZegoPublishChannel) channel;

视频编码器变更回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
fromCodecID	ZegoVideoCodecID	变更前的视频编码器 ID。
toCodecID	ZegoVideoCodecID	变更后的视频编码器 ID。
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

推流使用的编码类型发生变化的回调。

通知时机：以 H.265 编码进行推流过程中，如果不支持 H.265 编码或编码失败，SDK 会主动降级为指定编码（H.264），此时会触发本回调。

支持版本：2.12.0 及以上。
注意事项：在触发本回调时，如果正在进行本地视频录制或云端录制，则会导致生成多个录制文件，开发者需要在录制结束后，收集所有录制文件进行处理。在触发本回调时，因为推流编码发生变更，开发者可以评估是否通知拉流端，以便拉流端做对应处理。

onPublisherStreamEvent:streamID:extraInfo:

- (void)onPublisherStreamEvent:(ZegoStreamEvent) eventID streamID:(NSString *) streamID extraInfo:(NSString *) extraInfo;

推流事件回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
eventID	ZegoStreamEvent	推流事件ID
streamID	NSString *	推流的流 ID。
extraInfo	NSString *	附加信息。JSON 格式的字符串。目前包括的信息有 "url"表示地址, "streamProtocol"表示流协议，包括rtmp,flv,avertp，hls，webrtc等, "netProtocol"表示网络协议，包括tcp,udp,quic, "resourceType"表示资源类型，包括cdn,rtc,l3。

详情

发起推流后，这个回调会返回当前使用的推流地址，资源类型和协议相关信息。

通知时机：推流以及重试推流的事件。

支持版本：2.18.0 及以上。
注意事项：无。

onVideoObjectSegmentationStateChanged:channel:errorCode:

- (void)onVideoObjectSegmentationStateChanged:(ZegoObjectSegmentationState) state channel:(ZegoPublishChannel) channel errorCode:(int) errorCode;

视频主体分割状态变化。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoObjectSegmentationState	主体分割状态。
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。
errorCode	int	主体分割状态变更对应的错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html

详情

推流端视频主体分割状态变化。

通知时机：当 [enableVideoObjectSegmentation] 开启或关闭主体分割后，根据实际情况通知开发者是否开启主体分割。

支持版本：3.4.0 及以上。
注意事项：该回调依赖于开启预览或者推流。

onPublisherLowFpsWarning:channel:

- (void)onPublisherLowFpsWarning:(ZegoVideoCodecID) codecID channel:(ZegoPublishChannel) channel;

视频编码低帧率警告。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
codecID	ZegoVideoCodecID	视频编码器 ID。
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

推流视频编码低帧率警告。

通知时机：推流视频编码出现低帧率会触发本回调。

支持版本：3.8.0 及以上。
注意事项：该回调默认关闭，若有需要，请联系 ZEGO 技术支持。

onPublisherDummyCaptureImagePathError:path:channel:

- (void)onPublisherDummyCaptureImagePathError:(int) errorCode path:(NSString *) path channel:(ZegoPublishChannel) channel;

通知设置关闭摄像头时所推静态图片的路径错误。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	错误码。
path	NSString *	图片路径。
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

通知设置关闭摄像头时所推静态图片的路径错误。

通知时机：通过 [setDummyCaptureImagePath] 设置了图片的路径，但是推流时无法获取到该图片，就会触发本回调。

支持版本：3.9.0 及以上。
注意事项：设置前请确保该图片路径正确，有读权限。

onPublisherFaceDetectInfo:channel:

- (void)onPublisherFaceDetectInfo:(ZegoFaceDetectionInfo *) info channel:(ZegoPublishChannel) channel;

人脸检测信息更新通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
info	ZegoFaceDetectionInfo *	人脸检测信息。
channel	ZegoPublishChannel	推流通道，如果只推一路音视频流，可以不关注该参数。

详情

人脸检测信息更新。

通知时机：通过 [enableFaceDetection] 接口开启人脸检测，启动相机或人脸数量变化时，就会触发本回调。

支持版本：3.20.0 及以上。
注意事项：该回调是低频的，无法与自定义视频前处理配合使用。

onPlayerStateUpdate:errorCode:extendedData:streamID:

- (void)onPlayerStateUpdate:(ZegoPlayerState) state errorCode:(int) errorCode extendedData:(nullable NSDictionary *) extendedData streamID:(NSString *) streamID;

拉流状态变更回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoPlayerState	拉流状态。
errorCode	int	拉流状态变更对应的错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
extendedData	nullable NSDictionary *	状态更新附带的扩展信息。备用，目前仅返回空 json 表。
streamID	NSString *	流 ID。

详情

在调用拉流接口 [startPlayingStream] 成功后，可以通过该回调函数获取拉流状态变更的通知。开发者可根据 state 参数是否在 [正在请求拉流状态] 来大体判断用户的拉流网络情况。

通知时机：在调用拉流接口 [startPlayingStream] 成功后，拉流状态变更时。
相关回调：在调用推流接口 [startPublishingStream] 成功后，可以通过回调函数 [onPublisherStateUpdate] 获取推流状态变更的通知。开发者可根据 state 参数是否在 [正在请求推流状态] 来大体判断用户的推流网络情况。

支持版本：1.1.0 及以上。

onPlayerSwitched:streamID:

- (void)onPlayerSwitched:(int) errorCode streamID:(NSString *) streamID;

切换拉流结果回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	切换流结果对应的错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
streamID	NSString *	当前播放的流 ID。

详情

在调用切换流接口 [switchPlayingStream] 成功后，可以通过该回调函数获取切换流的结果。

通知时机：在调用切换流接口 [switchPlayingStream] 成功后，切换流请求最终成功或失败时。
相关回调：在切换流成功或失败后，可以通过回调函数 [onPlayerStateUpdate] 获取当前拉流状态。

支持版本：3.16.0 及以上。

onPlayerQualityUpdate:streamID:

- (void)onPlayerQualityUpdate:(ZegoPlayStreamQuality *) quality streamID:(NSString *) streamID;

拉流质量回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
quality	ZegoPlayStreamQuality *	拉流质量，包含了音视频帧率、码率、RTT 等值。
streamID	NSString *	拉流的流 ID。

详情

在调用拉流接口 [startPlayingStream] 成功后每3秒(该时间如果需要变更，请联系 ZEGO 技术支持配置)会收到此回调，通过该回调可以获取拉取的音视频流的帧率，码率，RTT，丢包率等质量数据。

业务场景：开发者可根据此函数的质量参数实时监控拉取的音视频流的健康情况，以便在设备 UI 界面上实时展示下行网络状况。
相关回调：当调用推流接口 [startPublishingStream] 成功后每3秒会收到回调 [onPublisherQualityUpdate]，开发者可根据推送的音视频流的帧率，码率，RTT，丢包率等质量数据，实时监控推送流的健康情况。

支持版本：1.1.0 及以上。
注意事项：若开发者不清楚该回调函数的各个参数应该如何使用，可以只关注其中的 quality 参数的 level 字段，这是 SDK 内部根据质量参数计算的一个描述下行网络的综合值。

onPlayerMediaEvent:streamID:

- (void)onPlayerMediaEvent:(ZegoPlayerMediaEvent) event streamID:(NSString *) streamID;

拉流媒体事件回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
event	ZegoPlayerMediaEvent	拉流时收到的具体事件。
streamID	NSString *	拉流的流 ID。

详情

该回调用于接收拉流媒体事件。

业务场景：开发者可以根据此回调对卡顿情况做统计或在 App 的 UI 界面做友好的展示。
通知时机：在调用拉流接口 [startPlayingStream]后，当拉流发生音视频卡顿以及恢复等事件发生时会触发此回调。

支持版本：1.1.0 及以上。

onPlayerRecvAudioFirstFrame:

- (void)onPlayerRecvAudioFirstFrame:(NSString *) streamID;

拉流端音频接收首帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 接收到第一帧音频数据时会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：SDK 从网络接收到第一帧音频数据时，会收到该回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerRecvVideoFirstFrame] 判断 SDK 是否接收到视频数据，通过回调 [onPlayerRenderVideoFirstFrame] 判断 SDK 是否渲染完接收到的第一帧视频数据。

支持版本：1.1.0 及以上。

onPlayerSyncRecvAudioFirstFrame:

- (void)onPlayerSyncRecvAudioFirstFrame:(NSString *) streamID;

拉流端音频接收首帧回调。请不要在回调线程调用 SDK 接口。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 接收到第一帧音频数据时会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：SDK 从网络接收到第一帧音频数据时，会收到该回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerSyncRecvVideoFirstFrame] 判断 SDK 是否接收到视频数据，通过回调 [onPlayerSyncRecvRenderVideoFirstFrame] 判断 SDK 是否渲染完接收到的第一帧视频数据。

支持版本：3.22.0 及以上。

onPlayerRecvVideoFirstFrame:

- (void)onPlayerRecvVideoFirstFrame:(NSString *) streamID;

拉流端视频接收首帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 接收到第一帧视频数据时会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：SDK 从网络接收到第一帧视频数据时，会收到该回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerRecvAudioFirstFrame] 判断 SDK 是否接收到音频数据，通过回调 [onPlayerRenderVideoFirstFrame] 判断 SDK 是否渲染完接收到的第一帧视频数据。

支持版本：1.1.0 及以上。

onPlayerSyncRecvVideoFirstFrame:

- (void)onPlayerSyncRecvVideoFirstFrame:(NSString *) streamID;

拉流端视频接收首帧回调，请不要在回调线程调用 SDK 接口。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 接收到第一帧视频数据时会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时。
通知时机：SDK 从网络接收到第一帧视频数据时，会收到该回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerSyncRecvAudioFirstFrame] 判断 SDK 是否接收到音频数据，通过回调 [onPlayerSyncRecvRenderVideoFirstFrame] 判断 SDK 是否渲染完接收到的第一帧视频数据。

支持版本：3.8.0 及以上。

onPlayerRenderVideoFirstFrame:

- (void)onPlayerRenderVideoFirstFrame:(NSString *) streamID;

拉流端渲染完视频首帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 拉流并渲染完第一帧视频数据后会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：SDK 拉流并渲染完第一帧视频数据后会收到此回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerRecvAudioFirstFrame] 判断 SDK 是否接收到音频数据，通过回调 [onPlayerRecvVideoFirstFrame] 判断 SDK 是否接收到第一帧视频数据。

支持版本：1.1.0 及以上。

onPlayerSyncRecvRenderVideoFirstFrame:

- (void)onPlayerSyncRecvRenderVideoFirstFrame:(NSString *) streamID;

拉流端渲染完视频首帧回调。请不要在回调线程调用 SDK 接口。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，SDK 拉流并渲染完第一帧视频数据后会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：SDK 拉流并渲染完第一帧视频数据后会收到此回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerSyncRecvAudioFirstFrame] 判断 SDK 是否接收到音频数据，通过回调 [onPlayerSyncRecvVideoFirstFrame] 判断 SDK 是否接收到第一帧视频数据。

支持版本：3.22.0 及以上。

onPlayerRenderCameraVideoFirstFrame:

- (void)onPlayerRenderCameraVideoFirstFrame:(NSString *) streamID;

拉流端渲染完远端摄像头视频首帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。

详情

调用 [startPlayingStream] 函数拉流成功后，SDK 拉流并渲染完第一帧远端摄像头视频数据后会收到此回调。

业务场景：开发者可用该回调来统计首帧耗时或更新播放流的 UI 组件。
通知时机：远端 [enableCamera] 开启摄像头后，或者 [mutePublishStreamVideo] 为 true 开始发送视频数据后，SDK 拉流并渲染完第一帧远端摄像头视频数据后会收到此回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调 [onPlayerRecvVideoFirstFrame] 判断 SDK 是否接收到第一帧视频数据。

支持版本：3.0.0 及以上。
注意事项：仅适用于远端使用摄像头推流的情况。仅适用于 RTC 推拉流场景。

onPlayerRenderMultiViewFirstFrame:viewContext:

- (void)onPlayerRenderMultiViewFirstFrame:(NSString *) streamID viewContext:(NSString *) viewContext;

拉流设置多个视图时，某个视图渲染完视频首帧的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。
viewContext	NSString *	视图上下文

详情

调用拉流函数 [startPlayingStream] 并且调用 [setPlayingCanvas] 添加了多个视图，SDK 拉流并在相应视图渲染完第一帧视频数据后会收到此回调。

业务场景：开发者可用该回调来更新播放流的 UI 组件。
通知时机：用户拉取混流，通过 [setPlayingCanvas] 添加了多个视图，且设置了正确的 viewContext 参数，相应视图渲染完第一帧视频数据后会触发此回调。
相关回调：调用拉流函数 [startPlayingStream] 成功后, 通过回调函数 [onPlayerRecvAudioFirstFrame] 判断 SDK 是否接收到音频数据，通过回调 [onPlayerRecvVideoFirstFrame] 判断 SDK 是否接收到第一帧视频数据。

支持版本：3.21.0 及以上。

onPlayerVideoSizeChanged:streamID:

- (void)onPlayerVideoSizeChanged:(CGSize) size streamID:(NSString *) streamID;

拉流分辨率变更通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
size	CGSize	视频解码分辨率
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，当收到视频首帧数据，或推流方通过 [setVideoConfig] 改变编码分辨率，或流控策略生效时，拉流分辨率会发生改变。

业务场景：开发者可根据流的最终分辨率来更新或切换真正播放流的 UI 组件。
通知时机：拉流 [startPlayingStream] 成功后，在拉流中途如果有视频分辨率发生变化将会收到此回调。

支持版本：1.1.0 及以上。
注意事项： 1. 若拉的是流只有音频数据，则不会收到该回调。

若用户开启 ZegoVideoBufferTypeEncodedData 类型的自定义视频渲染， SDK 不负责视频解码，则不会收到该回调。

onPlayerRecvSEI:streamID:

deprecated

- (void)onPlayerRecvSEI:(NSData *) data streamID:(NSString *) streamID;

收到远端流的 SEI 内容。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	NSData *	SEI 内容。
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，当远端流发送 SEI 后（如直接调用 [sendSEI] 、混音中带 SEI 数据、自定义视频采集发送码流数据时附带 SEI 等等），本端会收到此回调。

通知时机：拉流 [startPlayingStream] 成功后，当远端流发送 SEI 后，本端会收到此回调。

支持版本：1.1.0 及以上。
注意事项： 1. 客户可在此回调函数中直接操作 UI 控件。

由于视频编码器自身会产生 payload type 为 5 的 SEI，或者使用视频文件推流时，视频文件中也可能存在这样的 SEI，因此若开发者需要过滤掉这类型的 SEI 时，可在 [createEngine] 之前调用 [ZegoEngineConfig.advancedConfig("unregister_sei_filter", "XXXXX")]。其中 unregister_sei_filter 为 key，XXXXX 为需要设置的uuid过滤字符串。 3.调用 [mutePlayStreamVideo] 或 [muteAllPlayStreamVideo] 设置只拉音频流时，将无法接收媒体次要信息。

已废弃

此函数将在 3.4.0 版本及以上已废弃，请使用 [onPlayerSyncRecvSEI] 函数代替。

onPlayerSyncRecvSEI:streamID:

- (void)onPlayerSyncRecvSEI:(NSData *) data streamID:(NSString *) streamID;

同步接收远端流的 SEI 内容。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	NSData *	SEI 内容。
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，当远端流发送 SEI 后（例如直接调用 [sendSEI] 、混音中带 SEI 数据、自定义视频采集发送码流数据时附带 SEI 等等），本端会收到此回调。

通知时机：拉流 [startPlayingStream] 成功且远端流发送 SEI 后，本端会收到此回调。

支持版本：3.4.0 及以上。
注意事项： 1. 由于视频编码器自身会产生 payload type 为 5 的 SEI，或者使用视频文件推流时，视频文件中也可能存在这样的 SEI，因此若开发者需要过滤掉这类型的 SEI 时，可在 [createEngine] 之前调用 [ZegoEngineConfig.advancedConfig("unregister_sei_filter", "XXXXX")]，其中 unregister_sei_filter 为 key，XXXXX 为需要设置的 uuid 过滤字符串。 2.执行 [mutePlayStreamVideo] 或 [muteAllPlayStreamVideo] 设置只拉音频流时，将无法接收媒体次要信息。

onPlayerRecvMediaSideInfo:

- (void)onPlayerRecvMediaSideInfo:(ZegoMediaSideInfo *) info;

同步接收远端流的 SEI 内容，包含时间戳。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
info	ZegoMediaSideInfo *	SEI 回调信息。

详情

通知时机：拉流 [startPlayingStream] 成功且远端流发送 SEI 后，本端会收到此回调。

支持版本：3.9.0 及以上。
注意事项：1. 由于视频编码器自身会产生 payload type 为 5 的 SEI，或者使用视频文件推流时，视频文件中也可能存在这样的 SEI，因此若开发者需要过滤掉这类型的 SEI 时，可在 [createEngine] 之前调用 [ZegoEngineConfig.advancedConfig("unregister_sei_filter", "XXXXX")]，其中 unregister_sei_filter 为 key，XXXXX 为需要设置的 uuid 过滤字符串。 2.执行 [mutePlayStreamVideo] 或 [muteAllPlayStreamVideo] 设置只拉音频流时，将无法接收媒体次要信息。

onPlayerRecvAudioSideInfo:streamID:

- (void)onPlayerRecvAudioSideInfo:(NSData *) data streamID:(NSString *) streamID;

收到远端流的音频次要信息内容。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
data	NSData *	音频次要信息内容。
streamID	NSString *	拉流的流 ID。

详情

调用拉流函数 [startPlayingStream] 成功后，当远端流发送音频次要信息成功后 [sendAudioSideInfo]，本端会收到此回调。

通知时机：拉流 [startPlayingStream] 成功后，当远端流发送音频次要信息后，本端会收到此回调。
相关接口：可通过接口 [sendAudioSideInfo] 发送音频次要信息。

支持版本：2.19.0 及以上。
注意事项：1. 调用 [mutePlayStreamAudio] 或 [muteAllPlayStreamAudio] 设置只拉视频流时，将无法接收音频次要信息。2. 受网络等因素影响，收到的数据可能会有缺失，但是保证顺序。

onPlayerLowFpsWarning:streamID:

- (void)onPlayerLowFpsWarning:(ZegoVideoCodecID) codecID streamID:(NSString *) streamID;

拉流低帧率警告。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
codecID	ZegoVideoCodecID	视频解码器 ID。
streamID	NSString *	拉流的流 ID。

详情

拉流出现低帧率触发的回调。

通知时机：拉流出现低帧率会触发本回调。

支持版本：2.14.0 及以上。
注意事项：如果用户拉 H.265 流触发本回调，可以停拉 H.265 流，转拉 H.264 流。

onPlayerStreamEvent:streamID:extraInfo:

- (void)onPlayerStreamEvent:(ZegoStreamEvent) eventID streamID:(NSString *) streamID extraInfo:(NSString *) extraInfo;

拉流事件回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
eventID	ZegoStreamEvent	拉流事件ID
streamID	NSString *	拉流的流 ID。
extraInfo	NSString *	附加信息。JSON 格式的字符串。目前包括的信息有 "url"表示地址, "streamProtocol"表示流协议，包括rtmp,flv,avertp，hls，webrtc等, "netProtocol"表示网络协议，包括tcp,udp,quic, "resourceType"表示资源类型，包括cdn,rtc,l3。

详情

发起拉流后，这个回调会返回当前使用的拉流地址，资源类型和协议相关信息。

通知时机：拉流以及重试拉流的事件。

支持版本：2.18.0 及以上。
注意事项：无。

onPlayerVideoSuperResolutionUpdate:state:errorCode:

- (void)onPlayerVideoSuperResolutionUpdate:(NSString *) streamID state:(ZegoSuperResolutionState) state errorCode:(int) errorCode;

拉流视频超分辨率开启状态变化。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
streamID	NSString *	拉流的流 ID。
state	ZegoSuperResolutionState	超分状态。
errorCode	int	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html

详情

拉流视频超分辨率开启状态变化。

通知时机：当 [enableVideoSuperResolution] 开启或关闭视频超分后，拉流视频渲染时根据实际情况通知开发者是否开启超分。

支持版本：3.0.0 及以上。
注意事项：无。

onMixerRelayCDNStateUpdate:taskID:

- (void)onMixerRelayCDNStateUpdate:(NSArray<ZegoStreamRelayCDNInfo *> *) infoList taskID:(NSString *) taskID;

混流转推 CDN 状态更新通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
infoList	NSArray<ZegoStreamRelayCDNInfo >	当前 CDN 正在混流的信息列表。
taskID	NSString *	混流任务 ID。取值范围：长度不超过256。注意事项：该参数为字符串格式，不可以包含 URL 关键字，例如 'http', '?' 等，否则推拉流失败。仅支持数字，英文字符和 '~', '!', '@', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '\'。

详情

在 ZEGO RTC 服务器的混流任务的一般情况会以 RTMP 协议将输出流向 CDN 推送，推送过程中出现的状态的变化会从该回调函数通知出来。

业务场景：常用于需要多个视频画面合成一个视频时使用混流，比如教育类，直播老师和学生的画面。
通知时机：开发者调用 [startMixerTask] 函数开始混流后，ZEGO RTC服务器将输出流向CDN推送的时候出现状态变化时。
相关回调：可通过 [onMixerSoundLevelUpdate] 获取混流中的每条单流的声浪更新通知。
相关接口：可通过 [startMixerTask] 开始混流任务。

支持版本：1.2.1 及以上。
使用限制：无。

onMixerSoundLevelUpdate:

- (void)onMixerSoundLevelUpdate:(NSDictionary<NSNumber *, NSNumber *> *) soundLevels;

混流中的每条单流的声浪更新通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
soundLevels	NSDictionary<NSNumber , NSNumber > *	混流中每条单流的声浪键值对，key 为每条单流的 soundLevelID，value 为对应的单流的声浪值。取值范围：value 的取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

开发者可根据此回调在观众拉混流的 UI 界面显示哪条流的主播在说话的效果。

业务场景：常用于需要多个视频画面合成一个视频时使用混流，比如教育类，直播老师和学生的画面。
通知时机：开发者调用 [startPlayingStream] 函数开始拉混流后，回调通知周期为 100 ms。
相关回调：可通过 [onMixerRelayCDNStateUpdate] 获取混流转推 CDN 状态更新通知。
相关接口：可通过 [startMixerTask] 开始混流任务。

支持版本：1.2.1 及以上。
使用限制：该回调每 100 ms 触发一次，触发频率不支持设置。由于该回调频率高，请勿在该回调中执行耗时任务或者 UI 操作，以免造成卡顿。

onAutoMixerSoundLevelUpdate:

- (void)onAutoMixerSoundLevelUpdate:(NSDictionary<NSString *, NSNumber *> *) soundLevels;

自动混流中的每条单流的声浪更新通知

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
soundLevels	NSDictionary<NSString , NSNumber > *	混流中每条单流的声浪键值对，key 为每条单流的 streamID，value 为对应的单流的声浪值，value 的取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

用户可根据此回调获取自动混流时拉取到的每条流的声浪信息，包括 streamID 和声浪值。

业务场景：常用于语聊房场景，用户可根据此回调在观众拉混流时显示哪条流的主播在说话。
通知时机：调用 [startPlayingStream] 函数拉流后触发。
相关接口：可调用 [startAutoMixerTask] 函数，开始自动混流任务。可调用 [stopAutoMixerTask] 函数，停止自动混流任务。

支持版本：2.10.0 及以上。

onAudioDeviceStateChanged:updateType:deviceType:

- (void)onAudioDeviceStateChanged:(ZegoDeviceInfo *) deviceInfo updateType:(ZegoUpdateType) updateType deviceType:(ZegoAudioDeviceType) deviceType;

音频设备状态改变

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
deviceInfo	ZegoDeviceInfo *	音频设备信息
updateType	ZegoUpdateType	更新类型（添加/删除）
deviceType	ZegoAudioDeviceType	音频设备类型

详情

只适用于 macOS；监测到系统中有音频设备添加或移除时，会触发此回调。通过监听此回调，用户可在必要的时候更新使用特定设备进行声音采集或输出。

onAudioDeviceVolumeChanged:deviceType:deviceID:

- (void)onAudioDeviceVolumeChanged:(int) volume deviceType:(ZegoAudioDeviceType) deviceType deviceID:(NSString *) deviceID;

音频设备音量变更。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
volume	int	音频设备音量
deviceType	ZegoAudioDeviceType	音频设备类型
deviceID	NSString *	音频设备ID

详情

音频设备音量变更事件回调。

通知时机：调用 [startAudioDeviceVolumeMonitor] 函数启动设备音量监控器后，且监控的音频设备音量发生变更时。
平台差异：仅支持 Windows 和 macOS。

支持版本：1.1.0 及以上。

onVideoDeviceStateChanged:updateType:

- (void)onVideoDeviceStateChanged:(ZegoDeviceInfo *) deviceInfo updateType:(ZegoUpdateType) updateType;

视频设备状态改变。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
deviceInfo	ZegoDeviceInfo *	视频设备信息
updateType	ZegoUpdateType	更新类型（添加/删除）

详情

只适用于 macOS；监测到系统中有视频设备添加或移除时，会触发此回调。通过监听此回调，用户可在必要的时候更新使用特定设备进行视频采集

onCapturedSoundLevelUpdate:

- (void)onCapturedSoundLevelUpdate:(NSNumber *) soundLevel;

本地采集音频声浪回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
soundLevel	NSNumber *	本地采集的声浪值，取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

本地采集音频声浪回调。

通知时机：调用 [startSoundLevelMonitor] 函数启动声浪监控器后。
相关接口：通过 [startSoundLevelMonitor] 启动声浪监控，通过回调 [onRemoteSoundLevelUpdate] 监控远端拉流音频声浪。

支持版本：1.1.0 及以上。
注意事项： 1. 回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值，当处于未推流 [startPublishingStream] 且未预览 [startPreview] 状态时，回调数值为默认值 0。 2. 该回调为高频回调，建议不要在回调内部做复杂逻辑处理。

onCapturedSoundLevelInfoUpdate:

- (void)onCapturedSoundLevelInfoUpdate:(ZegoSoundLevelInfo *) soundLevelInfo;

本地采集音频声浪回调，支持人声检测。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
soundLevelInfo	ZegoSoundLevelInfo *	本地采集的声浪值，取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

本地采集音频声浪回调。

通知时机：调用 [startSoundLevelMonitor] 函数启动声浪监控器后。
相关接口：通过 [startSoundLevelMonitor] 启动声浪监控，通过回调 [onRemoteSoundLevelUpdate] 或 [onRemoteSoundLevelInfoUpdate] 监控远端拉流音频声浪。

支持版本：2.10.0 及以上。
注意事项： 1. 回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值。 2. 该回调为高频回调，建议不要在回调内部做复杂逻辑处理。

onRemoteSoundLevelUpdate:

- (void)onRemoteSoundLevelUpdate:(NSDictionary<NSString *, NSNumber *> *) soundLevels;

远端拉流音频声浪回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
soundLevels	NSDictionary<NSString , NSNumber > *	远端的声浪键值对，key 为流 ID，value 为对应的流的声浪值，value 取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

远端拉流音频声浪回调。

通知时机：调用 [startSoundLevelMonitor] 函数启动声浪监控器后，且处于正在拉流 [startPlayingStream] 的状态。
相关接口：通过 [startSoundLevelMonitor] 启动声浪监控，通过回调 [onCapturedSoundLevelUpdate] 或 [onCapturedSoundLevelInfoUpdate] 监控本地拉流音频声浪。

支持版本：1.1.0 及以上。
注意事项：回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值。

onRemoteSoundLevelInfoUpdate:

- (void)onRemoteSoundLevelInfoUpdate:(NSDictionary<NSString *, ZegoSoundLevelInfo *> *) soundLevelInfos;

远端拉流音频声浪回调，支持人声检测。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
soundLevelInfos	NSDictionary<NSString , ZegoSoundLevelInfo > *	远端的声浪键值对，key 为流 ID，value 为对应的流的声浪值，value 取值范围为 0.0 ~ 100.0（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

远端拉流音频声浪回调。

通知时机：调用 [startSoundLevelMonitor] 函数启动声浪监控器后，且处于正在拉流 [startPlayingStream] 的状态。
相关接口：通过 [startSoundLevelMonitor] 启动声浪监控，通过回调 [onCapturedSoundLevelUpdate] 或 [onCapturedSoundLevelInfoUpdate] 监控本地拉流音频声浪。

支持版本：2.10.0 及以上。
注意事项：回调通知周期为调用 [startSoundLevelMonitor] 时设置的参数值。

onCapturedAudioSpectrumUpdate:

- (void)onCapturedAudioSpectrumUpdate:(NSArray<NSNumber *> *) audioSpectrum;

本地采集音频频谱回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
audioSpectrum	NSArray<NSNumber >	本地采集的音频频谱值数组，频谱值范围为 [0-2^30]。

详情

本地采集音频频谱回调。

通知时机：调用 [startAudioSpectrumMonitor] 函数启动声浪监控器后。
相关接口：通过 [startAudioSpectrumMonitor] 启动声浪监控，通过回调 [onRemoteAudioSpectrumUpdate] 监控远端拉流音频频谱。

支持版本：1.1.0 及以上。
注意事项：回调通知周期为调用 [startAudioSpectrumMonitor] 时设置的参数值，当处于未推流 [startPublishingStream] 且未预览 [startPreview] 状态时，回调数值为默认值 0。

onRemoteAudioSpectrumUpdate:

- (void)onRemoteAudioSpectrumUpdate:(NSDictionary<NSString *, NSArray<NSNumber *> *> *) audioSpectrums;

远端拉流音频频谱回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
audioSpectrums	NSDictionary<NSString , NSArray<NSNumber > >	远端音频频谱键值对，key 是流 ID，value 为对应的流的音频频谱值数组，频谱值范围为 [0-2^30]

详情

远端拉流音频频谱回调。

通知时机：调用 [startAudioSpectrumMonitor] 函数启动声浪监控器后，且处于正在拉流 [startPlayingStream] 的状态。
相关接口：通过 [startAudioSpectrumMonitor] 启动音频频谱监控，通过回调 [onCapturedAudioSpectrumUpdate] 监控本地采集音频频谱。

支持版本：1.1.0 及以上。
注意事项：回调通知周期为调用 [startAudioSpectrumMonitor] 时设置的参数值。

onLocalDeviceExceptionOccurred:deviceType:deviceID:

- (void)onLocalDeviceExceptionOccurred:(ZegoDeviceExceptionType) exceptionType deviceType:(ZegoDeviceType) deviceType deviceID:(NSString *) deviceID;

本地设备异常通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
exceptionType	ZegoDeviceExceptionType	设备异常类型。
deviceType	ZegoDeviceType	发生异常的设备类型。
deviceID	NSString *	设备 ID。目前仅支持桌面端设备，用于标识具体的设备；对于移动端设备，此参数将返回空字符串。

详情

本地设备异常。

通知时机：当本地音频或视频设备功能出现异常时会触发此回调。

支持版本：2.15.0 及以上。

onRemoteCameraStateUpdate:streamID:

- (void)onRemoteCameraStateUpdate:(ZegoRemoteDeviceState) state streamID:(NSString *) streamID;

远端摄像头设备状态通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoRemoteDeviceState	远端摄像头状态。
streamID	NSString *	拉流的流 ID。

详情

远端摄像头设备状态通知。

业务场景：1v1 教育场景的开发者或者教育小班课场景及相似场景的开发者可以根据此回调来判断远端推流设备的摄像头设备是否正常工作，以及根据相应的 state 初步了解设备出问题的原因。
通知时机：远端摄像头设备状态发生变更时，例如开关摄像头等，通过监听此回调，能够获取远端摄像头相关的事件，可以用于提示用户可能导致视频异常的情况。

支持版本：1.1.0 及以上。
注意事项：当从 CDN 拉流时，或对端使用了自定义视频采集时，不会触发此回调。

onRemoteMicStateUpdate:streamID:

- (void)onRemoteMicStateUpdate:(ZegoRemoteDeviceState) state streamID:(NSString *) streamID;

远端麦克风设备状态通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoRemoteDeviceState	远端麦克风状态。
streamID	NSString *	拉流的流 ID。

详情

远端麦克风设备状态通知。

业务场景：1v1 教育场景的开发者或者教育小班课场景及相似场景的开发者可以根据此回调来判断远端推流设备的麦克风设备是否正常工作，以及根据相应的 state 初步了解设备出问题的原因。
通知时机：远端麦克风设备状态发生变更时，例如开关麦克风等，通过监听此回调，能够获取远端麦克风相关的事件，可以用于提示用户可能导致音频异常的情况。

支持版本：1.1.0 及以上。
注意事项：当从 CDN 拉流时，或对端使用了自定义音频采集时（且不是推流到 ZEGO RTC服务器），不会触发此回调。

onRemoteSpeakerStateUpdate:streamID:

- (void)onRemoteSpeakerStateUpdate:(ZegoRemoteDeviceState) state streamID:(NSString *) streamID;

远端扬声器设备状态通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
state	ZegoRemoteDeviceState	远端扬声器状态。
streamID	NSString *	拉流的流 ID。

详情

远端扬声器设备状态通知。

业务场景：1v1 教育场景的开发者或者教育小班课场景及相似场景的开发者可以根据此回调来判断远端推流设备的扬声器设备是否正常工作，以及根据相应的 state 初步了解设备出问题的原因。
通知时机：远端扬声器设备状态发生变更时，例如开关扬声器等，通过监听此回调，能够获取远端扬声器相关的事件。

支持版本：1.1.0 及以上。
注意事项：此回调当从 CDN 拉流时不会回调。

onAudioRouteChange:

- (void)onAudioRouteChange:(ZegoAudioRoute) audioRoute;

音频设备路由变更通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
audioRoute	ZegoAudioRoute	当前音频路由。

详情

音频设备路由变更通知。

通知时机：当有耳机插拔、扬声器和听筒切换等音频路由发生变化时会抛出此回调。
平台差异：仅支持 iOS 和 Android。

支持版本：1.20.0 及以上。

onAudioVADStateUpdate:monitorType

- (void)onAudioVADStateUpdate:(ZegoAudioVADType)state monitorType:(ZegoAudioVADStableStateMonitorType)type;

检测音频数据的稳态语音状态的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
type	ZegoAudioVADStableStateMonitorType	语音检测器类型
state	ZegoAudioVADType	语音检测结果

详情

检测音频数据的稳态语音状态的回调。触发时机：调用 [startAudioVADStableStateMonitor] 启动语音状态检测，且处于正在推流的状态或预览预览状态。

相关接口：[startAudioVADStableStateMonitor]， [stopAudioVADStableStateMonitor]。

支持版本：2.14.0 及以上。
使用限制：回调通知周期为 3 秒。

onRecvRoomTransparentMessage:roomID:

- (void)onRecvRoomTransparentMessage:(ZegoRoomRecvTransparentMessage*) message roomID:(NSString *) roomID;

接收房间透传消息。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
message	ZegoRoomRecvTransparentMessage*	收到的消息。
roomID	NSString *	房间 ID。取值范围：最大长度为 128 字节。

详情

该回调用于接收相同房间内其他用户发送的房间透传消息。

通知时机：调用 [loginRoom] 登录房间之后，如果房间内有用户通过 [sendTransparentMessage] 函数发送指定客户端接收的消息，则触发此回调。

支持版本：3.11.0 及以上。
使用限制：无。
注意事项：用户自己发送的弹幕消息不会通过此回调得到通知。[sendTransparentMessage] 时指定仅服务端回调，则不会触发此回调。

onIMRecvBroadcastMessage:roomID:

- (void)onIMRecvBroadcastMessage:(NSArray<ZegoBroadcastMessageInfo *> *) messageList roomID:(NSString *) roomID;

接收房间广播消息通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
messageList	NSArray<ZegoBroadcastMessageInfo >	收到的消息列表。取值范围：每次最多接收 50 条消息。
roomID	NSString *	房间 ID。取值范围：最大长度为 128 字节。

详情

该回调用于接收相同房间内其他用户发送的广播消息。

业务场景：一般在直播房间内使用。
通知时机：调用 [loginRoom] 登录房间之后，如果房间内有用户通过 [sendBroadcastMessage] 函数发送广播消息，则触发此回调。
相关回调：可通过[onIMRecvBarrageMessage]接收房间弹幕消息，可通过 [onIMRecvCustomCommand] 接收房间自定义信令。

支持版本：1.2.1 及以上。
使用限制：无。
注意事项：用户自己发送的广播消息不会通过此回调得到通知。

onIMRecvBarrageMessage:roomID:

- (void)onIMRecvBarrageMessage:(NSArray<ZegoBarrageMessageInfo *> *) messageList roomID:(NSString *) roomID;

接收房间弹幕消息通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
messageList	NSArray<ZegoBarrageMessageInfo >	收到的消息列表。取值范围：每次最多接收 50 条消息。
roomID	NSString *	房间 ID。取值范围：最大长度为 128 字节。

详情

该回调用于接收相同房间内其他用户发送的弹幕消息。

业务场景：一般用于房间内有大量消息收发，且不需要保证消息可靠性的场景，例如直播弹幕。
通知时机：调用 [loginRoom] 登录房间之后，如果房间内有用户通过 [sendBarrageMessage] 函数发送弹幕消息，则触发此回调。
相关回调：可通过[onIMRecvBroadcastMessage]接收房间广播消息，可通过 [onIMRecvCustomCommand] 接收房间自定义信令。

支持版本：1.5.0 及以上。
使用限制：无。
注意事项：用户自己发送的弹幕消息不会通过此回调得到通知。在房间内有大量弹幕消息时可能会延迟收到通知，且可能丢失部分弹幕消息。

onIMRecvCustomCommand:fromUser:roomID:

- (void)onIMRecvCustomCommand:(NSString *) command fromUser:(ZegoUser *) fromUser roomID:(NSString *) roomID;

接收自定义信令通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
command	NSString *	信令内容。取值范围：最大长度为 1024 字节。
fromUser	ZegoUser *	信令的发送人。
roomID	NSString *	房间 ID。取值范围：最大长度为 128 字节。

详情

该回调用于接收相同房间内其他用户发送的自定义信令。

业务场景：一般在直播房间内使用。
通知时机：调用 [loginRoom] 登录房间之后，如果房间内有其他用户通过 [sendCustomCommand] 函数发送自定义信令给开发者，则触发此回调。
相关回调：可通过[onIMRecvBroadcastMessage]接收房间广播消息，可通过 [onIMRecvBarrageMessage] 接收房间弹幕消息。

支持版本：1.2.1 及以上。
使用限制：无。
注意事项：用户自己发送给自己的自定义信令不会通过此回调得到通知。

onPerformanceStatusUpdate:

- (void)onPerformanceStatusUpdate:(ZegoPerformanceStatus *) status;

系统性能监控回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
status	ZegoPerformanceStatus *	系统性能监控状态。

详情

系统性能监控回调。回调周期为调用 [startPerformanceMonitor] 时设置的 millisecond 参数值。

业务场景：通过监控系统性能，协助用户快速定位、解决性能问题，提升用户体验。
通知时机：需要在 [createEngine] 之后，调用 [startPerformanceMonitor] 启动系统性能监控后才会触发本回调函数。

支持版本：1.19.0 及以上。
使用限制：无。

onNetworkModeChanged:

- (void)onNetworkModeChanged:(ZegoNetworkMode) mode;

网络模式变更回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mode	ZegoNetworkMode	当前网络模式。

详情

网络模式变更回调。

通知时机：当设备的网络模式改变时，例如从 WiFi 切换到 5G，或断网等情况，将会触发本回调。

支持版本：1.20.0 及以上。
使用限制：无。

onNetworkSpeedTestError:type:

- (void)onNetworkSpeedTestError:(int) errorCode type:(ZegoNetworkSpeedTestType) type;

网络测速异常回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	网络测速错误码。请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html
type	ZegoNetworkSpeedTestType	上行或下行网络。

详情

网络测速异常回调。

业务场景：用于检测当前网络环境是否适合推/拉指定码率的流。
通知时机：网络测试过程中发生异常时，例如：连接测速服务器失败等，将触发本回调。

支持版本：1.20.0 及以上。
使用限制：无。

onNetworkSpeedTestQualityUpdate:type:

- (void)onNetworkSpeedTestQualityUpdate:(ZegoNetworkSpeedTestQuality *) quality type:(ZegoNetworkSpeedTestType) type;

网络测速质量回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
quality	ZegoNetworkSpeedTestQuality *	网速测速质量.
type	ZegoNetworkSpeedTestType	上行或下行网络。

详情

网络连通状态下的网络测速质量回调。

业务场景：用于检测当前网络环境是否适合推/拉指定码率的流。
通知时机：调用 [startNetworkSpeedTest] 启动网络测速后，将触发本回调。回调通知周期为调用 [startNetworkSpeedTest] 时设置的参数值，未设置该参数时，默认 3 秒回调一次。

支持版本：1.20.0 及以上。
使用限制：无。
注意事项：当测速发生异常或停止测速时，本回调将会不再触发。

onNetworkQuality:upstreamQuality:downstreamQuality:

- (void)onNetworkQuality:(NSString *) userID upstreamQuality:(ZegoStreamQualityLevel) upstreamQuality downstreamQuality:(ZegoStreamQualityLevel) downstreamQuality;

房间内正在推流的用户的网络质量回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
userID	NSString *	用户 ID，空表示本地用户
upstreamQuality	ZegoStreamQualityLevel	上行网络质量
downstreamQuality	ZegoStreamQualityLevel	下行网络质量

详情

本地和远端用户的上下行网络回调，默认每两秒回调一次本地和每个拉取的远端用户的网络状况。 2.10.0 至 2.13.1 版本： 1. 自身必须既推流又拉流，才会收到自身的网络质量回调。 2. 当拉一条流时，推流端有拉流且推流端在自己所在房间内，才会收到该用户的网络质量。 2.14.0 至 2.21.1 版本：

自身只要推流或拉流，就会收到自身的网络质量回调。 2. 当拉一条流时，推流端在自己所在房间内，就会收到该用户的网络质量。 2.22.0 及以上版本：
自身只要推流或拉流，就会收到自身的网络质量回调。 2. 当拉一条流时，推流端在自己所在房间内，就会收到该用户的网络质量。
预估远端推流用户的网络情况，如果远端推流用户心跳丢失 1 次，回调其网络质量为 unknown；如果远端推流用户心跳丢失达到 3 次，回调其网络质量为 die。

业务场景：当开发者希望分析链路上的网络情况，或想要了解本地和远端用户的网络状况。
通知时机：调用 [startPublishingStream] 推流或 [startPlayingStream] 拉流后触发。

支持版本：2.10.0 及以上。

onRtcStats:

- (void)onRtcStats:(ZegoRtcStatsInfo *) info;

RTC 网络统计信息回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
info	ZegoRtcStatsInfo *	统计信息.

详情

RTC 网络统计信息回调。

业务场景：当开发者希望分析本端的网络情况。
通知时机：调用 [startPublishingStream] 开始推 RTC 流后，会回调上行统计信息，调用 [startPlayingStream] 开始拉 RTC 或 L3 流后，会回调下行统计信息。默认回调周期为 3 秒。

支持版本：3.20.0 及以上。
使用限制：无。
注意事项：无。

onNetworkTimeSynchronized

- (void)onNetworkTimeSynchronized;

网络时间同步成功的回调

Declared in ZegoExpressEventHandler.h

支持版本：2.12.0 及以上。当开发者调用 [createEngine] 后，内部完成网络时间同步时会触发此回调。

onRequestDumpData

- (void)onRequestDumpData;

请求转储数据的回调。

Declared in ZegoExpressEventHandler.h

通知时机：当客户反馈问题后，ZEGO 希望用户转储数据用于分析音视频处理问题时会触发此回调。

支持版本：3.10.0 及以上。

onRequestUploadDumpData:takePhoto:

- (void)onRequestUploadDumpData:(NSString *) dumpDir takePhoto:(BOOL) takePhoto;

请求转储数据的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
dumpDir	NSString *	转储数据路径
takePhoto	BOOL	在上传转储文件时是否需要拍照

通知时机：当客户反馈问题后，ZEGO 希望用户转储数据用于分析音视频处理问题时会触发此回调。

支持版本：3.11.0 及以上。

onStartDumpData:

- (void)onStartDumpData:(int) errorCode;

开始转储数据时的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	错误码

通知时机：当调用 [startDumpData] 后会触发此回调。

支持版本：3.10.0 及以上。

onStopDumpData:dumpDir:

- (void)onStopDumpData:(int) errorCode dumpDir:(NSString *) dumpDir;

停止转储数据时的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	错误码
dumpDir	NSString *	转储数据路径

通知时机：当调用 [stopDumpData] 后会触发此回调。

支持版本：3.10.0 及以上。

onUploadDumpData:

- (void)onUploadDumpData:(int) errorCode;

上传转储数据完成后的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
errorCode	int	错误码

通知时机：当调用 [uploadDumpData] 后，SDK 执行上传任务后会触发此回调。

支持版本：3.10.0 及以上。

onMobileScreenCaptureExceptionOccurred:

- (void)onMobileScreenCaptureExceptionOccurred:(ZegoScreenCaptureExceptionType)exceptionType API_AVAILABLE(ios (12.0));

屏幕采集异常通知。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
exceptionType	ZegoScreenCaptureExceptionType	采集源异常类型。

详情

移动端屏幕采集错误通知。

通知时机：移动端屏幕开始采集后产生异常会触发此回调。

支持版本：3.6.0 及以上。
使用限制：仅对 Android 和 iOS 系统生效。
注意事项：调用接口 [setEventHandler] 设置后该回调才生效。

onMobileScreenCaptureStart

- (void)onMobileScreenCaptureStart API_AVAILABLE(ios (12.0));

屏幕采集开始通知。

Declared in ZegoExpressEventHandler.h

移动端屏幕采集开始通知。

通知时机：调用 [startScreenCapture] 后，成功开始屏幕采集会触发此回调，失败会触发 [onScreenCaptureExceptionOccurred]。

支持版本：3.16.0 及以上。
使用限制：仅对 Android 和 iOS 系统生效。
注意事项：调用接口 [setEventHandler] 设置后该回调才生效。

ZegoMediaPlayerAudioHandler

Declared in ZegoExpressEventHandler.h

方法

mediaPlayer:audioFrameData:dataLength:param

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer audioFrameData:(unsigned char *)data dataLength:(unsigned int)dataLength param:(ZegoAudioFrameParam *)param;

播放器抛音频数据的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
data	unsigned char *	音频频帧的裸数据。
dataLength	unsigned int	数据的长度。
param	ZegoAudioFrameParam *	音频帧参数。

详情

播放器抛音频数据的回调。

通知时机：媒体播放器开始播放时会产生此回调。

支持版本：1.3.4 及以上。
使用限制：播放版权音乐时，该回调会被默认禁用，若有需要，请联系 ZEGO 技术支持。
注意事项：调用接口 [setAudioHandler] 设置后该回调才生效。

ZegoMediaPlayerEventHandler

Declared in ZegoExpressEventHandler.h

方法

mediaPlayer:stateUpdate:errorCode

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer stateUpdate:(ZegoMediaPlayerState)state errorCode:(int)errorCode;

媒体播放器播放状态回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
state	ZegoMediaPlayerState	播放器状态。
errorCode	int	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html

详情

媒体播放器播放状态回调。

通知时机：当媒体播放器的播放状态改变时会触发此回调。

支持版本：1.3.4 及以上。
使用限制：无。

mediaPlayer:networkEvent

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer networkEvent:(ZegoMediaPlayerNetworkEvent)networkEvent;

媒体播放器网络状态事件回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
networkEvent	ZegoMediaPlayerNetworkEvent	网络状态事件。

详情

媒体播放器网络状态事件回调。

通知时机：当媒体播放器在播放网络资源时，当缓存数据的状态改变时会触发此回调。
相关接口：[setNetWorkBufferThreshold]。

支持版本：1.3.4 及以上。
使用限制：只有在播放网络资源时才会触发该回调。

mediaPlayer:playingProgress

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer playingProgress:(unsigned long long)millisecond;

播放器播放进度回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
millisecond	unsigned long long	进度，单位为毫秒。

详情

媒体播放器播放进度回调。通过调用 [setProgressInterval] 可以设置回调间隔时间。当设置回调间隔为 0 时，停止回调。默认回调间隔为 1 秒。

通知时机：当媒体播放器开始播放资源后会触发此回调。
相关接口：[setProgressInterval]。

支持版本：1.3.4 及以上。
使用限制：无。

mediaPlayer:renderingProgress

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer renderingProgress:(unsigned long long)millisecond;

播放器渲染进度回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
millisecond	unsigned long long	进度，单位为毫秒。

详情

媒体播放器渲染进度回调。通过调用 [setProgressInterval] 可以设置回调间隔时间。当设置回调间隔为 0 时，停止回调。默认回调间隔为 1 秒。

通知时机：当媒体播放器开始播放资源后会触发此回调。
相关接口：[setProgressInterval]。

支持版本：3.8.0 及以上。
使用限制：无。

mediaPlayer:videoSizeChanged

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoSizeChanged:(CGSize)size;

媒体播放器播放视频分辨率改变事件回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
size	CGSize	分辨率。

详情

媒体播放器播放视频分辨率改变事件回调。

通知时机：当媒体播放器在播放视频资源时，开始播放以及视频的分辨率变化时会触发此回调。

支持版本：3.11.0 及以上。

mediaPlayer:recvSEI

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer recvSEI:(NSData *)data;

媒体次要信息回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
data		SEI 内容。

详情

媒体次要信息回调。

通知时机：媒体播放器开始播放媒体文件时，如果解析到媒体文件中含有 SEI 时，将触发该回调。

支持版本：2.2.0 及以上。
注意事项：调用接口 [setEventHandler] 设置后该回调才生效。

mediaPlayer:soundLevelUpdate

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer soundLevelUpdate:(float)soundLevel;

声浪更新回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
soundLevel	float	声浪值，取值范围：[0.0, 100.0]（该取值仅表示回调的声浪取值范围，不表示精度）。

详情

声浪更新回调。

通知时机：回调频率由 [EnableSoundLevelMonitor] 指定。
相关接口：监听此回调需要通过 [EnableSoundLevelMonitor] 开启。

支持版本：2.15.0 及以上。
注意事项：调用接口 [setEventHandler] 设置后该回调才生效。

mediaPlayer:frequencySpectrumUpdate

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer frequencySpectrumUpdate:(NSArray<NSNumber *> *)spectrumList;

频谱更新回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
spectrumList	NSArray<NSNumber >	媒体播放器频谱值数组，频谱值范围为 [0-2^30]。

详情

频谱更新回调。

通知时机：回调频率由 [EnableFrequencySpectrumMonitor] 指定。
相关接口：监听此回调需要通过 [EnableFrequencySpectrumMonitor] 开启。

支持版本：2.15.0 及以上。
注意事项：调用接口 [setEventHandler] 设置后该回调才生效。

mediaPlayer:firstFrameEvent

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer firstFrameEvent:(ZegoMediaPlayerFirstFrameEvent)event;

媒体播放器播放首帧回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
event	ZegoMediaPlayerFirstFrameEvent	首帧回调事件类型。

详情

开始播放首帧回调。

通知时机：媒体播放器开始播放时会产生此回调。
相关接口：需要调用 [setPlayerCanvas] 接口，给媒体播放器设置视图，才能收到视频首帧事件回调。

支持版本：3.5.0 及以上。
注意事项：调用 [setEventHandler] 接口设置后该回调才生效。

mediaPlayer:localCacheError:resource:cachedFile

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer localCacheError:(int)errorCode resource:(NSString *)resource cachedFile:(NSString *)cachedFile;

媒体播放器本地缓存 http/https 网络资源后回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
errorCode	int	错误码。
resource	NSString *	播放的资源
cachedFile	NSString *	缓存的文件

详情

本地缓存 http/https 网络资源后回调。

通知时机：媒体播放器缓存 http/https 网络资源后会产生此回调。
相关接口：需要调用 [enableLocalCache] 接口。

支持版本：3.12.0 及以上。
注意事项：调用 [enableLocalCache] 接口设置后，且播放的是 http/https 网络资源时该回调才生效。

ZegoMediaPlayerVideoHandler

Declared in ZegoExpressEventHandler.h

方法

mediaPlayer:videoFrameRawData:dataLength:param

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoFrameRawData:(const unsigned char * _Nonnull * _Nonnull)data dataLength:(unsigned int *)dataLength param:(ZegoVideoFrameParam *)param;

播放器抛视频数据的回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
data	const unsigned char * _Nonnull * _Nonnull	视频帧的裸数据（例：RGBA 只需考虑 data[0]，I420 需考虑 data[0,1,2]）。
dataLength	unsigned int *	数据的长度（例：RGBA 只需考虑 dataLength[0]，I420 需考虑 dataLength[0,1,2]）。
param	ZegoVideoFrameParam *	视频帧参数。

详情

播放器抛视频数据的回调。

通知时机：媒体播放器开始播放时会产生此回调。

支持版本：1.3.4 及以上。
使用限制：播放版权音乐时，该回调会被默认禁用，若有需要，请联系 ZEGO 技术支持。
注意事项：调用接口 [setVideoHandler] 设置后该回调才生效。

mediaPlayer:videoFrameRawData:dataLength:param:extraInfo

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoFrameRawData:(const unsigned char * _Nonnull * _Nonnull)data dataLength:(unsigned int *)dataLength param:(ZegoVideoFrameParam *)param extraInfo:(NSDictionary *)extraInfo;

播放器抛视频数据的回调，带视频帧附加信息。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例。
data	const unsigned char * _Nonnull * _Nonnull	视频帧的裸数据（例：RGBA 只需考虑 data[0]，I420 需考虑 data[0,1,2]）。
dataLength	unsigned int *	数据的长度（例：RGBA 只需考虑 dataLength[0]，I420 需考虑 dataLength[0,1,2]）。
param	ZegoVideoFrameParam *	视频帧参数。
extraInfo	nullable NSDictionary *	视频帧附加信息。

详情

播放器抛视频数据的回调。

通知时机：媒体播放器开始播放时会产生此回调。

支持版本：2.16.0 及以上。
使用限制：播放版权音乐时，该回调会被默认禁用，若有需要，请联系 ZEGO 技术支持。
注意事项：调用接口 [setVideoHandler] 设置后该回调才生效。

mediaPlayer:videoFramePixelBuffer:param

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoFramePixelBuffer:(CVPixelBufferRef)buffer param:(ZegoVideoFrameParam *)param;

播放器视频帧 CVPixelBuffer 数据回调

Declared in ZegoExpressEventHandler.h

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例
buffer	CVPixelBufferRef	封装为 CVPixelBuffer 的视频帧数据
param	ZegoVideoFrameParam *	视频帧参数

mediaPlayer:videoFramePixelBuffer:param:extraInfo

- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoFramePixelBuffer:(CVPixelBufferRef)buffer param:(ZegoVideoFrameParam *)param extraInfo:(NSDictionary *)extraInfo;

播放器视频帧 CVPixelBuffer 数据回调

Declared in ZegoExpressEventHandler.h

名称	类型	描述
mediaPlayer	ZegoMediaPlayer *	回调的播放器实例
buffer	CVPixelBufferRef	封装为 CVPixelBuffer 的视频帧数据
param	ZegoVideoFrameParam *	视频帧参数
extraInfo	nullable NSDictionary *	视频帧附加信息

ZegoRangeAudioEventHandler

Declared in ZegoExpressEventHandler.h

方法

rangeAudio:microphoneStateUpdate:errorCode

- (void)rangeAudio:(ZegoRangeAudio *)rangeAudio microphoneStateUpdate:(ZegoRangeAudioMicrophoneState)state errorCode:(int)errorCode;

范围语音麦克风使用状态回调。

Declared in ZegoExpressEventHandler.h

参数

名称	类型	描述
rangeAudio	ZegoRangeAudio *	触发此次回调的范围语音实例。
state	ZegoRangeAudioMicrophoneState	麦克风使用状态。
errorCode	int	错误码，详情请参考常见错误码文档 https://doc-zh.zego.im/zh/4378.html

详情

麦克风的状态变化通知，开启发送音频是异步过程，中间的状态切换都通过该函数回调。

通知时机：在 [enableMicrophone] 函数后。

支持版本：2.11.0 及以上。
注意事项：1. 必须在 [enableMicrophone] 函数调用前监听。 2. 正常停止 [enableMicrophone] 时，是不会触发该回调的，只有异常停推的时候才会触发 Off 的状态。