#include <IAgoraRtcEngine.h>

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

deviceId Device 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

deviceId Device 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

enable

Whether 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

enable

Whether 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

testAudioFilePath The 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

volume Sets 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

volume Pointer 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

volume Sets 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

volume Pointer 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

mute	Sets 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

mute	Pointer 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

mute	Sets 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

mute	Pointer 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

indicationInterval The 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

deviceId Pointer 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

deviceId	Pointer to the device ID of the audio playback device.
deviceName	Pointer 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

deviceId Pointer 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

deviceId	Pointer to the device ID of the audio capturing device.
deviceName	Pointer 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

indicationInterval The 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).

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IAudioDeviceManager()

Member Function Documentation

◆ enumeratePlaybackDevices()

◆ enumerateRecordingDevices()

◆ setPlaybackDevice()

◆ setRecordingDevice()

◆ followSystemPlaybackDevice()

◆ followSystemRecordingDevice()

◆ startPlaybackDeviceTest()

◆ stopPlaybackDeviceTest()

◆ setPlaybackDeviceVolume()

◆ getPlaybackDeviceVolume()

◆ setRecordingDeviceVolume()

◆ getRecordingDeviceVolume()

◆ setPlaybackDeviceMute()

◆ getPlaybackDeviceMute()

◆ setRecordingDeviceMute()

◆ getRecordingDeviceMute()

◆ startRecordingDeviceTest()

◆ stopRecordingDeviceTest()

◆ getPlaybackDevice()

◆ getPlaybackDeviceInfo()

◆ getRecordingDevice()

◆ getRecordingDeviceInfo()

◆ startAudioDeviceLoopbackTest()

◆ stopAudioDeviceLoopbackTest()

◆ release()