Dev Center
Voice Call
Agora.io Community
English
search-icon
Agora C++ API Reference for All Platforms
Index IRtcEngine IRtcEngineEventHandler IChannel IChannelEventHandler IAudioDeviceManager IVideoDeviceManager

Public Member Functions

virtual IAudioDeviceCollection * enumeratePlaybackDevices ()=0
 
virtual IAudioDeviceCollection * enumerateRecordingDevices ()=0
 
virtual int setPlaybackDevice (const char deviceId[MAX_DEVICE_ID_LENGTH])=0
 
virtual int setRecordingDevice (const char deviceId[MAX_DEVICE_ID_LENGTH])=0
 
virtual int startPlaybackDeviceTest (const char *testAudioFilePath)=0
 
virtual int stopPlaybackDeviceTest ()=0
 
virtual int setPlaybackDeviceVolume (int volume)=0
 
virtual int getPlaybackDeviceVolume (int *volume)=0
 
virtual int setRecordingDeviceVolume (int volume)=0
 
virtual int getRecordingDeviceVolume (int *volume)=0
 
virtual int setPlaybackDeviceMute (bool mute)=0
 
virtual int getPlaybackDeviceMute (bool *mute)=0
 
virtual int setRecordingDeviceMute (bool mute)=0
 
virtual int getRecordingDeviceMute (bool *mute)=0
 
virtual int startRecordingDeviceTest (int indicationInterval)=0
 
virtual int stopRecordingDeviceTest ()=0
 
virtual int getPlaybackDevice (char deviceId[MAX_DEVICE_ID_LENGTH])=0
 
virtual int getPlaybackDeviceInfo (char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH])=0
 
virtual int getRecordingDevice (char deviceId[MAX_DEVICE_ID_LENGTH])=0
 
virtual int getRecordingDeviceInfo (char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH])=0
 
virtual int startAudioDeviceLoopbackTest (int indicationInterval)=0
 
virtual int stopAudioDeviceLoopbackTest ()=0
 
virtual void release ()=0
 

Protected Member Functions

virtual ~IAudioDeviceManager ()
 

Detailed Description

Audio device management methods.

The IAudioDeviceManager interface class allows for audio device interface testing. Instantiate an AAudioDeviceManager class to retrieve the IAudioDeviceManager interface.

Constructor & Destructor Documentation

◆ ~IAudioDeviceManager()

virtual agora::rtc::IAudioDeviceManager::~IAudioDeviceManager ( )
inlineprotectedvirtual

Member Function Documentation

◆ enumeratePlaybackDevices()

virtual IAudioDeviceCollection* agora::rtc::IAudioDeviceManager::enumeratePlaybackDevices ( )
pure virtual

Enumerates the audio playback devices.

This method returns an IAudioDeviceCollection object that includes all audio playback devices in the system. With the IAudioDeviceCollection object, the application can enumerate the audio playback devices.

Note
The application must call the release method to release the returned object after using it.
Returns
  • Success: Returns an IAudioDeviceCollection object that includes all audio playback devices in the system. For wireless Bluetooth headset devices with master and slave headsets, the master headset is the playback device.
  • Returns NULL: Failure.

◆ enumerateRecordingDevices()

virtual IAudioDeviceCollection* agora::rtc::IAudioDeviceManager::enumerateRecordingDevices ( )
pure virtual

Enumerates the audio capturing devices.

This method returns an IAudioDeviceCollection object that includes all audio capturing devices in the system. With the IAudioDeviceCollection object, the application can enumerate the audio capturing devices.

Note
The application needs to call the release method to release the returned object after using it.
Returns
  • Returns an IAudioDeviceCollection object that includes all audio capturing devices in the system: Success.
  • Returns NULL: Failure.

◆ setPlaybackDevice()

virtual int agora::rtc::IAudioDeviceManager::setPlaybackDevice ( const char  deviceId[MAX_DEVICE_ID_LENGTH])
pure virtual

Sets the audio playback device using the device ID.

