视频渲染

enableInstantMediaRendering

开启音视频帧加速渲染。

Java

public abstract int enableInstantMediaRendering();

自从

v4.1.1

成功调用该方法后，SDK 会开启加速出图和出声模式，可加快用户加入频道后的首帧出图与出声速度。

适用场景

声网推荐在直播场景下，对观众开启该模式。

调用时机

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

调用限制

一旦成功调用该方法，只能通过调用 destroy 方法销毁 RtcEngine 对象来取消加速渲染。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -7: RtcEngine 尚未初始化就调用方法。

所属接口类

• RtcEngine

setLocalRenderMode [1/2]

设置本地视图显示模式。

Java

public abstract int setLocalRenderMode(int renderMode);

详情

废弃

该方法已废弃，请使用 setLocalRenderMode [2/2] 作为替代。

该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。

参数

renderMode

本地视图显示模式。

• RENDER_MODE_HIDDEN (1)：优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，多出的视频将被截掉。
• RENDER_MODE_FIT (2)：优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同，视窗上未被填满的区域将被涂黑。
• RENDER_MODE_ADAPTIVE (3)：匹配模式。
  废弃

  该枚举已废弃，不推荐使用。

返回值

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

所属接口类

• RtcEngine

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

本地视图的镜像模式。

• VIDEO_MIRROR_MODE_AUTO (0)：SDK 决定镜像模式。如果你使用前置摄像头，默认启动本地视图镜像模式；如果你启用后置摄像头，默认关闭本地视图镜像模式。
• VIDEO_MIRROR_MODE_ENABLED (1)：开启本地视图的镜像模式。
• VIDEO_MIRROR_MODE_DISABLED (2)：关闭本地视图的镜像模式。

注意

如果你使用前置摄像头，默认启动本地用户视图镜像模式；如果你使用后置摄像头，默认关闭本地视图镜像模式。

返回值

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

所属接口类

• RtcEngine

setLocalVideoMirrorMode

设置本地视频镜像。

Java

public abstract int setLocalVideoMirrorMode(int mode);

详情

废弃

该方法已废弃。

请改用 setupLocalVideo 或 setLocalRenderMode [2/2]。

参数

mode

• VIDEO_MIRROR_MODE_AUTO (0)：SDK 决定镜像模式。如果你使用前置摄像头，默认启动本地视图镜像模式；如果你启用后置摄像头，默认关闭本地视图镜像模式。
• VIDEO_MIRROR_MODE_ENABLED (1)：开启本地视图的镜像模式。
• VIDEO_MIRROR_MODE_DISABLED (2)：关闭本地视图的镜像模式。

返回值

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

所属接口类

• RtcEngine

setRemoteRenderMode

更新远端视图显示模式。

Java

public abstract int setRemoteRenderMode(int userId, int renderMode, int mirrorMode);

详情

初始化远端用户视图后，你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

注意

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

参数

userId

远端用户 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)：关闭本地视图的镜像模式。

返回值

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

所属接口类

• RtcEngine

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

Connection 信息。详见 RtcConnection。

返回值

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

所属接口类

• RtcEngineEx

setRenderMode

设置播放器视图的渲染模式。

Java

int setRenderMode(int mode);

参数

mode

播放器视图的渲染模式：

• RENDER_MODE_HIDDEN (1)：优先保证视窗被填满。视频尺寸等比缩放，直至整个视窗被视频填满。如果视频长宽与显示窗口不同，多出的视频将被截掉。
• RENDER_MODE_FIT (2)：优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同，视窗上未被填满的区域将被涂黑。
• RENDER_MODE_ADAPTIVE (3)：匹配模式。
  废弃

  该枚举已废弃，不推荐使用。

返回值

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

所属接口类

• IMediaPlayer

setupLocalVideo

初始化本地视图。

Java

public abstract int setupLocalVideo(VideoCanvas local);

该方法初始化本地视图并设置本地用户视频显示属性，只影响本地用户看到的视频画面，不影响本地视频的发布。调用该方法绑定本地视频流的显示视窗 (view)，并设置本地用户视图的渲染模式和镜像模式。

退出频道后绑定仍然有效。如果需要停止渲染或解除绑定，可以调用该方法将参数 view 设为 NULL，以停止渲染并清理渲染缓存。

注意

• 如果你希望在通话中仅更新本地用户视图的渲染或镜像模式，请使用 setLocalRenderMode [2/2] 方法。

适用场景

在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。

如果你需要在本地视频预览的画面中同时看到多个预览画面、且不同画面分别处于视频链路上不同观测点，可以重复调用该方法设置不同的 view，并针对每个 view 设置不同的观测位置。例如：将视频源设置为摄像头，然后对应两个 view 分别设置 position 为 VIDEO_MODULE_POSITION_POST_CAPTURER_ORIGIN 和 VIDEO_MODULE_POSITION_POST_CAPTURER，即可在本地视频预览中同时看到没有经过视频前处理的原始画面和已经过视频前处理（美颜、虚拟背景、水印本地预览）的画面。

调用时机

该方法在加入频道前后均可调用。

调用限制

无。

