视频设备管理
- Flutter
更新时间不可用
enableMultiCamera
开启或关闭多路摄像头采集。
Future<void> enableMultiCamera(
{required bool enabled, required CameraCapturerConfiguration config});在已有摄像头采集视频的场景下，声网推荐你采用以下步骤实现多路摄像头采集、发布视频：
- 调用该方法开启多路摄像头采集。
- 调用 startPreview 开启本地视频预览。
- 调用 startCameraCapture 并设置
sourceType指定第二个摄像头开始采集。 - 调用 joinChannelEx 并设置
publishSecondaryCameraTrack为 true，在频道内发布第二路摄像头采集的视频流。
如果要关闭多路摄像头采集，可参考以下步骤：
- 调用 stopCameraCapture。
- 调用该方法并将
enabled设置为 false。
该方法仅适用于 iOS。使用多路摄像头采集视频时，请确保系统版本为 13.0 及以上。支持多路摄像头采集的最低 iOS 设备类型如下所示：
- iPhone XR
- iPhone XS
- iPhone XS Max
- iPad Pro (第三代及以上)
注： 你可以在 startPreview 前后调用该方法开启多摄像头采集：
- 如果在 startPreview 之前开启，则本地视频预览会同时出现两个摄像头采集的画面。
- 如果在 startPreview 之后开启，SDK 会先停止当前的摄像头采集，然后再开启原摄像头和第二个摄像头，本地视频预览会出现短暂黑屏、然后自动恢复正常。
参数
| 参数名 | 描述 |
|---|---|
enabled | |
config | 第二个摄像头的采集配置。详见 CameraCapturerConfiguration。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
enumerateVideoDevices
获取系统中所有的视频设备列表。
List<VideoDeviceInfo> enumerateVideoDevices();注： 该方法仅适用于 Windows 和 macOS。
返回值
- 方法调用成功：返回一个 VideoDeviceInfo 数组，其中包含系统中所有视频设备。
- 方法调用失败: 返回空列表。
所属接口类
getCameraMaxZoomFactor
获取摄像头支持的最大放大倍率。
Future<double> getCameraMaxZoomFactor();注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为
localVideoStreamStateCapturing(1) 之后调用。
返回值
设备摄像头支持的最大放大倍率。
所属接口类
getCapability
获取视频采集设备在指定的视频格式下的详细视频帧信息。
Future<VideoFormat> getCapability(
{required String deviceIdUTF8, required int deviceCapabilityNumber});在调用 numberOfCapabilities 获取视频采集设备支持的视频格式数量后，你可以调用该方法获取指定索引号支持的具体视频帧信息。
注： 该方法仅适用于 Windows 和 macOS。
参数
| 参数名 | 描述 |
|---|---|
deviceIdUTF8 | |
deviceCapabilityNumber | 视频格式的索引号。如果 numberOfCapabilities 的返回值为 i，则该参数取值范围为[0,i)。 |
返回值
指定视频格式的具体信息，包括宽度（px），高度（px）和帧率（fps）。详见 VideoFormat。
所属接口类
getDevice
获取当前使用的视频采集设备。
Future<String> getDevice();注： 该方法仅适用于 Windows 和 macOS。
返回值
视频采集设备。
所属接口类
getVideoDeviceManager
获取 VideoDeviceManager 对象，以管理视频设备。
VideoDeviceManager getVideoDeviceManager();返回值
一个 VideoDeviceManager 对象。
所属接口类
isCameraAutoExposureFaceModeSupported
检测设备是否支持自动曝光功能。
Future<bool> isCameraAutoExposureFaceModeSupported();返回值
- true: 设备支持自动曝光功能。
- false: 设备不支持自动曝光功能。
所属接口类
isCameraAutoFocusFaceModeSupported
检测设备是否支持人脸对焦功能。
Future<bool> isCameraAutoFocusFaceModeSupported();注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为
localVideoStreamStateCapturing(1) 之后调用。
返回值
- true: 设备支持人脸对焦功能。
- false: 设备不支持人脸对焦功能。
所属接口类
isCameraExposurePositionSupported
检测设备是否支持手动曝光功能。
Future<bool> isCameraExposurePositionSupported();注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为
localVideoStreamStateCapturing(1) 之后调用。
返回值
- true: 设备支持手动曝光功能。
- false: 设备不支持手动曝光功能。
所属接口类
isCameraExposureSupported
查询当前摄像头是否支持曝光调节。
Future<bool> isCameraExposureSupported();注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为
localVideoStreamStateCapturing(1) 之后调用。 - 建议你在调用 setCameraExposureFactor 调节曝光系数前，先调用该方法查询当前摄像头是否支持曝光调节。
- 当你调用该方法时，查询的是当前正在使用的摄像头是否支持曝光调节，即调用 setCameraCapturerConfiguration 时指定的摄像头。
返回值
- true：方法调用成功。
- false：方法调用失败。详见错误码了解详情和解决建议。
所属接口类
isCameraFaceDetectSupported
检查设备摄像头是否支持人脸检测。
Future<bool> isCameraFaceDetectSupported();注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为
localVideoStreamStateCapturing(1) 之后调用。
返回值
- true: 设备摄像头支持人脸检测。
- false: 设备摄像头不支持人脸检测。
所属接口类
isCameraFocusSupported
检测设备是否支持手动对焦功能。
Future<bool> isCameraFocusSupported();注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为
localVideoStreamStateCapturing(1) 之后调用。
返回值
- true: 设备支持手动对焦功能。
- false: 设备不支持手动对焦功能。
所属接口类
isCameraTorchSupported
检测设备是否支持闪光灯常开。
Future<bool> isCameraTorchSupported();注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为
localVideoStreamStateCapturing(1) 之后调用。 - 一般情况下，App 默认开启前置摄像头，因此如果你的前置摄像头不支持闪光灯常开，直接使用该方法会返回
false。如果需要检查后置摄像头是否支持闪光灯常开，需要先使用 switchCamera 切换摄像头，再使用该方法。 - 在系统版本 15 的 iPad 上，即使 isCameraTorchSupported 返回 true，也可能因系统问题导致你无法通过 setCameraTorchOn 成功开启闪光灯。
返回值
- true: 设备支持闪光灯常开。
- false: 设备不支持闪光灯常开。
所属接口类
isCameraZoomSupported
检测设备是否支持摄像头缩放功能。
Future<bool> isCameraZoomSupported();注： 该方法仅适用于 Android 和 iOS。
调用时机
该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 localVideoStreamStateCapturing (1) 之后调用。
返回值
- true: 设备支持相机缩放功能。
- false: 设备不支持相机缩放功能。
所属接口类
numberOfCapabilities
获取指定视频采集设备支持的视频格式数量。
Future<void> numberOfCapabilities(String deviceIdUTF8);视频采集设备可能支持多种视频格式，每一种格式都支持不同的视频帧宽度、视频帧高度、帧率组合。 你可以通过调用该方法，获取指定的视频采集设备可支持多少种视频格式，然后调用 getCapability 获取指定视频格式下的具体视频帧信息。
注： 该方法仅适用于 Windows 和 macOS。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
- ≤ 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
queryCameraFocalLengthCapability
查询摄像头支持的焦距能力。
Future<List<FocalLengthInfo>> queryCameraFocalLengthCapability();如需开启摄像头广角、超广角拍摄模式，建议你先调用该方法查询设备是否具备相应的焦距能力，再根据查询结果调用 setCameraCapturerConfiguration 调整摄像头的焦距配置，以达到最佳的摄像头采集效果。
注： 该方法仅适用于 Android 和 iOS。
返回值
返回 FocalLengthInfo 对象数组，其中包含摄像头的方向和焦距类型。
所属接口类
queryCodecCapability
查询 SDK 支持的视频编解码能力。
Future<List<CodecCapInfo>> queryCodecCapability(int size);参数
| 参数名 | 描述 |
|---|---|
size | CodecCapInfo 的大小。 |
返回值
- 如果调用成功，则返回 CodecCapInfo 数组，表示 SDK 的视频编码能力。
- 如果调用超时，请修改调用逻辑，不要在主线程中调用该方法。
所属接口类
release
释放 VideoDeviceManager 对象占用的所有资源。
Future<void> release();注： 该方法仅适用于 Windows 和 macOS。
所属接口类
setCameraAutoExposureFaceModeEnabled
设置是否开启自动曝光功能。
Future<void> setCameraAutoExposureFaceModeEnabled(bool enabled);参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setCameraAutoFocusFaceModeEnabled
设置是否开启人脸对焦功能。
Future<void> setCameraAutoFocusFaceModeEnabled(bool enabled);SDK 默认在 Android 平台关闭人脸自动对焦，在 iOS 平台开启人脸自动对焦。如需自行设置人脸自动对焦，请调用该方法。
注： 该方法仅适用于 Android 和 iOS。
调用时机
该方法必须在 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 localVideoStreamStateCapturing (1) 之后调用。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setCameraCapturerConfiguration
设置摄像头采集配置。
Future<void> setCameraCapturerConfiguration(
CameraCapturerConfiguration config);注： 在调整摄像头的焦距配置前，建议先调用 queryCameraFocalLengthCapability 查询设备支持的焦距能力，再根据查询结果进行配置。 由于部分 Android 设备的限制，即使根据 queryCameraFocalLengthCapability 的查询结果设置焦距类型，设置结果也可能不生效。
调用时机
该方法必须在开启本地摄像头采集前调用，如 startPreview 和 joinChannel 前调用。
参数
| 参数名 | 描述 |
|---|---|
config |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
setCameraDeviceOrientation
设置采集视频的旋转角度。
Future<void> setCameraDeviceOrientation(
{required VideoSourceType type, required VideoOrientation orientation});注：
- 该方法仅适用于 Windows。
- 该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为
localVideoStreamStateCapturing(1) 后。 - 当视频采集设备不带重力感应功能时，你可以调用该方法手动调整采集到的视频画面的旋转角度。
参数
| 参数名 | 描述 |
|---|---|
type | 视频源类型，详见 VideoSourceType。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setCameraExposureFactor
设置当前摄像头的曝光系数。
Future<void> setCameraExposureFactor(double factor);当拍摄环境光线不足或过于明亮时，会影响视频采集的画质。为了获得更好的视频效果，你可以使用该方法调节摄像头的曝光系数。
注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为
localVideoStreamStateCapturing(1) 后。 - 建议你在调用该方法前，先调用 isCameraExposureSupported 查询当前摄像头是否支持调节曝光系数。
- 当你调用该方法时，设置的是当前正在使用的摄像头的曝光系数，即调用 setCameraCapturerConfiguration 时指定的摄像头。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setCameraExposurePosition
设置手动曝光位置。
Future<void> setCameraExposurePosition(
{required double positionXinView, required double positionYinView});注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为
localVideoStreamStateCapturing(1) 后。 - 成功调用该方法后，本地会触发 onCameraExposureAreaChanged 回调。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setCameraFocusPositionInPreview
设置手动对焦位置，并触发对焦。
Future<void> setCameraFocusPositionInPreview(
{required double positionX, required double positionY});注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为
localVideoStreamStateCapturing(1) 后。 - 成功调用该方法后，本地会触发 onCameraFocusAreaChanged 回调。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setCameraTorchOn
设置是否打开闪光灯。
Future<void> setCameraTorchOn(bool isOn);注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为
localVideoStreamStateCapturing(1) 后。
参数
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
setCameraZoomFactor
设置摄像头放大比例。
Future<void> setCameraZoomFactor(double factor);部分 iOS 设备的后置摄像头为多个摄像头组成的融合镜头，如双摄（广角和超广角）或三摄（广角、超广角和长焦），对于这种具备超广角能力的融合镜头，你可以调用 setCameraCapturerConfiguration 将 cameraFocalLengthType 设置为 cameraFocalLengthDefault (0)（标准镜头），然后调用该方法将摄像头缩放比例设置为小于 1.0 的数值，从而实现超广角的拍摄效果。
注：
- 该方法仅适用于 Android 和 iOS。
- 该方法必须在 enableVideo 后调用，设置结果在摄像头成功开启后生效，即 SDK 触发 onLocalVideoStateChanged 回调返回本地视频状态为
localVideoStreamStateCapturing(1) 后。
参数
| 参数名 | 描述 |
|---|---|
factor | 摄像头放大比例。对不支持超广角的设备，取值范围从 1.0 到最大放大比例；对支持超广角的设备，取值范围从 0.5 到最大放大比例。你可以通过 getCameraMaxZoomFactor 方法获取设备支持的最大放大比例。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
- 方法调用失败: 返回值 < 0。
所属接口类
setDevice
通过设备 ID 指定视频采集设备。
Future<void> setDevice(String deviceIdUTF8);注：
- 插拔设备不会改变设备 ID。
- 该方法仅适用于 Windows 和 macOS。
参数
| 参数名 | 描述 |
|---|---|
deviceIdUTF8 | 设备 ID。可通过调用 enumerateVideoDevices 方法获取。 最大长度为 MaxDeviceIdLengthType。 |
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
switchCamera
切换前置/后置摄像头。
Future<void> switchCamera();你可以调用该方法在 App 运行期间基于可用摄像头的实际情况来动态切换摄像头，而无需重启视频流或重新配置视频源。
注： 该方法仅适用于 Android 和 iOS。
该方法仅会对第一路摄像头采集的视频流进行摄像头切换操作，即调用 startCameraCapture 时设置为 videoSourceCamera (0) 的视频源。
调用时机
该方法必须在摄像头成功开启后调用，即 SDK 触发 onLocalVideoStateChanged 回调，返回本地视频状态为 localVideoStreamStateCapturing (1) 后。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类
onCameraExposureAreaChanged
摄像头曝光区域已改变回调。
final void Function(int x, int y, int width, int height)?
onCameraExposureAreaChanged;该回调是由本地用户调用 setCameraExposurePosition 方法改变曝光位置触发的。
注： 该回调仅适用于 Android 和 iOS。
所属接口类
onCameraFocusAreaChanged
相机对焦区域已改变回调。
final void Function(int x, int y, int width, int height)?
onCameraFocusAreaChanged;该回调是由本地用户调用 setCameraFocusPositionInPreview 方法改变对焦位置触发的。
注： 该回调仅适用于 Android 和 iOS。
参数
所属接口类
onCameraReady
摄像头就绪回调。
final void Function()? onCameraReady;废弃
弃用: 请改用 onLocalVideoStateChanged 中的 localVideoStreamStateCapturing(1)。
该回调提示已成功打开摄像头，可以开始捕获视频。
所属接口类
onVideoDeviceStateChanged
视频设备变化回调。
final void Function(String deviceId, MediaDeviceType deviceType,
MediaDeviceStateType deviceState)? onVideoDeviceStateChanged;该回调提示系统视频设备状态发生改变，比如被拔出或移除。如果设备已使用外接摄像头采集，外接摄像头被拔开后，视频会中断。
注： 该回调仅适用于 Windows 和 macOS。
参数
| 参数名 | 描述 |
|---|---|
deviceId | |
deviceType | 设备类型。详见 MediaDeviceType。 |
deviceState | 设备状态。详见 MediaDeviceStateType 。 |