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

视频渲染

  • Android

更新时间不可用

enableInstantMediaRendering

启用音视频帧的即时渲染。

Java
public abstract int enableInstantMediaRendering();

自从

自 v4.1.1 版本新增。

成功调用该方法后，SDK 会启用即时帧渲染模式，从而加快用户加入频道后首帧的渲染速度。

注： 主播和观众都需要调用该方法，才能体验音视频帧的即时渲染效果。一旦成功调用该方法，只能通过调用 destroy [2/2] 方法销毁 RtcEngine 对象来取消即时渲染。

适用场景

声网建议在直播场景中为观众开启该模式。

调用时机

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

返回值

  • 0：方法调用成功。

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

    • -7：在 RtcEngine 初始化之前调用该方法。

所属接口类

setLocalRenderMode [1/2]

设置本地视频的显示模式。

Java
public abstract int setLocalRenderMode(int renderMode)

废弃

该方法已废弃，不推荐使用。

你可以调用该方法设置本地视频的显示模式。在通话过程中可以多次调用以动态调整显示模式。

参数

参数名描述
renderMode

本地视频的显示模式：

  • RENDER_MODE_HIDDEN（1）：隐藏模式。按比例缩放视频，直到填满视图边界，可能会裁剪视频的一部分内容。
  • RENDER_MODE_FIT（2）：适应模式。按比例缩放视频，直到某一边适配视图边界，未填满的区域以黑色填充。
  • RENDER_MODE_ADAPTIVE（3）：自适应模式。该枚举值已废弃，不推荐使用。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setLocalRenderMode [2/2]

更新本地视频画面的显示模式。

Java
public abstract int setLocalRenderMode(int renderMode, int mirrorMode);

该方法仅影响本地用户看到的视频画面，不影响本地视频的发布。

调用时机

确保在调用此方法前已调用 setupLocalVideo 方法初始化本地视频画面。在通话过程中，你可以根据需要多次调用此方法更新本地视频画面的显示模式。

参数

参数名描述
renderMode

本地视频的显示模式：

  • RENDER_MODE_HIDDEN (1)：隐藏模式。按比例缩放视频，直到填满视图边界（可能被裁剪）。视频的一条边可能会被裁剪。
  • RENDER_MODE_FIT (2)：适应模式。按比例缩放视频，直到某一边适配视图边界。由于宽高比不一致而未填满的区域将以黑色填充。
  • RENDER_MODE_ADAPTIVE (3)：自适应模式（已废弃，不推荐使用）。
mirrorMode

注： 如果你使用前置摄像头，SDK 默认启用镜像模式；如果你使用后置摄像头，SDK 默认关闭镜像模式。

本地用户的视频镜像模式：

  • VIDEO_MIRROR_MODE_AUTO (0)：SDK 自动决定是否启用镜像模式。
  • VIDEO_MIRROR_MODE_ENABLED (1)：启用本地视图的镜像模式。
  • VIDEO_MIRROR_MODE_DISABLED (2)：关闭本地视图的镜像模式。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setLocalRenderTargetFps

设置本地视频渲染的最大帧率。

Java
public abstract int setLocalRenderTargetFps(Constants.VideoSourceType sourceType, int targetFps);

你可以在对视频渲染帧率要求不高的场景中调用该方法，例如屏幕共享或在线教育。SDK 会尝试将本地渲染的实际帧率保持在该值附近，从而降低 CPU 消耗并提升系统性能。

适用场景

在对视频渲染帧率要求不高的场景（如屏幕共享或在线教育）中，你可以调用该方法设置本地视频渲染的最大帧率。SDK 会尝试将本地渲染的实际帧率保持在该值附近，以降低 CPU 消耗并提升系统性能。

调用时机

你可以在加入频道前或后调用该方法。

参数

参数名描述
sourceType

视频源类型，详见 VideoSourceType。

targetFps

本地视频的采集帧率（fps）。支持的取值包括：1、7、10、15、24、30、60。

注： 该参数需设置为低于实际视频帧率的值，否则设置不生效。

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

