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

视频基础功能

  • Flutter

更新时间不可用

disableVideo

关闭视频模块。

Dart
Future<void> disableVideo();

该方法用于关闭视频模块。

注：

  • 该方法设置的是内部引擎为禁用状态，在离开频道后仍然有效。

  • 调用该方法会重置整个引擎，响应时间较慢。你可以根据实际需求用以下方法来独立控制视频模块的某一项功能：

调用时机

加入频道前后均可调用：

  • 如果在加入频道前调用，则开启纯音频模式。
  • 如果在加入频道后调用，则由视频模式切换为纯音频模式，然后再调用 enableVideo 方法可开启视频模式。

相关回调

成功调用该方法后，远端会触发 onUserEnableVideo (false) 回调。

返回值

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

所属接口类

enableLocalVideo

开关本地视频采集。

Dart
Future<void> enableLocalVideo(bool enabled);

该方法禁用或重新启用本地视频采集，不影响接收远端视频。 调用 enableVideo 后，本地视频采集即默认开启。 如果你在频道内调用 enableLocalVideo(false) 关闭本地视频采集，也会同时停止在频道内发布视频流。如果想要重新开启，则可调用 enableLocalVideo(true)，然后调用 updateChannelMediaOptions 并设置 options 参数，将本地采集的视频流发布到频道中。 成功禁用或启用本地视频采集后，远端会触发 onRemoteVideoStateChanged 回调。

注：

  • 该方法在加入频道前后均可调用，但加入频道前调用的设置，在加入频道后才会生效。
  • 该方法设置内部引擎为启用状态，在离开频道后仍然有效。

参数

参数名描述
enabled

是否开启本地视频采集。

  • true:（默认）开启本地视频采集。
  • false: 关闭本地视频采集。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

enableVideo

启用视频模块。

Dart
Future<void> enableVideo();

视频模块默认为关闭状态，需要调用该方法启用。如果后续需要关闭视频模块，需调用 disableVideo 方法。

注：

调用时机

该方法可以在加入频道前或者频道内调用：

  • 如果在加入频道前调用，则开启视频模块。
  • 如果在纯音频通话中调用，则音频通话将自动切换为视频通话。

相关回调

成功调用该方法后，远端会触发 onRemoteVideoStateChanged 回调。

返回值

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

所属接口类

setVideoEncoderConfiguration

设置视频编码属性。

Dart
Future<void> setVideoEncoderConfiguration(VideoEncoderConfiguration config);

设置本地视频的编码属性。每一种视频编码属性对应一系列视频相关参数设置，包含分辨率、帧率和码率。

注：

  • 该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好，视频引擎便不能使用该 config 渲染本地视频，它会自动降低到一个合适的视频参数设置。

调用时机

该方法在加入频道前后都能调用。如果用户在加入频道后不需要重新设置视频编码属性，则建议在 enableVideo 前调用该方法，可以加快首帧出图的时间。

参数

参数名描述
config

视频编码参数配置。详见 VideoEncoderConfiguration。

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

返回值

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

所属接口类

setVideoEncoderConfigurationEx

设置视频编码属性。

Dart
Future<void> setVideoEncoderConfigurationEx(
      {required VideoEncoderConfiguration config,
      required RtcConnection connection});

设置本地视频的编码属性。每一种视频编码属性对应一系列视频相关参数设置，包含分辨率、帧率和码率。

注： 该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好，视频引擎便不能使用该 config 渲染本地视频，它会自动降低到一个合适的视频参数设置。

调用时机

该方法需要在 joinChannelEx 之后调用。

参数

参数名描述
config

视频编码参数配置。详见 VideoEncoderConfiguration。

connection

Connection 信息。详见 RtcConnection。

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

返回值

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

所属接口类

setVideoScenario

设置视频业务场景。

Dart
Future<void> setVideoScenario(VideoApplicationScenarioType scenarioType);

成功调用该方法设置视频业务场景后，SDK 会基于指定场景启用最佳实践策略，自动调整关键性能指标，进而优化视频体验质量。

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

参数

参数名描述
scenarioType

