# 视频基础功能 (/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## disableVideo [#disablevideo]
禁用视频模块。
```cpp
virtual int disableVideo() = 0;
```
该方法会影响内部引擎,且可以在离开频道后调用。调用该方法会重置整个引擎,可能导致响应时间变慢。你可以根据实际需求,使用以下方法分别控制视频模块的具体功能:
- [enableLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablelocalvideo):是否启用摄像头以创建本地视频流。
- [muteLocalVideoStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalvideostream):是否发布本地视频流。
- [muteRemoteVideoStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteremotevideostream):是否订阅并播放远端视频流。
- [muteAllRemoteVideoStreams](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteallremotevideostreams):是否订阅并播放所有远端视频流。
### 调用时机 [#调用时机]
该方法可以在加入频道前或加入频道后调用:
- 如果在加入频道前调用,则进入纯语音模式。
- 如果在加入频道后调用,则从视频模式切换为纯语音模式。
之后调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 可重新切换回视频模式。
### 相关回调 [#相关回调]
成功调用该方法后,远端会触发 `onUserEnableVideo(false)` 回调,报告视频被禁用。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## enableLocalVideo [#enablelocalvideo]
启用或关闭本地视频采集。
```cpp
virtual int enableLocalVideo(bool enabled) = 0;
```
该方法用于关闭或重新启用本地视频采集,不影响接收远端视频流。调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 后,默认启用本地视频采集。如果在频道内调用 `enableLocalVideo(false)` 关闭本地视频采集,则会同时停止在频道内发布视频流。若需重新开始视频采集,可调用 `enableLocalVideo(true)`,然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengine_updatechannelmediaoptions) 设置 `options` 参数以在频道中发布本地采集的视频流。
:::note
注:
- 可以在加入频道前或加入频道后调用该方法。但如果在加入频道前调用,设置仅在加入频道后生效。
- 该方法会启用内部引擎,并在离开频道后依然有效。
:::
### 相关回调 [#相关回调-1]
成功关闭或重新启用本地视频采集后,SDK 会在远端客户端触发 [onRemoteVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调报告状态变化。
### 参数 [#参数]
是否启用本地视频采集:
- true:(默认)启用本地视频采集。
- false:关闭本地视频采集。关闭后,远端用户无法接收到本地用户的视频流,但本地用户仍可接收远端用户的视频流。设置为 false 时,无需本地摄像头。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## enableVideo [#enablevideo]
启用视频模块。
```cpp
virtual int enableVideo() = 0;
```
默认情况下,视频模块处于关闭状态。调用该方法可启用视频模块。如果你需要在之后关闭视频模块,需要调用 [disableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_disablevideo) 方法。
:::note
注: 该方法会启用内部引擎,离开频道后依然有效。
调用该方法会重置整个引擎,可能导致响应变慢。你可以根据实际需求使用以下方法分别控制视频模块的具体功能:
- [enableLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablelocalvideo):是否启用摄像头以创建本地视频流。
- [muteLocalVideoStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalvideostream):是否发布本地视频流。
- [muteRemoteVideoStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteremotevideostream):是否订阅并播放远端视频流。
- [muteAllRemoteVideoStreams](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteallremotevideostreams):是否订阅并播放所有远端视频流。
成功调用该方法会重置 [enableLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablelocalvideo)、[muteRemoteVideoStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteremotevideostream) 和 [muteAllRemoteVideoStreams](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_muteallremotevideostreams) 的设置,请谨慎使用。
:::
### 调用时机 [#调用时机-1]
该方法可以在加入频道前或加入频道后调用:
- 如果在加入频道前调用,则启用视频模块。
- 如果在语音通话中调用,则语音通话会自动切换为视频通话。
### 相关回调 [#相关回调-2]
成功调用该方法后,SDK 会触发 [onRemoteVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调,报告远端视频状态发生变化。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## setVideoEncoderConfiguration [#setvideoencoderconfiguration]
设置本地视频的编码器配置。
```cpp
virtual int setVideoEncoderConfiguration(const VideoEncoderConfiguration& config) = 0;
```
:::note
注:
- 该方法和 [getMirrorApplied](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-raw#api_ivideoframeobserver_getmirrorapplied) 方法都支持设置镜像效果。声网建议只使用其中一种方法进行设置,同时使用两种方法会导致镜像效果叠加,从而使设置失效。
- 该方法中指定的 `config` 是在理想网络条件下的最大值。如果由于网络条件不稳定,视频引擎无法使用指定的 `config` 渲染视频,则会依次尝试列表中更低的参数,直到找到可用的配置。
:::
### 调用时机 [#调用时机-2]
你可以在加入频道前或后调用该方法。如果在加入频道后不需要重新设置视频编码属性,声网建议在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 之前调用该方法,以减少首帧视频渲染时间。
### 参数 [#参数-1]
视频编码配置,详见 [VideoEncoderConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoencoderconfiguration)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## setVideoEncoderConfigurationEx [#setvideoencoderconfigurationex]
设置本地视频的编码器配置。
```cpp
virtual int setVideoEncoderConfigurationEx(const VideoEncoderConfiguration& config, const RtcConnection& connection) = 0;
```
每个配置文件对应一组视频参数,包括分辨率、帧率和码率。`config` 参数表示在理想网络条件下的最大值。如果由于网络条件不稳定,视频引擎无法使用指定的 `config` 渲染视频,则会依次尝试列表中较低的参数,直到找到可用的配置。
### 适用场景 [#适用场景]
该方法适用于多频道场景。
### 调用时机 [#调用时机-3]
你可以在加入频道前或后调用此方法。如果你在加入频道后不需要重新设置视频编码属性,声网建议你在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 之前调用此方法,以减少首帧视频渲染时间。
### 参数 [#参数-2]
视频编码配置。详见 [VideoEncoderConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videoencoderconfiguration)。
连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)
## setVideoScenario [#setvideoscenario]
设置视频应用场景。
```cpp
virtual int setVideoScenario(VIDEO_APPLICATION_SCENARIO_TYPE scenarioType) = 0;
```
:::info[自从]
自 v4.2.0 版本新增。
:::
:::note
注: 请在加入频道前调用该方法。
:::
### 参数 [#参数-3]
视频应用场景类型,详见 [VIDEO_APPLICATION_SCENARIO_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videoapplicationscenariotype)。
- `APPLICATION_SCENARIO_MEETING`(1):适用于会议场景。SDK 会自动启用以下策略:
- 当低画质视频流需要较高码率时,SDK 会启用多种抗网络拥塞技术,提升低画质视频流的性能,确保订阅端流畅接收。
- SDK 实时监控高画质视频流的订阅人数,并动态调整其配置:
- 若无人订阅高画质视频流,SDK 会自动降低其码率和帧率以节省上行带宽。
- 若有人订阅高画质视频流,SDK 会将其重置为最近一次调用 [setVideoEncoderConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoencoderconfiguration) 设置的 [VideoEncoderConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/class-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](/zh-CN/api-reference/rtc/cpp-all-platforms/class-simulcaststreamconfig) 配置;若未设置,则使用以下默认值:
- 分辨率:480 × 272。
- 帧率:15 fps。
- 码率:500 Kbps。
- `APPLICATION_SCENARIO_1V1`(2):适用于一对一直播场景。SDK 会优化策略,以满足低延迟和高画质的需求,提升视频质量、首帧渲染速度、中低端设备的延迟表现以及弱网环境下的流畅性。注意:该枚举值仅适用于主播对主播的场景。
- `APPLICATION_SCENARIO_LIVESHOW`(3):适用于秀场场景。SDK 会启用多项性能优化,包括自动启用音视频帧加速渲染(无需调用 [enableInstantMediaRendering](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_enableinstantmediarendering))以减少首帧延迟,以及启用 B 帧编码以提升图像质量和带宽效率,即使在弱网或低端设备上也能提供更好的视频质量和播放流畅性。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -1:发生通用错误(无具体原因)。
- -4:不支持视频应用场景,可能是因为使用了语音 SDK 而非视频 SDK。
- -7:[IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象尚未初始化。请在调用该方法前初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象。
### 所属接口类 [#所属接口类-5]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## startPreview [1/2] [#startpreview-12]
启用本地视频预览。
```cpp
virtual int startPreview() = 0;
```
:::note
注:
- 本地预览默认启用镜像模式。
- 离开频道后,本地预览仍保持开启状态。你需要调用 `stopPreview` 来关闭本地预览。
:::
### 调用时机 [#调用时机-4]
此方法必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 和 [setupLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 之后调用。
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## startPreview [2/2] [#startpreview-22]
启用本地视频预览,并指定用于预览的视频源。
```cpp
virtual int startPreview(VIDEO_SOURCE_TYPE sourceType) = 0;
```
:::note
注:
- 本地预览默认启用镜像模式。
- 离开频道后,本地预览仍保持开启状态。你需要调用 `stopPreview` 来关闭本地预览。
:::
### 调用时机 [#调用时机-5]
必须在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 和 [setupLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-rendering#api_irtcengine_setuplocalvideo) 之后调用该方法。
### 参数 [#参数-4]
视频源类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
### 返回值 [#返回值-7]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## stopPreview [1/2] [#stoppreview-12]
停止本地视频预览。
```cpp
virtual int stopPreview() = 0;
```
调用 `startPreview` 开启预览后,如果你需要停止本地视频预览,可以调用该方法。
### 调用时机 [#调用时机-6]
在加入频道前或离开频道后调用此方法。
### 返回值 [#返回值-8]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## stopPreview [2/2] [#stoppreview-22]
停止本地视频预览。
```cpp
virtual int stopPreview(VIDEO_SOURCE_TYPE sourceType) = 0;
```
调用 `startPreview` 后,如果你需要停止预览,可以调用该方法。
### 调用时机 [#调用时机-7]
在加入频道前或离开频道后调用该方法。
### 参数 [#参数-5]
视频源类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
### 返回值 [#返回值-9]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## onFirstLocalVideoFrame [#onfirstlocalvideoframe]
本地视频画面首次在本地视图中显示时触发的回调。
```cpp
virtual void onFirstLocalVideoFrame(VIDEO_SOURCE_TYPE source, int width, int height, int elapsed)
```
### 触发时机 [#触发时机]
当本地视频画面首次在本地视图中显示时触发。
### 参数 [#参数-6]
视频源类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
本地首帧视频画面的宽度,单位为像素。
本地首帧视频画面的高度,单位为像素。
从本地用户调用 `joinChannel` 加入频道到该回调触发的时间间隔,单位为毫秒。如果在加入频道前调用了 `startPreview`,该参数表示从调用 `startPreview` 到该事件触发的时间间隔。
### 所属接口类 [#所属接口类-10]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onFirstLocalVideoFramePublished [#onfirstlocalvideoframepublished]
首帧本地视频发布时触发的回调。
```cpp
virtual void onFirstLocalVideoFramePublished(VIDEO_SOURCE_TYPE source, int elapsed)
```
当满足以下任一条件时,SDK 会触发该回调:
- 本地客户端启用视频模块并调用 `joinChannel` 成功加入频道。
- 本地客户端依次调用 `muteLocalVideoStream(true)` 和 `muteLocalVideoStream(false)`。
- 本地客户端依次调用 [disableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_disablevideo) 和 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo)。
- 本地客户端调用 [pushVideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-custom-capturenrendering#api_imediaengine_pushvideoframe_imediaengine) 成功向 SDK 推送视频帧。
### 触发时机 [#触发时机-1]
当首帧本地视频发布时触发。
### 参数 [#参数-7]
视频源类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
从本地用户调用 `joinChannel` 到该回调触发的时间间隔(毫秒)。
### 所属接口类 [#所属接口类-11]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onFirstRemoteVideoDecoded [#onfirstremotevideodecoded]
接收到并解码首帧远端视频时触发的回调。
```cpp
virtual void onFirstRemoteVideoDecoded(uid_t uid, int width, int height, int elapsed) __deprecated
```
:::error[废弃]
该方法已废弃。
:::
### 触发时机 [#触发时机-2]
当远端用户加入频道并发送视频流,或在停止发送视频流 15 秒后重新发送时触发。中断的原因包括:远端用户离开频道、掉线或调用 [disableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_disablevideo) 关闭视频。
### 参数 [#参数-8]
发送视频流的远端用户 ID。
视频流的宽度(单位为像素)。
视频流的高度(单位为像素)。
从本地用户调用 `joinChannel` 加入频道到 SDK 触发该回调的时间(单位为毫秒)。
### 所属接口类 [#所属接口类-12]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onFirstRemoteVideoFrame [#onfirstremotevideoframe]
远端视频首帧显示回调。
```cpp
virtual void onFirstRemoteVideoFrame(uid_t uid, int width, int height, int elapsed)
```
:::note
注: [onFirstRemoteVideoFrame](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onfirstremotevideoframe) 回调仅在视频帧由 SDK 渲染时触发。如果你使用自定义视频渲染,则不会触发该回调。你需要使用 SDK 之外的方法独立实现此功能。
:::
### 触发时机 [#触发时机-3]
当渲染器接收到远端视频的首帧时触发。
### 参数 [#参数-9]
远端用户 ID,即发送视频流的用户。
视频流的宽度(像素)。
视频流的高度(像素)。
从本地用户调用 `joinChannel` 到触发该回调的时间(毫秒)。
### 所属接口类 [#所属接口类-13]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onLocalVideoEvent [#onlocalvideoevent]
本地视频事件发生时触发的回调。
```cpp
virtual void onLocalVideoEvent(VIDEO_SOURCE_TYPE source, LOCAL_VIDEO_EVENT_TYPE event)
```
:::info[自从]
自 v4.6.1 版本新增。
:::
你可以通过该回调获取本地视频事件的原因。
### 参数 [#参数-10]
视频源类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
本地视频事件类型,详见 [LOCAL_VIDEO_EVENT_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localvideoeventtype)。
### 所属接口类 [#所属接口类-14]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onLocalVideoStateChanged [#onlocalvideostatechanged]
本地视频状态发生变化回调。
```cpp
virtual void onLocalVideoStateChanged(VIDEO_SOURCE_TYPE source, LOCAL_VIDEO_STREAM_STATE state, LOCAL_VIDEO_STREAM_REASON reason)
```
:::note
注: 请注意,视频帧重复检测仅适用于分辨率大于 200 × 200、帧率大于等于 10 fps 且码率小于 20 Kbps 的视频帧。
通常情况下,如果视频采集出现异常,可以通过该回调中的 `reason` 参数排查问题。但在部分设备上,采集异常(如卡顿)时,Android 系统不会抛出任何错误回调,导致 SDK 无法上报本地视频状态变化的原因。此时,你可以通过以下方式判断是否未采集到视频帧:该回调上报的 `state` 为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` 或 `LOCAL_VIDEO_STREAM_STATE_ENCODING`,且 [onLocalVideoStats](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostats) 回调中的 `captureFrameRate` 为 0。
:::
### 触发时机 [#触发时机-4]
SDK 在以下情况下会触发该回调,并将 `state` 设置为 `LOCAL_VIDEO_STREAM_STATE_FAILED`,`reason` 设置为 `LOCAL_VIDEO_STREAM_REASON_CAPTURE_FAILURE`:
- 应用切换到后台,系统回收了摄像头资源。
- 在 Android 9 及以上版本中,应用在后台运行一段时间后,系统自动回收摄像头权限。
- 在 Android 6 及以上版本中,摄像头被第三方应用占用一段时间后释放,SDK 会触发该回调并上报 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_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`。
### 参数 [#参数-11]
视频源的类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
本地视频的状态,详见 [LOCAL_VIDEO_STREAM_STATE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localvideostreamstate)。
本地视频状态变化的原因,详见 [LOCAL_VIDEO_STREAM_REASON](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-localvideostreamreason)。
### 所属接口类 [#所属接口类-15]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onLocalVideoStats [#onlocalvideostats]
本地视频流统计信息回调。
```cpp
virtual void onLocalVideoStats(VIDEO_SOURCE_TYPE source, const LocalVideoStats& stats)
```
### 触发时机 [#触发时机-5]
SDK 每两秒触发一次该回调。
### 参数 [#参数-12]
视频源的类型,详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
本地视频流的统计信息。详见 [LocalVideoStats](/zh-CN/api-reference/rtc/cpp-all-platforms/class-localvideostats)。
### 所属接口类 [#所属接口类-16]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onRemoteVideoStateChanged [#onremotevideostatechanged]
远端视频状态发生改变回调。
```cpp
virtual void onRemoteVideoStateChanged(uid_t uid, REMOTE_VIDEO_STATE state, REMOTE_VIDEO_STATE_REASON reason, int elapsed)
```
:::note
注: 当频道中的用户数(在通信频道场景中)或主播数(在直播频道中)超过 32 时,该回调无法正常工作。
:::
### 触发时机 [#触发时机-6]
当远端视频流状态发生变化时触发。
### 参数 [#参数-13]
发生视频状态变化的远端用户 ID。
远端视频的状态,详见 [REMOTE_VIDEO_STATE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-remotevideostate)。
远端视频状态变化的原因,详见 [REMOTE_VIDEO_STATE_REASON](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-remotevideostatereason)。
从本地用户调用 `joinChannel` 方法到 SDK 触发该回调的时间间隔(毫秒)。
### 所属接口类 [#所属接口类-17]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onRemoteVideoStats [#onremotevideostats]
远端用户发送的视频流统计信息回调。
```cpp
virtual void onRemoteVideoStats(const RemoteVideoStats& stats)
```
### 触发时机 [#触发时机-7]
SDK 每两秒为每位远端用户触发一次该回调。如果频道中有多个用户或主播发送视频流,SDK 会相应地多次触发该回调。
### 参数 [#参数-14]
远端视频流的统计信息。详见 [RemoteVideoStats](/zh-CN/api-reference/rtc/cpp-all-platforms/class-remotevideostats)。
### 所属接口类 [#所属接口类-18]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onRemoteVideoTransportStats [#onremotevideotransportstats]
报告每个远端视频流的传输层统计信息。
```cpp
virtual void onRemoteVideoTransportStats(uid_t uid, unsigned short delay, unsigned short lost, unsigned short rxKBitRate) __deprecated
```
:::error[废弃]
该方法已废弃,请改用 [onRemoteVideoStats](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onremotevideostats)。
:::
### 触发时机 [#触发时机-8]
通话过程中,当你接收到远端用户或主播发送的视频包时,每 2 秒触发一次该回调。
### 参数 [#参数-15]
远端用户 ID,表示发送视频包的用户。
从发送端到接收端的网络时延(毫秒)。
远端用户发送的视频包的丢包率(%)。
接收视频的码率(Kbps)。
### 所属接口类 [#所属接口类-19]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onUserEnableLocalVideo [#onuserenablelocalvideo]
远端用户启用或关闭本地视频采集功能回调。
```cpp
virtual void onUserEnableLocalVideo(uid_t uid, bool enabled) __deprecated
```
:::error[废弃]
该方法已废弃。请改用 [onRemoteVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调中的以下枚举值:`REMOTE_VIDEO_STATE_STOPPED` 和 `REMOTE_VIDEO_STATE_REASON_REMOTE_MUTED`,`REMOTE_VIDEO_STATE_DECODING` 和 `REMOTE_VIDEO_STATE_REASON_REMOTE_UNMUTED`。
:::
当远端用户调用 [enableLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablelocalvideo) 恢复或停止视频采集时,SDK 会触发该回调。
### 参数 [#参数-16]
远端用户 ID。
指定的远端用户是否启用本地视频采集功能:
- true:启用视频模块,频道内其他用户可以看到该远端用户的视频。
- false:关闭视频模块,频道内其他用户无法接收该远端用户的视频流,但该远端用户仍可接收其他用户的视频流。
### 所属接口类 [#所属接口类-20]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onUserEnableVideo [#onuserenablevideo]
远端用户启用或关闭视频模块时触发的回调。
```cpp
virtual void onUserEnableVideo(uid_t uid, bool enabled)
```
一旦视频模块被关闭,用户只能进行语音通话,无法发送或接收任何视频。
### 触发时机 [#触发时机-9]
该回调在远端用户调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 或 [disableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_disablevideo) 时触发。
### 参数 [#参数-17]
远端用户 ID。
是否启用视频模块:
- true:视频模块已启用。
- false:视频模块已关闭。
### 所属接口类 [#所属接口类-21]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onUserMuteVideo [#onusermutevideo]
远端视频发布状态变化回调。
```cpp
virtual void onUserMuteVideo(uid_t uid, bool muted)
```
当远端用户调用 [muteLocalVideoStream](/zh-CN/api-reference/rtc/cpp-all-platforms/publishnsubscribe#api_irtcengine_mutelocalvideostream) 方法停止或恢复发布视频流时,SDK 会触发该回调,向本地用户报告该远端用户的视频发布状态。
:::note
注: 当频道中的用户数(在通信场景下)或主播数(在直播场景下)超过 32 时,该回调可能不准确。
:::
### 参数 [#参数-18]
远端用户的用户 ID。
远端用户是否停止发布视频流:
- true:远端用户停止发布视频流。
- false:远端用户恢复发布视频流。
### 所属接口类 [#所属接口类-22]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onVideoPublishStateChanged [#onvideopublishstatechanged]
视频发布状态发生变化回调。
```cpp
virtual void onVideoPublishStateChanged(VIDEO_SOURCE_TYPE source, const char* channel, STREAM_PUBLISH_STATE oldState, STREAM_PUBLISH_STATE newState, int elapseSinceLastState)
```
### 参数 [#参数-19]
视频源类型。详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
频道名。
之前的视频发布状态。详见 [STREAM_PUBLISH_STATE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-streampublishstate)。
当前的视频发布状态。详见 [STREAM_PUBLISH_STATE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-streampublishstate)。
从上一个状态切换到当前状态所经历的时间(毫秒)。
### 所属接口类 [#所属接口类-23]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onVideoSizeChanged [#onvideosizechanged]
当指定用户的视频尺寸或旋转发生变化时触发。
```cpp
virtual void onVideoSizeChanged(VIDEO_SOURCE_TYPE sourceType, uid_t uid, int width, int height, int rotation)
```
:::note
注: `rotation` 参数在 iOS 平台上始终为 0。
:::
### 参数 [#参数-20]
视频源类型。详见 [VIDEO_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-videosourcetype)。
发生视频尺寸或旋转变化的用户 ID。本地用户的 `uid` 为 0,表示本地用户的视频预览。
视频流的宽度(单位为像素)。
视频流的高度(单位为像素)。
视频旋转角度,取值范围为 [0, 360)。
:::note
注: `rotation` 参数在 iOS 平台上始终为 0。
:::
### 所属接口类 [#所属接口类-24]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onVideoStopped [#onvideostopped]
视频停止播放时触发的回调。
```cpp
virtual void onVideoStopped() __deprecated {}
```
:::error[废弃]
该方法已废弃,请改用 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调中的 `LOCAL_VIDEO_STREAM_STATE_STOPPED`。
:::
:::note
注: 你可以在视频停止播放后使用该回调更改视图配置,例如在视图中显示其他图片。
:::
### 所属接口类 [#所属接口类-25]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)