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

视频渲染

  • Electron

更新时间不可用

destroyRendererByConfig

销毁多个视频渲染器对象。

TypeScript
abstract destroyRendererByConfig(sourceType: VideoSourceType, channelId?: string, uid?: number): void;

参数

参数名描述
sourceType

视频源的类型，详见 VideoSourceType。

uid

远端用户 ID。

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

所属接口类

destroyRendererByView

销毁单个视频渲染器对象。

TypeScript
abstract destroyRendererByView(view: any): void;

参数

参数名描述
view

需要销毁的 HTMLElement 对象。

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

所属接口类

enableInstantMediaRendering

开启音视频帧加速渲染。

TypeScript
abstract enableInstantMediaRendering(): number;

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

注： 主播端和观众端都需调用该方法开启音视频帧加速渲染才可体验该功能。 一旦成功调用该方法，只能通过调用 release 方法销毁 IRtcEngine 对象来取消加速渲染。

适用场景

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

调用时机

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

返回值

  • 0: 方法调用成功。

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

    • -7: IRtcEngine 尚未初始化就调用方法。

所属接口类

setLocalRenderMode

更新本地视图显示模式。

TypeScript
abstract setLocalRenderMode(
    renderMode: RenderModeType,
    mirrorMode?: VideoMirrorModeType
  ): number;

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

注： 该方法仅对第一个摄像头 (PrimaryCameraSource) 生效。在自定义视频采集或使用其他类型视频源的场景下，你需要使用 setupLocalVideo 方法替代该方法。

调用时机

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

参数

参数名描述
renderMode

本地视图显示模式。详见 RenderModeType。

mirrorMode

本地视图的镜像模式，详见 VideoMirrorModeType。

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

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

返回值

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

所属接口类

setLocalRenderTargetFps

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

TypeScript
abstract setLocalRenderTargetFps(
    sourceType: VideoSourceType,
    targetFps: number
  ): number;

适用场景

在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）下，你可以调用该方法设置本地视频渲染的最大帧率，SDK 进行本地渲染的实际帧率会尽量接近该值，从而减小 CPU 消耗、提升系统性能。

调用时机

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

参数

参数名描述
sourceType

视频源的类型，详见 VideoSourceType。

targetFps

最大渲染帧率 (fps)。支持的参数值为：1、7、10、15、24、30、60。

注： 请将此参数设置为低于视频实际帧率的渲染帧率，否则设置将不会生效。

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

返回值

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

所属接口类

setLocalVideoMirrorMode

设置本地视频镜像。

TypeScript
abstract setLocalVideoMirrorMode(mirrorMode: VideoMirrorModeType): number;

废弃

弃用: 该方法已废弃。

参数

参数名描述
mirrorMode

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

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

返回值

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

所属接口类

setRemoteRenderMode

更新远端视图显示模式。

TypeScript
abstract setRemoteRenderMode(
    uid: number,
    renderMode: RenderModeType,
    mirrorMode: VideoMirrorModeType
  ): number;

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

注：

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

参数

参数名描述
uid

远端用户 ID。

renderMode

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

mirrorMode

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

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

返回值

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

所属接口类

setRemoteRenderModeEx

设置远端视图显示模式。

TypeScript
abstract setRemoteRenderModeEx(
    uid: number,
    renderMode: RenderModeType,
    mirrorMode: VideoMirrorModeType,
    connection: RtcConnection
  ): number;

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

参数

参数名描述
uid

远端用户 ID。

renderMode

远端视图显示模式，详见 RenderModeType。

mirrorMode

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

connection

Connection 信息。详见 RtcConnection。

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

返回值

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

所属接口类

setRemoteRenderTargetFps

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

TypeScript
abstract setRemoteRenderTargetFps(targetFps: number): number;

适用场景

在对视频渲染帧率要求不高的场景（例如：屏幕共享、在线教育）或者远端使用中低端设备的场景下，你可以调用该方法设置视频在远端渲染的最大帧率，SDK 进行远端视频渲染的实际帧率会尽量接近该值，从而减小 CPU 消耗、提升系统性能。

调用时机

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

参数

参数名描述
targetFps

