# 视频设备管理 (/zh-CN/api-reference/rtc/android/4.6.0/device-management/video-device)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## getCameraMaxZoomFactor [#getcameramaxzoomfactor]
获取摄像头支持的最大变焦倍数。
```java
public abstract float getCameraMaxZoomFactor();
```
:::info[注]
你必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后调用该方法。
:::
### 返回值 [#返回值]
方法调用成功,返回摄像头支持的最大变焦倍数。
### 所属接口类 [#所属接口类]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## isCameraAutoFocusFaceModeSupported [#iscameraautofocusfacemodesupported]
检查设备是否支持人脸自动对焦功能。
```java
public abstract boolean isCameraAutoFocusFaceModeSupported();
```
:::info[注]
你必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后调用该方法。
:::
### 返回值 [#返回值-1]
- true:设备支持人脸自动对焦功能。
- false:设备不支持人脸自动对焦功能。
### 所属接口类 [#所属接口类-1]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## isCameraExposurePositionSupported [#iscameraexposurepositionsupported]
检查设备是否支持手动曝光。
```java
public abstract boolean isCameraExposurePositionSupported();
```
#### `自从` [#自从]
自 v2.3.2 版本新增。
:::info[注]
你必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后调用该方法。
:::
### 返回值 [#返回值-2]
- true:设备支持手动曝光。
- false:设备不支持手动曝光。
### 所属接口类 [#所属接口类-2]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## isCameraExposureSupported [#iscameraexposuresupported]
查询当前摄像头是否支持调节曝光值。
```java
public abstract boolean isCameraExposureSupported();
```
#### `自从` [#自从-1]
自 v4.2.2 版本新增。
:::info[注]
该方法必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后调用。在调用 [setCameraExposureFactor](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameraexposurefactor) 之前,建议先调用该方法查询当前摄像头是否支持调节曝光值。该方法会调节当前激活摄像头的曝光值,即调用 [setCameraCapturerConfiguration](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 时指定的摄像头。
:::
### 返回值 [#返回值-3]
- true:当前摄像头支持调节曝光值。
- false:当前摄像头不支持调节曝光值。
### 所属接口类 [#所属接口类-3]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## isCameraFaceDetectSupported [#iscamerafacedetectsupported]
检查设备摄像头是否支持人脸检测。
```java
public abstract boolean isCameraFaceDetectSupported();
```
### 返回值 [#返回值-4]
- true:设备摄像头支持人脸检测。
- false:设备摄像头不支持人脸检测。
### 所属接口类 [#所属接口类-4]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## isCameraFocusSupported [#iscamerafocussupported]
检查设备是否支持手动对焦功能。
```java
public abstract boolean isCameraFocusSupported();
```
:::info[注]
你必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后调用该方法。
:::
### 返回值 [#返回值-5]
- true:设备支持手动对焦功能。
- false:设备不支持手动对焦功能。
### 所属接口类 [#所属接口类-5]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## isCameraTorchSupported [#iscameratorchsupported]
检查设备是否支持相机闪光灯功能。
```java
public abstract boolean isCameraTorchSupported();
```
:::info[注]
你必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后调用该方法。App 默认启用前置摄像头。如果前置摄像头不支持闪光灯,该方法返回 false。如果你想检查后置摄像头是否支持闪光灯功能,请在调用该方法前调用 `switchCamera`。
:::
### 返回值 [#返回值-6]
- true:设备支持相机闪光灯功能。
- false:设备不支持相机闪光灯功能。
### 所属接口类 [#所属接口类-6]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## isCameraZoomSupported [#iscamerazoomsupported]
检查设备是否支持摄像头变焦。
```java
public abstract boolean isCameraZoomSupported();
```
### 调用时机 [#调用时机]
必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后调用。
### 返回值 [#返回值-7]
- true:设备支持摄像头变焦。
- false:设备不支持摄像头变焦。
### 所属接口类 [#所属接口类-7]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## queryCameraFocalLengthCapability [#querycamerafocallengthcapability]
查询摄像头支持的焦距能力。
```java
public abstract AgoraFocalLengthInfo[] queryCameraFocalLengthCapability();
```
建议在启用广角或超广角模式进行视频采集前,调用该方法检查设备是否支持所需的焦距能力。根据查询结果调用 [setCameraCapturerConfiguration](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameracapturerconfiguration) 方法调整摄像头的焦距配置,以确保最佳的视频采集性能。
### 返回值 [#返回值-8]
- 方法调用成功,返回 AgoraFocalLengthInfo 对象数组,包含摄像头的方向和焦距类型。
- 方法调用失败,返回空数组。
### 所属接口类 [#所属接口类-8]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## queryCodecCapability [#querycodeccapability]
查询 SDK 的视频编解码能力。
```java
public abstract CodecCapInfo[] queryCodecCapability();
```
### 返回值 [#返回值-9]
方法调用成功,返回 [CodecCapInfo](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-codeccapinfo) 数组,表示设备的视频编码能力。方法调用超时,请修改调用逻辑,避免在主线程中调用该方法。
### 所属接口类 [#所属接口类-9]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setCameraAutoFocusFaceModeEnabled [#setcameraautofocusfacemodeenabled]
启用或关闭摄像头人脸自动对焦功能。
```java
public abstract int setCameraAutoFocusFaceModeEnabled(boolean enabled);
```
### 调用时机 [#调用时机-1]
必须在 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后调用。
### 参数 [#参数]
#### `enabled` [#enabled]
是否启用人脸自动对焦功能:
- true:启用摄像头人脸自动对焦功能。
- false:关闭摄像头人脸自动对焦功能。
### 返回值 [#返回值-10]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-10]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setCameraCapturerConfiguration [#setcameracapturerconfiguration]
设置摄像头采集配置。
```java
public abstract int setCameraCapturerConfiguration(CameraCapturerConfiguration config);
```
该方法需要在启用本地视频采集前调用,例如调用 `startPreview` 或 `joinChannel` 之前。
:::info[注]
如需调整摄像头焦距配置,建议先调用 [queryCameraFocalLengthCapability](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 查询设备的焦距能力,并根据查询结果进行设置。由于部分 Android 设备的限制,即使根据 [queryCameraFocalLengthCapability](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_querycamerafocallengthcapability) 返回的结果设置了焦距类型,设置也可能不生效。
:::
### 调用时机 [#调用时机-2]
该方法需要在启用本地视频采集前调用,例如调用 `startPreview` 或 `joinChannel` 之前。
### 参数 [#参数-1]
#### `config` [#config]
摄像头采集配置。详见 [CameraCapturerConfiguration](/zh-CN/api-reference/rtc/android/class-and-enum/classes/class-cameracapturerconfiguration)。
### 返回值 [#返回值-11]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-11]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setCameraExposureFactor [#setcameraexposurefactor]
设置摄像头曝光值。
```java
public abstract int setCameraExposureFactor(int factor);
```
#### `自从` [#自从-2]
自 v4.2.2 版本新增。
注:
- 你必须在调用 enableVideo 后再调用此方法。设置结果将在摄像头成功开启后生效,即 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1)后。
- 在调用此方法前,声网建议调用 isCameraExposureSupported 检查当前摄像头是否支持调整曝光值。
- 通过调用此方法,你可以调整当前激活摄像头的曝光值,即调用 setCameraCapturerConfiguration 时指定的摄像头。
### 参数 [#参数-2]
#### `factor` [#factor]
摄像头曝光值。默认值为 0,表示使用摄像头的默认曝光值。值越大,曝光越强。当视频图像过曝时,可以降低曝光值;当视频图像曝光不足且暗部细节丢失时,可以提高曝光值。如果设置的曝光值超出设备支持的范围,SDK 会自动将其调整为设备实际支持的范围。取值范围为 [-20, 20]。
### 返回值 [#返回值-12]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-12]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setCameraExposurePosition [#setcameraexposureposition]
设置摄像头曝光位置。
```java
public abstract int setCameraExposurePosition(float positionXinView, float positionYinView);
```
#### `自从` [#自从-3]
自 v2.3.2 版本新增。
:::info[注]
你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_enablevideo) 方法之后再调用此方法。设置结果会在摄像头成功开启后生效,即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后生效。成功调用该方法后,SDK 会触发 [onCameraExposureAreaChanged](/zh-CN/api-reference/rtc/android/device-management/video-device#callback_irtcengineeventhandler_oncameraexposureareachanged) 回调。
:::
### 参数 [#参数-3]
#### `positionXinView` [#positionxinview]
视图中触摸点的水平坐标。
#### `positionYinView` [#positionyinview]
视图中触摸点的垂直坐标。
### 返回值 [#返回值-13]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-13]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setCameraFocusPositionInPreview [#setcamerafocuspositioninpreview]
设置摄像头的手动对焦位置。
```java
public abstract int setCameraFocusPositionInPreview(float positionX, float positionY);
```
:::info[注]
你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_enablevideo) 之后再调用此方法。设置结果会在摄像头成功开启后生效,即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后生效。成功调用该方法后,SDK 会触发 [onCameraFocusAreaChanged](/zh-CN/api-reference/rtc/android/device-management/video-device#callback_irtcengineeventhandler_oncamerafocusareachanged) 回调。
:::
### 参数 [#参数-4]
#### `positionX` [#positionx]
视图中触摸点的水平坐标。
#### `positionY` [#positiony]
视图中触摸点的垂直坐标。
### 返回值 [#返回值-14]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-14]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setCameraTorchOn [#setcameratorchon]
打开或关闭摄像头闪光灯。
```java
public abstract int setCameraTorchOn(boolean isOn);
```
:::info[注]
你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_enablevideo) 之后再调用此方法。设置结果会在摄像头成功开启后生效,即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后。
:::
### 参数 [#参数-5]
#### `isOn` [#ison]
是否打开摄像头闪光灯:
- true:打开闪光灯。
- false:(默认)关闭闪光灯。
### 返回值 [#返回值-15]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-15]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## setCameraZoomFactor [#setcamerazoomfactor]
设置摄像头的缩放因子。
```java
public abstract int setCameraZoomFactor(float factor);
```
:::info[注]
你必须在调用 [enableVideo](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_enablevideo) 之后再调用此方法。该设置在摄像头成功开启后生效,即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)后。
:::
### 参数 [#参数-6]
#### `factor` [#factor-1]
摄像头缩放因子。你可以通过调用 [getCameraMaxZoomFactor](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_getcameramaxzoomfactor) 获取设备支持的最大缩放因子。
### 返回值 [#返回值-16]
- 方法调用成功,返回摄像头缩放因子 factor 的值。
- 方法调用失败,返回小于 0 的值。
### 所属接口类 [#所属接口类-16]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## switchCamera [1/2] [#switchcamera-12]
切换前置和后置摄像头。
```java
public abstract int switchCamera();
```
你可以调用该方法在应用运行过程中根据实际可用的摄像头动态切换前置或后置摄像头,无需重启视频流或重新配置视频源。该方法与 `switchCamera` (带参数版本)都可用于切换摄像头。不同之处在于, `switchCamera(String cameraId)` 通过指定摄像头 ID 切换到特定摄像头,而本方法则切换摄像头的方向(前置或后置)。
:::info[注]
该方法仅用于切换由第一个摄像头采集的视频流的摄像头,即调用 [startCameraCapture](/zh-CN/api-reference/rtc/android/video/camera-capture#api_irtcengine_startcameracapture) 时视频源设置为 `VIDEO_SOURCE_CAMERA_PRIMARY` (0)的视频流。
:::
### 调用时机 [#调用时机-3]
必须在摄像头成功启用后调用,即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)之后。
### 返回值 [#返回值-17]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-17]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## switchCamera [2/2] [#switchcamera-22]
通过摄像头 ID 切换摄像头。
```java
public abstract int switchCamera(String cameraId);
```
你可以调用该方法在应用运行过程中根据实际可用的摄像头动态切换摄像头,无需重启视频流或重新配置视频源。该方法与 `switchCamera` 功能类似,区别在于: `switchCamera` 切换的是摄像头方向(前置或后置),而该方法通过指定摄像头 ID 切换到特定摄像头。
:::info[注]
该方法仅用于切换由第一个摄像头采集的视频流,即调用 [startCameraCapture](/zh-CN/api-reference/rtc/android/video/camera-capture#api_irtcengine_startcameracapture) 时视频源设置为 `VIDEO_SOURCE_CAMERA_PRIMARY` (0)的视频流。
:::
### 调用时机 [#调用时机-4]
必须在摄像头成功启用后调用,即 SDK 触发 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged) 回调并返回本地视频状态为 `LOCAL_VIDEO_STREAM_STATE_CAPTURING` (1)之后。
### 参数 [#参数-7]
#### `cameraId` [#cameraid]
摄像头 ID。你可以通过 Android 原生系统 API 获取摄像头 ID,例如 `Camera.open` 和 `CameraManager.getCameraIdList`。
### 返回值 [#返回值-18]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/realtime-media/rtc/reference/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [RtcEngine](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengine)
## onCameraExposureAreaChanged [#oncameraexposureareachanged]
摄像头曝光区域发生变化回调。
```java
public void onCameraExposureAreaChanged(Rect rect)
```
当本地用户调用 [setCameraExposurePosition](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameraexposureposition) 更改摄像头曝光位置时,SDK 会触发该回调。
### 触发时机 [#触发时机]
该回调在调用 [setCameraExposurePosition](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcameraexposureposition) 更改摄像头曝光位置时被触发。
### 参数 [#参数-8]
#### `rect` [#rect]
本地预览中的曝光矩形区域。详见 [`Rect`](https://developer.android.google.cn/reference/android/graphics/Rect)。
### 所属接口类 [#所属接口类-19]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)
## onCameraFocusAreaChanged [#oncamerafocusareachanged]
摄像头对焦区域发生变化的回调。
```java
public void onCameraFocusAreaChanged(Rect rect)
```
当本地用户调用 [setCameraFocusPositionInPreview](/zh-CN/api-reference/rtc/android/device-management/video-device#api_irtcengine_setcamerafocuspositioninpreview) 更改摄像头对焦位置时,SDK 会触发该回调。
### 参数 [#参数-9]
#### `rect` [#rect-1]
本地预览中的对焦矩形区域。详见 [`Rect`](https://developer.android.google.cn/reference/android/graphics/Rect)。
### 所属接口类 [#所属接口类-20]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)
## onCameraReady [#oncameraready]
摄像头开启并准备好采集视频时触发的回调。
```java
public void onCameraReady() {}
```
#### `废弃` [#废弃]
该方法已废弃,请改用 [onLocalVideoStateChanged](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onlocalvideostatechanged)。
### 触发时机 [#触发时机-1]
该回调在摄像头成功开启并准备好采集视频时被触发。
### 所属接口类 [#所属接口类-21]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/android/full-sdk-api-list#class_irtcengineeventhandler)