需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

自定义视频采集和渲染

  • Android

更新时间不可用

createCustomVideoTrack

创建一个自定义视频轨道。

Java
public abstract int createCustomVideoTrack();

调用该方法创建一个视频轨道，并获取视频轨道 ID。该 ID 可用于发布自定义视频源。要发布自定义视频源，请按照以下步骤操作：

  1. 调用该方法创建一个视频轨道，并获取视频轨道 ID。
  2. 调用 joinChannel 加入频道。在 ChannelMediaOptions 中，将 customVideoTrackId 设置为要发布的视频轨道 ID，并将 publishCustomVideoTrack 设置为 true。
  3. 调用 pushExternalVideoFrameById，并将 videoTrackId 设置为第 2 步中指定的视频轨道 ID，即可在频道中发布对应的自定义视频源。

返回值

  • 方法调用成功，返回视频轨道的唯一标识符，即视频轨道 ID。
  • 方法调用失败，返回 0xffffffff。

所属接口类

destroyCustomVideoTrack

销毁指定的视频轨道。

Java
public abstract int destroyCustomVideoTrack(int video_track_id);

参数

参数名描述
video_track_id

调用 createCustomVideoTrack 返回的视频轨道 ID。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

isTextureEncodeSupported

检查视频是否支持 Texture 编码。

Java
public abstract boolean isTextureEncodeSupported();

返回值

  • true：支持 Texture 编码。
  • false：不支持 Texture 编码。

所属接口类

pushExternalVideoFrameById [1/2]

通过视频轨道向 SDK 推送外部原始视频帧。

Java
public abstract int pushExternalVideoFrameById(VideoFrame frame, int videoTrackId);

在 Android 自采集场景中，声网推荐优先使用 io.agora.base.VideoFrame 配合 pushExternalVideoFrameById(VideoFrame frame, int videoTrackId) 推送视频帧。VideoFrame 支持通过统一的 Buffer 抽象封装 I420、NV21、NV12 和 Texture 等数据，适合新接入场景。 如果你只需向当前频道发布一路自采集视频，推荐在加入频道前调用 setExternalVideoSource 启用外部视频源，并在 ChannelMediaOptions 中将 publishCustomVideoTrack 设置为 true、将 customVideoTrackId 设置为 0。此场景下，SDK 会自动创建默认自定义视频轨道，你无需先调用 createCustomVideoTrack。 如果你需要发布多路自采集视频，或者需要在多个频道中分别发布不同的自采集视频流，请按照以下步骤操作：

  1. 调用 createCustomVideoTrack 创建视频轨道并获取视频轨道 ID。
  2. 调用 joinChannel 加入频道。在 ChannelMediaOptions 中，将 customVideoTrackId 设置为要发布的视频轨道 ID，并将 publishCustomVideoTrack 设置为 true。
  3. 调用 pushExternalVideoFrameById，并将 videoTrackId 设置为第 2 步中设置的视频轨道 ID，即可在频道中发布对应的自定义视频源。

如果你的现有采集模块已经基于 AgoraVideoFrame 封装，仍可继续调用 pushExternalVideoFrameById(AgoraVideoFrame frame, int videoTrackId)；但该重载不支持 Texture 数据，且可扩展能力弱于 VideoFrame。你可以通过调用 pushExternalVideoFrameById 或调用 pushExternalVideoFrameById（参数为 AgoraVideoFrame）推送视频帧。

注： 如果你只需向频道中推送一个自定义视频源，可以直接调用 setExternalVideoSource，SDK 会自动创建一个 videoTrackId 为 0 的视频轨道。 危险：调用本方法后，即使你停止向 SDK 推送外部视频帧，自定义视频流仍会计入视频时长并产生费用。声网建议你根据实际情况采取适当措施以避免此类视频计费：

参数

参数名描述
frame

要推送的视频帧。详见 VideoFrame。

videoTrackId

调用 createCustomVideoTrack 返回的视频轨道 ID。

注： 如果你只需推送一个自定义视频源，请将 videoTrackId 设置为 0。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

pushExternalVideoFrame [1/2]

将外部原始视频帧推送至 SDK。

Java
public abstract boolean pushExternalVideoFrame(VideoFrame frame)

废弃

该方法已废弃。

调用 setExternalVideoSource 方法并将 enabled 参数设置为 true，encodedFrame 参数设置为 false 后，可以使用该方法将外部原始视频帧推送至 SDK。你可以调用该方法或 pushExternalVideoFrame 推送视频帧。

注： 在 Android 自采集场景中，声网推荐优先使用 io.agora.base.VideoFrame 配合 pushExternalVideoFrameById(VideoFrame frame, int videoTrackId) 推送视频帧。VideoFrame 支持通过统一的 Buffer 抽象封装 I420、NV21、NV12 和 Texture 等数据，适合新接入场景；AgoraVideoFrame 更适合兼容现有基于字节数组的推帧实现。

参数

参数名描述
frame

要推送的视频帧。详见 VideoFrame。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • true：推送视频帧成功。
  • false：推送视频帧失败。

所属接口类

pushExternalVideoFrameById [2/2]

通过视频轨道向 SDK 推送外部原始视频帧。

Java
public abstract int pushExternalVideoFrameById(AgoraVideoFrame frame, int videoTrackId);

如果你的现有采集模块已经基于 AgoraVideoFrame 封装，可继续调用该重载推送视频帧。 如果你只需向当前频道发布一路自采集视频，推荐在加入频道前调用 setExternalVideoSource 启用外部视频源，并在 ChannelMediaOptions 中将 publishCustomVideoTrack 设置为 true、将 customVideoTrackId 设置为 0。此场景下，SDK 会自动创建默认自定义视频轨道，你无需先调用 createCustomVideoTrack。 如果你需要发布多路自采集视频，或者需要在多个频道中分别发布不同的自采集视频流，请按照以下步骤操作：

  1. 调用 createCustomVideoTrack 创建视频轨道并获取视频轨道 ID。
  2. 调用 joinChannel 加入频道。在 ChannelMediaOptions 中，将 customVideoTrackId 设置为要发布的视频轨道 ID，并将 publishCustomVideoTrack 设置为 true。
  3. 调用 pushExternalVideoFrameById，并将 videoTrackId 设置为步骤 2 中设置的视频轨道 ID，即可在频道中发布对应的自定义视频源。

AgoraVideoFrame 更适合兼容现有基于字节数组的推帧实现；如果你是新接入场景，声网更推荐使用 pushExternalVideoFrameById(VideoFrame frame, int videoTrackId) 重载，因为它支持 Texture 数据，且可通过统一的 Buffer 抽象封装更多格式。你可以通过调用 pushExternalVideoFrameById 或调用 pushExternalVideoFrame 推送视频帧。

注： 如果你只需向频道中推送一个自定义视频源，可以直接调用 setExternalVideoSource 方法，SDK 会自动创建一个 videoTrackId 为 0 的视频轨道。 警告：调用 pushExternalVideoFrameById 后，即使你停止向 SDK 推送外部视频帧，自定义视频流仍会被计入视频时长并产生费用。声网建议你根据实际情况采取适当措施以避免此类视频计费：

参数

参数名描述
frame

要推送的外部原始视频帧。详见 AgoraVideoFrame。

videoTrackId

调用 createCustomVideoTrack 返回的视频轨道 ID。

注： 如果你只需推送一个自定义视频源，请将 videoTrackId 设置为 0。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

pushExternalVideoFrame [2/2]

将外部原始视频帧推送至 SDK。

Java
public abstract boolean pushExternalVideoFrame(AgoraVideoFrame frame)

废弃

自 v4.5.0 版本废弃。

调用 setExternalVideoSource 方法并将 enabled 参数设置为 true，encodedFrame 参数设置为 false 后，可以使用 pushExternalVideoFrame 将外部原始视频帧推送至 SDK。你也可以调用 pushExternalVideoFrame 推送视频帧。

参数

参数名描述
frame

要推送的外部原始视频帧。详见 AgoraVideoFrame。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • true：推送成功。
  • false：推送失败。

所属接口类

setExternalRemoteEglContext

设置用于渲染远端视频流的 EGL 上下文。

Java
public abstract int setExternalRemoteEglContext(Object eglContext);

该方法用于替换 SDK 默认的远端 EGL 上下文，便于你自行管理 EGL 上下文。当引擎销毁时，SDK 会自动释放该上下文。

适用场景

该方法适用于使用自定义渲染方式（如 Texture 格式）替代 SDK 默认渲染方式渲染远端视频帧的场景。

调用时机

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

参数

参数名描述
eglContext

用于渲染远端视频流的 EGL 上下文。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setExternalVideoSource

配置外部视频源。

Java
public abstract int setExternalVideoSource(boolean enable, boolean useTexture, Constants.ExternalVideoSourceType sourceType);

调用该方法后，可以调用 pushExternalVideoFrameById 向 SDK 推送外部视频数据。

注： 频道内不支持动态切换视频源。若需从外部视频源切换为内部视频源，必须先离开频道，调用该方法关闭外部视频源，再重新加入频道。

调用时机

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

参数

参数名描述
enable

是否使用外部视频源：

  • true：使用外部视频源，SDK 会准备接收外部视频帧。
  • false：（默认）不使用外部视频源。
useTexture

是否使用 Texture 格式的外部视频帧：

  • true：使用 Texture 格式的外部视频帧。
  • false：（默认）不使用 Texture 格式的外部视频帧。
sourceType

外部视频帧是否为编码格式，详见 ExternalVideoSourceType。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利