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