视频设备管理

getCameraMaxZoomFactor

获取摄像头支持的最大变焦倍数。

Java

public abstract float getCameraMaxZoomFactor();

信息

你必须在 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后调用该方法。

返回值

方法调用成功，返回摄像头支持的最大变焦倍数。

所属接口类

• RtcEngine

isCameraAutoFocusFaceModeSupported

检查设备是否支持人脸自动对焦功能。

Java

public abstract boolean isCameraAutoFocusFaceModeSupported();

信息

你必须在 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后调用该方法。

返回值

• true：设备支持人脸自动对焦功能。
• false：设备不支持人脸自动对焦功能。

所属接口类

• RtcEngine

isCameraExposurePositionSupported

检查设备是否支持手动曝光。

Java

public abstract boolean isCameraExposurePositionSupported();

自从

自 v2.3.2 版本新增。

信息

你必须在 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后调用该方法。

返回值

• true：设备支持手动曝光。
• false：设备不支持手动曝光。

所属接口类

• RtcEngine

isCameraExposureSupported

查询当前摄像头是否支持调节曝光值。

Java

public abstract boolean isCameraExposureSupported();

自从

自 v4.2.2 版本新增。

信息

该方法必须在 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后调用。在调用 setCameraExposureFactor 之前，建议先调用该方法查询当前摄像头是否支持调节曝光值。该方法会调节当前激活摄像头的曝光值，即调用 setCameraCapturerConfiguration 时指定的摄像头。

返回值

• true：当前摄像头支持调节曝光值。
• false：当前摄像头不支持调节曝光值。

所属接口类

• RtcEngine

isCameraFaceDetectSupported

检查设备摄像头是否支持人脸检测。

Java

public abstract boolean isCameraFaceDetectSupported();

返回值

• true：设备摄像头支持人脸检测。
• false：设备摄像头不支持人脸检测。

所属接口类

• RtcEngine

isCameraFocusSupported

检查设备是否支持手动对焦功能。

Java

public abstract boolean isCameraFocusSupported();

信息

你必须在 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后调用该方法。

返回值

• true：设备支持手动对焦功能。
• false：设备不支持手动对焦功能。

所属接口类

• RtcEngine

isCameraTorchSupported

检查设备是否支持相机闪光灯功能。

Java

public abstract boolean isCameraTorchSupported();

信息

你必须在 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后调用该方法。App 默认启用前置摄像头。如果前置摄像头不支持闪光灯，该方法返回 false。如果你想检查后置摄像头是否支持闪光灯功能，请在调用该方法前调用 switchCamera。

返回值

• true：设备支持相机闪光灯功能。
• false：设备不支持相机闪光灯功能。

所属接口类

• RtcEngine

isCameraZoomSupported

检查设备是否支持摄像头变焦。

Java

public abstract boolean isCameraZoomSupported();

调用时机

必须在 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后调用。

返回值

• true：设备支持摄像头变焦。
• false：设备不支持摄像头变焦。

所属接口类

• RtcEngine

queryCameraFocalLengthCapability

查询摄像头支持的焦距能力。

Java

public abstract AgoraFocalLengthInfo[] queryCameraFocalLengthCapability();

建议在启用广角或超广角模式进行视频采集前，调用该方法检查设备是否支持所需的焦距能力。根据查询结果调用 setCameraCapturerConfiguration 方法调整摄像头的焦距配置，以确保最佳的视频采集性能。

返回值

• 方法调用成功，返回 AgoraFocalLengthInfo 对象数组，包含摄像头的方向和焦距类型。
• 方法调用失败，返回空数组。

所属接口类

• RtcEngine

queryCodecCapability

查询 SDK 的视频编解码能力。

Java

public abstract CodecCapInfo[] queryCodecCapability();

返回值

方法调用成功，返回 CodecCapInfo 数组，表示设备的视频编码能力。方法调用超时，请修改调用逻辑，避免在主线程中调用该方法。

所属接口类

• RtcEngine

setCameraAutoFocusFaceModeEnabled

启用或关闭摄像头人脸自动对焦功能。

Java

public abstract int setCameraAutoFocusFaceModeEnabled(boolean enabled);

调用时机

必须在 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后调用。

参数

enabled

是否启用人脸自动对焦功能：

• true：启用摄像头人脸自动对焦功能。
• false：关闭摄像头人脸自动对焦功能。

返回值

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

所属接口类

• RtcEngine

setCameraCapturerConfiguration

设置摄像头采集配置。

Java

public abstract int setCameraCapturerConfiguration(CameraCapturerConfiguration config);

该方法需要在启用本地视频采集前调用，例如调用 startPreview 或 joinChannel 之前。

信息

如需调整摄像头焦距配置，建议先调用 queryCameraFocalLengthCapability 查询设备的焦距能力，并根据查询结果进行设置。由于部分 Android 设备的限制，即使根据 queryCameraFocalLengthCapability 返回的结果设置了焦距类型，设置也可能不生效。

调用时机

该方法需要在启用本地视频采集前调用，例如调用 startPreview 或 joinChannel 之前。

参数

config

摄像头采集配置。详见 CameraCapturerConfiguration。

返回值

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

所属接口类

• RtcEngine

setCameraExposureFactor

设置摄像头曝光值。

Java

public abstract int setCameraExposureFactor(int factor);

自从

自 v4.2.2 版本新增。

信息