视频业务场景。详见 VideoApplicationScenarioType。 applicationScenarioMeeting (1) 适用于会议场景。如果用户已调用 setDualStreamMode 将小流设置为始终不发送 (disableSimulcastStream)，会议场景对小流的动态开关不生效。 该枚举值仅适用于主播 vs 主播场景。SDK 会针对该场景启用以下策略：

  • 针对会议场景对小流码率要求较高的情况，自动启用多项抗弱网技术，提升小流的抗弱网能力，确保多路流订阅时接收端的流畅性。

  • 实时监测接收端大流的订阅人数，根据订阅人数动态调节大流配置：

    • 无人订阅大流时，会自动降低大流的码率和帧率，节省上行带宽和消耗。

    • 有人订阅大流时，大流会重置为用户最近一次调用 setVideoEncoderConfiguration 时的 VideoEncoderConfiguration 配置。如果用户此前没有进行设置，则使用如下值：

      • 视频分辨率：桌面端为 1280 × 720；移动端为 960 × 540
      • 视频帧率：15 fps
      • 码率：桌面端为 1600 Kbps；移动端为 1000 Kbps

  • 实时监测接收端小流的订阅人数，根据订阅人数动态开启和关闭小流：

    • 无人订阅小流时，自动关闭小流，节省上行带宽和消耗。

    • 有人订阅小流时，开启小流并重置为用户最近一次调用 setDualStreamMode 时的 SimulcastStreamConfig 配置。如果用户此前没有进行设置，则使用如下值：

      • 视频分辨率：480 × 272
      • 视频帧率：15 fps
      • 码率：500 Kbps

applicationScenario1v1 (2) 适用于视频 1v1 通话场景。针对该场景低延迟、高画质的体验要求，SDK 进行了策略调优，提升了画质、首帧出图、中低端机延迟及弱网流畅度等性能表现。applicationScenarioLiveshow (3) 适用于秀场直播场景。针对该场景对首帧出图时间和画质清晰度的高要求，SDK 进行了策略调优，例如，默认开启音视频帧加速渲染来提升首帧出图体验，无需再额外调用 enableInstantMediaRendering，同时会默认开启 B 帧来确保较高的图像质量、提高传输效率。此外，也增强了在弱网环境和低端设备上的画质和流畅度表现。

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

返回值

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

所属接口类

startPreviewWithoutSourceType

开启视频预览。

Dart
Future<void> startPreviewWithoutSourceType();

该方法用于启动本地视频预览。

注：

  • 本地预览默认开启镜像功能。
  • 在离开频道后，本地预览依然处于开启状态。你需要调用 stopPreview 关闭本地预览。

调用时机

该方法必须在 enableVideo 之后调用。

返回值

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

所属接口类

startPreview

开启视频预览并指定预览的视频源。

Dart
Future<void> startPreview(
            {VideoSourceType sourceType = VideoSourceType.videoSourceCameraPrimary});

该方法用于启动本地视频预览，并指定出现在预览画面中的视频源。

注：

  • 本地预览默认开启镜像功能。
  • 在离开频道后，本地预览依然处于开启状态。你需要调用 stopPreview 关闭本地预览。

调用时机

该方法必须在 enableVideo 之后调用。

参数

参数名描述
sourceType

视频源的类型，详见 VideoSourceType。

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

返回值

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

所属接口类

stopPreview

停止视频预览。

Dart
Future<void> stopPreview(
    {VideoSourceType sourceType = VideoSourceType.videoSourceCameraPrimary});

适用场景

调用 startPreview 开启预览后，如果你想关闭本地视频预览，请调用该方法。

调用时机

请在加入频道前或离开频道后调用该方法。

参数

参数名描述
sourceType

视频源的类型，详见 VideoSourceType。

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

返回值

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

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

所属接口类

onFirstLocalVideoFrame

已显示本地视频首帧回调。

Dart
final void Function(
          VideoSourceType source, int width, int height, int elapsed)?
      onFirstLocalVideoFrame;

本地视频首帧显示在本地视图上时，SDK 会触发此回调。

参数

参数名描述
source

视频源的类型。详见 VideoSourceType。

width

本地渲染视频的宽 (px) 。

height

本地渲染视频的高 (px)。

elapsed

从调用 joinChannel 加入频道时到发生此事件过去的时间（毫秒）。如果在加入频道前调用了 startPreviewWithoutSourceType/startPreview，则该参数表示从调用 startPreviewWithoutSourceType 或 startPreview 开启本地视频预览到发生此事件过去的时间。

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

所属接口类

onFirstLocalVideoFramePublished

已发布本地视频首帧回调。

Dart
final void Function(RtcConnection connection, int elapsed)?
      onFirstLocalVideoFramePublished;

SDK 会在以下三种时机触发该回调：

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

elapsed

从调用 joinChannel 方法到触发该回调的时间间隔（毫秒）。

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

所属接口类

onFirstRemoteVideoDecoded

已接收到远端视频并完成解码回调。

Dart
final void Function(RtcConnection connection, int remoteUid, int width,
      int height, int elapsed)? onFirstRemoteVideoDecoded;

SDK 会在以下时机触发该回调：

  • 远端用户首次上线后发送视频。

  • 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括：

    • 远端用户离开频道。
    • 远端用户掉线。
    • 远端用户调用 disableVideo 方法关闭视频模块。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

用户 ID，指定是哪个用户的视频流。

width

视频流宽（px）。

height

视频流高（px）。

elapsed

从本地调用 joinChannel 开始到该回调触发的延迟（毫秒）。

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

所属接口类

