移动端摄像头管理

enableMultiCamera

开启或关闭多路摄像头采集。

C++
#if defined(__APPLE__) && TARGET_OS_IOS
    virtual int enableMultiCamera(bool enabled, const CameraCapturerConfiguration& config) = 0;
#endif

自从

v4.1.0

在已有摄像头采集视频的场景下，声网推荐你采用以下步骤实现多路摄像头采集、发布视频：

调用该方法开启多路摄像头采集。
调用 startPreview [2/2] 开启本地视频预览。
调用 startCameraCapture 并设置 sourceType 指定第二个摄像头开始采集。
调用 joinChannelEx 并设置 publishSecondaryCameraTrack 为 true，在频道内发布第二路摄像头采集的视频流。

如果要关闭多路摄像头采集，可参考以下步骤：

调用 stopCameraCapture。
调用该方法并将 enabled 设置为 false。

注：你可以在 startPreview [2/2] 前后调用该方法开启多摄像头采集：

如果在 startPreview [2/2] 之前开启，则本地视频预览会同时出现两个摄像头采集的画面。
如果在 startPreview [2/2] 之后开启，SDK 会先停止当前的摄像头采集，然后再开启原摄像头和第二个摄像头，本地视频预览会出现短暂黑屏、然后自动恢复正常。

该方法仅适用于 iOS。

使用多路摄像头采集视频时，请确保系统版本为 13.0 及以上。

支持多路摄像头采集的最低 iOS 设备类型如下所示：

iPhone XR
iPhone XS
iPhone XS Max
iPad Pro (第三代及以上)

参数

参数名描述

参数名	描述
enabled	是否开启多摄像头视频采集模式： `true`：开启多摄像头采集模式，SDK 使用多路摄像头采集视频。 `false`：关闭多摄像头采集模式，SDK 仅使用单路摄像头采集视频。
config	第二个摄像头的采集配置。详见 `CameraCapturerConfiguration`。

enabled

是否开启多摄像头视频采集模式：

true：开启多摄像头采集模式，SDK 使用多路摄像头采集视频。
false：关闭多摄像头采集模式，SDK 仅使用单路摄像头采集视频。

config

第二个摄像头的采集配置。详见 CameraCapturerConfiguration。

返回值

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

所属接口类

IRtcEngine

getCameraMaxZoomFactor

获取摄像头支持最大缩放比例。

C++
virtual float getCameraMaxZoomFactor() = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

设备摄像头支持的最大缩放比例。

所属接口类

IRtcEngine

isCameraAutoExposureFaceModeSupported

检测设备是否支持自动曝光功能。

C++
virtual bool isCameraAutoExposureFaceModeSupported() = 0;

注意：

该方法仅适用于 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

true: 设备支持自动曝光功能。
false: 设备不支持自动曝光功能。

所属接口类

IRtcEngine

isCameraAutoFocusFaceModeSupported

检测设备是否支持人脸对焦功能。

C++
virtual bool isCameraAutoFocusFaceModeSupported() = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

true: 设备支持人脸对焦功能。
false: 设备不支持人脸对焦功能。

所属接口类

IRtcEngine

isCameraExposurePositionSupported

检测设备是否支持手动曝光功能。

C++
virtual bool isCameraExposurePositionSupported() = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

true: 设备支持手动曝光功能。
false: 设备不支持手动曝光功能。

所属接口类

IRtcEngine

isCameraExposureSupported

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

C++
virtual bool isCameraExposureSupported() = 0;

自从

v4.2.2

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。
建议你在调用 setCameraExposureFactor 调节曝光系数前，先调用该方法查询当前摄像头是否支持曝光调节。
当你调用该方法时，查询的是当前正在使用的摄像头是否支持曝光调节，即调用 setCameraCapturerConfiguration 时指定的摄像头。

返回值

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

所属接口类

IRtcEngine

isCameraFaceDetectSupported

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

C++
virtual bool isCameraFaceDetectSupported() = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

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

所属接口类

IRtcEngine

isCameraFocusSupported

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

C++
virtual bool isCameraFocusSupported() = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

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

所属接口类

IRtcEngine

isCameraTorchSupported

检测设备是否支持闪光灯常开。

