原始视频数据

getMirrorApplied

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

Java

@CalledByNative boolean getMirrorApplied();

如果你希望获取的视频数据是原始视频的镜像图像，需要在调用 registerVideoFrameObserver 时注册该回调。成功注册视频帧观察器后，SDK 每次接收到视频帧时都会触发该回调。你需要在该回调的返回值中设置是否对视频帧进行镜像。

信息

• 在 Android 平台，该回调支持的视频数据格式包括：I420、RGBA 和 Texture。
• 该方法与 setVideoEncoderConfiguration 都支持设置镜像效果。建议你仅使用其中一种方式进行设置，同时使用两种方式会导致镜像效果叠加，从而使设置失效。

调用时机

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

返回值

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

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

所属接口类

• IVideoFrameObserver

getObservedFramePosition

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

Java

@CalledByNative int getObservedFramePosition();

在成功注册视频数据观察器后，SDK 会通过该回调判断是否在特定的视频帧处理位置触发 onCaptureVideoFrame、onRenderVideoFrame 和 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 回调。

返回值

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

• VIDEO_MODULE_POSITION_POST_CAPTURER (1 << 0)：视频采集后的位置。
• VIDEO_MODULE_POSITION_PRE_RENDERER (1 << 1)：远端视频渲染前的位置。
• VIDEO_MODULE_POSITION_PRE_ENCODER (1 << 2)：编码前的位置。

所属接口类

• IVideoFrameObserver

getRotationApplied

getRotationApplied 回调在每次 SDK 接收到视频帧时触发，用于设置是否旋转采集的视频。

Java

@CalledByNative boolean getRotationApplied();

如果你希望根据 VideoFrame 中的 rotation 成员旋转采集的视频，需要在调用 registerVideoFrameObserver 时注册该回调。注册成功后，SDK 每次接收到视频帧时会触发该回调。你需要通过该回调的返回值设置是否旋转视频帧。

信息

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

调用时机

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

返回值

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

所属接口类

• IVideoFrameObserver

getVideoFormatPreference

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

Java

@CalledByNative int getVideoFormatPreference();

调用 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。
• 已集成图像增强扩展并启用了视频降噪或弱光增强功能。

返回值

方法调用成功，返回 SDK 输出的原始数据格式：

• VIDEO_PIXEL_DEFAULT（0）：原始视频格式，需适配 I420Buffer 或 TextureBuffer。
• VIDEO_PIXEL_I420（1）：I420 格式。
• VIDEO_PIXEL_RGBA（4）：RGBA 格式。
• VIDEO_PIXEL_I422（16）：I422 格式。

所属接口类

• IVideoFrameObserver

getVideoFrameProcessMode

getVideoFrameProcessMode 回调。每次 SDK 接收到视频帧时触发，并提示你设置视频帧的处理模式。

Java

@CalledByNative int getVideoFrameProcessMode();

在成功注册视频帧观察器后，SDK 每次接收到视频帧时会触发 getVideoFrameProcessMode 回调。你需要在该回调的返回值中设置偏好的处理模式。

返回值

视频帧的处理模式：

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

所属接口类

• IVideoFrameObserver

registerVideoFrameObserver

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

Java

public abstract int registerVideoFrameObserver(IVideoFrameObserver observer);

建议通过该方法注册一个 IVideoFrameObserver 实例，并在该类中根据需要实现回调。成功注册后，每当接收到视频帧时，SDK 会触发相应的回调。你可以在虚拟背景、图像增强等视频预处理场景中使用这些原始视频数据。

信息

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

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

调用时机

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

参数

observer

观察器实例。详见 IVideoFrameObserver。

信息

如需释放该实例，请将该参数设为 null。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

onCaptureVideoFrame

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

Java

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

你可以通过该回调获取本地设备采集的原始视频数据，并根据需要进行预处理。预处理完成后，可以直接在该回调中修改 videoFrame，并将返回值设置为 true，以将修改后的视频数据发送给 SDK。如果需要将预处理后的视频数据发送给 SDK，需先调用 getVideoFrameProcessMode 将视频处理模式设置为读写模式（PROCESS_MODE_READ_WRITE）。

信息

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

触发时机

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

参数

sourceType

视频源类型，包括摄像头、屏幕或媒体播放器。详见 VideoSourceType。

videoFrame

视频帧。

信息

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

• Android：I420 或 RGB（GLES20.GL_TEXTURE_2D）

返回值

• 当视频处理模式为 PROCESS_MODE_READ_ONLY 时：
  • true：保留以供后续使用。
  • false：保留以供后续使用。
• 当视频处理模式为 PROCESS_MODE_READ_WRITE 时：
  • true：设置 SDK 接收该视频帧。
  • false：设置 SDK 丢弃该视频帧。

所属接口类

• 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 中修改后的参数与视频帧缓冲区中视频帧的实际情况一致，否则可能导致本地预览和远端视频显示出现异常旋转、图像拉伸等问题。

触发时机

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

参数

sourceType

视频源类型。详见 VideoSourceType。

videoFrame

视频帧。

信息

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

• Android：I420 或 RGB（GLES20.GL_TEXTURE_2D）。

返回值

• 当视频处理模式为 PROCESS_MODE_READ_ONLY 时：
  • true：保留以供后续使用。
  • false：保留以供后续使用。
• 当视频处理模式为 PROCESS_MODE_READ_WRITE 时：
  • true：SDK 接收该视频帧。
  • false：SDK 丢弃该视频帧。

所属接口类

• IVideoFrameObserver

onRenderVideoFrame

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

Java

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

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

信息

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

触发时机

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

参数

channelId

频道 ID。

uid

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

videoFrame

视频帧。

返回值

• 当视频处理模式为 PROCESS_MODE_READ_ONLY 时：
  • true：保留以供后续使用。
  • false：保留以供后续使用。
• 当视频处理模式为 PROCESS_MODE_READ_WRITE 时：
  • true：SDK 接收该视频帧。
  • false：SDK 丢弃该视频帧。

所属接口类

• IVideoFrameObserver