Note
Plugging or unplugging the audio device does not change the device ID.
Parameters
deviceIdDevice ID of the audio playback device, retrieved by calling the enumeratePlaybackDevices method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRecordingDevice()

virtual int agora::rtc::IAudioDeviceManager::setRecordingDevice ( const char  deviceId[MAX_DEVICE_ID_LENGTH])
pure virtual

Sets the audio capturing device using the device ID.

Parameters
deviceIdDevice ID of the audio capturing device, retrieved by calling the enumerateRecordingDevices method.
Note
Plugging or unplugging the audio device does not change the device ID.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startPlaybackDeviceTest()

virtual int agora::rtc::IAudioDeviceManager::startPlaybackDeviceTest ( const char *  testAudioFilePath)
pure virtual

Starts the audio playback device test.

This method tests if the audio playback device works properly. Once a user starts the test, the SDK plays an audio file specified by the user. If the user can hear the audio, the playback device works properly.

After calling this method, the SDK triggers the onAudioVolumeIndication callback every 100 ms, which reports uid = 1 and the volume of the playback device.

Note
  • Call this method before joining a channel.
  • This method is for Windows and macOS only.
Parameters
testAudioFilePathPointer to the path of the audio file for the audio playback device test in UTF-8:
  • Supported file formats: wav, mp3, m4a, and aac.
  • Supported file sample rates: 8000, 16000, 32000, 44100, and 48000 Hz.
Returns
  • 0: Success, and you can hear the sound of the specified audio file.
  • < 0: Failure.

◆ stopPlaybackDeviceTest()

virtual int agora::rtc::IAudioDeviceManager::stopPlaybackDeviceTest ( )
pure virtual

Stops the audio playback device test.

This method stops testing the audio playback device. You must call this method to stop the test after calling the startPlaybackDeviceTest method.

Returns
  • 0: Success.
  • < 0: Failure.

◆ setPlaybackDeviceVolume()

virtual int agora::rtc::IAudioDeviceManager::setPlaybackDeviceVolume ( int  volume)
pure virtual

Sets the volume of the audio playback device.

Parameters
volumeSets the volume of the audio playback device. The value ranges between 0 (lowest volume) and 255 (highest volume).
Returns
  • 0: Success.
  • < 0: Failure.

◆ getPlaybackDeviceVolume()

virtual int agora::rtc::IAudioDeviceManager::getPlaybackDeviceVolume ( int *  volume)
pure virtual

Retrieves the volume of the audio playback device.

Parameters
volumePointer to the audio playback device volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRecordingDeviceVolume()

virtual int agora::rtc::IAudioDeviceManager::setRecordingDeviceVolume ( int  volume)
pure virtual

Sets the volume of the microphone.

Parameters
volumeSets the volume of the microphone. The value ranges between 0 (lowest volume) and 255 (highest volume).
Returns
  • 0: Success.
  • < 0: Failure.

◆ getRecordingDeviceVolume()

virtual int agora::rtc::IAudioDeviceManager::getRecordingDeviceVolume ( int *  volume)
pure virtual

Retrieves the volume of the microphone.

Parameters
volumePointer to the microphone volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setPlaybackDeviceMute()

virtual int agora::rtc::IAudioDeviceManager::setPlaybackDeviceMute ( bool  mute)
pure virtual

Mutes the audio playback device.

Parameters
muteSets whether to mute/unmute the audio playback device:
  • true: Mutes.
  • false: Unmutes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getPlaybackDeviceMute()

virtual int agora::rtc::IAudioDeviceManager::getPlaybackDeviceMute ( bool *  mute)
pure virtual

Retrieves the mute status of the audio playback device.

Parameters
mutePointer to whether the audio playback device is muted/unmuted.
  • true: Muted.
  • false: Unmuted.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRecordingDeviceMute()

virtual int agora::rtc::IAudioDeviceManager::setRecordingDeviceMute ( bool  mute)
pure virtual

Mutes/Unmutes the microphone.

Parameters
muteSets whether to mute/unmute the microphone:
  • true: Mutes.
  • false: Unmutes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getRecordingDeviceMute()

