# 原始视频数据 (/zh-CN/api-reference/rtc/android/4.6.0/video/video-raw)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## getMirrorApplied [#getmirrorapplied]
每次 SDK 接收到视频帧时触发的回调,用于设置是否对采集的视频进行镜像。
```java
@CalledByNative boolean getMirrorApplied();
```
如果你希望获取的视频数据是原始视频的镜像图像,需要在调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/android/video/video-raw#api_irtcengine_registervideoframeobserver) 时注册该回调。成功注册视频帧观察器后,SDK 每次接收到视频帧时都会触发该回调。你需要在该回调的返回值中设置是否对视频帧进行镜像。
注:
- 在 Android 平台,该回调支持的视频数据格式包括:I420、RGBA 和 Texture。
- 该方法与 setVideoEncoderConfiguration 都支持设置镜像效果。建议你仅使用其中一种方式进行设置,同时使用两种方式会导致镜像效果叠加,从而使设置失效。
### 调用时机 [#调用时机]
该回调在 SDK 每次接收到视频帧时被触发。
### 返回值 [#返回值]
是否对采集的视频进行镜像:
- true:对采集的视频进行镜像。
- false:(默认)不对采集的视频进行镜像。
### 所属接口类 [#所属接口类]
- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)
## getObservedFramePosition [#getobservedframeposition]
设置视频观察器的帧位置。
```java
@CalledByNative int getObservedFramePosition();
```
在成功注册视频数据观察器后,SDK 会通过该回调判断是否在特定的视频帧处理位置触发 [onCaptureVideoFrame](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe)、 [onRenderVideoFrame](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 和 [onPreEncodeVideoFrame](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调。你可以根据业务场景,通过修改返回值设置一个或多个需要观察的位置:
- VIDEO_MODULE_POSITION_POST_CAPTURER (1 << 0):视频采集后的位置,对应 onCaptureVideoFrame 回调。
- VIDEO_MODULE_POSITION_PRE_RENDERER (1 << 1):远端视频渲染前的位置,对应 onRenderVideoFrame 回调。
- VIDEO_MODULE_POSITION_PRE_ENCODER (1 << 2):编码前的位置,对应 onPreEncodeVideoFrame 回调。
### 返回值 [#返回值-1]
方法调用成功,返回用于控制视频观察器帧位置的位掩码:
- VIDEO_MODULE_POSITION_POST_CAPTURER (1 << 0):视频采集后的位置。
- VIDEO_MODULE_POSITION_PRE_RENDERER (1 << 1):远端视频渲染前的位置。
- VIDEO_MODULE_POSITION_PRE_ENCODER (1 << 2):编码前的位置。
### 所属接口类 [#所属接口类-1]
- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)
## getRotationApplied [#getrotationapplied]
getRotationApplied 回调在每次 SDK 接收到视频帧时触发,用于设置是否旋转采集的视频。
```java
@CalledByNative boolean getRotationApplied();
```
如果你希望根据 `VideoFrame` 中的 `rotation` 成员旋转采集的视频,需要在调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/android/video/video-raw#api_irtcengine_registervideoframeobserver) 时注册该回调。注册成功后,SDK 每次接收到视频帧时会触发该回调。你需要通过该回调的返回值设置是否旋转视频帧。
:::info[注]
在 Android 平台上,该回调支持的视频数据格式包括:I420、RGBA 和 Texture。
:::
### 调用时机 [#调用时机-1]
该回调在 SDK 每次接收到视频帧时被触发。
### 返回值 [#返回值-2]
- true:旋转采集的视频。
- false:(默认)不旋转采集的视频。
### 所属接口类 [#所属接口类-2]
- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)
## getVideoFormatPreference [#getvideoformatpreference]
设置 SDK 输出的原始视频数据格式。
```java
@CalledByNative int getVideoFormatPreference();
```
调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/android/video/video-raw#api_irtcengine_registervideoframeobserver) 方法注册回调后,SDK 每次接收到视频帧时会触发该回调。你需要在该回调的返回值中设置期望的视频数据格式。
注: `VIDEO_PIXEL_DEFAULT` 表示原始视频的默认像素格式类型,具体如下:
- 在 Android 平台上,默认的视频帧类型可能为 I420Buffer 或 TextureBuffer。 TextureBuffer 类型的纹理格式可能为 OES 或 RGB。如果 getVideoFormatPreference 返回的视频帧类型为 VIDEO_PIXEL_DEFAULT,则在处理视频数据时需要适配 I420Buffer 或 TextureBuffer。
视频帧类型固定为 `I420Buffer` 的情况包括但不限于:
- 特定设备,例如:LG G5 SE(H848)、Google Pixel 4a、Samsung Galaxy A7 或小米 Max。
- 已集成美颜特效扩展并启用了视频降噪或弱光增强功能。
### 返回值 [#返回值-3]
方法调用成功,返回 SDK 输出的原始数据格式:
- VIDEO_PIXEL_DEFAULT (0):原始视频格式,需适配 I420Buffer 或 TextureBuffer。
- VIDEO_PIXEL_I420 (1):I420 格式。
- VIDEO_PIXEL_RGBA (4):RGBA 格式。
- VIDEO_PIXEL_I422 (16):I422 格式。
### 所属接口类 [#所属接口类-3]
- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)
## getVideoFrameProcessMode [#getvideoframeprocessmode]
getVideoFrameProcessMode 回调。每次 SDK 接收到视频帧时触发,并提示你设置视频帧的处理模式。
```java
@CalledByNative int getVideoFrameProcessMode();
```
在成功注册视频帧观察器后,SDK 每次接收到视频帧时会触发 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 回调。你需要在该回调的返回值中设置偏好的处理模式。
### 返回值 [#返回值-4]
视频帧的处理模式:
- PROCESS_MODE_READ_ONLY (0):(默认)只读取视频帧。
- PROCESS_MODE_READ_WRITE (1):读取并写入视频帧。
### 所属接口类 [#所属接口类-4]
- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)
## registerVideoFrameObserver [#registervideoframeobserver]
注册原始视频帧观察器对象。
```java
public abstract int registerVideoFrameObserver(IVideoFrameObserver observer);
```
建议通过该方法注册一个 [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver) 实例,并在该类中根据需要实现回调。成功注册后,每当接收到视频帧时,SDK 会触发相应的回调。你可以在虚拟背景、美颜特效等视频预处理场景中使用这些原始视频数据。
注: 在处理回调中返回的视频数据时,请注意 `width` 和 `height` 参数可能发生变化,具体情况如下:
- 当网络状况恶化时,视频分辨率会逐步降低。
- 当用户调整视频配置时,回调中返回的视频分辨率也会随之变化。
### 调用时机 [#调用时机-2]
请在加入频道前调用此方法。
### 参数 [#参数]
#### `observer` [#observer]
观察器实例。详见 [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)。
:::info[注]
如需释放该实例,请将该参数设为 `null`。
:::
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## onCaptureVideoFrame [#oncapturevideoframe]
本地设备采集到视频帧时触发的回调。
```java
@CalledByNative boolean onCaptureVideoFrame(int sourceType, VideoFrame videoFrame);
```
你可以通过该回调获取本地设备采集的原始视频数据,并根据需要进行预处理。预处理完成后,可以直接在该回调中修改 `videoFrame`,并将返回值设置为 true,以将修改后的视频数据发送给 SDK。如果需要将预处理后的视频数据发送给 SDK,需先调用 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 将视频处理模式设置为读写模式(`PROCESS_MODE_READ_WRITE` )。
注:
- 如果获取的视频数据类型为 RGBA,SDK 不支持处理 alpha 通道的数据。
- 建议确保 videoFrame 中修改后的参数与视频帧缓冲区中视频帧的实际情况一致。否则,可能会导致本地预览和远端视频显示出现异常旋转、拉伸等问题。
- 通过该回调获取的视频格式默认可能为 I420Buffer 或 TextureBuffer。 TextureBuffer 的纹理格式可能为 OES 格式或 RGB 格式。如果你需要其他格式的视频数据,可以在 getVideoFormatPreference 回调的返回值中设置期望的数据格式。
### 触发时机 [#触发时机]
该回调在成功注册视频数据观察器后,每次 SDK 采集到视频帧时被触发。
### 参数 [#参数-1]
#### `sourceType` [#sourcetype]
视频源类型,包括摄像头、屏幕或媒体播放器。详见 [VideoSourceType](/zh-CN/api-reference/rtc/android/class-and-enum/enums/enum-videosourcetype)。
#### `videoFrame` [#videoframe]
视频帧。
注: 通过该回调获取的视频帧数据格式默认值如下:
- Android:I420 或 RGB(GLES20.GL_TEXTURE_2D)
### 返回值 [#返回值-6]
- 当视频处理模式为 PROCESS_MODE_READ_ONLY 时:
- true:保留以供后续使用。
- false:保留以供后续使用。
- 当视频处理模式为 PROCESS_MODE_READ_WRITE 时:
- true:设置 SDK 接收该视频帧。
- false:设置 SDK 丢弃该视频帧。
### 所属接口类 [#所属接口类-6]
- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)
## onPreEncodeVideoFrame [#onpreencodevideoframe]
每次 SDK 接收到编码前视频帧时触发该回调。
```java
@CalledByNative boolean onPreEncodeVideoFrame(int sourceType, VideoFrame videoFrame);
```
在你成功注册视频帧观察器后,SDK 每次接收到视频帧时都会触发该回调。在该回调中,你可以获取编码前的视频数据,并根据具体场景对数据进行处理。处理完成后,可以将处理后的视频数据返回给 SDK。
注:
- 如果你需要将预处理后的视频数据发送回 SDK,需要先调用 getVideoFrameProcessMode 将视频处理模式设置为读写模式(PROCESS_MODE_READ_WRITE )。
- 若需获取从第二路屏幕采集的编码前视频数据,需要通过 getObservedFramePosition 设置帧位置为 VIDEO_MODULE_POSITION_PRE_ENCODER (1 << 2)。
- 该回调获取的视频数据已被预处理,包括裁剪、旋转和美颜特效。
- 建议确保 videoFrame 中修改后的参数与视频帧缓冲区中视频帧的实际情况一致,否则可能导致本地预览和远端视频显示出现异常旋转、图像拉伸等问题。
### 触发时机 [#触发时机-1]
该回调在 SDK 每次接收到编码前的视频帧时被触发。
### 参数 [#参数-2]
#### `sourceType` [#sourcetype-1]
视频源类型。详见 [VideoSourceType](/zh-CN/api-reference/rtc/android/class-and-enum/enums/enum-videosourcetype)。
#### `videoFrame` [#videoframe-1]
视频帧。
注: 通过该回调获取的视频帧数据格式默认如下:
- Android:I420 或 RGB(GLES20.GL_TEXTURE_2D)。
### 返回值 [#返回值-7]
- 当视频处理模式为 PROCESS_MODE_READ_ONLY 时:
- true:保留以供后续使用。
- false:保留以供后续使用。
- 当视频处理模式为 PROCESS_MODE_READ_WRITE 时:
- true:SDK 接收该视频帧。
- false:SDK 丢弃该视频帧。
### 所属接口类 [#所属接口类-7]
- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)
## onRenderVideoFrame [#onrendervideoframe]
远端用户发送视频帧时触发的回调。
```java
boolean onRenderVideoFrame(String channelId, int uid, VideoFrame videoFrame)
```
在你成功注册视频帧观察器后,SDK 每次接收到远端用户发送的视频帧时会触发该回调。你可以在渲染前获取远端发送的视频数据,并根据具体场景进行处理。通过该回调获取的视频帧默认格式可能为 `I420Buffer` 或 `TextureBuffer`, `TextureBuffer` 的纹理格式可能为 `OES` 或 `RGB`。如果你需要其他格式的视频数据,可以在 [getVideoFormatPreference](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoformatpreference) 回调中设置期望的数据格式。
注:
- 如果你需要将预处理后的视频数据发送回 SDK,需要先调用 getVideoFrameProcessMode 将视频处理模式设置为读写模式(PROCESS_MODE_READ_WRITE )。
- 如果你获取的视频数据类型为 RGBA,SDK 不支持处理 alpha 通道的数据。
- 建议你确保 videoFrame 中修改后的参数与视频帧缓冲区中视频帧的实际情况一致。否则,可能会导致本地预览和远端视频显示出现异常旋转、图像拉伸等问题。
### 触发时机 [#触发时机-2]
该回调在 SDK 接收到远端用户发送的视频帧时被触发。
### 参数 [#参数-3]
#### `channelId` [#channelid]
频道 ID。
#### `uid` [#uid]
发送当前视频帧的远端用户 ID。
#### `videoFrame` [#videoframe-2]
视频帧。
### 返回值 [#返回值-8]
- 当视频处理模式为 PROCESS_MODE_READ_ONLY 时:
- true:保留以供后续使用。
- false:保留以供后续使用。
- 当视频处理模式为 PROCESS_MODE_READ_WRITE 时:
- true:SDK 接收该视频帧。
- false:SDK 丢弃该视频帧。
### 所属接口类 [#所属接口类-8]
- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_ivideoframeobserver)