原始视频数据

getMirrorApplied

设置视频数据镜像。

Objective-C

- (BOOL)getMirrorApplied;

如果你希望获取的视频数据为原始视频的镜像，需要在调用 setVideoFrameDelegate 方法时注册该回调。成功注册视频数据观测器后，SDK 会在捕捉到每个视频帧时触发该回调，你需要在该回调的返回值中设置是否对原始视频数据作镜像处理。

注意：

• 该功能仅支持 RGBA 和 YUV420 格式的视频数据。

• 该方法和 setVideoEncoderConfiguration 方法均支持设置镜像效果，声网建议你仅选择一种方法进行设置，同时使用两种方法会导致镜像效果叠加从而造成设置镜像失败。

返回值

设置 SDK 输出视频数据时是否作镜像处理：

• YES: 镜像。

• NO: （默认）不镜像。

所属接口类

• AgoraVideoFrameDelegate

getObservedFramePosition

设置视频观测位置。

Objective-C

- (unsigned int)getObservedFramePosition;

成功注册视频数据观测器后，SDK 会在每个特定的视频帧处理节点通过该回调来判断是否触发 onCaptureVideoFrame、 onRenderVideoFrame 和 onPreEncodeVideoFrame 回调，供你观测本地采集视频数据、远端发送的视频数据以及编码前的视频数据。你可以根据场景需求，通过修改该方法的返回值，设置你需要观测的某个或多个位置：

• AgoraVideoFramePositionPostCapture(1 << 0)，本地采集视频数据后的位置，对应 onCaptureVideoFrame 回调。

• AgoraVideoFramePositionPreRenderer(1 << 1)，接收远端发送的视频在渲染前的位置，对应 onRenderVideoFrame 回调。

• AgoraVideoFramePositionPreEncoder(1 << 2)，本地视频编码前的位置，对应 onPreEncodeVideoFrame 回调。

注意：

• 观测多个位置时，需要使用 '|' （或）运算符。

• 该回调默认观测 AgoraVideoFramePositionPostCapture(1 << 0)和 AgoraVideoFramePositionPreRenderer(1 << 1)。

• 为降低设备耗能，你可以根据实际需求适当减少观测位置。

• 当视频处理模式为 AgoraVideoFrameProcessModeReadWrite、并且设置观测点为 AgoraVideoFramePositionPreEncoder | AgoraVideoFramePositionPostCapture 时，会造成 getMirrorApplied 不生效，需要修改视频处理模式或观测点的位置。

返回值

设置观测位置的 bit mask。详见 AgoraVideoFramePosition。

所属接口类

• AgoraVideoFrameDelegate

getRotationApplied

设置视频数据旋转。

Objective-C

- (BOOL)getRotationApplied;

如果你在采集端已经根据 AgoraOutputVideoFrame 中的旋转信息 rotation 进行旋转，就无需调用该方法设置视频数据旋转。

注意：

• 该功能仅支持视频处理模式为 AgoraVideoFrameProcessModeReadOnly 的场景。

• 该功能仅支持 RGBA 和 YUV420 格式的视频数据。

返回值

设置 SDK 输出视频数据时是否作旋转处理：

• YES: 旋转。

• NO: （默认）不旋转。

所属接口类

• AgoraVideoFrameDelegate

getVideoFormatPreference

设置 SDK 输出的原始视频数据格式。

Objective-C

- (AgoraVideoFormat)getVideoFormatPreference;

如果你想获取 YUV 420 格式以外的原始视频数据，需要在调用 setVideoFrameDelegate 方法时注册该回调。 成功注册视频数据观测器后，SDK 会在捕捉到每个视频帧时触发该回调，你需要在该回调返回值中设置期望的视频数据格式。

返回值

设置 SDK 输出的原始数据格式。详见 AgoraVideoFormat。

所属接口类

• AgoraVideoFrameDelegate

getVideoFrameProcessMode

