# 原始视频数据 (/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## getMirrorApplied [#getmirrorapplied] 每次 SDK 接收到视频帧时触发的回调,用于设置是否镜像采集的视频。 ```cpp virtual bool getMirrorApplied() { return false; } ``` 如果你希望获取的视频数据是原始视频的镜像图像,需要在调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_imediaengine_registervideoframeobserver_imediaengine) 时注册该回调。成功注册视频帧观察器后,SDK 每次接收到视频帧时都会触发该回调。你需要通过该回调的返回值设置是否对视频帧进行镜像处理。 :::note 注: - 在 Windows 平台,该回调支持的视频数据格式包括:I420、RGBA 和 TextureBuffer。 - 在 Android 平台,该回调支持的视频数据格式包括:I420、RGBA 和 Texture。 - 在 iOS 平台,该回调支持的视频数据格式包括:I420、RGBA 和 CVPixelBuffer。 - 在 macOS 平台,该回调支持的视频数据格式包括:I420 和 RGBA。 - 该方法与 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 方法均支持设置镜像效果。建议你仅使用其中一种方法。若同时使用两种方法,可能导致镜像效果叠加,从而使设置失效。 ::: ### 调用时机 [#调用时机] 每次 SDK 接收到视频帧时触发。 ### 返回值 [#返回值] - true:镜像采集的视频。 - false:(默认)不镜像采集的视频。 ### 所属接口类 [#所属接口类] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) ## getObservedFramePosition [#getobservedframeposition] 设置视频观察器的帧位置。 ```cpp virtual uint32_t getObservedFramePosition() ``` 在成功注册视频数据观察器后,SDK 会通过该回调判断是否在特定的视频帧处理位置触发 [onCaptureVideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe)、[onRenderVideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 和 [onPreEncodeVideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调,从而让你观察本地采集的视频数据、远端接收的视频数据以及编码前的视频数据。你可以根据实际场景,通过修改返回值设置一个或多个需要观察的位置: - `POSITION_POST_CAPTURER` (1 << 0):视频采集后的位置,对应 [onCaptureVideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调。 - `POSITION_PRE_RENDERER` (1 << 1):远端视频数据在渲染前的位置,对应 [onRenderVideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调。 - `POSITION_PRE_ENCODER` (1 << 2):编码前的位置,对应 [onPreEncodeVideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调。 :::note 注: - 使用 `|`(按位或运算符)设置多个观察位置。 - 默认观察位置为 `POSITION_POST_CAPTURER` (1 << 0) 和 `POSITION_PRE_RENDERER` (1 << 1)。 - 为节省系统资源,建议减少观察的位置数量。 - 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 且观察位置为 `POSITION_PRE_ENCODER | POSITION_POST_CAPTURER` 时,[getMirrorApplied](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getmirrorapplied) 不生效。你需要修改视频处理模式或观察位置。 ::: ### 返回值 [#返回值-1] 方法调用成功,返回用于控制视频观察器帧位置的位掩码。详见 [VIDEO_MODULE_POSITION](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videomoduleposition)。 ### 所属接口类 [#所属接口类-1] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) ## getRotationApplied [#getrotationapplied] 是否旋转采集视频的回调。 ```cpp virtual bool getRotationApplied() { return false; } ``` 如果你希望根据 [VideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoframe) 类中的 `rotation` 成员旋转采集的视频,请确保在调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_imediaengine_registervideoframeobserver_imediaengine) 时注册该回调。在成功注册视频帧观察器后,SDK 每次接收到视频帧时都会触发该回调。你需要通过该回调的返回值设置是否旋转视频帧。 :::note 注: - 在 Android 平台,该回调支持的视频数据格式包括:I420、RGBA 和 Texture。 - 在 Windows 平台,该回调支持的视频数据格式包括:I420、RGBA 和 TextureBuffer。 - 在 iOS 平台,该回调支持的视频数据格式包括:I420、RGBA 和 CVPixelBuffer。 - 在 macOS 平台,该回调支持的视频数据格式包括:I420 和 RGBA。 ::: ### 调用时机 [#调用时机-1] 每次 SDK 接收到视频帧时触发。 ### 返回值 [#返回值-2] - true:旋转采集的视频。 - false:(默认)不旋转采集的视频。 ### 所属接口类 [#所属接口类-2] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) ## getVideoFormatPreference [#getvideoformatpreference] 设置 SDK 输出的原始视频数据格式。 ```cpp virtual VIDEO_PIXEL_FORMAT getVideoFormatPreference() { return VIDEO_PIXEL_DEFAULT; } ``` 调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_imediaengine_registervideoframeobserver_imediaengine) 方法注册回调后,每次接收到视频帧时,SDK 会触发该回调。你需要在该回调的返回值中设置偏好的视频数据格式。 :::note 注: 原始视频的默认像素格式(`VIDEO_PIXEL_DEFAULT`)如下: - 在 Windows 平台,默认的视频帧类型为 `YUV420`。 - 在 Android 平台,默认的视频帧类型可能为 `I420Buffer` 或 `TextureBuffer`。`TextureBuffer` 类型的纹理格式可能为 OES 或 RGB。如果你调用 [getVideoFormatPreference](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getvideoformatpreference) 返回的视频帧类型为 `VIDEO_PIXEL_DEFAULT`,则在处理视频数据时需要适配 `I420Buffer` 或 `TextureBuffer`。视频帧类型固定为 `I420Buffer` 的情况包括但不限于: - 特定设备,例如:LG G5 SE(H848)、Google Pixel 4a、Samsung Galaxy A7 或小米 Max。 - 集成了美颜特效扩展并启用了视频降噪或弱光增强功能。 - 在 iOS 和 macOS 平台,默认的视频帧类型可能为 `I420` 或 `CVPixelBufferRef`。 ::: ### 返回值 [#返回值-3] 设置 SDK 输出的原始数据格式,详见 [VIDEO_PIXEL_FORMAT](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videopixelformat)。 ### 所属接口类 [#所属接口类-3] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) ## getVideoFrameProcessMode [#getvideoframeprocessmode] [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 回调。每次 SDK 接收到视频帧时触发,用于设置视频帧的处理模式。 ```cpp virtual VIDEO_FRAME_PROCESS_MODE getVideoFrameProcessMode() { return PROCESS_MODE_READ_ONLY; } ``` 在你成功注册视频帧观察器后,SDK 每次接收到视频帧时都会触发该回调。你需要通过该回调的返回值设置你偏好的处理模式。 ### 调用时机 [#调用时机-2] 每次 SDK 接收到视频帧时触发。 ### 返回值 [#返回值-4] 方法调用成功时,返回一个 [VIDEO_FRAME_PROCESS_MODE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videoframeprocessmode) 枚举值,表示你设置的视频帧处理模式。详见 [VIDEO_FRAME_PROCESS_MODE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videoframeprocessmode)。 ### 所属接口类 [#所属接口类-4] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) ## registerVideoFrameObserver [#registervideoframeobserver] 注册原始视频帧观察器对象。 ```cpp virtual int registerVideoFrameObserver(IVideoFrameObserver* observer) = 0; ``` 通过此方法注册自定义的 [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) 实例,可以观察原始视频帧(如 YUV 或 RGBA 格式)。注册成功后,每当接收到视频帧时,SDK 会触发相应的回调。你可以在虚拟背景、美颜特效等视频预处理场景中使用这些原始视频数据。 :::note 注: 处理回调中返回的视频数据时,请注意 `width` 和 `height` 参数可能会发生变化,具体情况如下: - 当网络状况恶化时,视频分辨率会逐步降低。 - 当用户调整视频配置文件时,回调中返回的视频分辨率也会随之变化。 ::: ### 调用时机 [#调用时机-3] 在加入频道前调用此方法。 ### 参数 [#参数] 观察器实例。若要释放该实例,请将该值设为 NULL。详见 [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver)。 ### 返回值 [#返回值-5] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-5] - [IMediaEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imediaengine) ## onCaptureVideoFrame [#oncapturevideoframe] 本地采集视频帧回调。 ```cpp virtual bool onCaptureVideoFrame(agora::rtc::VIDEO_SOURCE_TYPE sourceType, VideoFrame& videoFrame) = 0; ``` 该回调用于获取本地设备采集的原始视频数据,并进行预处理。你可以在该回调中直接修改 `videoFrame`,并返回 true 将修改后的视频数据发送给 SDK。若需将预处理后的视频数据传递给 SDK,需先调用 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 将视频处理模式设置为读写模式(`PROCESS_MODE_READ_WRITE`)。 :::note 注: - 如果获取的视频数据类型为 RGBA,SDK 不支持处理 alpha 通道的数据。 - 建议确保 `videoFrame` 中修改后的参数与视频帧缓冲区中的实际数据一致,否则可能导致本地预览或远端显示出现旋转、拉伸等异常。 - 该回调默认返回的视频格式为 YUV420。如需其他格式,可在 [getVideoFormatPreference](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getvideoformatpreference) 回调中设置期望的数据格式。 ::: ### 触发时机 [#触发时机] 成功注册视频数据观察器后,每次 SDK 采集到视频帧时触发。 ### 参数 [#参数-1] 视频源类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。 输出参数,表示视频帧,详见 [VideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoframe)。 :::note 注: 通过该回调获取的视频帧数据格式默认如下: - Android:I420 或 RGB(GLES20.GL_TEXTURE_2D) - iOS:I420 或 CVPixelBufferRef - macOS:I420 或 CVPixelBufferRef - Windows:YUV420 ::: ### 返回值 [#返回值-6] - 当视频处理模式为 `PROCESS_MODE_READ_ONLY` 时: - true:保留以供后续使用。 - false:保留以供后续使用。 - 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 时: - true:设置 SDK 接收该视频帧。 - false:设置 SDK 丢弃该视频帧。 ### 所属接口类 [#所属接口类-6] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) ## onFrame [#onframe] 播放器接收到视频帧时触发的回调。 ```cpp virtual void onFrame(const VideoFrame* frame) = 0; ``` 注册视频帧观察器后,该回调会在播放器每次接收到视频帧时触发,并上报视频帧的详细信息。 ### 参数 [#参数-2] 视频帧信息,详见 [VideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoframe)。 ### 所属接口类 [#所属接口类-7] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) ## onPreEncodeVideoFrame [#onpreencodevideoframe] 接收到编码前视频帧回调。 ```cpp virtual bool onPreEncodeVideoFrame(agora::rtc::VIDEO_SOURCE_TYPE sourceType, VideoFrame& videoFrame) = 0; ``` 当你成功注册视频帧观察器后,SDK 每次接收到视频帧时都会触发该回调。在该回调中,你可以获取编码前的视频数据,并根据具体场景进行处理。处理完成后,可以将处理后的视频数据返回给 SDK。 :::note 注: - 如果你需要将预处理后的视频数据发送回 SDK,需要先调用 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 将视频处理模式设置为读写模式(`PROCESS_MODE_READ_WRITE`)。 - 如果你需要获取从第二路屏幕采集的编码前视频数据,需要通过 [getObservedFramePosition](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getobservedframeposition) 设置帧位置为 `POSITION_PRE_ENCODER`(1 << 2)。 - 该回调获取的视频数据已经过预处理,包括裁剪、旋转和美颜特效。 - 建议你确保 `videoFrame` 中修改后的参数与视频帧缓冲区中视频帧的实际情况一致,否则可能导致本地预览和远端视频显示中出现旋转异常、图像失真等问题。 ::: ### 触发时机 [#触发时机-1] 当 SDK 接收到编码前视频帧时触发。 ### 参数 [#参数-3] 视频源类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。 输出参数,表示编码前的视频帧,详见 [VideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoframe)。 :::note 注: 通过该回调获取的视频帧数据的默认格式如下: - Android:I420 或 RGB(GLES20.GL_TEXTURE_2D)。 - iOS:I420 或 CVPixelBufferRef。 - macOS:I420 或 CVPixelBufferRef。 - Windows:YUV420。 ::: ### 返回值 [#返回值-7] - 当视频处理模式为 `PROCESS_MODE_READ_ONLY` 时: - true:保留以供后续使用。 - false:保留以供后续使用。 - 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 时: - true:设置 SDK 接收该视频帧。 - false:设置 SDK 丢弃该视频帧。 ### 所属接口类 [#所属接口类-8] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver) ## onRenderVideoFrame [#onrendervideoframe] 接收到远端用户发送的视频帧回调。 ```cpp virtual bool onRenderVideoFrame(const char* channelId, rtc::uid_t remoteUid, VideoFrame& videoFrame) = 0; ``` 当你成功注册视频帧观察器后,SDK 每次接收到远端用户发送的视频帧时会触发该回调。在该回调中,你可以在渲染前获取远端的视频数据,并根据具体场景进行处理。默认返回的视频格式为 `YUV420`。如需其他格式,可在 [getVideoFormatPreference](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getvideoformatpreference) 中设置期望格式。 :::note 注: - 如果你需要将预处理后的视频数据发送回 SDK,需先调用 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 将视频处理模式设置为读写模式(`PROCESS_MODE_READ_WRITE`)。 - 如果你获取的视频数据类型为 `RGBA`,SDK 不支持处理 alpha 通道数据。 - 建议确保 `videoFrame` 中修改后的参数与视频帧缓冲区中的实际帧数据一致,否则可能导致本地预览或远端显示出现旋转、拉伸等异常。 ::: ### 触发时机 [#触发时机-2] 该回调在每次 SDK 接收到远端用户发送的视频帧时触发。 ### 参数 [#参数-4] 频道 ID。 发送当前视频帧的远端用户的用户 ID。 视频帧,详见 [VideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoframe)。 :::note 注: 通过该回调获取的视频帧数据格式默认如下: - Android:I420 或 RGB(GLES20.GL_TEXTURE_2D) - iOS:I420 或 CVPixelBufferRef - macOS:I420 或 CVPixelBufferRef - Windows:YUV420 ::: ### 返回值 [#返回值-8] - 当视频处理模式为 `PROCESS_MODE_READ_ONLY` 时: - true:保留以供后续使用。 - false:保留以供后续使用。 - 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 时: - true:设置 SDK 接收该视频帧。 - false:设置 SDK 丢弃该视频帧。 ### 所属接口类 [#所属接口类-9] - [IVideoFrameObserver](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_ivideoframeobserver)