onFirstRemoteVideoFrame

渲染器已接收首帧远端视频回调。

Dart
final void Function(RtcConnection connection, int remoteUid, int width,
      int height, int elapsed)? onFirstRemoteVideoFrame;

注： 该回调只在 SDK 渲染时才会触发；如果用户采用自定义视频渲染则不会触发，客户需要通过 SDK 以外的方法自行实现。

参数

参数名描述
uid

用户 ID，指定是哪个用户的视频流。

connection

Connection 信息。详见 RtcConnection。

width

视频流宽（px）。

height

视频流高（px）。

elapsed

从本地调用 joinChannel 到发生此事件过去的时间（毫秒）。

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

所属接口类

onLocalVideoEvent

本地视频事件发生时触发的回调。

Dart
  final void Function(VideoSourceType source, LocalVideoEventType event)?
      onLocalVideoEvent;

自从

自 v6.6.2 版本新增。

你可以通过该回调获取本地视频事件的原因。

参数

参数名描述
source

视频源类型，详见 VideoSourceType。

event

本地视频事件类型，详见 LocalVideoEventType。

  • localVideoEventTypeScreenCaptureWindowHidden：屏幕采集窗口被隐藏。
  • localVideoEventTypeScreenCaptureWindowRecoverFromHidden：屏幕采集窗口从隐藏状态恢复。
  • localVideoEventTypeScreenCaptureStoppedByUser：屏幕采集被用户停止。
  • localVideoEventTypeScreenCaptureSystemInternalError：屏幕采集过程中发生系统内部错误。
  • localVideoEventTypeCameraFocalLengthApplied：请求的广角或超广角摄像头已应用。
  • localVideoEventTypeCameraFocalLengthFallbackToDefault：请求的广角或超广角摄像头无法打开，SDK 回退到默认摄像头。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onLocalVideoStateChanged

本地视频状态发生改变回调。

Dart
final void Function(VideoSourceType source, LocalVideoStreamState state,
    LocalVideoStreamReason reason)? onLocalVideoStateChanged;;

本地视频的状态发生改变时，SDK 会触发该回调，报告当前的本地视频状态以及状态改变的原因。

注：

  • 帧重复检测仅针对分辨率大于 200 × 200、帧率大于等于 10 fps、码率小于 20 Kbps 的视频帧。
  • 如果视频采集出现异常，正常情况下可以通过该回调的 reason 参数来排查问题。但在部分设备上，采集出现问题时（如卡死） Android 系统不会抛出任何错误回调，因此 SDK 无法报告本地视频状态改变的原因，此时你可以通过下列方式来判断采集是否无帧：该回调报告 state 为 localVideoStreamStateCapturing 或 localVideoStreamStateEncoding，且 onLocalVideoStats 回调的 captureFrameRate 为 0。

触发时机

  • SDK 会在如下情况触发该回调，且 state 为 localVideoStreamStateFailed，reason 为 localVideoStreamReasonCaptureFailure：

    • 应用退到后台，系统回收摄像头。
    • Android 9 及以上版本，App 切后台一段时间后，系统会收回相机权限。
    • Android 6 及以上版本，如果相机被第三方应用占用一段时间后释放，则 SDK 会触发该回调，并报告 onLocalVideoStateChanged(localVideoStreamStateCapturing，localVideoStreamReasonOk) 回调。
    • 摄像头正常启动，但连续 4 秒都没有输出采集的视频。

  • 当摄像头输出采集的视频帧时，如果 SDK 检测到连续 15 个重复的视频帧，会触发该回调，且 state 为 localVideoStreamStateCapturing，reason 为 localVideoStreamReasonCaptureFailure。

参数

参数名描述
source

视频源的类型。详见 VideoSourceType。

state

本地视频状态，详见 LocalVideoStreamState。

reason

本地视频状态改变原因，详见 LocalVideoStreamReason。

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

所属接口类

onLocalVideoStats

本地视频流统计信息回调。

Dart
final void Function(RtcConnection connection, LocalVideoStats stats)?
      onLocalVideoStats;

该回调描述本地设备发送视频流的统计信息，每 2 秒触发一次。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

stats

本地视频流统计信息。详见 LocalVideoStats。

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

所属接口类

onRemoteVideoStateChanged

远端视频状态发生改变回调。

Dart
final void Function(
      RtcConnection connection,
      int remoteUid,
      RemoteVideoState state,
      RemoteVideoStateReason reason,
      int elapsed)? onRemoteVideoStateChanged;

注： 频道内的用户（通信场景）或主播（直播场景）人数超过 32 人时，该回调可能不准确。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

发生视频状态改变的远端用户 ID。

state

远端视频流状态，详见 RemoteVideoState。

reason

远端视频流状态改变的具体原因，详见 RemoteVideoStateReason。

elapsed

从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为毫秒。

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