最大渲染帧率 (fps)。支持的参数值为：1、7、10、15、24、30、60。

注： 请将此参数设置为低于视频实际帧率的渲染帧率，否则设置将不会生效。

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

返回值

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

所属接口类

setRenderMode

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

TypeScript
abstract setRenderMode(renderMode: RenderModeType): number;

参数

参数名描述
renderMode

播放器视图的渲染模式。详见 RenderModeType。

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

返回值

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

所属接口类

setupLocalVideo

初始化本地视图。

TypeScript
abstract setupLocalVideo(canvas: VideoCanvas): number;

该方法初始化本地视图并设置本地用户视频显示属性，只影响本地用户看到的视频画面，不影响本地视频的发布。调用该方法绑定本地视频流的显示视窗 (view)，并设置本地用户视图的渲染模式和镜像模式。 退出频道后绑定仍然有效。如果需要停止渲染或解除绑定，可以调用该方法将参数 view 设为 null，以停止渲染并清理渲染缓存。

注：

  • 在 Flutter 中你不需要主动调用该方法，请使用 AgoraVideoView 渲染本地和远端视图。

适用场景

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

调用时机

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

参数

参数名描述
canvas

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

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

返回值

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

所属接口类

setupRemoteVideo

初始化远端用户视图。

TypeScript
abstract setupRemoteVideo(canvas: VideoCanvas): number;

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。 调用该方法时需要指定远端视频的用户 ID，一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID，可以在收到 onUserJoined 回调时调用该方法。 如需解除某个远端用户的绑定视图，可以调用该方法并将 view 设置为空。 离开频道后，SDK 会清除远端用户视图的绑定关系。

注：

  • 当使用录制服务时，由于它不会发送视频流，App 无需为它绑定视图。如果 App 无法识别录制服务，可以在收到 onFirstRemoteVideoDecoded 回调时再绑定远端用户视图。
  • 如果想要停止渲染视图，需要将 view 设为 null 后再次调用该方法，以停止渲染并清理渲染缓存。

参数

参数名描述
canvas

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

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

返回值

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

所属接口类

setupRemoteVideoEx

初始化远端用户视图。

TypeScript
abstract setupRemoteVideoEx(
    canvas: VideoCanvas,
    connection: RtcConnection
  ): number;

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。 调用该方法时需要在 VideoCanvas 中指定远端视频的用户 ID，一般可以在进频道前提前设置好。 如果无法在加入频道前得到远端用户的 uid，可以在收到 onUserJoined 回调时调用该方法。如果启用了视频录制功能，视频录制服务会做为一个哑客户端加入频道，因此其他客户端也会收到它的 onUserJoined 事件， App 不应给它绑定视图（因为它不会发送视频流）。 如需解除某个远端用户的绑定视图，可以调用该方法并将 view 设置为空。 离开频道后，SDK 会清除远端用户视图的绑定关系。

注：

  • 该方法需要在 joinChannelEx 之后调用。
  • 在 Flutter 中你不需要主动调用该方法，请使用 AgoraVideoView 渲染本地和远端视图。
  • 如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 setRemoteRenderModeEx 方法。

参数

参数名描述
canvas

视频画布信息。详见 VideoCanvas。

connection

Connection 信息。详见 RtcConnection。

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

返回值

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

所属接口类

startMediaRenderingTracing

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

TypeScript
abstract startMediaRenderingTracing(): number;

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

注：

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

适用场景

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

返回值

  • 0: 方法调用成功。

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

    • -7: IRtcEngine 尚未初始化就调用方法。

所属接口类

startMediaRenderingTracingEx

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

TypeScript
abstract startMediaRenderingTracingEx(connection: RtcConnection): number;

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

注：

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

适用场景

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

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

返回值

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

所属接口类

onVideoRenderingTracingResult

视频帧渲染事件回调。

TypeScript
onVideoRenderingTracingResult?(
    connection: RtcConnection,
    uid: number,
    currentEvent: MediaTraceEvent,
    tracingInfo: VideoRenderingTracingInfo
  ): void;

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

uid

用户 ID。

currentEvent

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

tracingInfo

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

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利