C++
virtual bool isCameraTorchSupported() = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。
一般情况下，app 默认开启前置摄像头，因此如果你的前置摄像头不支持闪光灯常开，直接使用该方法会返回 false。如果需要检查后置摄像头是否支持闪光灯常开，需要先使用 switchCamera 切换摄像头，再使用该方法。
在系统版本 15 的 iPad 上，即使 isCameraTorchSupported 返回 true，也可能因系统问题导致你无法通过 setCameraTorchOn 成功开启闪光灯。

返回值

true: 设备支持闪光灯常开。
false: 设备不支持闪光灯常开。

所属接口类

IRtcEngine

isCameraZoomSupported

检测设备是否支持摄像头缩放功能。

C++
virtual bool isCameraZoomSupported() = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

true: 设备支持相机缩放功能。
false: 设备不支持相机缩放功能。

所属接口类

IRtcEngine

setCameraAutoExposureFaceModeEnabled

设置是否开启自动曝光功能。

C++
virtual int setCameraAutoExposureFaceModeEnabled(bool enabled) = 0;

注意：

该方法仅适用于 iOS。
该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

参数

参数名描述

参数名	描述
enabled	是否开启自动曝光： `true`: 开启自动曝光。 `false`: 关闭自动曝光。

enabled

是否开启自动曝光：

true: 开启自动曝光。
false: 关闭自动曝光。

返回值

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

所属接口类

IRtcEngine

setCameraAutoFocusFaceModeEnabled

设置是否开启人脸对焦功能。

C++
virtual int setCameraAutoFocusFaceModeEnabled(bool enabled) = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

参数

参数名描述

参数名	描述
enabled	是否开启人脸对焦： `true`: 开启人脸对焦功能。 `false`: 关闭人脸对焦功能。

enabled

是否开启人脸对焦：

true: 开启人脸对焦功能。
false: 关闭人脸对焦功能。

返回值

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

所属接口类

IRtcEngine

setCameraCapturerConfiguration

设置摄像头采集配置。

C++
virtual int setCameraCapturerConfiguration(const CameraCapturerConfiguration& config) = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在开启摄像头后调用，如 startPreview [2/2] 和 enableVideo 后调用。

参数

参数名	描述
config	摄像头采集配置，详见 `CameraCapturerConfiguration`。注：在该方法中，不需要设置 `deviceId` 参数。

返回值

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

所属接口类

IRtcEngine

setCameraExposureFactor

设置当前摄像头的曝光系数。

C++
virtual int setCameraExposureFactor(float factor) = 0;

自从

v4.2.2

当拍摄环境光线不足或过于明亮时，会影响视频采集的画质。为了获得更好的视频效果，你可以使用该方法调节摄像头的曝光系数。

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。
建议你在调用该方法前，先调用 isCameraExposureSupported 查询当前摄像头是否支持调节曝光系数。
当你调用该方法时，设置的是当前正在使用的摄像头的曝光系数，即调用 setCameraCapturerConfiguration 时指定的摄像头。

参数

参数名	描述
factor	摄像头的曝光系数。默认值为 0，表示使用摄像头的默认曝光量。取值越大，曝光量越大。视频图像过曝时，你可以降低曝光系数；视频图像欠曝且暗部细节丢失时，你可以增加曝光系数。如果你指定的曝光系数超出设备支持的范围，SDK 会自动调节为设备实际支持的范围。在 Android 平台上，取值范围为 [-20.0,20.0]；在 iOS 平台上，取值范围为 [-8.0,8.0]。

参数名

描述

factor

摄像头的曝光系数。默认值为 0，表示使用摄像头的默认曝光量。取值越大，曝光量越大。视频图像过曝时，你可以降低曝光系数；视频图像欠曝且暗部细节丢失时，你可以增加曝光系数。如果你指定的曝光系数超出设备支持的范围，SDK 会自动调节为设备实际支持的范围。

在 Android 平台上，取值范围为 [-20.0,20.0]；在 iOS 平台上，取值范围为 [-8.0,8.0]。

返回值

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

所属接口类

IRtcEngine

setCameraExposurePosition

设置手动曝光位置。

C++
virtual int setCameraExposurePosition(float positionXinView, float positionYinView) = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。
成功调用该方法后，本地会触发 onCameraExposureAreaChanged 回调。