返回值

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

所属接口类

setLocalVideoMirrorMode

设置本地视频镜像模式。

Java
public abstract int setLocalVideoMirrorMode(int mode)

废弃

该方法已废弃。

参数

参数名描述
mode

本地视频镜像模式：

  • VIDEO_MIRROR_MODE_AUTO (0)：由 SDK 决定是否启用镜像模式。如果使用前置摄像头，SDK 默认启用镜像模式；如果使用后置摄像头，SDK 默认关闭镜像模式。
  • VIDEO_MIRROR_MODE_ENABLED (1)：开启本地视图的镜像模式。
  • VIDEO_MIRROR_MODE_DISABLED (2)：关闭本地视图的镜像模式。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setRemoteRenderMode

更新远端用户视频视图的显示模式。

Java
public abstract int setRemoteRenderMode(int uid, int renderMode)

废弃

该方法已废弃。

你可以调用该方法更新远端用户视频视图的渲染模式和镜像模式。该方法仅影响本地用户看到的视频视图。

注：

  • 请确保在调用此方法前已调用 setupRemoteVideo 初始化远端视频视图。
  • 通话过程中，你可以多次调用此方法以更新远端用户视频视图的显示模式。

参数

参数名描述
uid

远端用户 ID。

renderMode

设置远端用户视频视图的显示模式：

  • RENDER_MODE_HIDDEN(1)：按比例缩放视频，直到填满视图边界（可能被裁剪）。视频的一部分内容可能会被截断。
  • RENDER_MODE_FIT(2)：按比例缩放视频，直到某一维度适配视图边界。由于宽高比不一致而未填满的区域将以黑色填充。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setRemoteRenderModeEx

设置指定远端用户的视频显示模式。

Java
public abstract int setRemoteRenderModeEx(int uid, int renderMode, int mirrorMode, RtcConnection connection);

请在调用 setupRemoteVideo 方法初始化远端视图后再调用此方法。通话过程中，你可以多次调用此方法以更新远端用户视频视图的显示模式。

适用场景

该方法适用于多频道场景。

参数

参数名描述
uid

远端用户 ID。

renderMode

远端用户的视频显示模式：

  • RENDER_MODE_HIDDEN (1)：隐藏模式。按比例缩放视频，直到填满视图边界（可能被裁剪）。视频的一部分内容可能被截断。
  • RENDER_MODE_FIT (2)：适应模式。按比例缩放视频，直到某一维度适配视图边界。由于宽高比不一致而未填满的区域将以黑色填充。
  • RENDER_MODE_ADAPTIVE (3)：自适应模式（已废弃，不推荐使用）。
mirrorMode

远端用户视图的镜像模式：

  • VIDEO_MIRROR_MODE_AUTO (0)：SDK 自动决定是否启用镜像模式。使用前置摄像头时默认启用镜像模式；使用后置摄像头时默认关闭镜像模式。
  • VIDEO_MIRROR_MODE_ENABLED (1)：启用本地视图的镜像模式。
  • VIDEO_MIRROR_MODE_DISABLED (2)：关闭本地视图的镜像模式。
connection

连接信息。详见 RtcConnection。

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

返回值

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

所属接口类

setRemoteRenderTargetFps

设置远端视频渲染的最大帧率。

Java
public abstract int setRemoteRenderTargetFps(int targetFps);

在对视频渲染帧率要求不高的场景（如屏幕共享、在线教育）或远端用户使用中低端设备时，可以调用该方法设置远端客户端的视频渲染最大帧率。SDK 会尽可能将实际渲染帧率控制在该值附近，从而降低 CPU 消耗并提升系统性能。

适用场景

在视频渲染帧率要求不高的场景（例如屏幕共享、在线教育）或远端用户使用中低端设备的情况下，你可以调用该方法设置远端客户端的视频渲染最大帧率。SDK 会尽可能将实际渲染帧率控制在该值附近，从而降低 CPU 消耗并提升系统性能。

调用时机

你可以在加入频道前或加入频道后调用该方法。

参数

