LiteAVSDK
腾讯云音视频 SDK ,服务于数万家企业客户的高可用组件,致力于最大限度地节省您的研发成本。
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 

全程通话音量