Documentation
Voice Call
Console Agora.io Community Submit ticket
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 followSystemPlaybackDevice (bool enable)=0
 
virtual int followSystemRecordingDevice (bool enable)=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 get 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 (for macOS and Windows only).

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 (for macOS and Windows only).

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 (for macOS and Windows only).

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 (for macOS and Windows only).

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.

◆ followSystemPlaybackDevice()

virtual int agora::rtc::IAudioDeviceManager::followSystemPlaybackDevice ( bool  enable)
pure virtual

Sets the audio playback device used by the SDK to follow the system default audio playback device (for macOS and Windows only).

Since
v3.6.0
Parameters
enableWhether to follow the system default audio playback device:
  • true: Follow. The SDK immediately switches the audio playback device when the system default audio playback device changes.
  • false: Do not follow. The SDK switches the audio playback device to the system default audio playback device only when the currently used audio playback device is disconnected.
Returns
  • 0: Success.
  • < 0: Failure.

◆ followSystemRecordingDevice()

virtual int agora::rtc::IAudioDeviceManager::followSystemRecordingDevice ( bool  enable)
pure virtual

Sets the audio recording device used by the SDK to follow the system default audio recording device (for macOS and Windows only).

Since
v3.6.0
Parameters
enableWhether to follow the system default audio recording device:
  • true: Follow. The SDK immediately switches the audio recording device when the system default audio recording device changes.
  • false: Do not follow. The SDK switches the audio recording device to the system default audio recording device only when the currently used audio recording device is disconnected.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startPlaybackDeviceTest()

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

Starts the audio playback device test (for macOS and Windows only).

This method tests whether 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.

As of v3.6.2, you can call this method either before or after joining a channel. Depending on the call sequence, the SDK triggers the following callbacks every 100 ms to report the volume of the audio playback device:

  • onAudioVolumeIndication and onAudioDeviceTestVolumeIndication when you call this method before joining the channel, with the following values:

    • uid = 1 and volume in onAudioVolumeIndication.
    • volumeType = AudioTestPlaybackVolume(1) and volume in onAudioDeviceTestVolumeIndication.

    The two callbacks report the same volume information. Agora recommends using onAudioDeviceTestVolumeIndication.

  • onAudioDeviceTestVolumeIndication when you call this method after joining a channel, which reports volumeType = AudioTestPlaybackVolume(1) and volume.
Note
  • Calling this method after joining a channel tests the audio playback device that the SDK is using.
  • After calling startPlaybackDeviceTest, you must call stopPlaybackDeviceTest to stop the test.
Parameters
testAudioFilePathThe absolute path in UTF-8 of the audio file used for the audio playback device test.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPlaybackDeviceTest()

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

Stops the audio playback device test (for macOS and Windows only).

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 (for macOS and Windows only).

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

Gets the volume of the audio playback device (for macOS and Windows only).

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 (for macOS and Windows only).

Note
Ensure that you call this method after joining a channel.
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

Gets the volume of the microphone (for macOS and Windows only).

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 (for macOS and Windows only).

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

Gets the mute status of the audio playback device (for macOS and Windows only).

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 (for macOS and Windows only).

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

Gets the microphone's mute status (for macOS and Windows only).

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 (for macOS and Windows only).

This method tests whether the audio capturing device works properly.

As of v3.6.2, you can call this method either before or after joining a channel. Depending on the call sequence, the SDK triggers the following callbacks at the set time interval to report the volume of the audio capturing device:

  • onAudioVolumeIndication and onAudioDeviceTestVolumeIndication when you call this method before joining the channel, with the following values:

    • uid = 0 and volume in onAudioVolumeIndication.
    • volumeType = AudioTestRecordingVolume(0) and volume in onAudioDeviceTestVolumeIndication.

    The two callbacks report the same volume information. Agora recommends using onAudioDeviceTestVolumeIndication.

  • onAudioDeviceTestVolumeIndication when you call this method after joining a channel, which reports volumeType = AudioTestRecordingVolume(0) and volume.
Note
  • When you call this method after joining a channel, ensure the audio capturing device is on ( enableLocalAudio is set as true); otherwise, the method call fails, and the SDK triggers the onError callback with ERR_ADM_START_RECORDING(1012).
  • Calling this method after joining a channel tests the audio capturing device that the SDK is using.
  • After calling startRecordingDeviceTest, you must call stopRecordingDeviceTest to stop the test.
Parameters
indicationIntervalThe time interval (ms) at which the onAudioVolumeIndication or onAudioDeviceTestVolumeIndication callback returns. Agora recommends a setting greater than 200 ms. This value must be 10 ms or greater; otherwise, you cannot receive the onAudioVolumeIndication or onAudioDeviceTestVolumeIndication callback.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopRecordingDeviceTest()

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

Stops the audio capturing device test (for macOS and Windows only).

This method stops the audio capturing device 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

Gets the audio playback device associated with the device ID (for macOS and Windows only).

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

Gets the audio playback device information associated with the device ID and device name (for macOS and Windows only).

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

Gets the audio capturing device associated with the device ID (for macOS and Windows only).

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

Gets the audio capturing device information associated with the device ID and device name (for macOS and Windows only).

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 (for macOS and Windows only).

This method tests whether the local audio capturing device and playback device work properly. After calling this method, the audio capturing device samples the local audio, and then the audio playback device plays the sampled audio.

As of v3.6.2, you can call this method either before or after joining a channel. Depending on the call sequence, the SDK triggers the following callbacks at the set time interval to report the volume of the audio capturing and playback devices:

  • Two onAudioVolumeIndication callbacks and two onAudioDeviceTestVolumeIndication callbacks when you call this method before joining the channel, with the following values:

    • uid = 0 and volume in one onAudioVolumeIndication callback; uid = 1 and volume in the other onAudioVolumeIndication callback.
    • volumeType = AudioTestRecordingVolume(0) and volume in one onAudioDeviceTestVolumeIndication callback; volumeType = AudioTestPlaybackVolume(1) and volume in the other onAudioDeviceTestVolumeIndication callback.

    The onAudioVolumeIndication and onAudioDeviceTestVolumeIndication callbacks report the same volume information. Agora recommends using onAudioDeviceTestVolumeIndication.

  • Two onAudioDeviceTestVolumeIndication callbacks when you call this method after joining a channel, with the following values:
    • volumeType = AudioTestRecordingVolume(0) and volume in one callback;
    • volumeType = AudioTestPlaybackVolume(1) and volume in the other one.
Note
  • When you call this method after joining a channel, ensure the audio capturing device is on (enableLocalAudio is set as true); otherwise, the method call fails, and the SDK triggers the onError callback with ERR_ADM_START_RECORDING(1012).
  • Calling this method after joining a channel tests the audio capturing and playback devices that the SDK is using.
  • This method tests local audio devices and does not report the network conditions.
  • After calling this method, you must call stopAudioDeviceLoopbackTest to stop the test.
Parameters
indicationIntervalThe time interval (ms) at which the onAudioVolumeIndication or onAudioDeviceTestVolumeIndication callbacks return. Agora recommends a setting greater than 200 ms. This value must be 10 ms or greater; otherwise, you cannot receive these callbacks.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopAudioDeviceLoopbackTest()

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

Stops the audio device loopback test (for macOS and Windows only).

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 (for macOS and Windows only).