LiteAVSDK
Tencent Cloud TRTC SDK, is a high availability components serving tens of thousands of enterprise customers, which is committed to helping you to minimize your research and development costs.
TXDeviceManager

Data Structures

class  TXMediaDeviceInfo
 
protocol  <TXDeviceObserver>
 
class  TXDeviceManager
 

Type definitions of audio/video devices

enum  TXSystemVolumeType : NSInteger
 
enum  TXAudioRoute : NSInteger
 
enum  TXMediaDeviceType : NSInteger
 
enum  TXMediaDeviceState : NSInteger
 

Detailed Description

Tencent Cloud Device Management Module.

Module: audio/video device management module Description: manages audio/video devices such as camera, mic, and speaker.


Data Structure Documentation

◆ TXMediaDeviceInfo

class TXMediaDeviceInfo

Audio/Video device information (for desktop OS)

This structure describes key information (such as device ID and device name) of an audio/video device, so that users can choose on the UI the device to use.

+ Inheritance diagram for TXMediaDeviceInfo:

Properties

TXMediaDeviceType type
 
NSString * deviceId
 
NSString * deviceName
 
NSString * deviceProperties
 

Property Documentation

◆ 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

The status of a local device changed (for desktop OS only)

The SDK returns this callback when a local device (camera, mic, or speaker) is connected or disconnected.

Parameters
deviceIdDevice ID
typeDevice type
stateDevice status. 0: connected; 1: disconnected; 2: started
+ Inheritance diagram for <TXDeviceObserver>:

Instance Methods

(void) - onDeviceChanged:type:state:
 

Method Documentation

◆ onDeviceChanged:type:state:()

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

◆ TXDeviceManager

class TXDeviceManager
+ Inheritance diagram for TXDeviceManager:

Device APIs for mobile OS

(BOOL) - isFrontCamera
 
(NSInteger) - switchCamera:
 
(BOOL) - isCameraZoomSupported
 
(CGFloat) - getCameraZoomMaxRatio
 
(NSInteger) - setCameraZoomRatio:
 
(BOOL) - isAutoFocusEnabled
 
(NSInteger) - enableCameraAutoFocus:
 
(NSInteger) - setCameraFocusPosition:
 
(BOOL) - isCameraTorchSupported
 
(NSInteger) - enableCameraTorch:
 
(NSInteger) - setAudioRoute:
 

Device APIs for desktop OS

