TXDeviceManager

详细描述

TRTC 音视频设备管理模块

Module: TRTC 音视频设备管理模块 Function: 用于管理摄像头、麦克风和扬声器等音视频相关的硬件设备

音视频设备相关的类型定义
enum	TXSystemVolumeType : NSInteger
enum	TXAudioRoute : NSInteger
enum	TXMediaDeviceType : NSInteger
enum	TXMediaDeviceState : NSInteger

---

结构体说明

TXMediaDeviceInfo

class TXMediaDeviceInfo

属性
TXMediaDeviceType	type
NSString *	deviceId
NSString *	deviceName
NSString *	deviceProperties

属性说明

deviceId

- (NSString*) deviceId

readwritenonatomiccopy

device id

deviceName

- (NSString*) deviceName

readwritenonatomiccopy

device name

deviceProperties

- (NSString*) deviceProperties

readwritenonatomiccopy

device properties

type

- (TXMediaDeviceType) type

readwritenonatomicassign

device type

TXDeviceObserver-p

protocol TXDeviceObserver-p

构造函数
(void)	- onDeviceChanged:type:state:

函数文档

onDeviceChanged:type:state:()

- (void) onDeviceChanged:		(NSString *)	deviceId
type:		(TXMediaDeviceType)	mediaType
state:		(TXMediaDeviceState)	mediaState

TXDeviceManager

class TXDeviceManager

移动端设备操作接口
(BOOL)	- isFrontCamera
(NSInteger)	- switchCamera:
(BOOL)	- isCameraZoomSupported
(CGFloat)	- getCameraZoomMaxRatio
(NSInteger)	- setCameraZoomRatio:
(BOOL)	- isAutoFocusEnabled
(NSInteger)	- enableCameraAutoFocus:
(NSInteger)	- setCameraFocusPosition:
(BOOL)	- isCameraTorchSupported
(NSInteger)	- enableCameraTorch:
(NSInteger)	- setAudioRoute:
桌面端设备操作接口
(NSArray< TXMediaDeviceInfo * > *_Nullable)	- getDevicesList:
(NSInteger)	- setCurrentDevice:deviceId:
(TXMediaDeviceInfo *_Nullable)	- getCurrentDevice:
(NSInteger)	- setCurrentDeviceVolume:deviceType:
(NSInteger)	- getCurrentDeviceVolume:
(NSInteger)	- setCurrentDeviceMute:deviceType:
(BOOL)	- getCurrentDeviceMute:
(NSInteger)	- startCameraDeviceTest:
(NSInteger)	- stopCameraDeviceTest
(NSInteger)	- startMicDeviceTest:testEcho:
(NSInteger)	- stopMicDeviceTest
(NSInteger)	- startSpeakerDeviceTest:onVolumeChanged:
(NSInteger)	- stopSpeakerDeviceTest
(void)	- setObserver:
弃用接口（建议使用对应的新接口）
(NSInteger)	- setSystemVolumeType:

函数文档

enableCameraAutoFocus:()

- (NSInteger) enableCameraAutoFocus:

(BOOL)

enabled

开启自动对焦功能（仅适用于移动端）

开启后，SDK 会自动检测画面中的人脸位置，并将摄像头的焦点始终对焦在人脸位置上。

enableCameraTorch:()

- (NSInteger) enableCameraTorch:

(BOOL)

enabled

开启/关闭闪光灯，也就是手电筒模式（仅适用于移动端）

getCameraZoomMaxRatio()

- (CGFloat) getCameraZoomMaxRatio

获取摄像头的最大缩放倍数（仅适用于移动端）

getCurrentDevice:()

- (TXMediaDeviceInfo *_Nullable) getCurrentDevice:

(TXMediaDeviceType)

type

获取当前正在使用的设备（仅适用于桌面端）

getCurrentDeviceMute:()

- (BOOL) getCurrentDeviceMute:

(TXMediaDeviceType)

type

获取当前设备的静音状态（仅适用于桌面端）

这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。

getCurrentDeviceVolume:()

- (NSInteger) getCurrentDeviceVolume:

(TXMediaDeviceType)

type

获取当前设备的音量（仅适用于桌面端）

这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持获取音量的。

getDevicesList:()

- (NSArray<TXMediaDeviceInfo *> *_Nullable) getDevicesList:

(TXMediaDeviceType)

type

获取设备列表（仅适用于桌面端）

参数

type	设备类型，指定需要获取哪种设备的列表。详见 TXMediaDeviceType 定义。