设置视频处理模式。

Objective-C

- (AgoraVideoFrameProcessMode)getVideoFrameProcessMode;

成功注册视频观测器后，SDK 会触发一次该回调。你需要在该回调的返回值中设置期望的视频处理模式。

返回值

详见 AgoraVideoFrameProcessMode。

所属接口类

• AgoraVideoFrameDelegate

setVideoFrameDelegate

注册原始视频观测器对象。

Objective-C

- (BOOL)setVideoFrameDelegate:(id<AgoraVideoFrameDelegate> _Nullable)delegate;

如果你想要观测原始视频帧 (如 YUV 或 RGBA 格式)，声网推荐你通过该方法注册一个 AgoraVideoFrameDelegate 类。

调用该方法注册视频观测器时，你可以根据需要注册 AgoraVideoFrameDelegate 类中的回调。在成功注册视频观测器后，SDK 会在捕捉到每个视频帧时，触发你所注册的上述回调。

如果你想获取一部分远端用户的原始视频数据 (简称为 A 组)、获取另一部分远端用户的编码后视频数据 (简称为 B 组)，可参考以下步骤：

• 在加入频道前调用 setVideoFrameDelegate 注册原始视频帧观测器。

• 在加入频道前调用 registerVideoEncodedFrameObserver 注册编码后的视频帧观测器。

• 加入频道后通过 didJoinedOfUid 获取 B 组用户的 ID，然后调用 setRemoteVideoSubscriptionOptions 设置该组用户的 encodedFrameOnly 为 YES。

• 调用 muteAllRemoteVideoStreams(NO)，开始接收所有远端用户的视频流。此时：

  • 可通过 AgoraVideoFrameDelegate 中的回调获取 A 组用户的原始视频数据，SDK 默认对该数据进行渲染。

  • 可通过 AgoraEncodedVideoFrameDelegate 中的回调获取 B 组用户的已编码视频数据。

注意：

• 该方法需要在加入频道前调用。

• 在处理回调时，你需要考虑视频帧中 width 和 height 参数的变化，因为观测得到的视频帧可能会随以下情况变化：

  • 当网络状况差时，分辨率会阶梯式下降。

  • 当用户自行调整分辨率时，回调中报告的分辨率也会变化。

提示： 注册原始视频观测器后，你可以将获取到的原始视频数据应用于各种视频前处理场景，例如自行实现虚拟背景、美颜等场景，声网在 GitHub 上提供了开源的示例项目 BeautyAPI 供你参考。

参数

参数名	描述
delegate	接口对象实例。详见 AgoraVideoFrameDelegate。如果传入 nil，则取消注册。

返回值

• < 0：方法调用失败。详见错误码了解详情和解决建议。

• YES：方法调用成功。

• NO：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• AgoraRtcEngineKit

onCaptureVideoFrame

获取本地设备采集到的视频数据。

Objective-C

- (BOOL)onCaptureVideoFrame:(AgoraOutputVideoFrame * _Nonnull)videoFrame sourceType:(AgoraVideoSourceType)sourceType;

成功注册视频数据观测器后，SDK 会在捕捉到每个视频帧时触发该回调。你可以在回调中获取本地设备采集到的视频数据，然后根据场景需要，对视频数据进行前处理。

完成前处理后，你可以在该回调中直接修改 videoFrame，并将返回值设置为 YES，即可将修改后的视频数据发送给 SDK。

注意：

• 此处获取的视频数据未经过前处理，如水印、裁剪、旋转和美颜等。

• 如果你获取到的视频数据类型为 RGBA，SDK 不支持对 alpha 通道的值进行处理。

参数

参数名	描述
sourceType	视频源类型，可能的视频源包括：摄像头、屏幕或媒体播放器。详见 AgoraVideoSourceType 。
videoFrame	视频帧数据。详见 AgoraOutputVideoFrame。 注： 通过该回调获取的视频帧数据格式默认值如下： iOS：cvPixelBuffer

