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

视频基础功能

  • Unity

更新时间不可用

DisableVideo

关闭视频模块。

C#
public abstract int DisableVideo();

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

注：

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

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

调用时机

加入频道前后均可调用：

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

相关回调

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

返回值

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

所属接口类

EnableLocalVideo

开关本地视频采集。

C#
public abstract int EnableLocalVideo(bool enabled);

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

注：

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

参数

参数名描述
enabled

是否开启本地视频采集。

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

返回值

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

所属接口类

EnableVideo

启用视频模块。

C#
public abstract int EnableVideo();

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

注：

调用时机

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

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

相关回调

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

返回值

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

所属接口类

SetVideoEncoderConfiguration

设置视频编码属性。

C#
public abstract int SetVideoEncoderConfiguration(VideoEncoderConfiguration config);

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

注：

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

调用时机

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

参数

参数名描述
config

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

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

返回值

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

所属接口类

SetVideoEncoderConfigurationEx

设置视频编码属性。

C#
public abstract int SetVideoEncoderConfigurationEx(VideoEncoderConfiguration config, RtcConnection connection);

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

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

调用时机

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

参数

参数名描述
config

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

connection

Connection 信息。详见 RtcConnection。

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

返回值

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

所属接口类

SetVideoScenario

设置视频业务场景。

C#
public abstract int SetVideoScenario(VIDEO_APPLICATION_SCENARIO_TYPE scenarioType);

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

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

参数

参数名描述
scenarioType

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

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

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

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

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

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

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

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

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

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

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

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

返回值

  • 0: 方法调用成功。

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

    • -1：一般性的错误（未明确归类）。
    • -4：不支持设置视频业务场景。可能的原因是当前使用的是音频 SDK。
    • -7：IRtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 IRtcEngine 对象。

所属接口类

StartPreview [1/2]

开启视频预览。

C#
public abstract int StartPreview();

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

注：

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

调用时机

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

返回值

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

所属接口类

StartPreview [2/2]

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

C#
public abstract int StartPreview(VIDEO_SOURCE_TYPE sourceType);

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

注：

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

调用时机

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

参数

参数名描述
sourceType

视频源的类型，详见 VIDEO_SOURCE_TYPE。

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

返回值

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

所属接口类

StopPreview [1/2]

停止视频预览。

C#
public abstract int StopPreview();

适用场景

调用 StartPreview [1/2] 开启预览后，如果你想关闭本地视频预览，请调用该方法。

调用时机

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

返回值

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

所属接口类

StopPreview [2/2]

停止视频预览。

C#
public abstract int StopPreview(VIDEO_SOURCE_TYPE sourceType);

适用场景

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

调用时机

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

参数

参数名描述
sourceType

视频源的类型，详见 VIDEO_SOURCE_TYPE。

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

返回值

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

所属接口类

OnFirstLocalVideoFrame

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

C#
public virtual void OnFirstLocalVideoFrame(VIDEO_SOURCE_TYPE source, int width, int height, int elapsed) { }

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

参数

参数名描述
source

视频源的类型。详见 VIDEO_SOURCE_TYPE。

width

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

height

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

elapsed

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

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

所属接口类

OnFirstLocalVideoFramePublished

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

C#
public virtual void OnFirstLocalVideoFramePublished(RtcConnection connection, int elapsed) {}

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

elapsed

从调用 JoinChannel [1/2] 或 JoinChannel [2/2] 方法到触发该回调的时间间隔（毫秒）。

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

所属接口类

OnFirstRemoteVideoDecoded

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

C#
public virtual void OnFirstRemoteVideoDecoded(RtcConnection connection, uint remoteUid, int width, int height, int elapsed) {}

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

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

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

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

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

width

视频流宽（px）。

height

视频流高（px）。

elapsed

从本地调用 JoinChannel [1/2] 或 JoinChannel [2/2] 开始到该回调触发的延迟（毫秒）。

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

所属接口类

OnFirstRemoteVideoFrame

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

C#
public virtual void OnFirstRemoteVideoFrame(RtcConnection connection, uint remoteUid, int width, int height, int elapsed) {}

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