注意

• 使用完毕后请调用 release 方法释放资源，这样可以让 SDK 维护 ITXDeviceCollection 对象的生命周期。
• 不要使用 delete 释放返回的 Collection 对象，delete ITXDeviceCollection* 指针会导致异常崩溃。
• type 只支持 TXMediaDeviceTypeMic、TXMediaDeviceTypeSpeaker、TXMediaDeviceTypeCamera。
• 此接口只支持 Mac 和 Windows 平台

isAutoFocusEnabled()

- (BOOL) isAutoFocusEnabled

查询是否支持自动识别人脸位置（仅适用于移动端）

isCameraTorchSupported()

- (BOOL) isCameraTorchSupported

查询是否支持开启闪光灯（仅适用于移动端）

isCameraZoomSupported()

- (BOOL) isCameraZoomSupported

查询当前摄像头是否支持缩放（仅适用于移动端）

isFrontCamera()

- (BOOL) isFrontCamera

判断当前是否为前置摄像头（仅适用于移动端）

setAudioRoute:()

- (NSInteger) setAudioRoute:

(TXAudioRoute)

route

设置音频路由（仅适用于移动端）

手机有两个音频播放设备：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。

setCameraFocusPosition:()

- (NSInteger) setCameraFocusPosition:

(CGPoint)

position

设置摄像头的对焦位置（仅适用于移动端）

您可以通过该接口实现如下交互：

1. 在本地摄像头的预览画面上，允许用户单击操作。
2. 在用户的单击位置显示一个矩形方框，以示摄像头会在此处对焦。
3. 随后将用户点击位置的坐标通过本接口传递给 SDK，之后 SDK 会操控摄像头按照用户期望的位置进行对焦。

   注意

   使用该接口的前提是先通过 enableCameraAutoFocus 关闭自动对焦功能。

   参数

   position

   对焦位置，请传入期望对焦点的坐标值

   返回

   0：操作成功；负数：操作失败。

setCameraZoomRatio:()

- (NSInteger) setCameraZoomRatio:

(CGFloat)

zoomRatio

设置摄像头的缩放倍数（仅适用于移动端）

参数

zoomRatio

取值范围1 - 5，取值为1表示最远视角（正常镜头），取值为5表示最近视角（放大镜头）。

setCurrentDevice:deviceId:()

- (NSInteger) setCurrentDevice:		(TXMediaDeviceType)	type
deviceId:		(NSString *)	deviceId

设置当前要使用的设备（仅适用于桌面端）

参数

type	设备类型，详见 TXMediaDeviceType 定义。
deviceId	设备ID，您可以通过接口 getDevicesList 获得设备 ID。

返回

0：操作成功；负数：操作失败。

setCurrentDeviceMute:deviceType:()

- (NSInteger) setCurrentDeviceMute:		(BOOL)	mute
deviceType:		(TXMediaDeviceType)	type

设置当前设备的静音状态（仅适用于桌面端）

这里的音量指的是麦克风和扬声器，摄像头是不支持静音操作的。

setCurrentDeviceVolume:deviceType:()

- (NSInteger) setCurrentDeviceVolume:		(NSInteger)	volume
deviceType:		(TXMediaDeviceType)	type

设置当前设备的音量（仅适用于桌面端）

这里的音量指的是麦克风的采集音量或者扬声器的播放音量，摄像头是不支持设置音量的。

参数

volume

音量大小，取值范围为0 - 100，默认值：100。

注意

如果将 volume 设置成 100 之后感觉音量还是太小，可以将 volume 最大设置成 150，但超过 100 的 volume 会有爆音的风险，请谨慎操作。

setObserver:()

- (void) setObserver:

(nullable id< TXDeviceObserver >)

observer

设备热插拔回调（仅适用于 Mac 系统）

setSystemVolumeType:()

- (NSInteger) setSystemVolumeType:

(TXSystemVolumeType)

type

设置系统音量类型（仅适用于移动端）

弃用:

v9.5 版本开始不推荐使用，建议使用 TRTCCloud 中的 startLocalAudio(quality) 接口替代之，通过 quality 参数来决策音质。

startCameraDeviceTest:()

- (NSInteger) startCameraDeviceTest:

(NSView *)

view

开始摄像头测试（仅适用于桌面端）

注意

在测试过程中可以使用 setCurrentDevice 接口切换摄像头。

startMicDeviceTest:testEcho:()

