# 原始视频数据 (/zh-CN/api-reference/rtc/android/video/video-raw)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_video_raw"></a>

<a id="api_ivideoframeobserver_getmirrorapplied"></a>

<a id="ariaid-title2"></a>

## getMirrorApplied [#getmirrorapplied]

每次 SDK 接收到视频帧时触发的回调，用于设置是否对采集的视频进行镜像。

<a id="api_ivideoframeobserver_getmirrorapplied__prototype"></a>

```java
@CalledByNative boolean getMirrorApplied();
```

<a id="api_ivideoframeobserver_getmirrorapplied__detailed_desc"></a>

如果你希望获取的视频数据是原始视频的镜像图像，需要在调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/android/video/video-raw#api_irtcengine_registervideoframeobserver) 时注册该回调。成功注册视频帧观察器后，SDK 每次接收到视频帧时都会触发该回调。你需要在该回调的返回值中设置是否对视频帧进行镜像。

:::note
注：

- 在 Android 平台，该回调支持的视频数据格式包括：I420、RGBA 和 Texture。
- 该方法与 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 都支持设置镜像效果。建议你仅使用其中一种方式进行设置，同时使用两种方式会导致镜像效果叠加，从而使设置失效。
:::

<a id="api_ivideoframeobserver_getmirrorapplied__timing"></a>

### 调用时机 [#调用时机]

该回调在 SDK 每次接收到视频帧时被触发。

<a id="api_ivideoframeobserver_getmirrorapplied__return_values"></a>

### 返回值 [#返回值]

是否对采集的视频进行镜像：

- true：对采集的视频进行镜像。
- false：（默认）不对采集的视频进行镜像。

### 所属接口类 [#所属接口类]

- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver)

<a id="api_ivideoframeobserver_getobservedframeposition"></a>

<a id="ariaid-title3"></a>

## getObservedFramePosition [#getobservedframeposition]

设置视频观察器的帧位置。

<a id="api_ivideoframeobserver_getobservedframeposition__prototype"></a>

```java
@CalledByNative int getObservedFramePosition();
```

<a id="api_ivideoframeobserver_getobservedframeposition__detailed_desc"></a>

在成功注册视频数据观察器后，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 &lt;&lt; 0)：视频采集后的位置，对应 [onCaptureVideoFrame](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_oncapturevideoframe) 回调。
- `VIDEO_MODULE_POSITION_PRE_RENDERER` (1 &lt;&lt; 1)：远端视频渲染前的位置，对应 [onRenderVideoFrame](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_onrendervideoframe) 回调。
- `VIDEO_MODULE_POSITION_PRE_ENCODER` (1 &lt;&lt; 2)：编码前的位置，对应 [onPreEncodeVideoFrame](/zh-CN/api-reference/rtc/android/video/video-raw#callback_ivideoframeobserver_onpreencodevideoframe) 回调。

<a id="api_ivideoframeobserver_getobservedframeposition__return_values"></a>

### 返回值 [#返回值-1]

方法调用成功，返回用于控制视频观察器帧位置的位掩码：

- `VIDEO_MODULE_POSITION_POST_CAPTURER` (1 &lt;&lt; 0)：视频采集后的位置。
- `VIDEO_MODULE_POSITION_PRE_RENDERER` (1 &lt;&lt; 1)：远端视频渲染前的位置。
- `VIDEO_MODULE_POSITION_PRE_ENCODER` (1 &lt;&lt; 2)：编码前的位置。

### 所属接口类 [#所属接口类-1]

- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver)

<a id="api_ivideoframeobserver_getrotationapplied"></a>

<a id="ariaid-title4"></a>

## getRotationApplied [#getrotationapplied]

[getRotationApplied](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getrotationapplied) 回调在每次 SDK 接收到视频帧时触发，用于设置是否旋转采集的视频。

<a id="api_ivideoframeobserver_getrotationapplied__prototype"></a>

```java
@CalledByNative boolean getRotationApplied();
```

<a id="api_ivideoframeobserver_getrotationapplied__detailed_desc"></a>

如果你希望根据 [VideoFrame](/zh-CN/api-reference/rtc/android/class-videoframe) 中的 `rotation` 成员旋转采集的视频，需要在调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/android/video/video-raw#api_irtcengine_registervideoframeobserver) 时注册该回调。注册成功后，SDK 每次接收到视频帧时会触发该回调。你需要通过该回调的返回值设置是否旋转视频帧。

:::note
注： 在 Android 平台上，该回调支持的视频数据格式包括：I420、RGBA 和 Texture。
:::