virtual int agora::rtc::IAudioDeviceManager::getRecordingDeviceMute ( bool *  mute)
pure virtual

Retrieves the microphone's mute status.

Parameters
mutePointer to whether the microphone is muted/unmuted.
  • true: Muted.
  • false: Unmuted.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startRecordingDeviceTest()

virtual int agora::rtc::IAudioDeviceManager::startRecordingDeviceTest ( int  indicationInterval)
pure virtual

Starts the audio capturing device test.

This method tests whether the audio sampling device works properly.

After calling this method, the SDK triggers the onAudioVolumeIndication callback at the time interval set in this method, which reports uid = 0 and the volume of the sampling device.

Note
  • Call this method before joining a channel.
  • This method is for Windows and macOS only.
Parameters
indicationIntervalThe time interval (ms) at which the onAudioVolumeIndication callback returns. We recommend a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive the onAudioVolumeIndication callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopRecordingDeviceTest()

virtual int agora::rtc::IAudioDeviceManager::stopRecordingDeviceTest ( )
pure virtual

Stops the microphone test.

This method stops the microphone test. You must call this method to stop the test after calling the startRecordingDeviceTest method.

Returns
  • 0: Success.
  • < 0: Failure.

◆ getPlaybackDevice()

virtual int agora::rtc::IAudioDeviceManager::getPlaybackDevice ( char  deviceId[MAX_DEVICE_ID_LENGTH])
pure virtual

Retrieves the audio playback device associated with the device ID.

Parameters
deviceIdPointer to the ID of the audio playback device.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getPlaybackDeviceInfo()

virtual int agora::rtc::IAudioDeviceManager::getPlaybackDeviceInfo ( char  deviceId[MAX_DEVICE_ID_LENGTH],
char  deviceName[MAX_DEVICE_ID_LENGTH] 
)
pure virtual

Retrieves the audio playback device information associated with the device ID and device name.

Parameters
deviceIdPointer to the device ID of the audio playback device.
deviceNamePointer to the device name of the audio playback device.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getRecordingDevice()

virtual int agora::rtc::IAudioDeviceManager::getRecordingDevice ( char  deviceId[MAX_DEVICE_ID_LENGTH])
pure virtual

Retrieves the audio capturing device associated with the device ID.

Parameters
deviceIdPointer to the device ID of the audio capturing device.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getRecordingDeviceInfo()

virtual int agora::rtc::IAudioDeviceManager::getRecordingDeviceInfo ( char  deviceId[MAX_DEVICE_ID_LENGTH],
char  deviceName[MAX_DEVICE_ID_LENGTH] 
)
pure virtual

Retrieves the audio capturing device information associated with the device ID and device name.

Parameters
deviceIdPointer to the device ID of the audio capturing device.
deviceNamePointer to the device name of the audio capturing device.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startAudioDeviceLoopbackTest()

virtual int agora::rtc::IAudioDeviceManager::startAudioDeviceLoopbackTest ( int  indicationInterval)
pure virtual

Starts the audio device loopback test.

This method tests whether the local audio sampling device and playback device are working properly. After calling this method, the audio sampling device samples the local audio, and the audio playback device plays the sampled audio. The SDK triggers two independent onAudioVolumeIndication callbacks at the time interval set in this method, which reports the following information:

  • uid = 0 and the volume information of the sampling device.
  • uid = 1 and the volume information of the playback device.
Note
  • Call this method before joining a channel.
  • This method tests local audio devices and does not report the network conditions.
  • This method is for Windows and macOS only.
Parameters
indicationIntervalThe time interval (ms) at which the onAudioVolumeIndication callback returns. We recommend a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive the onAudioVolumeIndication callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopAudioDeviceLoopbackTest()

virtual int agora::rtc::IAudioDeviceManager::stopAudioDeviceLoopbackTest ( )
pure virtual

Stops the audio device loopback test.

Note
Ensure that you call this method to stop the loopback test after calling the startAudioDeviceLoopbackTest method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ release()

virtual void agora::rtc::IAudioDeviceManager::release ( )
pure virtual

Releases all IAudioDeviceManager resources.

score