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