<a id="api_ivideoframeobserver_getrotationapplied__timing"></a>

### 调用时机 [#调用时机-1]

该回调在 SDK 每次接收到视频帧时被触发。

<a id="api_ivideoframeobserver_getrotationapplied__return_values"></a>

### 返回值 [#返回值-2]

- true：旋转采集的视频。
- false：（默认）不旋转采集的视频。

### 所属接口类 [#所属接口类-2]

- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver)

<a id="api_ivideoframeobserver_getvideoformatpreference"></a>

<a id="ariaid-title5"></a>

## getVideoFormatPreference [#getvideoformatpreference]

设置 SDK 输出的原始视频数据格式。

<a id="api_ivideoframeobserver_getvideoformatpreference__prototype"></a>

```java
@CalledByNative int getVideoFormatPreference();
```

<a id="api_ivideoframeobserver_getvideoformatpreference__detailed_desc"></a>

调用 [registerVideoFrameObserver](/zh-CN/api-reference/rtc/android/video/video-raw#api_irtcengine_registervideoframeobserver) 方法注册回调后，SDK 每次接收到视频帧时会触发该回调。你需要在该回调的返回值中设置期望的视频数据格式。

:::note
注： `VIDEO_PIXEL_DEFAULT` 表示原始视频的默认像素格式类型，具体如下：

- 在 Android 平台上，默认的视频帧类型可能为 `I420Buffer` 或 `TextureBuffer`。`TextureBuffer` 类型的纹理格式可能为 OES 或 RGB。如果 [getVideoFormatPreference](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoformatpreference) 返回的视频帧类型为 `VIDEO_PIXEL_DEFAULT`，则在处理视频数据时需要适配 `I420Buffer` 或 `TextureBuffer`。

视频帧类型固定为 `I420Buffer` 的情况包括但不限于：

- 特定设备，例如：LG G5 SE（H848）、Google Pixel 4a、Samsung Galaxy A7 或小米 Max。
- 已集成美颜特效扩展并启用了视频降噪或弱光增强功能。
:::

<a id="api_ivideoframeobserver_getvideoformatpreference__return_values"></a>

### 返回值 [#返回值-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/rtc-interface-class#class_ivideoframeobserver)

<a id="api_ivideoframeobserver_getvideoframeprocessmode"></a>

<a id="ariaid-title6"></a>

## getVideoFrameProcessMode [#getvideoframeprocessmode]

[getVideoFrameProcessMode](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 回调。每次 SDK 接收到视频帧时触发，并提示你设置视频帧的处理模式。

<a id="api_ivideoframeobserver_getvideoframeprocessmode__prototype"></a>

```java
@CalledByNative int getVideoFrameProcessMode();
```

<a id="api_ivideoframeobserver_getvideoframeprocessmode__detailed_desc"></a>

在成功注册视频帧观察器后，SDK 每次接收到视频帧时会触发 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 回调。你需要在该回调的返回值中设置偏好的处理模式。

<a id="api_ivideoframeobserver_getvideoframeprocessmode__return_values"></a>

### 返回值 [#返回值-4]

视频帧的处理模式：

- `PROCESS_MODE_READ_ONLY`（0）：（默认）只读取视频帧。
- `PROCESS_MODE_READ_WRITE`（1）：读取并写入视频帧。

### 所属接口类 [#所属接口类-4]

- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver)

<a id="api_irtcengine_registervideoframeobserver"></a>

<a id="ariaid-title7"></a>

## registerVideoFrameObserver [#registervideoframeobserver]

注册原始视频帧观察器对象。

<a id="api_irtcengine_registervideoframeobserver__prototype"></a>

```java
public abstract int registerVideoFrameObserver(IVideoFrameObserver observer);
```

<a id="api_irtcengine_registervideoframeobserver__detailed_desc"></a>

建议通过该方法注册一个 [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver) 实例，并在该类中根据需要实现回调。成功注册后，每当接收到视频帧时，SDK 会触发相应的回调。你可以在虚拟背景、美颜特效等视频预处理场景中使用这些原始视频数据。

:::note
注： 在处理回调中返回的视频数据时，请注意 `width` 和 `height` 参数可能发生变化，具体情况如下：

- 当网络状况恶化时，视频分辨率会逐步降低。
- 当用户调整视频配置时，回调中返回的视频分辨率也会随之变化。
:::

<a id="api_irtcengine_registervideoframeobserver__timing"></a>

### 调用时机 [#调用时机-2]

请在加入频道前调用此方法。

<a id="api_irtcengine_registervideoframeobserver__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="observer"></a>
<Parameter name="observer">

观察器实例。详见 [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver)。

:::note
注： 如需释放该实例，请将该参数设为 `null`。
:::

</Parameter>
</ParameterList>

<a id="api_irtcengine_registervideoframeobserver__return_values"></a>

### 返回值 [#返回值-5]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-5]

- [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine)

<a id="callback_ivideoframeobserver_oncapturevideoframe"></a>

<a id="ariaid-title8"></a>

## onCaptureVideoFrame [#oncapturevideoframe]

本地设备采集到视频帧时触发的回调。

<a id="callback_ivideoframeobserver_oncapturevideoframe__prototype"></a>

```java
@CalledByNative boolean onCaptureVideoFrame(int sourceType, VideoFrame videoFrame);
```

<a id="callback_ivideoframeobserver_oncapturevideoframe__detailed_desc"></a>

你可以通过该回调获取本地设备采集的原始视频数据，并根据需要进行预处理。预处理完成后，可以直接在该回调中修改 `videoFrame`，并将返回值设置为 true，以将修改后的视频数据发送给 SDK。如果需要将预处理后的视频数据发送给 SDK，需先调用 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 将视频处理模式设置为读写模式（`PROCESS_MODE_READ_WRITE`）。

:::note
注：

- 如果获取的视频数据类型为 RGBA，SDK 不支持处理 alpha 通道的数据。
- 建议确保 `videoFrame` 中修改后的参数与视频帧缓冲区中视频帧的实际情况一致。否则，可能会导致本地预览和远端视频显示出现异常旋转、拉伸等问题。
- 通过该回调获取的视频格式默认可能为 `I420Buffer` 或 `TextureBuffer`。`TextureBuffer` 的纹理格式可能为 `OES` 格式或 `RGB` 格式。如果你需要其他格式的视频数据，可以在 [getVideoFormatPreference](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoformatpreference) 回调的返回值中设置期望的数据格式。
:::

<a id="callback_ivideoframeobserver_oncapturevideoframe__timing"></a>

### 触发时机 [#触发时机]

该回调在成功注册视频数据观察器后，每次 SDK 采集到视频帧时被触发。

<a id="callback_ivideoframeobserver_oncapturevideoframe__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="sourcetype"></a>
<Parameter name="sourceType">

视频源类型，包括摄像头、屏幕或媒体播放器。详见 [VideoSourceType](/zh-CN/api-reference/rtc/android/enum-videosourcetype)。

</Parameter>
<a id="videoframe"></a>
<Parameter name="videoFrame">

视频帧。

:::note
注： 通过该回调获取的视频帧数据格式默认值如下：

- Android：I420 或 RGB（GLES20.GL_TEXTURE_2D）
:::

</Parameter>
</ParameterList>

<a id="callback_ivideoframeobserver_oncapturevideoframe__return_values"></a>

### 返回值 [#返回值-6]

- 当视频处理模式为 `PROCESS_MODE_READ_ONLY` 时：

  - true：保留以供后续使用。
  - false：保留以供后续使用。
- 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 时：

  - true：设置 SDK 接收该视频帧。
  - false：设置 SDK 丢弃该视频帧。

### 所属接口类 [#所属接口类-6]

- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver)