• 你必须在调用 enableVideo 后再调用此方法。设置结果将在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后。
• 在调用此方法前，声网建议调用 isCameraExposureSupported 检查当前摄像头是否支持调整曝光值。
• 通过调用此方法，你可以调整当前激活摄像头的曝光值，即调用 setCameraCapturerConfiguration 时指定的摄像头。

参数

factor

摄像头曝光值。默认值为 0，表示使用摄像头的默认曝光值。值越大，曝光越强。当视频图像过曝时，可以降低曝光值；当视频图像曝光不足且暗部细节丢失时，可以提高曝光值。如果设置的曝光值超出设备支持的范围，SDK 会自动将其调整为设备实际支持的范围。取值范围为 [-20, 20]。

返回值

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

所属接口类

• RtcEngine

setCameraExposurePosition

设置摄像头曝光位置。

Java

public abstract int setCameraExposurePosition(float positionXinView, float positionYinView);

自从

自 v2.3.2 版本新增。

信息

你必须在调用 enableVideo 方法之后再调用此方法。设置结果会在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后生效。成功调用该方法后，SDK 会触发 onCameraExposureAreaChanged 回调。

参数

positionXinView

视图中触摸点的水平坐标。

positionYinView

视图中触摸点的垂直坐标。

返回值

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

所属接口类

• RtcEngine

setCameraFocusPositionInPreview

设置摄像头的手动对焦位置。

Java

public abstract int setCameraFocusPositionInPreview(float positionX, float positionY);

信息

你必须在调用 enableVideo 之后再调用此方法。设置结果会在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后生效。成功调用该方法后，SDK 会触发 onCameraFocusAreaChanged 回调。

参数

positionX

视图中触摸点的水平坐标。

positionY

视图中触摸点的垂直坐标。

返回值

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

所属接口类

• RtcEngine

setCameraTorchOn

打开或关闭摄像头闪光灯。

Java

public abstract int setCameraTorchOn(boolean isOn);

信息

你必须在调用 enableVideo 之后再调用此方法。设置结果会在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后。

参数

isOn

是否打开摄像头闪光灯：

• true：打开闪光灯。
• false：（默认）关闭闪光灯。

返回值

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

所属接口类

• RtcEngine

setCameraZoomFactor

设置摄像头的缩放因子。

Java

public abstract int setCameraZoomFactor(float factor);

信息

你必须在调用 enableVideo 之后再调用此方法。该设置在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）后。

参数

factor

摄像头缩放因子。你可以通过调用 getCameraMaxZoomFactor 获取设备支持的最大缩放因子。

返回值

• 方法调用成功，返回摄像头缩放因子 factor 的值。
• 方法调用失败，返回小于 0 的值。

所属接口类

• RtcEngine

switchCamera [1/2]

切换前置和后置摄像头。

Java

public abstract int switchCamera();

你可以调用该方法在应用运行过程中根据实际可用的摄像头动态切换前置或后置摄像头，无需重启视频流或重新配置视频源。该方法与 switchCamera（带参数版本）都可用于切换摄像头。不同之处在于，switchCamera(String cameraId) 通过指定摄像头 ID 切换到特定摄像头，而本方法则切换摄像头的方向（前置或后置）。

信息

该方法仅用于切换由第一个摄像头采集的视频流的摄像头，即调用 startCameraCapture 时视频源设置为 VIDEO_SOURCE_CAMERA_PRIMARY（0）的视频流。

调用时机

必须在摄像头成功启用后调用，即 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）之后。

返回值

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

所属接口类

• RtcEngine

switchCamera [2/2]

通过摄像头 ID 切换摄像头。

Java

public abstract int switchCamera(String cameraId);

你可以调用该方法在应用运行过程中根据实际可用的摄像头动态切换摄像头，无需重启视频流或重新配置视频源。该方法与 switchCamera 功能类似，区别在于：switchCamera 切换的是摄像头方向（前置或后置），而该方法通过指定摄像头 ID 切换到特定摄像头。

信息

该方法仅用于切换由第一个摄像头采集的视频流，即调用 startCameraCapture 时视频源设置为 VIDEO_SOURCE_CAMERA_PRIMARY（0）的视频流。

调用时机

必须在摄像头成功启用后调用，即 SDK 触发 onLocalVideoStateChanged 回调并返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING（1）之后。

参数

cameraId

摄像头 ID。你可以通过 Android 原生系统 API 获取摄像头 ID，例如 Camera.open 和 CameraManager.getCameraIdList。

返回值

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

所属接口类

• RtcEngine

onCameraExposureAreaChanged

摄像头曝光区域发生变化回调。

Java

public void onCameraExposureAreaChanged(Rect rect)

当本地用户调用 setCameraExposurePosition 更改摄像头曝光位置时，SDK 会触发该回调。

触发时机

该回调在调用 setCameraExposurePosition 更改摄像头曝光位置时被触发。

参数

rect

本地预览中的曝光矩形区域。详见 Rect。

所属接口类

• IRtcEngineEventHandler

onCameraFocusAreaChanged

摄像头对焦区域发生变化的回调。

Java

public void onCameraFocusAreaChanged(Rect rect)

当本地用户调用 setCameraFocusPositionInPreview 更改摄像头对焦位置时，SDK 会触发该回调。

参数

rect

本地预览中的对焦矩形区域。详见 Rect。

所属接口类

• IRtcEngineEventHandler

onCameraReady

摄像头开启并准备好采集视频时触发的回调。

Java

public void onCameraReady() {}

废弃

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

触发时机

该回调在摄像头成功开启并准备好采集视频时被触发。

所属接口类

• IRtcEngineEventHandler