视频渲染

enableInstantMediaRendering

启用音视频帧的极速渲染。

C++

virtual int enableInstantMediaRendering() = 0;

自从

自 v4.1.1 版本新增。

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

信息

主播和观众都需要调用该方法，才能体验音视频帧的极速渲染。如需关闭该模式，只能通过调用 release 销毁 IRtcEngine 对象。

适用场景

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

调用时机

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -7：在 IRtcEngine 初始化之前调用了该方法。

所属接口类

• IRtcEngine

setLocalRenderMode [1/2]

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

C++

virtual int setLocalRenderMode(media::base::RENDER_MODE_TYPE renderMode) __deprecated = 0;

废弃

自 v4.0.0 版本废弃，请改用 setLocalRenderMode [2/2]。

你可以在初始化本地视频画面后调用该方法，更新其渲染模式和镜像模式。该方法仅影响本地用户看到的视频画面，不影响发布的视频流。

信息

• 请确保在调用该方法前已调用 setupLocalVideo 初始化本地视频画面。
• 通话过程中，你可以多次调用该方法以更新本地视频画面。

参数

renderMode

本地画面的显示模式。详见 RENDER_MODE_TYPE。

返回值

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

所属接口类

• IRtcEngine

setLocalRenderMode [2/2]

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

C++

virtual int setLocalRenderMode(media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0;

你可以在初始化本地视频画面后调用该方法，更新其渲染模式和镜像模式。该方法仅影响本地用户看到的视频画面，不影响本地视频的发布。

信息

setLocalRenderMode 仅对主摄像头（PRIMARY_CAMERA_SOURCE）生效。在使用自定义视频采集或其他视频源的场景中，请使用 setupLocalVideo 代替。

调用时机

• 请确保在调用该方法前已调用 setupLocalVideo 初始化本地视频画面。
• 通话过程中，可多次调用该方法更新本地视频画面的显示模式。

参数

renderMode

本地视频画面的显示模式。详见 RENDER_MODE_TYPE。

mirrorMode

本地视频画面的镜像模式。详见 VIDEO_MIRROR_MODE_TYPE。

信息

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

返回值

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

所属接口类

• IRtcEngine

setLocalRenderTargetFps

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

C++

virtual int setLocalRenderTargetFps(VIDEO_SOURCE_TYPE sourceType, int targetFps) = 0;

适用场景

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

调用时机

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

参数

sourceType

视频源类型，详见 VIDEO_SOURCE_TYPE。

targetFps

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

信息

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

返回值

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

所属接口类

• IRtcEngine

setLocalVideoMirrorMode

设置本地视频镜像模式。

C++

virtual int setLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode) __deprecated = 0;

废弃

该方法已废弃，请改用 setupLocalVideo 或 setLocalRenderMode。

参数

mirrorMode

本地视频镜像模式。详见 VIDEO_MIRROR_MODE_TYPE。

返回值

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

所属接口类

• IRtcEngine

setRemoteRenderMode

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

C++

virtual int setRemoteRenderMode(uid_t uid, media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode) = 0;

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

信息

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

参数

uid

远端用户 ID。

renderMode

远端用户视图的渲染模式，详见 RENDER_MODE_TYPE。

mirrorMode

远端用户视图的镜像模式，详见 VIDEO_MIRROR_MODE_TYPE。

返回值

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

所属接口类

• IRtcEngine

setRemoteRenderModeEx

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

C++

virtual int setRemoteRenderModeEx(uid_t uid, media::base::RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode, const RtcConnection& connection) = 0;

调用 setupRemoteVideo 初始化远端用户的视频视图后，可以调用该方法更新其渲染模式和镜像模式。该方法仅影响本地用户看到的视频视图。

信息

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

适用场景

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

参数

uid

远端用户的用户 ID。

renderMode

视频显示模式，详见 RENDER_MODE_TYPE。

mirrorMode

镜像模式，详见 VIDEO_MIRROR_MODE_TYPE。

connection

连接信息，详见 RtcConnection。

返回值

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

所属接口类

• IRtcEngineEx

setRemoteRenderTargetFps

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

C++

virtual int setRemoteRenderTargetFps(int targetFps) = 0;

适用场景

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

调用时机

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

参数

targetFps

远端视频的渲染最大帧率（fps）。支持的取值包括：1、7、10、15、24、30、60。

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

