原始视频数据
- macOS
更新时间不可用
getMirrorApplied
设置是否镜像采集的视频。
- (BOOL)getMirrorApplied NS_SWIFT_NAME(getMirrorApplied());如果你希望获取的视频数据是原始视频的镜像图像，在调用 setVideoFrameDelegate: 时需要注册该回调。成功注册视频帧观察器后，SDK 每次接收到视频帧时都会触发该回调。你需要在该回调的返回值中设置是否对视频帧进行镜像处理。
- 在 iOS 平台，该回调支持的视频数据格式包括：I420、RGBA 和
CVPixelBuffer。 - 在 macOS 平台，该回调支持的视频数据格式包括：I420 和 RGBA。
- 此方法和 setVideoEncoderConfiguration: 方法都支持设置镜像效果。声网建议你仅使用其中一种方式进行设置，同时使用两种方式会导致镜像效果叠加，镜像设置失效。
调用时机
每次 SDK 接收到视频帧时触发。
返回值
是否镜像采集的视频：
- YES：镜像采集的视频。
- NO：（默认）不镜像采集的视频。
所属接口类
getObservedFramePosition
设置视频观察器的帧位置。
- (AgoraVideoFramePosition)getObservedFramePosition NS_SWIFT_NAME(getObservedFramePosition());在你成功注册视频数据观察器后，SDK 会通过该回调判断是否在特定的视频帧处理位置触发 onCaptureVideoFrame、onRenderVideoFrame 和 onPreEncodeVideoFrame 回调，从而让你观察本地采集的视频数据、远端发送的视频数据以及编码前的视频数据。你可以根据实际场景，通过修改返回值设置一个或多个需要观察的位置：
AgoraVideoModulePositionPostCapture(1 << 0)：视频采集后的位置，对应onCaptureVideoFrame回调。AgoraVideoModulePositionPreRenderer(1 << 1)：接收的远端视频数据在渲染前的位置，对应onRenderVideoFrame回调。AgoraVideoModulePositionPreEncoder(1 << 2)：编码前的视频数据位置，对应onPreEncodeVideoFrame回调。
注：
- 使用
|（按位或运算符）以观察多个帧位置。 - 默认情况下，该回调观察
AgoraVideoModulePositionPostCapture(1 << 0) 和AgoraVideoModulePositionPreRenderer(1 << 1)。 - 为节省系统资源，你可以减少需要观察的帧位置数量。
- 当视频处理模式为
AgoraVideoFrameProcessModeReadWrite且观察位置设置为AgoraVideoModulePositionPreEncoder | AgoraVideoModulePositionPostCapture时，getMirrorApplied 不生效。你需要修改视频处理模式或观察器的位置。
返回值
用于控制你希望观察的视频帧位置的位掩码。详见 AgoraVideoFramePosition。
所属接口类
getRotationApplied
每次 SDK 接收到视频帧时触发，并提示你是否旋转采集的视频。
- (BOOL)getRotationApplied NS_SWIFT_NAME(getRotationApplied());如果采集设备上的视频已根据 AgoraOutputVideoFrame 中的 rotation 进行了旋转，则你无需调用该方法设置视频旋转。
注：
- 在 iOS 上，该回调支持的视频数据格式包括：I420、RGBA 和
CVPixelBuffer。 - 在 macOS 上，该回调支持的视频数据格式包括：I420 和 RGBA。
返回值
- YES：旋转采集的视频。
- NO：（默认）不旋转采集的视频。
所属接口类
getVideoFormatPreference
设置 SDK 输出的原始视频数据格式。
- (AgoraVideoFormat)getVideoFormatPreference NS_SWIFT_NAME(getVideoFormatPreference());调用 setVideoFrameDelegate: 方法注册回调后，SDK 每次接收到视频帧时会触发该回调。你需要在该回调的返回值中设置所需的视频数据格式。
注： 原始视频的默认像素格式类型（AgoraVideoFormatDefault）如下：
- 默认的视频帧类型可能为
I420或CVPixelBufferRef。
返回值
方法调用成功时，返回原始视频数据的格式，详见 AgoraVideoFormat。
所属接口类
getVideoFrameProcessMode
getVideoFrameProcessMode 回调。每次 SDK 接收到视频帧时触发，并提示你设置视频帧的处理模式。
- (AgoraVideoFrameProcessMode)getVideoFrameProcessMode NS_SWIFT_NAME(getVideoFrameProcessMode());在你成功注册视频帧观察器后，SDK 每次接收到视频帧时都会触发该回调。你需要在该回调的返回值中设置你偏好的处理模式。
调用时机
每次 SDK 接收到视频帧时触发。
返回值
方法调用成功时，返回你设置的视频帧处理模式，详见 AgoraVideoFrameProcessMode。
所属接口类
setVideoFrameDelegate:
注册原始视频帧观察者对象。
- (BOOL)setVideoFrameDelegate:(id<AgoraVideoFrameDelegate> _Nullable)delegate NS_SWIFT_NAME(setVideoFrameDelegate(_:));如果你希望观察原始视频帧（例如 YUV 或 RGBA 格式），声网建议你通过此方法实现一个 AgoraVideoFrameDelegate 类。当你调用此方法注册视频观察者时，可以根据需要在 AgoraVideoFrameDelegate 类中注册回调。注册成功后，SDK 每次接收到视频帧时都会触发已注册的回调。
你可以在各种视频预处理场景中使用获取到的原始视频数据，例如虚拟背景和美颜特效。声网在 GitHub 上提供了一个开源的 iOS 示例项目 BeautyAPI 供你参考。
调用时机
该方法需要在加入频道前调用。
参数
| 参数名 | 描述 |
|---|---|
delegate | 观察者实例。要释放该实例，请将该参数设为 nil。详见 AgoraVideoFrameDelegate。 |
返回值
- YES：注册原始视频帧观察者成功。
- NO：注册原始视频帧观察者失败。
< 0：方法调用失败。
所属接口类
onCaptureVideoFrame:sourceType:
每次 SDK 接收到本地设备采集的视频帧时触发。
- (BOOL)onCaptureVideoFrame:(AgoraOutputVideoFrame * _Nonnull)videoFrame sourceType:(AgoraVideoSourceType)sourceType;你可以通过该回调获取本地设备采集的原始视频数据，并根据需要进行预处理。预处理完成后，你可以直接在该回调中修改 videoFrame，并将返回值设置为 YES，以将修改后的视频数据发送给 SDK。如果你需要将预处理后的视频数据发送给 SDK，需先调用 getVideoFrameProcessMode 将视频处理模式设置为读写模式（AgoraVideoFrameProcessModeReadWrite）。
注：
- 如果你获取的视频数据类型为 RGBA，SDK 不支持处理 alpha 通道的数据。
- 建议你确保
videoFrame中修改后的参数与视频帧缓冲区中视频帧的实际情况一致，否则可能导致本地预览和远端视频显示出现异常旋转、拉伸等问题。 - 默认通过该回调获取的视频格式为 I420 或
CVPixelBufferRef。如果你需要其他格式，可以在 getVideoFormatPreference 回调中设置期望的数据格式。
触发时机
该回调在成功注册视频数据观察器后，每次 SDK 采集到视频帧时被触发。
参数
| 参数名 | 描述 |
|---|---|
videoFrame | |
sourceType | 视频源类型，包括摄像头、屏幕或媒体播放器。详见 AgoraVideoSourceType。 |
返回值
-
当视频处理模式为
AgoraVideoFrameProcessModeReadOnly时：- YES：保留以供将来使用。
- NO：保留以供将来使用。
-
当视频处理模式为
AgoraVideoFrameProcessModeReadWrite时：- YES：设置 SDK 接收该视频帧。
- NO：设置 SDK 丢弃该视频帧。
所属接口类
onPreEncodeVideoFrame:sourceType:
每次 SDK 接收到编码前视频帧时触发。
- (BOOL)onPreEncodeVideoFrame:(AgoraOutputVideoFrame * _Nonnull)videoFrame sourceType:(AgoraVideoSourceType)sourceType;在你成功注册视频帧观察器后，SDK 每次接收到视频帧时都会触发该回调。在该回调中，你可以获取编码前的视频数据，并根据具体场景对其进行处理。处理完成后，你可以将处理后的视频数据返回给 SDK。
注：
- 如果你需要将预处理后的视频数据发送回 SDK，你需要先调用 getVideoFrameProcessMode 将视频处理模式设置为读写模式（
AgoraVideoFrameProcessModeReadWrite）。 - 如果你需要获取从第二屏幕采集的编码前的视频数据，你需要通过 getObservedFramePosition 设置帧位置为
AgoraVideoModulePositionPreEncoder（1 << 2）。 - 该回调获取的视频数据已被预处理，包括裁剪、旋转和美颜特效。
- 建议你确保
videoFrame中修改后的参数与视频帧缓冲区中视频帧的实际情况一致。否则，可能会导致本地预览和远端视频显示出现意外的旋转、变形等问题。
触发时机
该回调在每次 SDK 接收到编码前视频帧时被触发。
参数
| 参数名 | 描述 |
|---|---|
videoFrame | |
sourceType | 视频源的类型，详见 AgoraVideoSourceType。 |
返回值
-
当视频处理模式为
AgoraVideoFrameProcessModeReadOnly时：- YES：保留以供将来使用。
- NO：保留以供将来使用。
-
当视频处理模式为
AgoraVideoFrameProcessModeReadWrite时：- YES：设置 SDK 接收该视频帧。
- NO：设置 SDK 丢弃该视频帧。
所属接口类
onRenderVideoFrame:uid:channelId:
每次 SDK 接收到远端用户发送的视频帧时触发。
- (BOOL)onRenderVideoFrame:(AgoraOutputVideoFrame * _Nonnull)videoFrame uid:(NSUInteger)uid channelId:(NSString * _Nonnull)channelId NS_SWIFT_NAME(onRenderVideoFrame(_:uid:channelId:));在你成功注册视频帧观察器后，SDK 每次接收到视频帧时都会触发该回调。在该回调中，你可以在渲染前获取远端发送的视频数据，并根据具体场景进行处理。通过该回调获取的视频格式默认为 I420 或 CVPixelBufferRef。如果你需要其他格式，可以在 getVideoFormatPreference 回调中设置期望的数据格式。
注：
- 如果你需要将预处理后的视频数据发送给 SDK，需要先调用 getVideoFrameProcessMode 将视频处理模式设置为读写模式（
AgoraVideoFrameProcessModeReadWrite）。 - 如果你获取的视频数据类型为 RGBA，SDK 不支持处理 alpha 通道的数据。
- 建议确保
videoFrame中修改后的参数与视频帧缓冲区中视频帧的实际情况一致，否则可能导致本地预览和远端视频显示出现异常旋转、拉伸等问题。
触发时机
该回调在 SDK 每次接收到远端用户发送的视频帧时被触发。
参数
| 参数名 | 描述 |
|---|---|
videoFrame | |
uid | |
channelId |
返回值
-
当视频处理模式为
AgoraVideoFrameProcessModeReadOnly时：- YES：保留以供将来使用。
- NO：保留以供将来使用。
-
当视频处理模式为
AgoraVideoFrameProcessModeReadWrite时：- YES：设置 SDK 接收该视频帧。
- NO：设置 SDK 丢弃该视频帧。