TXDeviceManager
Copyright (c) 2021 Tencent. All rights reserved.
Module: 音视频设备管理模块
Function: 用于管理摄像头、麦克风和扬声器等音视频相关的硬件设备
TXDeviceManager
TXDeviceObserver
函数列表 | 描述 |
本地设备的通断状态发生变化（仅适用于桌面系统） |
TXDeviceManager
函数列表 | 描述 |
判断当前是否为前置摄像头（仅适用于移动端） | |
切换前置或后置摄像头（仅适用于移动端） | |
查询当前摄像头是否支持缩放（仅适用于移动端） | |
获取摄像头的最大缩放倍数（仅适用于移动端） | |
设置摄像头的缩放倍数（仅适用于移动端） | |
查询是否支持自动识别人脸位置（仅适用于移动端） | |
开启自动对焦功能（仅适用于移动端） | |
设置摄像头的对焦位置（仅适用于移动端） | |
查询是否支持开启闪光灯（仅适用于移动端） | |
开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端） | |
设置音频路由（仅适用于移动端） | |
设置摄像头的曝光参数，取值范围从-1到1 | |
获取设备列表（仅适用于桌面端） | |
设置当前要使用的设备（仅适用于桌面端） | |
获取当前正在使用的设备（仅适用于桌面端） | |
设置当前设备的音量（仅适用于桌面端） | |
获取当前设备的音量（仅适用于桌面端） | |
设置当前设备的静音状态（仅适用于桌面端） | |
获取当前设备的静音状态（仅适用于桌面端） | |
设置 SDK 使用的音频设备根据跟随系统默认设备（仅适用于桌面端） | |
开始摄像头测试（仅适用于桌面端） | |
结束摄像头测试（仅适用于桌面端） | |
开始麦克风测试（仅适用于桌面端） | |
开始麦克风测试（仅适用于桌面端） | |
结束麦克风测试（仅适用于桌面端） | |
开始扬声器测试（仅适用于桌面端） | |
结束扬声器测试（仅适用于桌面端） | |
设备热插拔回调（仅适用于 Mac 系统） | |
设置摄像头采集偏好 | |
设置系统音量类型（仅适用于移动端） |
结构体类型
函数列表 | 描述 |
摄像头采集参数 | |
音视频设备的相关信息（仅适用于桌面平台） |
枚举类型
枚举类型 | 描述 |
系统音量类型（仅适用于移动设备） | |
音频路由（即声音的播放模式） | |
设备类型（仅适用于桌面平台） | |
设备操作 | |
摄像头采集偏好 |
onDeviceChanged:type:state:
onDeviceChanged:type:state:
- (void)onDeviceChanged: | (NSString*)deviceId |
type: | |
state: |
本地设备的通断状态发生变化（仅适用于桌面系统）
当本地设备（包括摄像头、麦克风以及扬声器）被插入或者拔出时，SDK 便会抛出此事件回调。
参数 | 描述 |
deviceId | 设备 ID |
state | 通断状态，0：设备已添加；1：设备已被移除；2：设备已启用。 |
type | 设备类型 |
isFrontCamera
isFrontCamera
判断当前是否为前置摄像头（仅适用于移动端）
switchCamera:
switchCamera:
- (NSInteger)switchCamera: | (BOOL)frontCamera |
切换前置或后置摄像头（仅适用于移动端）
isCameraZoomSupported
isCameraZoomSupported
查询当前摄像头是否支持缩放（仅适用于移动端）
getCameraZoomMaxRatio
getCameraZoomMaxRatio
获取摄像头的最大缩放倍数（仅适用于移动端）
setCameraZoomRatio:
setCameraZoomRatio:
- (NSInteger)setCameraZoomRatio: | (CGFloat)zoomRatio |
设置摄像头的缩放倍数（仅适用于移动端）
参数 | 描述 |
zoomRatio | 取值范围1 - 5，取值为1表示最远视角（正常镜头），取值为5表示最近视角（放大镜头）。最大值推荐为5，若超过5，视频数据会变得模糊不清。 |
isAutoFocusEnabled
isAutoFocusEnabled
查询是否支持自动识别人脸位置（仅适用于移动端）
enableCameraAutoFocus:
enableCameraAutoFocus:
- (NSInteger)enableCameraAutoFocus: | (BOOL)enabled |
开启自动对焦功能（仅适用于移动端）
开启后，SDK 会自动检测画面中的人脸位置，并将摄像头的焦点始终对焦在人脸位置上。
setCameraFocusPosition:
setCameraFocusPosition:
- (NSInteger)setCameraFocusPosition: | (CGPoint)position |
设置摄像头的对焦位置（仅适用于移动端）
您可以通过该接口实现如下交互：
1. 在本地摄像头的预览画面上，允许用户单击操作。
2. 在用户的单击位置显示一个矩形方框，以示摄像头会在此处对焦。
3. 随后将用户点击位置的坐标通过本接口传递给 SDK，之后 SDK 会操控摄像头按照用户期望的位置进行对焦。
参数 | 描述 |
position | 对焦位置，请传入期望对焦点的坐标值 |
注意
返回值说明：
0：操作成功；负数：操作失败。
isCameraTorchSupported
isCameraTorchSupported
查询是否支持开启闪光灯（仅适用于移动端）
enableCameraTorch:
enableCameraTorch:
- (NSInteger)enableCameraTorch: | (BOOL)enabled |
开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端）
setAudioRoute:
setAudioRoute:
- (NSInteger)setAudioRoute: |
设置音频路由（仅适用于移动端）
手机有两个音频播放设备：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
setExposureCompensation:
setExposureCompensation:
- (NSInteger)setExposureCompensation: | (CGFloat)value |
设置摄像头的曝光参数，取值范围从-1到1
getDevicesList:
getDevicesList:
- (NSArray<TXMediaDeviceInfo *> * _Nullable)getDevicesList: |
获取设备列表（仅适用于桌面端）
参数 | 描述 |
type | 设备类型，指定需要获取哪种设备的列表。详见 TXMediaDeviceType 定义。 |
注意
使用完毕后请调用 release 方法释放资源，这样可以让 SDK 维护 ITXDeviceCollection 对象的生命周期。
不要使用 delete 释放返回的 Collection 对象，delete ITXDeviceCollection* 指针会导致异常崩溃。
type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker、TXMediaDeviceTypeCamera。
此接口只支持 Mac 和 Windows 平台。
setCurrentDevice:deviceId:
setCurrentDevice:deviceId:
- (NSInteger)setCurrentDevice: | |
deviceId: | (NSString *)deviceId |
设置当前要使用的设备（仅适用于桌面端）
参数 | 描述 |
deviceId | |
type | 设备类型，详见 TXMediaDeviceType 定义。 |
返回值说明：
0：操作成功；负数：操作失败。
getCurrentDevice:
getCurrentDevice:
- (TXMediaDeviceInfo * _Nullable)getCurrentDevice: |
获取当前正在使用的设备（仅适用于桌面端）
setCurrentDeviceVolume:deviceType:
setCurrentDeviceVolume:deviceType:
- (NSInteger)setCurrentDeviceVolume: | (NSInteger)volume |
deviceType: |
设置当前设备的音量（仅适用于桌面端）
这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持设置音量的。
参数 | 描述 |
volume | 音量大小，取值范围为0 - 100，默认值：100。 |
getCurrentDeviceVolume:
getCurrentDeviceVolume:
- (NSInteger)getCurrentDeviceVolume: |
获取当前设备的音量（仅适用于桌面端）
这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持获取音量的。
setCurrentDeviceMute:deviceType:
setCurrentDeviceMute:deviceType:
- (NSInteger)setCurrentDeviceMute: | (BOOL)mute |
deviceType: |
设置当前设备的静音状态（仅适用于桌面端）
这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
getCurrentDeviceMute:
getCurrentDeviceMute:
- (BOOL)getCurrentDeviceMute: |
获取当前设备的静音状态（仅适用于桌面端）
这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。
enableFollowingDefaultAudioDevice:enable:
enableFollowingDefaultAudioDevice:enable:
- (NSInteger)enableFollowingDefaultAudioDevice: | |
enable: | (BOOL)enable |
设置 SDK 使用的音频设备根据跟随系统默认设备（仅适用于桌面端）
仅支持设置麦克风和扬声器类型，摄像头暂不支持跟随系统默认设备
参数 | 描述 |
enable | 是否跟随系统默认的音频设备。 true：跟随。当系统默认音频设备发生改变或者有新音频设备插入时，SDK 立即切换音频设备。 false：不跟随。当系统默认音频设备发生改变或者有新音频设备插入时，SDK 不会切换音频设备。 |
type | 设备类型，详见 TXMediaDeviceType 定义。 |
startCameraDeviceTest:
startCameraDeviceTest:
- (NSInteger)startCameraDeviceTest: | (NSView *)view |
开始摄像头测试（仅适用于桌面端）
注意
stopCameraDeviceTest
stopCameraDeviceTest
结束摄像头测试（仅适用于桌面端）
startMicDeviceTest:
startMicDeviceTest:
- (NSInteger)startMicDeviceTest: | (NSInteger)interval |
开始麦克风测试（仅适用于桌面端）
该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为0 - 100。
参数 | 描述 |
interval | 麦克风音量的回调间隔。 |
注意
该接口调用后默认会回播麦克风录制到的声音到扬声器中。
startMicDeviceTest:playback:
startMicDeviceTest:playback:
- (NSInteger)startMicDeviceTest: | (NSInteger)interval |
playback: | (BOOL)playback |
开始麦克风测试（仅适用于桌面端）
该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为0 - 100。
参数 | 描述 |
interval | 麦克风音量的回调间隔。 |
playback | 是否开启回播麦克风声音，开启后用户测试麦克风时会听到自己的声音。 |
stopMicDeviceTest
stopMicDeviceTest
结束麦克风测试（仅适用于桌面端）
startSpeakerDeviceTest:
startSpeakerDeviceTest:
- (NSInteger)startSpeakerDeviceTest: | (NSString *)audioFilePath |
开始扬声器测试（仅适用于桌面端）
该接口通过播放指定的音频文件，用于测试播放设备是否能正常工作。如果用户在测试时能听到声音，说明播放设备能正常工作。
参数 | 描述 |
filePath | 声音文件的路径 |
stopSpeakerDeviceTest
stopSpeakerDeviceTest
结束扬声器测试（仅适用于桌面端）
setObserver:
setCameraCapturerParam:
setSystemVolumeType:
setSystemVolumeType:
- (NSInteger)setSystemVolumeType: |
设置系统音量类型（仅适用于移动端）
@deprecated v9.5 版本开始不推荐使用，建议使用
TRTCCloud 中的 startLocalAudio(quality) 接口替代之，通过 quality 参数来决策音质。TXSystemVolumeType(Deprecated)
TXSystemVolumeType(Deprecated)
系统音量类型（仅适用于移动设备）
@deprecated v9.5 版本开始不推荐使用。
现代智能手机中一般都具备两套系统音量类型，即“通话音量”和“媒体音量”。
通话音量：手机专门为接打电话所设计的音量类型，自带回声抵消（AEC）功能，并且支持通过蓝牙耳机上的麦克风进行拾音，缺点是音质比较一般。
当您通过手机侧面的音量按键下调手机音量时，如果无法将其调至零（也就是无法彻底静音），说明您的手机当前处于通话音量。
媒体音量：手机专门为音乐场景所设计的音量类型，无法使用系统的 AEC 功能，并且不支持通过蓝牙耳机的麦克风进行拾音，但具备更好的音乐播放效果。
当您通过手机侧面的音量按键下调手机音量时，如果能够将手机音量调至彻底静音，说明您的手机当前处于媒体音量。
SDK 目前提供了三种系统音量类型的控制模式：自动切换模式、全程通话音量模式、全程媒体音量模式。
枚举 | 取值 | 描述 |
TXSystemVolumeTypeAuto | 0 | 自动切换模式 |
TXSystemVolumeTypeMedia | 1 | 全程媒体音量 |
TXSystemVolumeTypeVOIP | 2 | 全程通话音量 |
TXAudioRoute
TXAudioRoute
音频路由（即声音的播放模式）
音频路由，即声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。
手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。
设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。
枚举 | 取值 | 描述 |
TXAudioRouteSpeakerphone | 0 | Speakerphone：使用扬声器播放（即“免提”），扬声器位于手机底部，声音偏大，适合外放音乐。 |
TXAudioRouteEarpiece | 1 | Earpiece：使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。 |
TXMediaDeviceType
TXMediaDeviceType
设备类型（仅适用于桌面平台）
该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。
枚举 | 取值 | 描述 |
TXMediaDeviceTypeUnknown | -1 | 未定义的设备类型 |
TXMediaDeviceTypeAudioInput | 0 | 麦克风类型设备 |
TXMediaDeviceTypeAudioOutput | 1 | 扬声器类型设备 |
TXMediaDeviceTypeVideoCamera | 2 | 摄像头类型设备 |
TXMediaDeviceState
TXMediaDeviceState
设备操作
枚举 | 取值 | 描述 |
TXMediaDeviceStateAdd | 0 | 设备已被插入 |
TXMediaDeviceStateRemove | 1 | 设备已被移除 |
TXMediaDeviceStateActive | 2 | 设备已启用 |
TXMediaDefaultDeviceChanged | 3 | 系统默认设备变更 |
TXCameraCaptureMode
TXCameraCaptureMode
摄像头采集偏好
该枚举类型用于摄像头采集参数设置。
枚举 | 取值 | 描述 |
TXCameraResolutionStrategyAuto | 0 | 自动调整采集参数。 SDK 根据实际的采集设备性能及网络情况，选择合适的摄像头输出参数，在设备性能及视频预览质量之间，维持平衡。 |
TXCameraResolutionStrategyPerformance | Not Defined | 优先保证设备性能。 SDK 根据用户设置编码器的分辨率和帧率，选择最接近的摄像头输出参数，从而保证设备性能。 |
TXCameraResolutionStrategyHighQuality | Not Defined | 优先保证视频预览质量。 SDK选择较高的摄像头输出参数，从而提高预览视频的质量。在这种情况下，会消耗更多的 CPU 及内存做视频前处理。 |
TXCameraCaptureManual | Not Defined | 允许用户设置本地摄像头采集的视频宽高。 |
TXCameraCaptureParam
TXCameraCaptureParam
摄像头采集参数
该设置能决定本地预览图像画质。
枚举类型 | 描述 |
height | 字段含义： 采集图像宽度 |
mode | |
width | 字段含义： 采集图像长度 |
TXMediaDeviceInfo
TXMediaDeviceInfo
音视频设备的相关信息（仅适用于桌面平台）
该结构体用于描述一个音视频设备的关键信息，比如设备 ID、设备名称等等，以便用户能够在用户界面上选择自己期望使用的音视频设备。
枚举类型 | 描述 |
deviceId | 设备 ID （UTF-8） |
deviceName | 设备名称 （UTF-8） |
deviceProperties | 设备属性 |
type | 设备类型 |
- TXDeviceObserver
- TXDeviceManager
- 结构体类型
- 枚举类型
- onDeviceChanged:type:state:
- isFrontCamera
- switchCamera:
- isCameraZoomSupported
- getCameraZoomMaxRatio
- setCameraZoomRatio:
- isAutoFocusEnabled
- enableCameraAutoFocus:
- setCameraFocusPosition:
- isCameraTorchSupported
- enableCameraTorch:
- setAudioRoute:
- setExposureCompensation:
- getDevicesList:
- setCurrentDevice:deviceId:
- getCurrentDevice:
- setCurrentDeviceVolume:deviceType:
- getCurrentDeviceVolume:
- setCurrentDeviceMute:deviceType:
- getCurrentDeviceMute:
- enableFollowingDefaultAudioDevice:enable:
- startCameraDeviceTest:
- stopCameraDeviceTest
- startMicDeviceTest:
- startMicDeviceTest:playback:
- stopMicDeviceTest
- startSpeakerDeviceTest:
- stopSpeakerDeviceTest
- setObserver:
- setCameraCapturerParam:
- setSystemVolumeType:
- TXSystemVolumeType(Deprecated)
- TXAudioRoute
- TXMediaDeviceType
- TXMediaDeviceState
- TXCameraCaptureMode
- TXCameraCaptureParam
- TXMediaDeviceInfo