(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:
 

Disused APIs (the corresponding new APIs are recommended)

(NSInteger) - setSystemVolumeType:
 

Method Documentation

◆ enableCameraAutoFocus:()

- (NSInteger) enableCameraAutoFocus: (BOOL)  enabled

Enabling auto focus (for mobile OS)

After auto focus is enabled, the camera will automatically detect and always focus on faces.

◆ enableCameraTorch:()

- (NSInteger) enableCameraTorch: (BOOL)  enabled

Enabling/Disabling flash, i.e., the torch mode (for mobile OS)

◆ getCameraZoomMaxRatio()

- (CGFloat) getCameraZoomMaxRatio

Getting the maximum zoom ratio of the camera (for mobile OS)

◆ getCurrentDevice:()

- (TXMediaDeviceInfo *_Nullable) getCurrentDevice: (TXMediaDeviceType type

Getting the device currently in use (for desktop OS)

◆ getCurrentDeviceMute:()

- (BOOL) getCurrentDeviceMute: (TXMediaDeviceType type

Querying whether the current device is muted (for desktop OS)

This API is used to query whether the mic or speaker is muted. Camera muting is not supported.

◆ getCurrentDeviceVolume:()

- (NSInteger) getCurrentDeviceVolume: (TXMediaDeviceType type

Getting the volume of the current device (for desktop OS)

This API is used to get the capturing volume of the mic or playback volume of the speaker, but not the volume of the camera.

◆ getDevicesList:()

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

Getting the device list (for desktop OS)

Parameters
typeDevice type. Set it to the type of device you want to get. For details, please see the definition of TXMediaDeviceType.
Attention
  • To ensure that the SDK can manage the lifecycle of the ITXDeviceCollection object, after using this API, please call the release method to release the resources.
  • Do not use delete to release the Collection object returned as deleting the ITXDeviceCollection* pointer will cause crash.
  • The valid values of type are TXMediaDeviceTypeMic, TXMediaDeviceTypeSpeaker, and TXMediaDeviceTypeCamera.
  • This API can be used only on macOS and Windows.

◆ isAutoFocusEnabled()

- (BOOL) isAutoFocusEnabled

Querying whether automatic face detection is supported (for mobile OS)

◆ isCameraTorchSupported()

- (BOOL) isCameraTorchSupported

Querying whether flash is supported (for mobile OS)

◆ isCameraZoomSupported()

- (BOOL) isCameraZoomSupported

Querying whether the current camera supports zooming (for mobile OS)

◆ isFrontCamera()

- (BOOL) isFrontCamera

Querying whether the front camera is being used

◆ setAudioRoute:()

- (NSInteger) setAudioRoute: (TXAudioRoute route

Setting the audio route (for mobile OS)

A mobile phone has two audio playback devices: the receiver at the top and the speaker at the bottom. If the audio route is set to the receiver, the volume is relatively low, and audio can be heard only when the phone is put near the ear. This mode has a high level of privacy and is suitable for answering calls. If the audio route is set to the speaker, the volume is relatively high, and there is no need to put the phone near the ear. This mode enables the "hands-free" feature.

◆ setCameraFocusPosition:()

- (NSInteger) setCameraFocusPosition: (CGPoint)  position

Adjusting the focus (for mobile OS)

This API can be used to achieve the following:

  1. A user can tap on the camera preview.
  2. A rectangle will appear where the user taps, indicating the spot the camera will focus on.
  3. The user passes the coordinates of the spot to the SDK using this API, and the SDK will instruct the camera to focus as required.
    Attention
    Before using this API, you must first disable auto focus using enableCameraAutoFocus.
    Parameters
    positionThe spot to focus on. Pass in the coordinates of the spot you want to focus on.
    Returns
    0: operation successful; negative number: operation failed.

◆ setCameraZoomRatio:()

- (NSInteger) setCameraZoomRatio: (CGFloat)  zoomRatio

Setting the camera zoom ratio (for mobile OS)

Parameters
zoomRatioValue range: 1-5. 1 indicates the widest angle of view (original), and 5 the narrowest angle of view (zoomed in).

◆ setCurrentDevice:deviceId:()

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

Setting the device to use (for desktop OS)

Parameters
typeDevice type. For details, please see the definition of TXMediaDeviceType.
deviceIdDevice ID. You can get the ID of a device using the getDevicesList API.
Returns
0: operation successful; negative number: operation failed.

◆ setCurrentDeviceMute:deviceType:()

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

Muting the current device (for desktop OS)

This API is used to mute the mic or speaker, but not the camera.

◆ setCurrentDeviceVolume:deviceType:()

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

Setting the volume of the current device (for desktop OS)

This API is used to set the capturing volume of the mic or playback volume of the speaker, but not the volume of the camera.

Parameters
volumeVolume. Value range: 0-100; default: 100
Attention
If 100 is still not loud enough for you, you can set the volume to up to 150, but there may be side effects.

◆ setObserver:()

- (void) setObserver: (nullable id< TXDeviceObserver >)  observer

set onDeviceChanged callback (for Mac)

◆ setSystemVolumeType:()

- (NSInteger) setSystemVolumeType: (TXSystemVolumeType type

Setting the system volume type (for mobile OS)

Deprecated:
This API is not recommended after v9.5. Please use the startLocalAudio(quality) API in TRTCCloud instead, which param quality is used to decide audio quality.

◆ startCameraDeviceTest:()

- (NSInteger) startCameraDeviceTest: (NSView *)  view

Starting camera testing (for desktop OS)

Attention
You can use the setCurrentDevice API to switch between cameras during testing.

◆ startMicDeviceTest:testEcho:()

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

Starting mic testing (for desktop OS)

This API is used to test whether the mic functions properly. The mic volume detected (value range: 0-100) is returned via a callback.

Parameters
intervalInterval of volume callbacks

◆ startSpeakerDeviceTest:onVolumeChanged:()

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

Starting speaker testing (for desktop OS)

This API is used to test whether the audio playback device functions properly by playing a specified audio file. If users can hear audio during testing, the device functions properly.

Parameters
filePathPath of the audio file

◆ stopCameraDeviceTest()

- (NSInteger) stopCameraDeviceTest

Ending camera testing (for desktop OS)

◆ stopMicDeviceTest()

- (NSInteger) stopMicDeviceTest

Ending mic testing (for desktop OS)

◆ stopSpeakerDeviceTest()

- (NSInteger) stopSpeakerDeviceTest

Ending speaker testing (for desktop OS)

◆ switchCamera:()

- (NSInteger) switchCamera: (BOOL)  frontCamera

Switching to the front/rear camera (for mobile OS)

Enumeration Type Documentation

◆ TXAudioRoute

enum TXAudioRoute : NSInteger

Audio route (the route via which audio is played)

Audio route is the route (speaker or receiver) via which audio is played. It applies only to mobile devices such as mobile phones. A mobile phone has two speakers: one at the top (receiver) and the other the bottom.

  • If the audio route is set to the receiver, the volume is relatively low, and audio can be heard only when the phone is put near the ear. This mode has a high level of privacy and is suitable for answering calls.
  • If the audio route is set to the speaker, the volume is relatively high, and there is no need to put the phone near the ear. This mode enables the "hands-free" feature.
Enumerator
TXAudioRouteSpeakerphone 

Speakerphone: the speaker at the bottom is used for playback (hands-free). With relatively high volume, it is used to play music out loud.

TXAudioRouteEarpiece 

Earpiece: the receiver at the top is used for playback. With relatively low volume, it is suitable for call scenarios that require privacy.

◆ TXMediaDeviceState

enum TXMediaDeviceState : NSInteger

Device operation

This enumerated value is used to notify the status change of the local device onDeviceChanged.

Enumerator
TXMediaDeviceStateAdd 

The device has been plugged in.

TXMediaDeviceStateRemove 

The device has been removed.

TXMediaDeviceStateActive 

The device has been enabled.

◆ TXMediaDeviceType

enum TXMediaDeviceType : NSInteger

Device type (for desktop OS)

This enumerated type defines three types of audio/video devices, namely camera, mic and speaker, so that you can use the same device management API to manage three types of devices.

Enumerator
TXMediaDeviceTypeUnknown 

undefined device type

TXMediaDeviceTypeAudioInput 

microphone

TXMediaDeviceTypeAudioOutput 

speaker or earpiece

TXMediaDeviceTypeVideoCamera 

camera

◆ TXSystemVolumeType

enum TXSystemVolumeType : NSInteger

System volume type (for mobile devices only)

Deprecated:
This API is not recommended after v9.5.

Smartphones usually have two types of system volume: call volume and media volume.

  • Call volume is designed for call scenarios. It comes with acoustic echo cancellation (AEC) and supports audio capturing by Bluetooth earphones, but its sound quality is average. If you cannot turn the volume down to 0 (i.e., mute the phone) using the volume buttons, then your phone is using call volume.
  • Media volume is designed for media scenarios such as music playback. AEC does not work when media volume is used, and Bluetooth earphones cannot be used for audio capturing. However, media volume delivers better music listening experience. If you are able to mute your phone using the volume buttons, then your phone is using media volume.

The SDK offers three system volume control modes: auto, call volume, and media volume.

Enumerator
TXSystemVolumeTypeAuto 

Auto.

TXSystemVolumeTypeMedia 

Media volume.

TXSystemVolumeTypeVOIP 

Call volume.