# 视频基础功能 (/zh-CN/api-reference/rtc/harmonyos/video/video-basic)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## disableVideo [#disablevideo]
关闭视频模块。
```ts
public abstract disableVideo(): number;
```
该方法用于关闭视频模块。
### 调用时机 [#调用时机]
加入频道前后均可调用:
- 如果在加入频道前调用,则开启纯音频模式。
- 如果在加入频道后调用,则由视频模式切换为纯音频模式,然后再调用 [enableVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_enablevideo) 方法可开启视频模式。
### 调用限制 [#调用限制]
- 该方法设置的是内部引擎为禁用状态,在离开频道后仍然有效。
- 调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制视频模块的某一项功能:
- [enableLocalVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_enablelocalvideo): 是否启动摄像头采集并创建本地视频流。
- [muteLocalVideoStream](/zh-CN/api-reference/rtc/harmonyos/publishnsubscribe#api_irtcengine_mutelocalvideostream): 是否发布本地视频流。
- [muteRemoteVideoStream](/zh-CN/api-reference/rtc/harmonyos/publishnsubscribe#api_irtcengine_muteremotevideostream): 是否接收并播放远端视频流。
- [muteAllRemoteVideoStreams](/zh-CN/api-reference/rtc/harmonyos/publishnsubscribe#api_irtcengine_muteallremotevideostreams): 是否接收并播放所有远端视频流。
### 相关回调 [#相关回调]
成功调用该方法后,远端会触发 [onUserEnableVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#callback_irtcengineeventhandler_onuserenablevideo) (`false`) 回调。
### 返回值 [#返回值]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## enableLocalVideo [#enablelocalvideo]
开关本地视频采集。
```ts
public abstract enableLocalVideo(enabled: boolean): number;
```
### 详情 [#详情]
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 [enableVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_enablevideo) 后,本地视频采集即默认开启。
如果你在频道内调用 [enableLocalVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_enablelocalvideo)(`false`) 关闭本地视频采集,也会同时停止在频道内发布视频流。如果想要重新开启,则可调用 enableLocalVideo(`true`),然后调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/harmonyos/channel#api_irtcengine_updatechannelmediaoptions) 并设置 options 参数,将本地采集的视频流发布到频道中。
成功禁用或启用本地视频采集后,远端会触发 [onRemoteVideoStateChanged](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调。
:::caution
注意:
- 该方法在加入频道前后都能调用。
- 该方法设置内部引擎为启用状态,在离开频道后仍然有效。
:::
### 参数 [#参数]
是否开启本地视频采集。
- `true`:(默认)开启本地视频采集。
- `false`: 关闭本地视频采集。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为 `false` 时,该方法不需要本地有摄像头。
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## enableVideo [#enablevideo]
启用视频模块。
```ts
public abstract enableVideo(): number;
```
视频模块默认为关闭状态,需要调用该方法启用。如果后续需要关闭视频模块,需调用 [disableVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_disablevideo) 方法。
### 调用时机 [#调用时机-1]
该方法可以在加入频道前或者频道内调用:
- 如果在加入频道前调用,则开启视频模块。
- 如果在纯音频通话中调用,则音频通话将自动切换为视频通话。
### 调用限制 [#调用限制-1]
- 该方法设置的是内部引擎为启用状态,在离开频道后仍然有效。
- 调用该方法会重置整个引擎,响应时间较慢。你可以根据实际需求用以下方法来独立控制视频模块的某一项功能:
- [enableLocalVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_enablelocalvideo): 是否启动摄像头采集并创建本地视频流。
- [muteLocalVideoStream](/zh-CN/api-reference/rtc/harmonyos/publishnsubscribe#api_irtcengine_mutelocalvideostream): 是否发布本地视频流。
- [muteRemoteVideoStream](/zh-CN/api-reference/rtc/harmonyos/publishnsubscribe#api_irtcengine_muteremotevideostream): 是否接收并播放远端视频流。
- [muteAllRemoteVideoStreams](/zh-CN/api-reference/rtc/harmonyos/publishnsubscribe#api_irtcengine_muteallremotevideostreams): 是否接收并播放所有远端视频流。
- 在频道内调用该方法时,会重置 enableLocalVideo、muteRemoteVideoStream 和 muteAllRemoteVideoStreams 的设置,需谨慎使用。
### 相关回调 [#相关回调-1]
成功调用该方法后,远端会触发 [onRemoteVideoStateChanged](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#callback_irtcengineeventhandler_onremotevideostatechanged) 回调。
### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## setVideoEncoderConfiguration [#setvideoencoderconfiguration]
设置视频编码属性。
```ts
public abstract setVideoEncoderConfiguration(configuration: VideoEncoderConfiguration): number;
```
设置本地视频的编码属性。每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
### 调用时机 [#调用时机-2]
该方法在加入频道前后都能调用。如果用户在加入频道后不需要重新设置视频编码属性,则建议在 [enableVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_enablevideo) 前调用该方法,可以加快首帧出图的时间。
### 调用限制 [#调用限制-2]
- 该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config 渲染本地视频,它会自动降低到一个合适的视频参数设置。
### 参数 [#参数-1]
视频编码参数配置。详见 [VideoEncoderConfiguration](/zh-CN/api-reference/rtc/harmonyos/class-videoencoderconfiguration)。
### 返回值 [#返回值-3]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## setVideoEncoderConfigurationEx [#setvideoencoderconfigurationex]
设置视频编码属性。
```ts
public abstract setVideoEncoderConfigurationEx(configuration: VideoEncoderConfiguration, connection: RtcConnection): number;
```
设置本地视频的编码属性。每一种视频编码属性对应一系列视频相关参数设置,包含分辨率、帧率和码率。
### 调用时机 [#调用时机-3]
该方法需要在 [joinChannelEx](/zh-CN/api-reference/rtc/harmonyos/channel#api_irtcengineex_joinchannelex) 之后调用。
### 调用限制 [#调用限制-3]
该方法的 config 参数设置是在理想网络状态下能达到的最大值。如果网络状态不好,视频引擎便不能使用该 config 渲染本地视频,它会自动降低到一个合适的视频参数设置。
### 参数 [#参数-2]
视频编码参数配置。详见 [VideoEncoderConfiguration](/zh-CN/api-reference/rtc/harmonyos/class-videoencoderconfiguration)。
Connection 信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/harmonyos/class-rtcconnection)。
### 返回值 [#返回值-4]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [RtcEngineEx](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineex)
## startPreview [#startpreview]
开启视频预览并指定预览的视频源。
```ts
public abstract startPreview(sourceType?: Constants.VideoSourceType): number;
```
该方法用于启动本地视频预览,并指定出现在预览画面中的视频源。
### 调用时机 [#调用时机-4]
该方法必须在 [enableVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_enablevideo) 和 [setupLocalVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-rendering#api_irtcengine_setuplocalvideo) 之后调用。
### 调用限制 [#调用限制-4]
- 本地预览默认开启镜像功能。
- 在离开频道后,本地预览依然处于开启状态。你需要调用 [stopPreview](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_stoppreview2) 关闭本地预览。
### 参数 [#参数-3]
视频源的类型,详见 [VideoSourceType](/zh-CN/api-reference/rtc/harmonyos/enum-videosourcetype)。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## stopPreview [#stoppreview]
停止视频预览。
```ts
public abstract stopPreview(sourceType?: Constants.VideoSourceType): number;
```
### 适用场景 [#适用场景]
调用 [startPreview](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_startpreview2) 开启预览后,如果你想关闭本地视频预览,请调用该方法。
### 调用时机 [#调用时机-5]
请在加入频道前或离开频道后调用该方法。
### 调用限制 [#调用限制-5]
无。
### 参数 [#参数-4]
视频源的类型,详见 [VideoSourceType](/zh-CN/api-reference/rtc/harmonyos/enum-videosourcetype)。
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)
## onFirstLocalVideoFrame [#onfirstlocalvideoframe]
已显示本地视频首帧回调。
```ts
onFirstLocalVideoFrame?:(source:Constants.VideoSourceType,width:number,height:number,elapsed:number) =>void;
```
### 详情 [#详情-1]
本地视频首帧显示在本地视图上时,SDK 会触发此回调。
### 参数 [#参数-5]
视频源的类型。详见 [VideoSourceType](/zh-CN/api-reference/rtc/harmonyos/enum-videosourcetype)。
本地渲染视频的宽 (px) 。
本地渲染视频的高 (px)。
从调用 [joinChannel](/zh-CN/api-reference/rtc/harmonyos/channel#api_irtcengine_joinchannel) 或[joinChannelWithOptions](/zh-CN/api-reference/rtc/harmonyos/channel#api_irtcengine_joinchannel2) 加入频道时到发生此事件过去的时间(毫秒)。如果在加入频道前调用了 [startPreview](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_startpreview2),则该参数表示从调用 startPreview 开启本地视频预览到发生此事件过去的时间。
### 所属接口类 [#所属接口类-7]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onFirstRemoteVideoFrame [#onfirstremotevideoframe]
渲染器已接收首帧远端视频回调。
```ts
onFirstRemoteVideoFrame?:(uid:number,width:number,height:number,elapsed:number) =>void;
```
### 详情 [#详情-2]
:::caution
注意: 该回调只在 SDK 渲染时才会触发;如果用户采用自定义视频渲染则不会触发,客户需要通过 SDK 以外的方法自行实现。
:::
### 参数 [#参数-6]
用户 ID,指定是哪个用户的视频流。
视频流宽(px)。
视频流高(px)。
从本地调用 joinChannel 或joinChannelWithOptions 到发生此事件过去的时间(毫秒)。
### 所属接口类 [#所属接口类-8]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onLocalVideoStateChanged [#onlocalvideostatechanged]
本地视频状态发生改变回调。
```ts
onLocalVideoStateChanged?:(source: Constants.VideoSourceType, state:Constants.LocalVideoStreamState,reason:Constants.LocalVideoStreamReason) => void
```
本地视频的状态发生改变时,SDK 会触发该回调,报告当前的本地视频状态以及状态改变的原因。
### 适用场景 [#适用场景-1]
你可以通过该回调及时了解本地视频流的状态变化,并根据状态改变的原因采取相应的措施,更好地管理和调试视频流相关的问题。
### 触发时机 [#触发时机]
- SDK 会在如下情况触发该回调,且 state 为 FAILED,reason 为 `CAPTURE_FAILURE`:
- 摄像头正常启动,但连续 4 秒都没有输出采集的视频。
- 当摄像头输出采集的视频帧时,如果 SDK 检测到连续 15 个重复的视频帧,会触发该回调,且 state 为 CAPTURING,reason 为 CAPTURE_FAILURE。
:::note
注: 帧重复检测仅针对分辨率大于 200 × 200、帧率大于等于 10 fps、码率小于 20 Kbps 的视频帧。
:::
### 使用限制 [#使用限制]
对某些机型而言,当本地视频采集设备正在使用中时,SDK 不会在本地视频状态发生改变时触发该回调,你需要自行做超时判断。
### 参数 [#参数-7]
视频源的类型。详见 [VideoSourceType](/zh-CN/api-reference/rtc/harmonyos/enum-videosourcetype)。
本地视频状态,详见 [LocalVideoStreamState](/zh-CN/api-reference/rtc/harmonyos/enum-localvideostreamstate)。
本地视频状态改变原因,详见 [LocalVideoStreamReason](/zh-CN/api-reference/rtc/harmonyos/enum-localvideostreamreason)。
### 所属接口类 [#所属接口类-9]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onLocalVideoStats [#onlocalvideostats]
本地视频流统计信息回调。
```ts
onLocalVideoStats?:(source:Constants.VideoSourceType , stats:LocalVideoStats ) => void;
```
### 详情 [#详情-3]
该回调描述本地设备发送视频流的统计信息,每 2 秒触发一次。
### 参数 [#参数-8]
视频源的类型。详见 [VideoSourceType](/zh-CN/api-reference/rtc/harmonyos/enum-videosourcetype)。
本地视频流统计信息。详见 [LocalVideoStats](/zh-CN/api-reference/rtc/harmonyos/class-localvideostats)。
### 所属接口类 [#所属接口类-10]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onRemoteVideoStateChanged [#onremotevideostatechanged]
远端视频状态发生改变回调。
```ts
onRemoteVideoStateChanged ? : (uid:number, state: Constants.RemoteVideoStreamState, reason: Constants.RemoteVideoStreamReason, elapsed:number) => void
```
### 详情 [#详情-4]
:::caution
注意: 频道内的用户(通信场景)或主播(直播场景)人数超过 32 人时,该回调可能不准确。
:::
### 参数 [#参数-9]
发生视频状态改变的远端用户 ID。
远端视频流状态,详见 [RemoteVideoStreamState](/zh-CN/api-reference/rtc/harmonyos/enum-remotevideostate)。
远端视频流状态改变的具体原因,详见 [RemoteVideoStreamReason](/zh-CN/api-reference/rtc/harmonyos/enum-remotevideostatereason)。
从本地用户调用 joinChannelWithOptions 方法到发生本事件经历的时间,单位为毫秒。
### 所属接口类 [#所属接口类-11]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onRemoteVideoStats [#onremotevideostats]
通话中远端视频流的统计信息回调。
```ts
onRemoteVideoStats?:(stats:RemoteVideoStats) =>void;
```
### 详情 [#详情-5]
该回调描述远端用户在通话中端到端的视频流统计信息, 针对每个远端用户/主播每 2 秒触发一次。如果远端同时存在多个用户/主播, 该回调每 2 秒会被触发多次。
### 参数 [#参数-10]
远端视频统计数据。详见 [RemoteVideoStats](/zh-CN/api-reference/rtc/harmonyos/class-remotevideostats)。
### 所属接口类 [#所属接口类-12]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onUserEnableVideo [#onuserenablevideo]
远端用户开/关视频模块回调。
```ts
onUserEnableVideo?:(uid:number, enabled:boolean) => void;
```
### 详情 [#详情-6]
关闭视频功能是指该用户只能进行语音通话,不能显示、发送自己的视频,也不能接收、显示别人的视频。
该回调是由远端用户调用 [enableVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_enablevideo) 或 [disableVideo](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_disablevideo) 方法开启或关闭视频模块触发的。
### 参数 [#参数-11]
用户 ID,提示是哪个用户的视频流。
- `true`: 该用户已启用视频功能。
- `false`: 该用户已关闭视频功能。
### 所属接口类 [#所属接口类-13]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onUserMuteVideo [#onusermutevideo]
远端用户取消或恢复发布视频流回调。
```ts
onUserMuteVideo?:(uid:number,muted:boolean) =>void;
```
### 详情 [#详情-7]
当远端用户调用 [muteLocalVideoStream](/zh-CN/api-reference/rtc/harmonyos/publishnsubscribe#api_irtcengine_mutelocalvideostream) 取消或恢复发布视频流时,SDK 会触发该回调向本地用户报告远端用户的发流状况。
:::caution
注意: 当频道内的用户(通信场景)或主播(直播场景)的人数超过 32 人时,该回调可能不准确。
:::
### 参数 [#参数-12]
远端用户 ID。
远端用户是否取消发布视频流:
- `true`: 取消发布视频流。
- `false`: 发布视频流。
### 所属接口类 [#所属接口类-14]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onVideoPublishStateChanged [#onvideopublishstatechanged]
视频发布状态改变回调。
```ts
onVideoPublishStateChanged?:(source:Constants.VideoSourceType, channel:string, oldState:Constants.StreamPublishState, newState:Constants.StreamPublishState, elapseSinceLastState:number) => void;
```
### 参数 [#参数-13]
之前的发布状态,详见 [StreamPublishState](/zh-CN/api-reference/rtc/harmonyos/enum-streampublishstate)。
当前的发布状态,详见 StreamPublishState。
两次状态变化时间间隔(毫秒)。
频道名。
视频源的类型。详见 [VideoSourceType](/zh-CN/api-reference/rtc/harmonyos/enum-videosourcetype)。
### 所属接口类 [#所属接口类-15]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)
## onVideoSizeChanged [#onvideosizechanged]
本地或远端视频大小和旋转信息发生改变回调。
```ts
onVideoSizeChanged?:(source:Constants.VideoSourceType, uid:number, width:number, height:number, rotation:number) => void
```
### 参数 [#参数-14]
视频源的类型。详见 [VideoSourceType](/zh-CN/api-reference/rtc/harmonyos/enum-videosourcetype)。
图像尺寸和旋转信息发生变化的用户 ID(本地用户的 uid 为 0。此时视频为本地用户的视频预览)。
视频流的宽度(像素)。
视频流的高度(像素)。
旋转信息,取值范围 [0,360)。
### 所属接口类 [#所属接口类-16]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengineeventhandler)