# 视频渲染 (/zh-CN/api-reference/rtc/electron/video/video-rendering)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## destroyRendererByConfig [#destroyrendererbyconfig]
销毁多个视频渲染器对象。
```ts
abstract destroyRendererByConfig(sourceType: VideoSourceType, channelId?: string, uid?: number): void;
```
### 参数 [#参数]
视频源的类型,详见 [VideoSourceType](/zh-CN/api-reference/rtc/electron/enum-videosourcetype)。
远端用户 ID。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## destroyRendererByView [#destroyrendererbyview]
销毁单个视频渲染器对象。
```ts
abstract destroyRendererByView(view: any): void;
```
### 参数 [#参数-1]
需要销毁的 HTMLElement 对象。
### 所属接口类 [#所属接口类-1]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## enableInstantMediaRendering [#enableinstantmediarendering]
开启音视频帧加速渲染。
```ts
abstract enableInstantMediaRendering(): number;
```
成功调用该方法后,SDK 会开启加速出图和出声模式,可加快用户加入频道后的首帧出图与出声速度。
:::note
注: 主播端和观众端都需调用该方法开启音视频帧加速渲染才可体验该功能。
一旦成功调用该方法,只能通过调用 [release](/zh-CN/api-reference/rtc/electron/initialize#api_irtcengine_release) 方法销毁 [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine) 对象来取消加速渲染。
:::
### 适用场景 [#适用场景]
声网推荐在直播场景下,对观众开启该模式。
### 调用时机 [#调用时机]
该方法需要在加入频道前调用。
### 返回值 [#返回值]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -7: [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine) 尚未初始化就调用方法。
### 所属接口类 [#所属接口类-2]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setLocalRenderMode [#setlocalrendermode]
更新本地视图显示模式。
```ts
abstract setLocalRenderMode(
renderMode: RenderModeType,
mirrorMode?: VideoMirrorModeType
): number;
```
初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地视频的发布。
:::note
注: 该方法仅对第一个摄像头 `(PrimaryCameraSource)` 生效。在自定义视频采集或使用其他类型视频源的场景下,你需要使用 [setupLocalVideo](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_setuplocalvideo) 方法替代该方法。
:::
### 调用时机 [#调用时机-1]
- 请在调用 [setupLocalVideo](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_setuplocalvideo) 方法初始化本地视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。
### 参数 [#参数-2]
本地视图显示模式。详见 [RenderModeType](/zh-CN/api-reference/rtc/electron/enum-rendermodetype)。
本地视图的镜像模式,详见 [VideoMirrorModeType](/zh-CN/api-reference/rtc/electron/enum-videomirrormodetype)。
:::note
注: 如果你使用前置摄像头,默认启动本地用户视图镜像模式;如果你使用后置摄像头,默认关闭本地视图镜像模式。
:::
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setLocalRenderTargetFps [#setlocalrendertargetfps]
设置本地视频渲染的最大帧率。
```ts
abstract setLocalRenderTargetFps(
sourceType: VideoSourceType,
targetFps: number
): number;
```
### 适用场景 [#适用场景-1]
在对视频渲染帧率要求不高的场景(例如:屏幕共享、在线教育)下,你可以调用该方法设置本地视频渲染的最大帧率,SDK 进行本地渲染的实际帧率会尽量接近该值,从而减小 CPU 消耗、提升系统性能。
### 调用时机 [#调用时机-2]
该方法在加入频道前后均可调用。
### 参数 [#参数-3]
视频源的类型,详见 [VideoSourceType](/zh-CN/api-reference/rtc/electron/enum-videosourcetype)。
最大渲染帧率 (fps)。支持的参数值为:1、7、10、15、24、30、60。
:::note
注: 请将此参数设置为低于视频实际帧率的渲染帧率,否则设置将不会生效。
:::
### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setLocalVideoMirrorMode [#setlocalvideomirrormode]
设置本地视频镜像。
```ts
abstract setLocalVideoMirrorMode(mirrorMode: VideoMirrorModeType): number;
```
:::error[废弃]
弃用: 该方法已废弃。
:::
### 参数 [#参数-4]
本地视频镜像模式。详见 [VideoMirrorModeType](/zh-CN/api-reference/rtc/electron/enum-videomirrormodetype)。
### 返回值 [#返回值-3]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setRemoteRenderMode [#setremoterendermode]
更新远端视图显示模式。
```ts
abstract setRemoteRenderMode(
uid: number,
renderMode: RenderModeType,
mirrorMode: VideoMirrorModeType
): number;
```
初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。
:::note
注:
- 请在调用 [setupRemoteVideo](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_setupremotevideo) 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
:::
### 参数 [#参数-5]
远端用户 ID。
远端用户视图的渲染模式,详见 [RenderModeType](/zh-CN/api-reference/rtc/electron/enum-rendermodetype)。
远端用户视图的镜像模式,详见 [VideoMirrorModeType](/zh-CN/api-reference/rtc/electron/enum-videomirrormodetype)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setRemoteRenderModeEx [#setremoterendermodeex]
设置远端视图显示模式。
```ts
abstract setRemoteRenderModeEx(
uid: number,
renderMode: RenderModeType,
mirrorMode: VideoMirrorModeType,
connection: RtcConnection
): number;
```
初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。
### 参数 [#参数-6]
远端用户 ID。
远端视图显示模式,详见 [RenderModeType](/zh-CN/api-reference/rtc/electron/enum-rendermodetype)。
远端用户视图的镜像模式,详见 [VideoMirrorModeType](/zh-CN/api-reference/rtc/electron/enum-videomirrormodetype)。
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/electron/class-rtcconnection)。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengineex)
## setRemoteRenderTargetFps [#setremoterendertargetfps]
设置视频在远端渲染的最大帧率。
```ts
abstract setRemoteRenderTargetFps(targetFps: number): number;
```
### 适用场景 [#适用场景-2]
在对视频渲染帧率要求不高的场景(例如:屏幕共享、在线教育)或者远端使用中低端设备的场景下,你可以调用该方法设置视频在远端渲染的最大帧率,SDK 进行远端视频渲染的实际帧率会尽量接近该值,从而减小 CPU 消耗、提升系统性能。
### 调用时机 [#调用时机-3]
该方法在加入频道前后均可调用。
### 参数 [#参数-7]
最大渲染帧率 (fps)。支持的参数值为:1、7、10、15、24、30、60。
:::note
注: 请将此参数设置为低于视频实际帧率的渲染帧率,否则设置将不会生效。
:::
### 返回值 [#返回值-6]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setRenderMode [#setrendermode]
设置播放器视图的渲染模式。
```ts
abstract setRenderMode(renderMode: RenderModeType): number;
```
### 参数 [#参数-8]
播放器视图的渲染模式。详见 [RenderModeType](/zh-CN/api-reference/rtc/electron/enum-rendermodetype)。
### 返回值 [#返回值-7]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [IMediaPlayer](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_imediaplayer)
## setupLocalVideo [#setuplocalvideo]
初始化本地视图。
```ts
abstract setupLocalVideo(canvas: VideoCanvas): number;
```
该方法初始化本地视图并设置本地用户视频显示属性,只影响本地用户看到的视频画面,不影响本地视频的发布。调用该方法绑定本地视频流的显示视窗 (`view`),并设置本地用户视图的渲染模式和镜像模式。
退出频道后绑定仍然有效。如果需要停止渲染或解除绑定,可以调用该方法将参数 `view` 设为 null,以停止渲染并清理渲染缓存。
:::note
注:
- 在 Flutter 中你不需要主动调用该方法,请使用 `AgoraVideoView` 渲染本地和远端视图。
:::
### 适用场景 [#适用场景-3]
在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。
如果你需要在本地视频预览的画面中同时看到多个预览画面、且不同画面分别处于视频链路上不同观测点,可以重复调用该方法设置不同的 `view`,并针对每个 `view` 设置不同的观测位置。例如:将视频源设置为摄像头,然后对应两个 `view` 分别设置 `position` 为 PositionPostCapturerOrigin 和 PositionPostCapturer,即可在本地视频预览中同时看到没有经过视频前处理的原始画面和已经过视频前处理(美颜、虚拟背景、水印本地预览)的画面。
### 调用时机 [#调用时机-4]
该方法在加入频道前后均可调用。
### 参数 [#参数-9]
本地视频显示属性。详见 [VideoCanvas](/zh-CN/api-reference/rtc/electron/class-videocanvas)。
### 返回值 [#返回值-8]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-10]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setupRemoteVideo [#setupremotevideo]
初始化远端用户视图。
```ts
abstract setupRemoteVideo(canvas: VideoCanvas): number;
```
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要指定远端视频的用户 ID,一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID,可以在收到 [onUserJoined](/zh-CN/api-reference/rtc/electron/channel#callback_irtcengineeventhandler_onuserjoined) 回调时调用该方法。
如需解除某个远端用户的绑定视图,可以调用该方法并将 `view` 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
:::note
注:
- 当使用录制服务时,由于它不会发送视频流,App 无需为它绑定视图。如果 App 无法识别录制服务,可以在收到 [onFirstRemoteVideoDecoded](/zh-CN/api-reference/rtc/electron/video/video-basic#callback_irtcengineeventhandler_onfirstremotevideodecoded) 回调时再绑定远端用户视图。
- 如果想要停止渲染视图,需要将 `view` 设为 null 后再次调用该方法,以停止渲染并清理渲染缓存。
:::
### 参数 [#参数-10]
远端视频显示属性。详见 [VideoCanvas](/zh-CN/api-reference/rtc/electron/class-videocanvas)。
### 返回值 [#返回值-9]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-11]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## setupRemoteVideoEx [#setupremotevideoex]
初始化远端用户视图。
```ts
abstract setupRemoteVideoEx(
canvas: VideoCanvas,
connection: RtcConnection
): number;
```
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要在 [VideoCanvas](/zh-CN/api-reference/rtc/electron/class-videocanvas) 中指定远端视频的用户 ID,一般可以在进频道前提前设置好。
如果无法在加入频道前得到远端用户的 uid,可以在收到 [onUserJoined](/zh-CN/api-reference/rtc/electron/channel#callback_irtcengineeventhandler_onuserjoined) 回调时调用该方法。如果启用了视频录制功能,视频录制服务会做为一个哑客户端加入频道,因此其他客户端也会收到它的 [onUserJoined](/zh-CN/api-reference/rtc/electron/channel#callback_irtcengineeventhandler_onuserjoined) 事件, App 不应给它绑定视图(因为它不会发送视频流)。
如需解除某个远端用户的绑定视图,可以调用该方法并将 `view` 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
:::note
注:
- 该方法需要在 [joinChannelEx](/zh-CN/api-reference/rtc/electron/channel#api_irtcengineex_joinchannelex) 之后调用。
- 在 Flutter 中你不需要主动调用该方法,请使用 `AgoraVideoView` 渲染本地和远端视图。
- 如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 [setRemoteRenderModeEx](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengineex_setremoterendermodeex) 方法。
:::
### 参数 [#参数-11]
视频画布信息。详见 [VideoCanvas](/zh-CN/api-reference/rtc/electron/class-videocanvas)。
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/electron/class-rtcconnection)。
### 返回值 [#返回值-10]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-12]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengineex)
## startMediaRenderingTracing [#startmediarenderingtracing]
开启视频帧渲染数据打点。
```ts
abstract startMediaRenderingTracing(): number;
```
成功调用该方法后,SDK 会以调用该方法的时刻作为起点,并通过 [onVideoRenderingTracingResult](/zh-CN/api-reference/rtc/electron/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告视频帧渲染的相关信息。
:::note
注:
- 如果你未调用该方法,SDK 默认以调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道的时刻为起始点开始打点,自动开始跟踪视频的渲染事件。你可以根据实际业务场景,在合适的时机调用该方法,进行自定义打点。
- 离开当前频道后,SDK 会自动重置该时间点为下一次加入频道的时刻。
:::
### 适用场景 [#适用场景-4]
声网推荐你将该方法和 App 中的 UI 设置(按钮、滑动条等)结合使用,用于获取符合终端用户实际体验的首帧出图耗时的场景。例如:在终端用户在点击 加入频道 按钮的时刻调用该方法进行打点,然后通过 `onVideoRenderingTracingResult` 回调获取视频帧渲染过程中的各阶段耗时,从而针对各阶段耗时进行专项优化。
### 返回值 [#返回值-11]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -7: [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine) 尚未初始化就调用方法。
### 所属接口类 [#所属接口类-13]
- [IRtcEngine](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengine)
## startMediaRenderingTracingEx [#startmediarenderingtracingex]
开启视频帧渲染数据打点。
```ts
abstract startMediaRenderingTracingEx(connection: RtcConnection): number;
```
成功调用该方法后,SDK 会以调用该方法的时刻作为起点,并通过 [onVideoRenderingTracingResult](/zh-CN/api-reference/rtc/electron/video/video-rendering#callback_irtcengineeventhandler_onvideorenderingtracingresult) 回调报告视频帧渲染的相关信息。
:::note
注:
- 如果你未调用该方法,SDK 默认以调用 [joinChannel](/zh-CN/api-reference/rtc/electron/channel#api_irtcengine_joinchannel2) 加入频道的时刻为起始点开始打点,自动开始跟踪视频的渲染事件。你可以根据实际业务场景,在合适的时机调用该方法,进行自定义打点。
- 离开当前频道后,SDK 会自动重置该时间点为下一次加入频道的时刻。
:::
### 适用场景 [#适用场景-5]
声网推荐你将该方法和 App 中的 UI 设置(按钮、滑动条等)结合使用,用于获取符合终端用户实际体验的首帧出图耗时的场景。例如:在终端用户在点击 加入频道 按钮的时刻调用该方法进行打点,然后通过 `onVideoRenderingTracingResult` 回调获取视频帧渲染过程中的各阶段耗时,从而针对各阶段耗时进行专项优化。
### 参数 [#参数-12]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/electron/class-rtcconnection)。
### 返回值 [#返回值-12]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-14]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengineex)
## onVideoRenderingTracingResult [#onvideorenderingtracingresult]
视频帧渲染事件回调。
```ts
onVideoRenderingTracingResult?(
connection: RtcConnection,
uid: number,
currentEvent: MediaTraceEvent,
tracingInfo: VideoRenderingTracingInfo
): void;
```
调用 [startMediaRenderingTracing](/zh-CN/api-reference/rtc/electron/video/video-rendering#api_irtcengine_startmediarenderingtracing) 方法或加入频道后,SDK 会触发该回调,报告视频帧渲染的事件和渲染过程中的指标。开发者可以针对指标进行专项优化,以提高出图效率。
### 参数 [#参数-13]
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/electron/class-rtcconnection)。
用户 ID。
当前视频帧渲染事件。详见 [MediaTraceEvent](/zh-CN/api-reference/rtc/electron/enum-mediatraceevent)。
视频帧渲染过程中的指标。开发者需要尽可能降低指标值,以提高出图效率。详见 [VideoRenderingTracingInfo](/zh-CN/api-reference/rtc/electron/class-videorenderingtracinginfo)。
### 所属接口类 [#所属接口类-15]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/electron/rtc-interface-class#class_irtcengineeventhandler)