参数

local

本地视频显示属性。详见 VideoCanvas。

返回值

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

所属接口类

• RtcEngine

setupRemoteVideo

初始化远端用户视图。

Java

public abstract int setupRemoteVideo(VideoCanvas remote);

详情

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。

调用该方法时需要指定远端视频的用户 ID，一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID，可以在收到 onUserJoined 回调时调用该方法。

如需解除某个远端用户的绑定视图，可以调用该方法并将 view 设置为空。

离开频道后，SDK 会清除远端用户视图的绑定关系。

在移动端自定义合图布局场景下，你可以调用该方法并针对合图视频流的每一路子视频流设置一个单独的 view 进行渲染。

注意

• 如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 setRemoteRenderMode 方法。
• 当使用录制服务时，由于它不会发送视频流，App 无需为它绑定视图。如果 App 无法识别录制服务，可以在收到 onFirstRemoteVideoDecoded 回调时再绑定远端用户视图。

参数

remote

远端视频显示属性。详见 VideoCanvas。

返回值

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

所属接口类

• RtcEngine

setupRemoteVideoEx

初始化远端用户视图。

Java

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

详情

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。

调用该方法时需要在 VideoCanvas 中指定远端视频的用户 ID，一般可以在进频道前提前设置好。

如果无法在加入频道前得到远端用户的 uid，可以在收到 onUserJoined 回调时调用该方法。如果启用了视频录制功能，视频录制服务会做为一个哑客户端加入频道，因此其他客户端也会收到它的 onUserJoined 事件， App 不应给它绑定视图（因为它不会发送视频流）。

如需解除某个远端用户的绑定视图，可以调用该方法并将 view 设置为空。

离开频道后，SDK 会清除远端用户视图的绑定关系。

注意

• 如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 setRemoteRenderModeEx 方法。

参数

remote

视频画布信息。详见 VideoCanvas。

connection

Connection 信息。详见 RtcConnection。

返回值

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

所属接口类

• RtcEngineEx

startMediaRenderingTracing

开启视频帧渲染数据打点。

Java

public abstract int startMediaRenderingTracing();

详情

自从

v4.1.1

成功调用该方法后，SDK 会以调用该方法的时刻作为起点，并通过 onVideoRenderingTracingResult 回调报告视频帧渲染的相关信息。

信息

• SDK 默认在成功加入频道的时刻起打点，自动开始跟踪视频频的渲染事件。你可以根据实际业务场景，在合适的时机调用该方法，进行自定义打点。
• 离开当前频道后，SDK 会自动重置该时间点为下一次成功加入频道的时刻。

适用场景

声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用，用于针对终端用户的体验改进。例如：在终端用户在点击 加入频道 按钮的时刻调用该方法进行打点，然后通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程中的指标，从而针对指标进行专项优化。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -7: RtcEngine 尚未初始化就调用方法。

所属接口类

• RtcEngine

startMediaRenderingTracingEx

开启视频帧渲染数据打点。

Java

public abstract int startMediaRenderingTracingEx(RtcConnection connection);

详情

自从

v4.1.1

成功调用该方法后，SDK 会以调用该方法的时刻作为起点，并通过 onVideoRenderingTracingResult 回调报告视频帧渲染的相关信息。

信息

• SDK 默认在成功加入频道的时刻起打点，自动开始跟踪视频频的渲染事件。你可以根据实际业务场景，在合适的时机调用该方法，进行自定义打点。
• 离开当前频道后，SDK 会自动重置该时间点为下一次成功加入频道的时刻。

适用场景

声网推荐你将该方法和 App 中的 UI 设置（按钮、滑动条等）结合使用，用于针对终端用户的体验改进。例如：在终端用户在点击 加入频道 按钮的时刻调用该方法进行打点，然后通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程中的指标，从而针对指标进行专项优化。

参数

connection

Connection 信息。详见 RtcConnection。

返回值

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

所属接口类

• RtcEngineEx

onTranscodedStreamLayoutInfo

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

Java

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

详情

自从

v4.3.0

当本地第一次接收到合图服务器发送的合图视频流，或者合图流的布局信息有变化时，SDK 会触发该回调，报告合图视频流中每一路子视频流的布局信息。

参数

uid

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

info

某一路合图视频流的详细布局信息。详见 VideoLayout。

所属接口类

• IRtcEngineEventHandler

onVideoRenderingTracingResult

视频帧渲染事件回调。

Java

public void onVideoRenderingTracingResult(int uid,
    Constants.MEDIA_RENDER_TRACE_EVENT currentEvent, VideoRenderingTracingInfo tracingInfo) {}

详情

自从

v4.1.1

调用 startMediaRenderingTracing 方法或加入频道后，SDK 会触发该回调，报告视频帧渲染的事件和渲染过程中的指标。开发者可以针对指标进行专项优化，以提高出图效率。

参数

uid

用户 ID。

currentEvent

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

tracingInfo

视频帧渲染过程中的指标。开发者需要尽可能降低指标值，以提高出图效率。详见 VideoRenderingTracingInfo。

所属接口类

• IRtcEngineEventHandler