视频设备管理
enableMultiCamera:config:
启用或关闭多摄像头采集模式。
Objective-C
- (int)enableMultiCamera:(BOOL)enabled config:(AgoraCameraCapturerConfiguration* _Nullable)config NS_SWIFT_NAME(enableMultiCamera(_:config:));
声网建议你在已有摄像头用于视频采集的场景中，按照以下步骤使用多摄像头进行视频采集和发布：
- 调用该方法启用多摄像头采集模式。
- 调用 startPreview: 启动本地视频预览。
- 调用 startCameraCapture:config:，并设置
sourceType以使用第二个摄像头进行视频采集。 - 调用 joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:，并将
publishSecondaryCameraTrack设置为 YES，以在频道中发布第二个摄像头采集的视频流。
- 调用 stopCameraCapture:。
- 调用该方法并将
enabled设置为 NO。
- iPhone XR
- iPhone XS
- iPhone XS Max
- iPad Pro 第三代及更新机型
信息
你可以在调用 startPreview: 之前或之后调用该方法启用多摄像头采集：
- 如果在 startPreview: 之前启用，本地视频预览会同时显示两个摄像头采集的画面。
- 如果在 startPreview: 之后启用，SDK 会先停止当前摄像头采集，然后启用主摄像头和第二个摄像头。本地视频预览会短暂变黑，然后自动恢复正常。
参数
- enabled
- 是否启用多摄像头视频采集模式：
- YES：启用多摄像头采集模式，SDK 使用多个摄像头进行视频采集。
- NO：关闭多摄像头采集模式，SDK 使用单个摄像头进行视频采集。
- config
- 第二个摄像头的采集配置。详见 AgoraCameraCapturerConfiguration。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
cameraMaxZoomFactor
获取摄像头支持的最大变焦倍数。
Objective-C
- (CGFloat)cameraMaxZoomFactor NS_SWIFT_NAME(cameraMaxZoomFactor());
信息
你必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调，并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后调用该方法。返回值
方法调用成功，返回摄像头支持的最大变焦倍数。
所属接口类isCameraAutoExposureFaceModeSupported
检查设备是否支持自动曝光。
Objective-C
- (BOOL)isCameraAutoExposureFaceModeSupported NS_SWIFT_NAME(isCameraAutoExposureFaceModeSupported());
信息
isCameraAutoExposureFaceModeSupported 方法必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后调用。返回值
- YES：设备支持自动曝光。
- NO：设备不支持自动曝光。
isCameraAutoFocusFaceModeSupported
检查设备是否支持人脸自动对焦功能。
Objective-C
- (BOOL)isCameraAutoFocusFaceModeSupported NS_SWIFT_NAME(isCameraAutoFocusFaceModeSupported());
信息
你必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后调用此方法。返回值
- YES：设备支持人脸自动对焦功能。
- NO：设备不支持人脸自动对焦功能。
isCameraExposurePositionSupported
检查设备是否支持手动曝光。
Objective-C
- (BOOL)isCameraExposurePositionSupported NS_SWIFT_NAME(isCameraExposurePositionSupported());
信息
必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后调用此方法。返回值
- YES：设备支持手动曝光。
- NO：设备不支持手动曝光。
isCameraExposureSupported
查询当前摄像头是否支持调节曝光值。
Objective-C
- (BOOL)isCameraExposureSupported NS_SWIFT_NAME(isCameraExposureSupported());
自从
自 v4.2.2 版本新增。
信息
- 你必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后调用该方法。 - 在调用 setCameraExposureFactor: 之前，建议你先调用该方法，确认当前摄像头是否支持调节曝光值。
- 该方法用于调节当前激活摄像头的曝光值，即调用 setCameraCapturerConfiguration: 时指定的摄像头。
返回值
- YES：查询成功，当前摄像头支持调节曝光值。
- NO：查询失败，当前摄像头不支持调节曝光值。
isCameraFocusPositionInPreviewSupported
检查设备是否支持手动对焦功能。
Objective-C
- (BOOL)isCameraFocusPositionInPreviewSupported NS_SWIFT_NAME(isCameraFocusPositionInPreviewSupported());
信息
必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后调用此方法。返回值
- YES：设备支持手动对焦功能。
- NO：设备不支持手动对焦功能。
isCameraTorchSupported
检查设备是否支持相机闪光灯。
Objective-C
- (BOOL)isCameraTorchSupported NS_SWIFT_NAME(isCameraTorchSupported());
信息
你必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后调用该方法。App 默认启用前置摄像头。如果前置摄像头不支持闪光灯，该方法返回 NO。如果你想检查后置摄像头是否支持闪光灯功能，请在调用该方法前调用 switchCamera。在系统版本为 15 的 iPad 上，即使 isCameraTorchSupported 返回 YES，你也可能因系统问题调用 setCameraTorchOn: 启用闪光灯失败。返回值
- YES：设备支持相机闪光灯。
- NO：设备不支持相机闪光灯。
isCameraZoomSupported
检查设备是否支持摄像头变焦。
Objective-C
- (BOOL)isCameraZoomSupported NS_SWIFT_NAME(isCameraZoomSupported());
调用时机
你必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为 AgoraVideoLocalStateCapturing（1）后调用该方法。
返回值
- YES：设备支持摄像头变焦。
- NO：设备不支持摄像头变焦。
queryCameraFocalLengthCapability
查询摄像头支持的焦距能力。
Objective-C
- (NSArray<AgoraFocalLengthInfo *>* _Nullable)queryCameraFocalLengthCapability NS_SWIFT_NAME(queryCameraFocalLengthCapability());
如果你希望在视频采集中启用广角或超广角模式，建议你首先调用 queryCameraFocalLengthCapability 方法检查设备是否支持所需的焦距能力。然后，根据查询结果调用 setCameraCapturerConfiguration: 方法调整摄像头的焦距配置，以确保最佳的视频采集性能。
返回值
- 方法调用成功，返回一个 AgoraFocalLengthInfo 对象数组，包含摄像头的方向和焦距类型，详见 AgoraFocalLengthInfo。
- 方法调用失败，返回 nil。
queryCodecCapability
查询设备支持的视频编解码能力。
Objective-C
- (NSArray <AgoraVideoCodecCapInfo *> *_Nullable)queryCodecCapability;
返回值
- 方法调用成功时，返回一个 AgoraVideoCodecCapInfo 数组，表示设备的视频编码能力，详见 AgoraVideoCodecCapInfo。
- 方法调用失败时，返回 nil。如果调用超时，请调整调用逻辑，避免在主线程中调用该方法。
setCameraAutoExposureFaceModeEnabled:
设置是否启用自动曝光。
Objective-C
- (BOOL)setCameraAutoExposureFaceModeEnabled:(BOOL)enable NS_SWIFT_NAME(setCameraAutoExposureFaceModeEnabled(_:));
信息
你必须在调用 enableVideo 方法之后再调用此方法。设置结果将在摄像头成功开启后生效，即 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）之后。参数
- enable
- 是否启用自动曝光：
- YES：启用自动曝光。
- NO：关闭自动曝光。
返回值
- YES：设置成功。
- NO：设置失败。
setCameraAutoFocusFaceModeEnabled:
启用或关闭摄像头人像自动对焦功能。
Objective-C
- (BOOL)setCameraAutoFocusFaceModeEnabled:(BOOL)enable NS_SWIFT_NAME(setCameraAutoFocusFaceModeEnabled(_:));
你可以通过调用该方法关闭人像自动对焦功能。SDK 默认启用该功能。
调用时机
必须在 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为 AgoraVideoLocalStateCapturing（1）后调用。
参数
- enable
- 是否启用摄像头人像自动对焦功能：
- YES：启用摄像头人像自动对焦功能。
- NO：关闭人像自动对焦功能。
返回值
- YES：设置成功。
- NO：设置失败。
setCameraCapturerConfiguration:
设置视频采集配置。
Objective-C
- (int)setCameraCapturerConfiguration:(AgoraCameraCapturerConfiguration * _Nullable)config NS_SWIFT_NAME(setCameraCapturerConfiguration(_:));
在启用本地摄像头采集前调用此方法，例如在调用 startPreview: 和 joinChannelByToken 之前。
信息
如需调整摄像头焦距配置，建议先调用 queryCameraFocalLengthCapability 查询设备的焦距能力，并根据查询结果进行配置。
调用时机
在启用本地摄像头采集前调用，例如在调用 startPreview: 和 joinChannelByToken 之前。
参数
- config
- 摄像头采集配置。详见 AgoraCameraCapturerConfiguration。信息在此方法中，无需设置
deviceId参数。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setCameraExposureFactor:
设置摄像头曝光值。
Objective-C
- (CGFloat)setCameraExposureFactor:(CGFloat)exposureFactor NS_SWIFT_NAME(setCameraExposureFactor(_:));
自从
自 v4.2.2 版本新增。
你可以通过此方法调整摄像头的曝光值，以获得最佳的视频质量。
信息
- 你必须在调用 enableVideo 方法之后再调用此方法。设置结果在摄像头成功开启后生效，即 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后。 - 在调用此方法前，建议你调用 isCameraExposureSupported 方法检查当前摄像头是否支持调整曝光值。
- 该方法调整的是当前正在使用的摄像头的曝光值，即调用 setCameraCapturerConfiguration: 方法时指定的摄像头。
参数
- exposureFactor
- 摄像头曝光值（默认值为 0）。值越大，曝光越强。当视频图像过曝时，可以降低曝光值；当视频图像曝光不足且暗部细节丢失时，可以提高曝光值。如果设置的曝光值超出设备支持的范围，SDK 会自动将其调整为设备实际支持的范围。取值范围为 [-8.0, 8.0]。
返回值
无实际意义。
所属接口类setCameraExposurePosition:
设置摄像头曝光位置。
Objective-C
- (BOOL)setCameraExposurePosition:(CGPoint)positionInView NS_SWIFT_NAME(setCameraExposurePosition(_:));
信息
你必须在调用 enableVideo 方法之后再调用该方法。设置结果会在摄像头成功开启后生效，即 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后生效。成功调用该方法后，SDK 会触发 rtcEngine:cameraExposureDidChangedToRect: 回调。参数
- positionInView
- 视图中触摸点的横坐标。
返回值
- YES：设置成功。
- NO：设置失败。
setCameraFocusPositionInPreview:
设置摄像头的手动对焦位置。
Objective-C
- (BOOL)setCameraFocusPositionInPreview:(CGPoint)position NS_SWIFT_NAME(setCameraFocusPositionInPreview(_:));
信息
你必须在调用 enableVideo 方法之后再调用本方法。设置结果会在摄像头成功开启后生效，即 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后生效。成功调用该方法后，SDK 会触发 rtcEngine:cameraFocusDidChangedToRect: 回调。参数
- position
- 视图中触摸点的坐标。
返回值
- YES：设置成功。
- NO：设置失败。
setCameraTorchOn:
启用摄像头闪光灯。
Objective-C
- (BOOL)setCameraTorchOn:(BOOL)isOn NS_SWIFT_NAME(setCameraTorchOn(_:));
信息
你必须在调用 enableVideo 后再调用此方法。设置结果将在摄像头成功开启后生效，即 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）后。参数
- isOn
- 是否打开摄像头闪光灯：
- YES：打开闪光灯。
- NO：（默认）关闭闪光灯。
返回值
- YES：设置成功。
- NO：设置失败。
setCameraZoomFactor:
设置摄像头的缩放因子。
Objective-C
- (CGFloat)setCameraZoomFactor:(CGFloat)zoomFactor NS_SWIFT_NAME(setCameraZoomFactor(_:));
你可以调用 setCameraCapturerConfiguration: 方法，将 cameraFocalLengthType 设置为 AgoraFocalLengthDefault（0），然后将摄像头缩放因子设置为小于 1.0 的值，以实现超广角视角的视频采集。该方法适用于配备多镜头后置摄像头的 iOS 设备，例如配有广角、超广角和长焦镜头的设备。
信息
你必须在调用 enableVideo 之后再调用此方法。设置结果将在摄像头成功开启后生效，即 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为
AgoraVideoLocalStateCapturing（1）之后。参数
- zoomFactor
- 摄像头缩放因子。对于不支持超广角的设备，该值范围为 1.0 到最大缩放因子；对于支持超广角的设备，该值范围为 0.5 到最大缩放因子。你可以通过调用 cameraMaxZoomFactor 方法获取设备支持的最大缩放因子。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
switchCamera
切换前后摄像头。
Objective-C
- (int)switchCamera NS_SWIFT_NAME(switchCamera());
你可以调用此方法，根据应用运行时实际可用的摄像头动态切换前后摄像头，无需重新启动视频流或重新配置视频源。
信息
此方法仅切换由第一个摄像头采集的视频流的摄像头，即调用 startCameraCapture:config: 时视频源设置为
AgoraVideoSourceTypeCamera（0）的视频流。调用时机
必须在摄像头成功启用后调用，即 SDK 触发 rtcEngine:localVideoStateChangedOfState:reason:sourceType: 回调并返回本地视频状态为 AgoraVideoLocalStateCapturing（1）之后。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
rtcEngine:cameraExposureDidChangedToRect:
摄像头曝光区域发生变化回调。
Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine cameraExposureDidChangedToRect:(CGRect)rect NS_SWIFT_NAME(rtcEngine(_:cameraExposureDidChangedTo:));
当你调用 setCameraExposurePosition: 方法更改摄像头曝光位置时，SDK 会触发该回调。
触发时机
该回调在你调用 setCameraExposurePosition: 更改摄像头曝光位置时被触发。
参数
- engine
- rect
- 本地预览中的曝光矩形区域。
rtcEngine:cameraFocusDidChangedToRect:
摄像头对焦区域发生变化时的回调。
Objective-C
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine cameraFocusDidChangedToRect:(CGRect)rect NS_SWIFT_NAME(rtcEngine(_:cameraFocusDidChangedTo:));
调用 setCameraFocusPositionInPreview: 方法更改摄像头对焦位置时，SDK 会触发该回调。
触发时机
该回调在你调用 setCameraFocusPositionInPreview: 更改摄像头对焦位置时被触发。
参数
- rect
- 本地预览画面中的对焦矩形区域。
- engine
rtcEngineCameraDidReady:
摄像头准备就绪回调。
Objective-C
- (void)rtcEngineCameraDidReady:(AgoraRtcEngineKit * _Nonnull)engine NS_SWIFT_NAME(rtcEngineCameraDidReady(_:)) __deprecated_msg("Use rtcEngine:localVideoStateChangedOfState:reason:sourceType: instead");
触发时机
该回调在摄像头成功打开并准备好采集视频时触发。
参数
- engine