返回值

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

所属接口类

• IRtcEngine

setRenderMode

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

C++

virtual int setRenderMode(media::base::RENDER_MODE_TYPE renderMode) = 0;

参数

renderMode

渲染模式，详见 RENDER_MODE_TYPE。

返回值

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

所属接口类

• IMediaPlayer

setupLocalVideo

初始化本地视频画面。

C++

virtual int setupLocalVideo(const VideoCanvas& canvas) = 0;

该方法在本地设备上初始化本地视频流的画面视图，仅影响本地用户看到的视频画面，不影响本地视频的发布。你可以调用该方法将本地视频流绑定到指定的视频视图（view），并设置该视图的渲染模式和镜像模式。 绑定关系在离开频道后仍然有效。若需停止渲染或解绑本地视频与视图的绑定关系，可将 view 设置为 NULL。 在实时互动场景中，如果你需要在本地视频预览中同时查看多个不同观察位置的画面，可以多次调用该方法，为每个 view 设置不同的观察位置。例如，将视频源设置为摄像头后，配置两个 view，其 position 分别设置为 POSITION_POST_CAPTURER_ORIGIN 和 POSITION_POST_CAPTURER，即可同时预览原始未处理的视频帧和经过美颜特效、虚拟背景、水印等预处理后的视频帧。

信息

若仅需在通话中更新本地视频视图的渲染模式或镜像模式，请改用 setLocalRenderMode。

适用场景

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

调用时机

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

参数

canvas

本地视频视图及相关设置，详见 VideoCanvas。

返回值

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

所属接口类

• IRtcEngine

setupRemoteVideo

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

C++

virtual int setupRemoteVideo(const VideoCanvas& canvas) = 0;

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

信息

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

参数

canvas

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

返回值

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

所属接口类

• IRtcEngine

setupRemoteVideoEx

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

C++

virtual int setupRemoteVideoEx(const VideoCanvas& canvas, const RtcConnection& connection) = 0;

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

信息

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

适用场景

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

参数

canvas

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

connection

连接信息。详见 RtcConnection。

返回值

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

所属接口类

• IRtcEngineEx

startMediaRenderingTracing

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

C++

virtual int startMediaRenderingTracing() = 0;

自从

自 v4.1.1 版本新增。

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

信息

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

适用场景

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

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -7：在初始化 IRtcEngine 之前调用了该方法。

所属接口类

• IRtcEngine

startMediaRenderingTracingEx

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

C++

virtual int startMediaRenderingTracingEx(const RtcConnection& connection) = 0;

自从

自 v4.1.1 版本新增。

调用该方法后，SDK 会从调用时刻开始追踪频道中视频帧的渲染状态，并通过 onVideoRenderingTracingResult 回调报告相关信息。你可以结合应用中的 UI 控件（如按钮、滑块）调用该方法，以优化用户体验，例如在用户点击“加入频道”按钮时调用该方法，并通过 onVideoRenderingTracingResult 回调获取视频帧渲染过程所耗时间，从而优化相关指标。

信息

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

适用场景

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

参数

connection

连接信息。详见 RtcConnection。

返回值

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

所属接口类

• IRtcEngineEx

onTranscodedStreamLayoutInfo

`本地用户接收到携带视频合图布局信息的合图视频时触发。

C++

virtual void onTranscodedStreamLayoutInfo(uid_t uid, int width, int height, int layoutCount,const VideoLayout* layoutlist)

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

信息

该回调仅适用于 Android 和 iOS 平台。

触发时机

当本地用户首次接收到视频合流服务器发送的合图视频，或混合流的布局信息发生变化时触发。

参数

uid

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

width

合图视频的宽度（单位为像素）。

height

合图视频的高度（单位为像素）。

layoutCount

合图视频中包含的布局信息数量。

layoutlist

子视频流的布局信息数组。详见 VideoLayout。

所属接口类

• IRtcEngineEventHandler

onVideoRenderingTracingResult

视频帧渲染事件回调。

C++

virtual void onVideoRenderingTracingResult(uid_t uid, MEDIA_TRACE_EVENT currentEvent, VideoRenderingTracingInfo tracingInfo)

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

触发时机

调用 startMediaRenderingTracing 方法或加入频道后触发。

参数

uid

用户 ID。

currentEvent

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

tracingInfo

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

所属接口类

• IRtcEngineEventHandler