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

视频基础功能

  • C++

更新时间不可用

disableVideo

禁用视频模块。

C++
virtual int disableVideo() = 0;

该方法会影响内部引擎，且可以在离开频道后调用。调用该方法会重置整个引擎，可能导致响应时间变慢。你可以根据实际需求，使用以下方法分别控制视频模块的具体功能：

调用时机

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

  • 如果在加入频道前调用，则进入纯语音模式。
  • 如果在加入频道后调用，则从视频模式切换为纯语音模式。

之后调用 enableVideo 可重新切换回视频模式。

相关回调

成功调用该方法后，远端会触发 onUserEnableVideo(false) 回调，报告视频被禁用。

返回值

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

所属接口类

enableLocalVideo

启用或关闭本地视频采集。

C++
virtual int enableLocalVideo(bool enabled) = 0;

该方法用于关闭或重新启用本地视频采集，不影响接收远端视频流。调用 enableVideo 后，默认启用本地视频采集。如果在频道内调用 enableLocalVideo(false) 关闭本地视频采集，则会同时停止在频道内发布视频流。若需重新开始视频采集，可调用 enableLocalVideo(true)，然后调用 updateChannelMediaOptions 设置 options 参数以在频道中发布本地采集的视频流。

注：

  • 可以在加入频道前或加入频道后调用该方法。但如果在加入频道前调用，设置仅在加入频道后生效。
  • 该方法会启用内部引擎，并在离开频道后依然有效。

相关回调

成功关闭或重新启用本地视频采集后，SDK 会在远端客户端触发 onRemoteVideoStateChanged 回调报告状态变化。

参数

参数名描述
enabled

是否启用本地视频采集：

  • true：（默认）启用本地视频采集。
  • false：关闭本地视频采集。关闭后，远端用户无法接收到本地用户的视频流，但本地用户仍可接收远端用户的视频流。设置为 false 时，无需本地摄像头。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

enableVideo

启用视频模块。

C++
virtual int enableVideo() = 0;

默认情况下，视频模块处于关闭状态。调用该方法可启用视频模块。如果你需要在之后关闭视频模块，需要调用 disableVideo 方法。

注： 该方法会启用内部引擎，离开频道后依然有效。 调用该方法会重置整个引擎，可能导致响应变慢。你可以根据实际需求使用以下方法分别控制视频模块的具体功能：

成功调用该方法会重置 enableLocalVideo、muteRemoteVideoStream 和 muteAllRemoteVideoStreams 的设置，请谨慎使用。

调用时机

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

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

相关回调

成功调用该方法后，SDK 会触发 onRemoteVideoStateChanged 回调，报告远端视频状态发生变化。

返回值

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

所属接口类

setVideoEncoderConfiguration

设置本地视频的编码器配置。

C++
virtual int setVideoEncoderConfiguration(const VideoEncoderConfiguration& config) = 0;

注：

  • 该方法和 getMirrorApplied 方法都支持设置镜像效果。声网建议只使用其中一种方法进行设置，同时使用两种方法会导致镜像效果叠加，从而使设置失效。
  • 该方法中指定的 config 是在理想网络条件下的最大值。如果由于网络条件不稳定，视频引擎无法使用指定的 config 渲染视频，则会依次尝试列表中更低的参数，直到找到可用的配置。

调用时机

你可以在加入频道前或后调用该方法。如果在加入频道后不需要重新设置视频编码属性，声网建议在调用 enableVideo 之前调用该方法，以减少首帧视频渲染时间。

参数

参数名描述
config

视频编码配置，详见 VideoEncoderConfiguration。

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

返回值

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

所属接口类

setVideoEncoderConfigurationEx

设置本地视频的编码器配置。

C++
virtual int setVideoEncoderConfigurationEx(const VideoEncoderConfiguration& config, const RtcConnection& connection) = 0;

每个配置文件对应一组视频参数，包括分辨率、帧率和码率。config 参数表示在理想网络条件下的最大值。如果由于网络条件不稳定，视频引擎无法使用指定的 config 渲染视频，则会依次尝试列表中较低的参数，直到找到可用的配置。

适用场景

该方法适用于多频道场景。

调用时机

你可以在加入频道前或后调用此方法。如果你在加入频道后不需要重新设置视频编码属性，声网建议你在调用 enableVideo 之前调用此方法，以减少首帧视频渲染时间。

参数

参数名描述
config

视频编码配置。详见 VideoEncoderConfiguration。

connection

连接信息。详见 RtcConnection。

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

返回值

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

所属接口类

setVideoScenario

设置视频应用场景。