参数

参数名	描述
positionXinView	触摸点相对于视图的横坐标。
positionYinView	触摸点相对于视图的纵坐标。

返回值

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

所属接口类

IRtcEngine

setCameraFocusPositionInPreview

设置手动对焦位置，并触发对焦。

C++
virtual int setCameraFocusPositionInPreview(float positionX, float positionY) = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。
成功调用该方法后，本地会触发 onCameraFocusAreaChanged 回调。

参数

参数名	描述
positionX	触摸点相对于视图的横坐标。
positionY	触摸点相对于视图的纵坐标。

返回值

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

所属接口类

IRtcEngine

setCameraTorchOn

设置是否打开闪光灯。

C++
virtual int setCameraTorchOn(bool isOn) = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

参数

参数名	描述
isOn	是否打开闪光灯： `true`: 打开闪光灯。 `false`:（默认）关闭闪光灯。

返回值

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

所属接口类

IRtcEngine

setCameraZoomFactor

设置摄像头缩放比例。

C++
virtual int setCameraZoomFactor(float factor) = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

方法调用成功: 返回设置的 factor 值。
方法调用失败: 返回值 < 0。

所属接口类

IRtcEngine

switchCamera

切换前置/后置摄像头。

C++
virtual int switchCamera() = 0;

注意：

该方法仅适用于 Android 和 iOS。
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 LOCAL_VIDEO_STREAM_STATE_CAPTURING (1) 后。

返回值

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

所属接口类

IRtcEngine

onCameraExposureAreaChanged

摄像头曝光区域已改变回调。

C++
virtual void onCameraExposureAreaChanged(int x, int y, int width, int height) {
     (void)x;
     (void)y;
     (void)width;
     (void)height;
     }

该回调是由本地用户调用 setCameraExposurePosition 方法改变曝光位置触发的。

注意：该回调仅适用于 Android 和 iOS。

参数

参数名	描述
x	发生改变的曝光区域的 x 坐标。
y	发生改变的曝光区域的 y 坐标。
width	发生改变的曝光区域的宽度。
height	发生改变的曝光区域的高度。

所属接口类

IRtcEngineEventHandler

onCameraFocusAreaChanged

相机对焦区域已改变回调。

C++
virtual void onCameraFocusAreaChanged(int x, int y, int width, int height) {
     (void)x;
     (void)y;
     (void)width;
     (void)height;
     }

注意：该回调仅适用于 Android 和 iOS。

参数

参数名	描述
x	发生改变的对焦区域的 x 坐标。
y	发生改变的对焦区域的 y 坐标。
width	发生改变的对焦区域的宽度。
height	发生改变的对焦区域的高度。

所属接口类

IRtcEngineEventHandler

onCameraReady

摄像头就绪回调。

C++
virtual void onCameraReady()

弃用:

请改用 onLocalVideoStateChanged 中的 LOCAL_VIDEO_STREAM_STATE_CAPTURING(1)。

该回调提示已成功打开摄像头，可以开始捕获视频。

所属接口类

IRtcEngineEventHandler

enableMultiCamera

参数​

返回值​

getCameraMaxZoomFactor

返回值​

isCameraAutoExposureFaceModeSupported

返回值​

isCameraAutoFocusFaceModeSupported

返回值​

isCameraExposurePositionSupported

返回值​

isCameraExposureSupported

返回值​

isCameraFaceDetectSupported

返回值​

isCameraFocusSupported

返回值​

isCameraTorchSupported

返回值​

isCameraZoomSupported

返回值​

setCameraAutoExposureFaceModeEnabled

参数​

返回值​

setCameraAutoFocusFaceModeEnabled

参数​

返回值​

setCameraCapturerConfiguration

参数​

返回值​

setCameraExposureFactor

参数​

返回值​

setCameraExposurePosition

参数​

返回值​

setCameraFocusPositionInPreview

参数​

返回值​

setCameraTorchOn

参数​

返回值​

setCameraZoomFactor

返回值​

switchCamera

返回值​

onCameraExposureAreaChanged

参数​

onCameraFocusAreaChanged

参数​

onCameraReady

参数

返回值

返回值

返回值

返回值

返回值

返回值

返回值

返回值

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

返回值

参数

参数