<a id="callback_ivideoframeobserver_onpreencodevideoframe"></a>

<a id="ariaid-title9"></a>

## onPreEncodeVideoFrame [#onpreencodevideoframe]

每次 SDK 接收到编码前视频帧时触发该回调。

<a id="callback_ivideoframeobserver_onpreencodevideoframe__prototype"></a>

```java
@CalledByNative boolean onPreEncodeVideoFrame(int sourceType, VideoFrame videoFrame);
```

<a id="callback_ivideoframeobserver_onpreencodevideoframe__detailed_desc"></a>

在你成功注册视频帧观察器后，SDK 每次接收到视频帧时都会触发该回调。在该回调中，你可以获取编码前的视频数据，并根据具体场景对数据进行处理。处理完成后，可以将处理后的视频数据返回给 SDK。

:::note
注：

- 如果你需要将预处理后的视频数据发送回 SDK，需要先调用 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 将视频处理模式设置为读写模式（`PROCESS_MODE_READ_WRITE`）。
- 若需获取从第二路屏幕采集的编码前视频数据，需要通过 [getObservedFramePosition](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getobservedframeposition) 设置帧位置为 `VIDEO_MODULE_POSITION_PRE_ENCODER`（1 &lt;&lt; 2）。
- 该回调获取的视频数据已被预处理，包括裁剪、旋转和美颜特效。
- 建议确保 `videoFrame` 中修改后的参数与视频帧缓冲区中视频帧的实际情况一致，否则可能导致本地预览和远端视频显示出现异常旋转、图像拉伸等问题。
:::