参数名描述
targetFps

目标渲染帧率（fps）。支持的取值包括：1、7、10、15、24、30、60。

注： 将该参数设置为低于实际视频帧率的值，否则设置不生效。

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

返回值

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

所属接口类

setVideoRenderMode

设置媒体播放器的渲染模式。

Java
int setRenderMode(int mode);

参数

参数名描述
mode

设置视图的渲染模式：

  • RENDER_MODE_HIDDEN（1）：隐藏模式。按比例缩放视频，直到填满视图边界，可能会裁剪视频的一部分内容。
  • RENDER_MODE_FIT（2）：适应模式。按比例缩放视频，直到某一边适配视图边界。由于宽高比不一致，未填满的区域将以黑色填充。
  • RENDER_MODE_ADAPTIVE（3）：自适应模式。该枚举值已废弃，不推荐使用。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setupLocalVideo

初始化本地视频画面。

Java
public abstract int setupLocalVideo(VideoCanvas local);

你可以调用该方法将本地视频流绑定到视频画面（view），并设置画面的渲染模式和镜像模式。绑定关系在离开频道后仍然有效。如需停止渲染或解绑本地视频与画面，可将 view 设为 null。

在实时互动场景中，如果你需要在本地视频预览中同时查看多个预览画面，且每个画面位于视频链路的不同观察位置，可以多次调用该方法设置不同的 view，并为每个 view 设置不同的观察位置。例如，将视频源设置为摄像头后，配置两个 view，其 position 分别设置为 VIDEO_MODULE_POSITION_POST_CAPTURER_ORIGIN 和 VIDEO_MODULE_POSITION_POST_CAPTURER，即可在本地视频预览中同时查看原始未处理的视频帧和经过美颜特效、虚拟背景、水印等预处理后的视频帧。

注： 如需在通话过程中仅更新本地视频画面的渲染模式或镜像模式，请调用 setLocalRenderMode。

适用场景

初始化后调用该方法设置本地视频，然后加入频道。在实时互动场景中，如需在本地预览中同时查看多个不同观察位置的画面，可多次调用该方法设置不同的 view 和观察位置。

调用时机

你可以在加入频道前或后调用该方法。

参数

参数名描述
local

本地视频画面及相关设置。详见 VideoCanvas。

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

返回值

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

所属接口类

setupRemoteVideo

初始化远端视频视图。

Java
public abstract int setupRemoteVideo(VideoCanvas remote);

该方法在本地设备上初始化远端视频流的视图，仅影响本地用户看到的视频画面。调用该方法可将远端视频流绑定到视频视图，并设置该视图的渲染模式和镜像模式。你需要在该方法中指定远端用户的 ID。如果应用尚未获取远端用户的 ID，请在收到 onUserJoined 回调后设置。若要将远端用户与视图解绑，请将 view 参数设置为 null。一旦远端用户离开频道，SDK 会自动解绑该用户。在移动端进行视频合流布局自定义的场景中，你可以调用该方法，并为合流视频流中的每个子视频流设置独立的 view 进行渲染。

注：

  • 若需在通话过程中更新远端视频视图的渲染模式或镜像模式，请使用 setRemoteRenderMode 方法。
  • 使用录制服务时，应用无需绑定视图，因为录制服务不会发送视频流。如果你的应用无法识别录制服务，请在 SDK 触发 onFirstRemoteVideoDecoded 回调时将远端用户绑定到视图。

参数

参数名描述
remote

远端视频视图及相关设置。详见 VideoCanvas。

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

返回值

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

所属接口类

setupRemoteVideoEx

初始化远端用户的视频视图。

Java
public abstract int setupRemoteVideoEx(VideoCanvas remote, RtcConnection connection);