所属接口类

onRemoteVideoStats

通话中远端视频流的统计信息回调。

Dart
final void Function(RtcConnection connection, RemoteVideoStats stats)?
      onRemoteVideoStats;

该回调描述远端用户在通话中端到端的视频流统计信息， 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播， 该回调每 2 秒会被触发多次。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

stats

远端视频统计数据。详见 RemoteVideoStats。

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

所属接口类

onRemoteVideoTransportStats

通话中远端视频流传输的统计信息回调。

Dart
final void Function(RtcConnection connection, int remoteUid, int delay,
      int lost, int rxKBitRate)? onRemoteVideoTransportStats;

废弃

弃用： 该回调已被废弃，请改用 onRemoteVideoStats。

该回调描述远端用户通话中端到端的网络统计信息，通过视频包计算，用客观的数据，如丢包、 网络延迟等，展示当前网络状态。 通话中，当用户收到远端用户/主播发送的视频数据包后，会每 2 秒触发一次该回调。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

用户 ID，指定是哪个用户/主播的视频包。

delay

视频包从发送端到接收端的延时（毫秒）。

lost

视频包从发送端到接收端的丢包率 (%)。

rxKBitRate

远端视频包的接收码率（Kbps）。

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

所属接口类

onUserEnableLocalVideo

远端用户开/关本地视频采集回调。

Dart
final void Function(RtcConnection connection, int remoteUid, bool enabled)?
      onUserEnableLocalVideo;

废弃

弃用： 该回调已废弃，请改用 onRemoteVideoStateChanged 回调的如下枚举：

  • remoteVideoStateStopped(0) 和 remoteVideoStateReasonRemoteMuted(5)。
  • remoteVideoStateDecoding (2) 和 remoteVideoStateReasonRemoteUnmuted(6)。

该回调是由远端用户调用 enableLocalVideo 方法开启或关闭视频采集触发的。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

用户 ID，提示是哪个用户的视频流。

enabled

远端用户是否启用视频采集：

  • true: 该用户已启用视频功能。启用后，其他用户可以接收到该用户的视频流。
  • false: 该用户已关闭视频功能。关闭后，该用户仍然可以接收其他用户的视频流，但其他用户接收不到该用户的视频流。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onUserEnableVideo

远端用户开/关视频模块回调。

Dart
final void Function(RtcConnection connection, int remoteUid, bool enabled)?
      onUserEnableVideo;

关闭视频功能是指该用户只能进行语音通话，不能显示、发送自己的视频，也不能接收、显示别人的视频。 该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

用户 ID，提示是哪个用户的视频流。

enabled
  • true: 该用户已启用视频功能。
  • false: 该用户已关闭视频功能。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onUserMuteVideo

远端用户取消或恢复发布视频流回调。

Dart
final void Function(RtcConnection connection, int remoteUid, bool muted)?
      onUserMuteVideo;

当远端用户调用 muteLocalVideoStream 取消或恢复发布视频流时，SDK 会触发该回调向本地用户报告远端用户的发流状况。

注： 当频道内的用户（通信场景）或主播（直播场景）的人数超过 32 人时，该回调可能不准确。

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

远端用户 ID。

muted

远端用户是否取消发布视频流：

  • true: 取消发布视频流。
  • false: 发布视频流。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onVideoPublishStateChanged

视频发布状态改变回调。

Dart
final void Function(
      VideoSourceType source,
      String channel,
      StreamPublishState oldState,
      StreamPublishState newState,
      int elapseSinceLastState)? onVideoPublishStateChanged;

参数

参数名描述
channel

频道名。

source

视频源的类型。详见 VideoSourceType。

oldState

之前的发布状态，详见 StreamPublishState。

newState

当前的发布状态，详见 StreamPublishState。

elapseSinceLastState

两次状态变化时间间隔（毫秒）。

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

所属接口类

onVideoSizeChanged

本地或远端视频大小和旋转信息发生改变回调。

Dart
final void Function(RtcConnection connection, VideoSourceType sourceType,
      int uid, int width, int height, int rotation)? onVideoSizeChanged;

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

sourceType

视频源的类型。详见 VideoSourceType。

uid

图像尺寸和旋转信息发生变化的用户 ID（本地用户的 uid 为 0。此时视频为本地用户的视频预览）。

width

视频流的宽度（像素）。

height

视频流的高度（像素）。

rotation

旋转信息，取值范围 [0,360)。

注： 在 iOS 平台上，该参数值始终为 0。

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

所属接口类

onVideoStopped

视频功能已停止回调。

Dart
final void Function()? onVideoStopped;

废弃

弃用： 请改用 onLocalVideoStateChanged 回调中的 localVideoStreamStateStopped(0)。

App 如需在停止视频后对 view 做其他处理（比如显示其他画面），可以在这个回调中进行。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利