参数

参数名描述
remoteUid

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

connection

Connection 信息。详见 RtcConnection。

width

视频流宽（px）。

height

视频流高（px）。

elapsed

从本地调用 JoinChannel [1/2] 或 JoinChannel [2/2] 到发生此事件过去的时间（毫秒）。

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

所属接口类

OnLocalVideoEvent

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

C#
public virtual void OnLocalVideoEvent(VideoSourceType source, LocalVideoEventType event)

自从

自 v4.6.1 版本新增。

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

参数

参数名描述
source

视频源类型，详见 VIDEO_SOURCE_TYPE。

event

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

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

所属接口类

OnLocalVideoStateChanged

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

C#
public virtual void OnLocalVideoStateChanged(VIDEO_SOURCE_TYPE source, LOCAL_VIDEO_STREAM_STATE state, LOCAL_VIDEO_STREAM_REASON reason)

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

注：

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

触发时机

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

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

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

参数

参数名描述
source

视频源的类型。详见 VIDEO_SOURCE_TYPE。

state

本地视频状态，详见 LOCAL_VIDEO_STREAM_STATE。

reason

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

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

所属接口类

OnLocalVideoStats

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

C#
public virtual void OnLocalVideoStats(RtcConnection connection, LocalVideoStats stats) {}

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

stats

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

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

所属接口类

OnRemoteVideoStateChanged

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

C#
public virtual void OnRemoteVideoStateChanged(RtcConnection connection, uint remoteUid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed) {}

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

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

state

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

reason

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

elapsed

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

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

所属接口类

OnRemoteVideoStats

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

C#
public virtual void OnRemoteVideoStats(RtcConnection connection, RemoteVideoStats stats) {}

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

stats

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

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

所属接口类

OnRemoteVideoTransportStats

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

C#
public virtual void OnRemoteVideoTransportStats(RtcConnection connection, uint remoteUid, UInt16 delay, UInt16 lost, UInt16 rxKBitRate) {}

废弃

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

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

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

delay

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

lost

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

rxKBitRate

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

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

所属接口类

OnUserEnableLocalVideo

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

C#
public virtual void OnUserEnableLocalVideo(RtcConnection connection, uint remoteUid, bool enabled) {}

废弃

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

  • REMOTE_VIDEO_STATE_STOPPED(0) 和 REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED(5)。
  • REMOTE_VIDEO_STATE_DECODING (2) 和 REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED(6)。

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

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

enabled

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

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

所属接口类

OnUserEnableVideo

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

C#
public virtual void OnUserEnableVideo(RtcConnection connection, uint remoteUid, bool enabled) {}

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

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

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

所属接口类

OnUserMuteVideo

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

C#
public virtual void OnUserMuteVideo(RtcConnection connection, uint remoteUid, bool muted) {}

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

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

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

remoteUid

远端用户 ID。

muted

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

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

所属接口类

OnVideoPublishStateChanged

视频发布状态改变回调。

C#
public virtual void OnVideoPublishStateChanged(VIDEO_SOURCE_TYPE source, string channel, STREAM_PUBLISH_STATE oldState, STREAM_PUBLISH_STATE newState, int elapseSinceLastState) { }

参数

参数名描述
channel

频道名。

source

视频源的类型。详见 VIDEO_SOURCE_TYPE。

oldState

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

newState

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

elapseSinceLastState

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

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

所属接口类

OnVideoSizeChanged

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

C#
public virtual void OnVideoSizeChanged(RtcConnection connection, VIDEO_SOURCE_TYPE sourceType, uint uid, int width, int height, int rotation) { }

参数

参数名描述
connection

Connection 信息。详见 RtcConnection。

sourceType

视频源的类型。详见 VIDEO_SOURCE_TYPE。

uid

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

width

视频流的宽度（像素）。

height

视频流的高度（像素）。

rotation

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

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

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

所属接口类

OnVideoStopped

视频功能已停止回调。

C#
public virtual void OnVideoStopped()

废弃

弃用： 请改用 OnLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED(0)。

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利