C++
virtual int setVideoScenario(VIDEO_APPLICATION_SCENARIO_TYPE scenarioType) = 0;

自从

自 v4.2.0 版本新增。

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

参数

参数名描述
scenarioType

视频应用场景类型，详见 VIDEO_APPLICATION_SCENARIO_TYPE。

  • APPLICATION_SCENARIO_MEETING（1）：适用于会议场景。SDK 会自动启用以下策略：

    • 当低画质视频流需要较高码率时，SDK 会启用多种抗网络拥塞技术，提升低画质视频流的性能，确保订阅端流畅接收。

    • SDK 实时监控高画质视频流的订阅人数，并动态调整其配置：

      • 若无人订阅高画质视频流，SDK 会自动降低其码率和帧率以节省上行带宽。

      • 若有人订阅高画质视频流，SDK 会将其重置为最近一次调用 setVideoEncoderConfiguration 设置的 VideoEncoderConfiguration 配置；若未设置，则使用以下默认值：

        • 分辨率：（Windows 和 macOS）1280 × 720；（Android 和 iOS）960 × 540。
        • 帧率：15 fps。
        • 码率：（Windows 和 macOS）1600 Kbps；（Android 和 iOS）1000 Kbps。

    • SDK 实时监控低画质视频流的订阅人数，并根据订阅情况动态启用或禁用该流。

      • 若用户调用了 setDualStreamMode 并设置为永不发送低画质视频流（DISABLE_SIMULCAST_STREAM），则该策略不生效。

      • 若无人订阅低画质视频流，SDK 会自动禁用该流以节省上行带宽。

      • 若有人订阅低画质视频流，SDK 会启用该流，并重置为最近一次调用 setDualStreamMode 设置的 SimulcastStreamConfig 配置；若未设置，则使用以下默认值：

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

  • APPLICATION_SCENARIO_1V1（2）：适用于一对一直播场景。SDK 会优化策略，以满足低延迟和高画质的需求，提升视频质量、首帧渲染速度、中低端设备的延迟表现以及弱网环境下的流畅性。注意：该枚举值仅适用于主播对主播的场景。

  • APPLICATION_SCENARIO_LIVESHOW（3）：适用于秀场场景。SDK 会启用多项性能优化，包括自动启用音视频帧加速渲染（无需调用 enableInstantMediaRendering）以减少首帧延迟，以及启用 B 帧编码以提升图像质量和带宽效率，即使在弱网或低端设备上也能提供更好的视频质量和播放流畅性。

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

返回值

  • 0：方法调用成功。

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

    • -1：发生通用错误（无具体原因）。
    • -4：不支持视频应用场景，可能是因为使用了语音 SDK 而非视频 SDK。
    • -7：IRtcEngine 对象尚未初始化。请在调用该方法前初始化 IRtcEngine 对象。

所属接口类

startPreview [1/2]

启用本地视频预览。

C++
virtual int startPreview() = 0;

注：

  • 本地预览默认启用镜像模式。
  • 离开频道后，本地预览仍保持开启状态。你需要调用 stopPreview 来关闭本地预览。

调用时机

此方法必须在调用 enableVideo 和 setupLocalVideo 之后调用。

返回值

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

所属接口类

startPreview [2/2]

启用本地视频预览，并指定用于预览的视频源。

C++
virtual int startPreview(VIDEO_SOURCE_TYPE sourceType) = 0;

注：

  • 本地预览默认启用镜像模式。
  • 离开频道后，本地预览仍保持开启状态。你需要调用 stopPreview 来关闭本地预览。

调用时机

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

参数

参数名描述
sourceType

视频源类型，详见 VIDEO_SOURCE_TYPE。

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

返回值

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

所属接口类

stopPreview [1/2]

停止本地视频预览。

C++
virtual int stopPreview() = 0;

调用 startPreview 开启预览后，如果你需要停止本地视频预览，可以调用该方法。

调用时机

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

返回值

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

所属接口类

stopPreview [2/2]

停止本地视频预览。

C++
virtual int stopPreview(VIDEO_SOURCE_TYPE sourceType) = 0;

调用 startPreview 后，如果你需要停止预览，可以调用该方法。

调用时机

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

参数

参数名描述
sourceType

视频源类型，详见 VIDEO_SOURCE_TYPE。

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

返回值

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

所属接口类

onFirstLocalVideoFrame

本地视频画面首次在本地视图中显示时触发的回调。

C++
virtual void onFirstLocalVideoFrame(VIDEO_SOURCE_TYPE source, int width, int height, int elapsed)

触发时机

当本地视频画面首次在本地视图中显示时触发。

参数

参数名描述
source