返回值

• 当视频处理模式为 AgoraVideoFrameProcessModeReadOnly 时：

  • YES：无实际含义。

  • NO：无实际含义。

• 当视频处理模式为 AgoraVideoFrameProcessModeReadWrite 时：

  • YES：设置 SDK 接收视频帧。

  • NO：设置 SDK 丢弃视频帧。

所属接口类

• AgoraVideoFrameDelegate

didReceiveVideoFrame

已获取视频帧回调。

Objective-C

- (void)AgoraRtcMediaPlayer:(id<AgoraRtcMediaPlayerProtocol> _Nonnull)playerKit
    didReceiveVideoFrame:(CVPixelBufferRef _Nonnull)pixelBuffer;

注册视频数据观测器后，每次接收到一帧视频帧时，都会触发该回调，报告视频帧信息。

参数

参数名	描述
playerKit	详见 AgoraRtcMediaPlayerProtocol。
pixelBuffer	纹理的 Buffer（CVPixelBufferRef）。

所属接口类

• AgoraVideoFrameDelegate

onPreEncodeVideoFrame

获取本地视频编码前的视频数据。

Objective-C

- (BOOL)onPreEncodeVideoFrame:(AgoraOutputVideoFrame * _Nonnull)videoFrame sourceType:(AgoraVideoSourceType)sourceType;

成功注册视频数据观测器后，SDK 会在捕捉到每个视频帧时触发该回调。你可以在回调中获取编码前的视频数据，然后根据场景需要，对视频数据进行处理。

完成处理后，你可以在该回调中，传入处理后的视频数据将其发送回 SDK。

注意：

• 你需要通过 getObservedFramePosition 设置观测 AgoraVideoFramePositionPreEncoder(1 << 2) 后，才能使用该回调获取本地视频编码前的视频数据。

• 此处获取的视频数据已经过前处理，如裁剪、旋转和美颜等。

参数

参数名	描述
sourceType	视频源的类型。详见 AgoraVideoSourceType。
videoFrame	视频帧数据。详见 AgoraOutputVideoFrame。 注： 通过该回调获取的视频帧数据格式默认值如下： iOS：cvPixelBuffer

返回值

• 当视频处理模式为 AgoraVideoFrameProcessModeReadOnly 时：

  • YES：无实际含义。

  • NO：无实际含义。

• 当视频处理模式为 AgoraVideoFrameProcessModeReadWrite 时：

  • YES：设置 SDK 接收视频帧。

  • NO：设置 SDK 丢弃视频帧。

所属接口类

• AgoraVideoFrameDelegate

onRenderVideoFrame

获取远端发送的视频数据。

Objective-C

- (BOOL)onRenderVideoFrame:(AgoraOutputVideoFrame * _Nonnull)videoFrame
    uid:(NSUInteger)uid
    channelId:(NSString * _Nonnull)channelId;

成功注册视频数据观测器后，SDK 会在捕捉到每个视频帧时触发该回调。你可以在回调中获取远端发送的渲染前的视频数据，然后根据场景需要，对视频数据进行处理。

注意：

• 如果你获取到的视频数据类型为 RGBA，SDK 不支持对 alpha 通道的值进行处理。

参数

参数名	描述
uid	发送该帧视频的远端用户 ID。
videoFrame	视频帧数据。详见 AgoraOutputVideoFrame。 注： 通过该回调获取的视频帧数据格式默认值如下： iOS：cvPixelBuffer
channelId	频道 ID。

返回值

• 当视频处理模式为 AgoraVideoFrameProcessModeReadOnly 时：

  • YES：无实际含义。

  • NO：无实际含义。

• 当视频处理模式为 AgoraVideoFrameProcessModeReadWrite 时：

  • YES：设置 SDK 接收视频帧。

  • NO：设置 SDK 丢弃视频帧。

所属接口类

• AgoraVideoFrameDelegate