# 视频基础功能 (/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)