视频源类型，详见 VIDEO_SOURCE_TYPE。

width

本地首帧视频画面的宽度，单位为像素。

height

本地首帧视频画面的高度，单位为像素。

elapsed

从本地用户调用 joinChannel 加入频道到该回调触发的时间间隔，单位为毫秒。如果在加入频道前调用了 startPreview，该参数表示从调用 startPreview 到该事件触发的时间间隔。

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

所属接口类

onFirstLocalVideoFramePublished

首帧本地视频发布时触发的回调。

C++
virtual void onFirstLocalVideoFramePublished(VIDEO_SOURCE_TYPE source, int elapsed)

当满足以下任一条件时，SDK 会触发该回调：

  • 本地客户端启用视频模块并调用 joinChannel 成功加入频道。
  • 本地客户端依次调用 muteLocalVideoStream(true) 和 muteLocalVideoStream(false)。
  • 本地客户端依次调用 disableVideo 和 enableVideo。
  • 本地客户端调用 pushVideoFrame 成功向 SDK 推送视频帧。

触发时机

当首帧本地视频发布时触发。

参数

参数名描述
source

视频源类型，详见 VIDEO_SOURCE_TYPE。

elapsed

从本地用户调用 joinChannel 到该回调触发的时间间隔（毫秒）。

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

所属接口类

onFirstRemoteVideoDecoded

接收到并解码首帧远端视频时触发的回调。

C++
virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed) __deprecated

废弃

该方法已废弃。

触发时机

当远端用户加入频道并发送视频流，或在停止发送视频流 15 秒后重新发送时触发。中断的原因包括：远端用户离开频道、掉线或调用 disableVideo 关闭视频。

参数

参数名描述
uid

发送视频流的远端用户 ID。

width

视频流的宽度（单位为像素）。

height

视频流的高度（单位为像素）。

elapsed

从本地用户调用 joinChannel 加入频道到 SDK 触发该回调的时间（单位为毫秒）。

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

所属接口类

onFirstRemoteVideoFrame

远端视频首帧显示回调。

C++
virtual void onFirstRemoteVideoFrame(uid_t uid, int width, int height, int elapsed)

注： onFirstRemoteVideoFrame 回调仅在视频帧由 SDK 渲染时触发。如果你使用自定义视频渲染，则不会触发该回调。你需要使用 SDK 之外的方法独立实现此功能。

触发时机

当渲染器接收到远端视频的首帧时触发。

参数

参数名描述
uid

远端用户 ID，即发送视频流的用户。

width

视频流的宽度（像素）。

height

视频流的高度（像素）。

elapsed

从本地用户调用 joinChannel 到触发该回调的时间（毫秒）。

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

所属接口类

onLocalVideoEvent

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

C++
virtual void onLocalVideoEvent(VIDEO_SOURCE_TYPE source, LOCAL_VIDEO_EVENT_TYPE event)

自从

自 v4.6.1 版本新增。

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

参数

参数名描述
source

视频源类型，详见 VIDEO_SOURCE_TYPE。

event

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

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

所属接口类

onLocalVideoStateChanged

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

C++
virtual void onLocalVideoStateChanged(VIDEO_SOURCE_TYPE source, LOCAL_VIDEO_STREAM_STATE state, LOCAL_VIDEO_STREAM_REASON reason)

注： 请注意，视频帧重复检测仅适用于分辨率大于 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 及以上版本中，应用在后台运行一段时间后，系统自动回收摄像头权限。
  • 在 Android 6 及以上版本中，摄像头被第三方应用占用一段时间后释放，SDK 会触发该回调并上报 onLocalVideoStateChanged 回调，state 为 LOCAL_VIDEO_STREAM_STATE_CAPTURING，reason 为 LOCAL_VIDEO_STREAM_REASON_OK。
  • 摄像头正常启动，但连续四秒未输出视频帧。
  • 当摄像头输出采集的视频帧时，若 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++
virtual void onLocalVideoStats(VIDEO_SOURCE_TYPE source, const LocalVideoStats& stats)

触发时机

SDK 每两秒触发一次该回调。

参数

参数名描述
source

视频源的类型，详见 VIDEO_SOURCE_TYPE。

stats

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

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

所属接口类

onRemoteVideoStateChanged

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

C++
virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed)

注： 当频道中的用户数（在通信频道场景中）或主播数（在直播频道中）超过 32 时，该回调无法正常工作。

触发时机

当远端视频流状态发生变化时触发。

参数

参数名描述
uid

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

state

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

reason

远端视频状态变化的原因，详见 REMOTE_VIDEO_STATE_REASON。

elapsed

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

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

所属接口类

