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