你可以调用该方法将远端视频流绑定到视频视图，并设置视频视图的渲染模式和镜像模式。该方法仅影响本地用户看到的视频视图。 应用需在远端用户加入频道前，通过 VideoCanvas 指定远端用户 ID。 如果应用尚未获取远端用户 ID，可在收到 onUserJoined 回调后设置。 如果启用了视频录制功能，视频录制服务会以虚拟客户端身份加入频道，其他客户端也会因此收到 onUserJoined 回调。请勿将虚拟客户端绑定到应用视图，因为其不会发送任何视频流。 如需解除远端用户与视图的绑定，可将 view 参数设为 null。 远端用户离开频道后，SDK 会自动解除其绑定。

注： 若需在通话过程中更新远端视频视图的渲染或镜像模式，请使用 setRemoteRenderModeEx 方法。

适用场景

该方法适用于多频道场景。

参数

参数名描述
remote

远端视频视图的设置。详见 VideoCanvas。

connection

连接信息。详见 RtcConnection。

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

返回值

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

所属接口类

startMediaRenderingTracing

启用视频帧渲染过程的追踪。

Java
public abstract int startMediaRenderingTracing();

自从

自 v4.1.1 版本新增。

从成功调用该方法开始，SDK 会追踪频道中视频帧的渲染状态，并通过 onVideoRenderingTracingResult 回调上报相关事件信息。

注：

  • 如果你未调用该方法，SDK 会从调用 joinChannel 加入频道开始追踪视频帧的渲染事件。
  • 本地用户离开当前频道后，SDK 会自动从再次加入频道开始追踪视频渲染事件。

适用场景

你可以结合应用中的 UI 设置（如按钮、滑块）调用该方法，以提升用户体验。例如，在用户点击“加入频道”按钮时调用该方法，然后通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程所耗费的时间，从而优化相关指标。

相关回调

该方法调用后会触发 onVideoRenderingTracingResult 回调。

返回值

  • 0：方法调用成功。

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

    • -7：在 RtcEngine 初始化之前调用该方法。

所属接口类

startMediaRenderingTracingEx

启用视频帧渲染过程的追踪。

Java
public abstract int startMediaRenderingTracingEx(RtcConnection connection);

自从

自 v4.1.1 版本新增。

从成功调用该方法开始，SDK 会追踪频道中视频帧的渲染状态，并通过 onVideoRenderingTracingResult 回调上报相关事件信息。

注：

  • 如果你未调用该方法，SDK 会从调用 joinChannel 加入频道开始追踪视频帧的渲染事件。你可以根据实际应用场景在合适的时间调用该方法，以设置追踪视频渲染事件的起始位置。
  • 本地用户离开当前频道后，SDK 会自动从再次加入频道开始追踪视频渲染事件。

适用场景

该方法适用于多频道场景。

相关回调

该方法调用后会触发 onVideoRenderingTracingResult 回调。

参数

参数名描述
connection

连接信息。详见 RtcConnection。

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

返回值

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

所属接口类

onTranscodedStreamLayoutInfo

接收到携带布局信息的合图视频流回调。

Java
public void onTranscodedStreamLayoutInfo(int uid, VideoLayoutInfo info) {}

当本地用户首次接收到由视频合图服务器发送的合图视频流，或该视频流的布局信息发生变化时，SDK 会触发该回调，报告该合图视频流中每个子视频流的布局信息。

触发时机

该回调在本地用户首次接收到合图视频流，或该视频流的布局信息发生变化时被触发。

参数

参数名描述
uid

发布该合图视频流的用户 ID。

info

子视频流的布局信息，详见 VideoLayoutInfo。

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

所属接口类

onVideoRenderingTracingResult

视频帧渲染事件回调。

Java
public void onVideoRenderingTracingResult(int uid, Constants.MEDIA_TRACE_EVENT currentEvent, VideoRenderingTracingInfo tracingInfo)

调用 startMediaRenderingTracing 方法或加入频道后，SDK 会触发该回调，报告视频帧渲染事件及渲染过程中的各项指标。你可以通过优化这些指标，提高首帧视频渲染的效率。

参数

参数名描述
uid

用户 ID。

currentEvent

当前的视频帧渲染事件，详见 MEDIA_TRACE_EVENT。

tracingInfo

视频帧渲染过程中的各项指标。详见 VideoRenderingTracingInfo。

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利