onRemoteVideoStats

远端用户发送的视频流统计信息回调。

C++
virtual void onRemoteVideoStats(const RemoteVideoStats& stats)

触发时机

SDK 每两秒为每位远端用户触发一次该回调。如果频道中有多个用户或主播发送视频流，SDK 会相应地多次触发该回调。

参数

参数名描述
stats

远端视频流的统计信息。详见 RemoteVideoStats。

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

所属接口类

onRemoteVideoTransportStats

报告每个远端视频流的传输层统计信息。

C++
virtual void onRemoteVideoTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) __deprecated

废弃

该方法已废弃，请改用 onRemoteVideoStats。

触发时机

通话过程中，当你接收到远端用户或主播发送的视频包时，每 2 秒触发一次该回调。

参数

参数名描述
uid

远端用户 ID，表示发送视频包的用户。

delay

从发送端到接收端的网络时延（毫秒）。

lost

远端用户发送的视频包的丢包率（%）。

rxKBitRate

接收视频的码率（Kbps）。

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

所属接口类

onUserEnableLocalVideo

远端用户启用或关闭本地视频采集功能回调。

C++
virtual void onUserEnableLocalVideo(uid_t uid, bool enabled) __deprecated

废弃

该方法已废弃。请改用 onRemoteVideoStateChanged 回调中的以下枚举值：REMOTE_VIDEO_STATE_STOPPED 和 REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED，REMOTE_VIDEO_STATE_DECODING 和 REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED。

当远端用户调用 enableLocalVideo 恢复或停止视频采集时，SDK 会触发该回调。

参数

参数名描述
uid

远端用户 ID。

enabled

指定的远端用户是否启用本地视频采集功能：

  • true：启用视频模块，频道内其他用户可以看到该远端用户的视频。
  • false：关闭视频模块，频道内其他用户无法接收该远端用户的视频流，但该远端用户仍可接收其他用户的视频流。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onUserEnableVideo

远端用户启用或关闭视频模块时触发的回调。

C++
virtual void onUserEnableVideo(uid_t uid, bool enabled)

一旦视频模块被关闭，用户只能进行语音通话，无法发送或接收任何视频。

触发时机

该回调在远端用户调用 enableVideo 或 disableVideo 时触发。

参数

参数名描述
uid

远端用户 ID。

enabled

是否启用视频模块：

  • true：视频模块已启用。
  • false：视频模块已关闭。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onUserMuteVideo

远端视频发布状态变化回调。

C++
virtual void onUserMuteVideo(uid_t uid, bool muted)

当远端用户调用 muteLocalVideoStream 方法停止或恢复发布视频流时，SDK 会触发该回调，向本地用户报告该远端用户的视频发布状态。

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

参数

参数名描述
uid

远端用户的用户 ID。

muted

远端用户是否停止发布视频流：

  • true：远端用户停止发布视频流。
  • false：远端用户恢复发布视频流。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onVideoPublishStateChanged

视频发布状态发生变化回调。

C++
virtual void onVideoPublishStateChanged(VIDEO_SOURCE_TYPE source, const char* channel, STREAM_PUBLISH_STATE oldState, STREAM_PUBLISH_STATE newState, int elapseSinceLastState)

参数

参数名描述
source

视频源类型。详见 VIDEO_SOURCE_TYPE。

channel

频道名。

oldState

之前的视频发布状态。详见 STREAM_PUBLISH_STATE。

newState

当前的视频发布状态。详见 STREAM_PUBLISH_STATE。

elapseSinceLastState

从上一个状态切换到当前状态所经历的时间（毫秒）。

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

所属接口类

onVideoSizeChanged

当指定用户的视频尺寸或旋转发生变化时触发。

C++
virtual void onVideoSizeChanged(VIDEO_SOURCE_TYPE sourceType, uid_t uid, int width, int height, int rotation)

注： rotation 参数在 iOS 平台上始终为 0。

参数

参数名描述
sourceType

视频源类型。详见 VIDEO_SOURCE_TYPE。

uid

发生视频尺寸或旋转变化的用户 ID。本地用户的 uid 为 0，表示本地用户的视频预览。

width

视频流的宽度（单位为像素）。

height

视频流的高度（单位为像素）。

rotation

视频旋转角度，取值范围为 [0, 360)。

注： rotation 参数在 iOS 平台上始终为 0。

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

所属接口类

onVideoStopped

视频停止播放时触发的回调。

C++
virtual void onVideoStopped() __deprecated {}

废弃

该方法已废弃，请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED。

注： 你可以在视频停止播放后使用该回调更改视图配置，例如在视图中显示其他图片。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利