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

视频渲染

  • Flutter

更新时间不可用

enableInstantMediaRendering

开启音视频帧加速渲染。

Dart
Future<void> enableInstantMediaRendering();

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

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

适用场景

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

调用时机

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setLocalRenderMode

更新本地视图显示模式。

Dart
Future<void> setLocalRenderMode(
    {required RenderModeType renderMode,
    VideoMirrorModeType mirrorMode =
        VideoMirrorModeType.videoMirrorModeAuto});

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

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

调用时机

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

参数

参数名描述
renderMode

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

mirrorMode

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

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setLocalRenderTargetFps

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

Dart
Future<void> setLocalRenderTargetFps(
      {required VideoSourceType sourceType, required int targetFps});

适用场景

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

调用时机

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

参数

参数名描述
sourceType

视频源的类型，详见 VideoSourceType。

targetFps

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

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setLocalVideoMirrorMode

设置本地视频镜像。

Dart
Future<void> setLocalVideoMirrorMode(VideoMirrorModeType mirrorMode);

废弃

弃用: 该方法已废弃。

参数

参数名描述
mirrorMode

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setRemoteRenderMode

更新远端视图显示模式。

Dart
Future<void> setRemoteRenderMode(
    {required int uid,
    required RenderModeType renderMode,
    required VideoMirrorModeType mirrorMode});

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

注：

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

参数

参数名描述
uid

远端用户 ID。

renderMode

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

mirrorMode

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

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

所属接口类

setRemoteRenderModeEx

设置远端视图显示模式。

Dart
Future<void> setRemoteRenderModeEx(
      {required int uid,
      required RenderModeType renderMode,
      required VideoMirrorModeType mirrorMode,
      required RtcConnection connection});

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

参数

参数名描述
uid

远端用户 ID。

renderMode

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

mirrorMode

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

connection

Connection 信息。详见 RtcConnection。

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

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

所属接口类

setRemoteRenderTargetFps

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

Dart
Future<void> setRemoteRenderTargetFps(int targetFps);

适用场景

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

调用时机

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

参数

参数名描述
targetFps

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

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setRenderMode

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

Dart
Future<void> setRenderMode(RenderModeType renderMode);

参数

参数名描述
renderMode

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

setupLocalVideo

初始化本地视图。

Dart
Future<void> setupLocalVideo(VideoCanvas canvas);

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

注：

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

适用场景

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

调用时机

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

参数

参数名描述
canvas

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

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

所属接口类

setupRemoteVideo

初始化远端用户视图。

Dart
Future<void> setupRemoteVideo(VideoCanvas canvas);

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。 调用该方法时需要指定远端视频的用户 ID，一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID，可以在收到 onUserJoined 回调时调用该方法。 如需解除某个远端用户的绑定视图，可以调用该方法并将 view 设置为空。 离开频道后，SDK 会清除远端用户视图的绑定关系。 在移动端自定义合图布局场景下，你可以调用该方法并针对合图视频流的每一路子视频流设置一个单独的 view 进行渲染。

注：

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

参数

参数名描述
canvas

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

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

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

所属接口类

setupRemoteVideoEx

初始化远端用户视图。

Dart
Future<void> setupRemoteVideoEx(
    {required VideoCanvas canvas, required RtcConnection connection});

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

注：

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

参数

参数名描述
canvas

视频画布信息。详见 VideoCanvas。

connection

Connection 信息。详见 RtcConnection。

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

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

所属接口类

startMediaRenderingTracing

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

Dart
Future<void> startMediaRenderingTracing();

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

注：

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

适用场景

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

startMediaRenderingTracingEx

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

Dart
Future<void> startMediaRenderingTracingEx(RtcConnection connection);

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

注：

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

适用场景

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

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

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

onTranscodedStreamLayoutInfo

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

Dart
final void Function(
    RtcConnection connection,
    int uid,
    int width,
    int height,
    int layoutCount,
    List<VideoLayout> layoutlist)? onTranscodedStreamLayoutInfo;

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

注： 该回调仅适用于 Android 和 iOS。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

uid

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

width

合图视频流的宽度 (px)。

height

合图视频流的高度 (px)。

layoutCount

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

layoutlist

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

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

所属接口类

onVideoRenderingTracingResult

视频帧渲染事件回调。

Dart
final void Function(
      RtcConnection connection,
      int uid,
      MediaTraceEvent currentEvent,
      VideoRenderingTracingInfo tracingInfo)? onVideoRenderingTracingResult;

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

uid

用户 ID。

currentEvent

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

tracingInfo

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

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利