<a id="callback_ivideoframeobserver_onpreencodevideoframe__timing"></a>

### 触发时机 [#触发时机-1]

该回调在 SDK 每次接收到编码前的视频帧时被触发。

<a id="callback_ivideoframeobserver_onpreencodevideoframe__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="sourcetype-1"></a>
<Parameter name="sourceType">

视频源类型。详见 [VideoSourceType](/zh-CN/api-reference/rtc/android/enum-videosourcetype)。

</Parameter>
<a id="videoframe-1"></a>
<Parameter name="videoFrame">

视频帧。

:::note
注： 通过该回调获取的视频帧数据格式默认如下：

- Android：I420 或 RGB（GLES20.GL_TEXTURE_2D）。
:::

</Parameter>
</ParameterList>

<a id="callback_ivideoframeobserver_onpreencodevideoframe__return_values"></a>

### 返回值 [#返回值-7]

- 当视频处理模式为 `PROCESS_MODE_READ_ONLY` 时：

  - true：保留以供后续使用。
  - false：保留以供后续使用。
- 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 时：

  - true：SDK 接收该视频帧。
  - false：SDK 丢弃该视频帧。

### 所属接口类 [#所属接口类-7]

- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver)

<a id="callback_ivideoframeobserver_onrendervideoframe"></a>

<a id="ariaid-title10"></a>

## onRenderVideoFrame [#onrendervideoframe]

远端用户发送视频帧时触发的回调。

<a id="callback_ivideoframeobserver_onrendervideoframe__prototype"></a>

```java
boolean onRenderVideoFrame(String channelId, int uid, VideoFrame videoFrame)
```

<a id="callback_ivideoframeobserver_onrendervideoframe__detailed_desc"></a>

在你成功注册视频帧观察器后，SDK 每次接收到远端用户发送的视频帧时会触发该回调。你可以在渲染前获取远端发送的视频数据，并根据具体场景进行处理。通过该回调获取的视频帧默认格式可能为 `I420Buffer` 或 `TextureBuffer`，`TextureBuffer` 的纹理格式可能为 `OES` 或 `RGB`。如果你需要其他格式的视频数据，可以在 [getVideoFormatPreference](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoformatpreference) 回调中设置期望的数据格式。

:::note
注：

- 如果你需要将预处理后的视频数据发送回 SDK，需要先调用 [getVideoFrameProcessMode](/zh-CN/api-reference/rtc/android/video/video-raw#api_ivideoframeobserver_getvideoframeprocessmode) 将视频处理模式设置为读写模式（`PROCESS_MODE_READ_WRITE`）。
- 如果你获取的视频数据类型为 `RGBA`，SDK 不支持处理 alpha 通道的数据。
- 建议你确保 `videoFrame` 中修改后的参数与视频帧缓冲区中视频帧的实际情况一致。否则，可能会导致本地预览和远端视频显示出现异常旋转、图像拉伸等问题。
:::

<a id="callback_ivideoframeobserver_onrendervideoframe__timing"></a>

### 触发时机 [#触发时机-2]

该回调在 SDK 接收到远端用户发送的视频帧时被触发。

<a id="callback_ivideoframeobserver_onrendervideoframe__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="channelid"></a>
<Parameter name="channelId">

频道 ID。

</Parameter>
<a id="uid"></a>
<Parameter name="uid">

发送当前视频帧的远端用户 ID。

</Parameter>
<a id="videoframe-2"></a>
<Parameter name="videoFrame">

视频帧。

</Parameter>
</ParameterList>

<a id="callback_ivideoframeobserver_onrendervideoframe__return_values"></a>

### 返回值 [#返回值-8]

- 当视频处理模式为 `PROCESS_MODE_READ_ONLY` 时：

  - true：保留以供后续使用。
  - false：保留以供后续使用。
- 当视频处理模式为 `PROCESS_MODE_READ_WRITE` 时：

  - true：SDK 接收该视频帧。
  - false：SDK 丢弃该视频帧。

### 所属接口类 [#所属接口类-8]

- [IVideoFrameObserver](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_ivideoframeobserver)