- (NSInteger) startMicDeviceTest:		(NSInteger)	interval
testEcho:		(void(^)(NSInteger volume))	testEcho

开始麦克风测试（仅适用于桌面端）

该接口可以测试麦克风是否能正常工作，测试到的麦克风采集音量的大小，会以回调的形式通知给您，其中 volume 的取值范围为0 - 100。

参数

interval

麦克风音量的回调间隔。

startSpeakerDeviceTest:onVolumeChanged:()

- (NSInteger) startSpeakerDeviceTest:		(NSString *)	audioFilePath
onVolumeChanged:		(void(^)(NSInteger volume, BOOL isLastFrame))	volumeBlock

开始扬声器测试（仅适用于桌面端）

该接口通过播放指定的音频文件，用于测试播放设备是否能正常工作。如果用户在测试时能听到声音，说明播放设备能正常工作。

参数

filePath

声音文件的路径

stopCameraDeviceTest()

- (NSInteger) stopCameraDeviceTest

结束摄像头测试（仅适用于桌面端）

stopMicDeviceTest()

- (NSInteger) stopMicDeviceTest

结束麦克风测试（仅适用于桌面端）

stopSpeakerDeviceTest()

- (NSInteger) stopSpeakerDeviceTest

结束扬声器测试（仅适用于桌面端）

switchCamera:()

- (NSInteger) switchCamera:

(BOOL)

frontCamera

切换前置或后置摄像头（仅适用于移动端）

枚举类型说明

TXAudioRoute

enum TXAudioRoute : NSInteger

音频路由（即声音的播放模式）

音频路由，即声音是从手机的扬声器还是从听筒中播放出来，因此该接口仅适用于手机等移动端设备。 手机有两个扬声器：一个是位于手机顶部的听筒，一个是位于手机底部的立体声扬声器。

• 设置音频路由为听筒时，声音比较小，只有将耳朵凑近才能听清楚，隐私性较好，适合用于接听电话。
• 设置音频路由为扬声器时，声音比较大，不用将手机贴脸也能听清，因此可以实现“免提”的功能。

枚举值
TXAudioRouteSpeakerphone	Speakerphone：使用扬声器播放（即“免提”），扬声器位于手机底部，声音偏大，适合外放音乐。
TXAudioRouteEarpiece	Earpiece：使用听筒播放，听筒位于手机顶部，声音偏小，适合需要保护隐私的通话场景。

TXMediaDeviceState

enum TXMediaDeviceState : NSInteger

设备操作

该枚举值用于本地设备的状态变化通知onDeviceChanged。

枚举值
TXMediaDeviceStateAdd	设备已被插入
TXMediaDeviceStateRemove	设备已被移除
TXMediaDeviceStateActive	设备已启用

TXMediaDeviceType

enum TXMediaDeviceType : NSInteger

设备类型（仅适用于桌面平台）

该枚举值用于定义三种类型的音视频设备，即摄像头、麦克风和扬声器，以便让一套设备管理接口可以操控三种不同类型的设备。

枚举值
TXMediaDeviceTypeUnknown	undefined device type
TXMediaDeviceTypeAudioInput	microphone
TXMediaDeviceTypeAudioOutput	speaker or earpiece
TXMediaDeviceTypeVideoCamera	camera

TXSystemVolumeType

enum TXSystemVolumeType : NSInteger

系统音量类型（仅适用于移动设备）

弃用:

v9.5 版本开始不推荐使用。

现代智能手机中一般都具备两套系统音量类型，即“通话音量”和“媒体音量”。

• 通话音量：手机专门为接打电话所设计的音量类型，自带回声抵消（AEC）功能，并且支持通过蓝牙耳机上的麦克风进行拾音，缺点是音质比较一般。 当您通过手机侧面的音量按键下调手机音量时，如果无法将其调至零（也就是无法彻底静音），说明您的手机当前出于通话音量。
• 媒体音量：手机专门为音乐场景所设计的音量类型，无法使用系统的 AEC 功能，并且不支持通过蓝牙耳机的麦克风进行拾音，但具备更好的音乐播放效果。 当您通过手机侧面的音量按键下调手机音量时，如果能够将手机音量调至彻底静音，说明您的手机当前出于媒体音量。

SDK 目前提供了三种系统音量类型的控制模式：自动切换模式、全程通话音量模式、全程媒体音量模式。

枚举值
TXSystemVolumeTypeAuto	自动切换模式
TXSystemVolumeTypeMedia	全程媒体音量
TXSystemVolumeTypeVOIP	全程通话音量