Audio Device Management
Introduces methods and callbacks related to audio device management.
enumeratePlaybackDevices
Enumerates the audio playback devices.
virtual IAudioDeviceCollection* enumeratePlaybackDevices() = 0;
This method returns an IAudioDeviceCollection object that includes all audio playback devices in the system. With the IAudioDeviceCollection object, the application can enumerate video devices. 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.
- Failure: NULL.
enumerateRecordingDevices
Enumerates the audio capture devices.
virtual IAudioDeviceCollection* enumerateRecordingDevices() = 0;
This method returns an IAudioDeviceCollection object that includes all audio capture devices in the system. With the IAudioDeviceCollection object, the application can enumerate video devices. The application must call the release method to release the returned object after using it.
Returns
- Success: An IAudioDeviceCollection object including all audio capture devices.
- Failure: NULL.
followSystemLoopbackDevice
Sets whether the loopback device follows the system default playback device.
virtual int followSystemLoopbackDevice(bool enable) = 0;
- Since
- v4.0.1
This method applies to Windows only.
Parameters
- enable
- Whether to follow the system default audio playback device:
true
: Follow. When the default playback device of the system is changed, the SDK immediately switches to the loopback device.false
: Do not follow. The SDK switches the audio loopback device to the system default audio playback device only when the current audio playback device is disconnected.
Returns
- 0: Success.
- < 0: Failure.
followSystemPlaybackDevice
Sets the audio playback device used by the SDK to follow the system default audio playback device.
virtual int followSystemPlaybackDevice(bool enable) = 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
Sets the audio recording device used by the SDK to follow the system default audio recording device.
virtual int followSystemRecordingDevice(bool enable) = 0;
- 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.
getApplicationVolume
Gets the volume of the application.
virtual int getApplicationVolume(int& volume) = 0;
Parameters
- volume
- The volume of the application. The value range is [0,255].
Returns
- 0: Success.
- < 0: Failure.
getAudioDeviceInfo
Gets the audio device information.
virtual int getAudioDeviceInfo(DeviceInfo& deviceInfo) = 0;
After calling this method, you can get whether the audio device supports ultra-low-latency capture and playback.
- This method is for Android only.
- You can call this method either before or after joining a channel.
Parameters
- deviceInfo
- Input and output parameter. A DeviceInfo object that identifies the audio device information.
- Input value: A DeviceInfo object.
- Output value: A DeviceInfo object containing audio device information.
Returns
- 0: Success.
- < 0: Failure.
getCount
Gets the total number of audio playback or audio capture devices.
virtual int getCount() = 0;
If you call enumeratePlaybackDevices before this method, the SDK returns the number of audio playback devices. If you call enumerateRecordingDevices before this method, the SDK returns the number of audio capture devices.
Returns
The number of audio playback or audio capture devices.
getDefaultDevice
Gets the default audio device of the system.
virtual int getDefaultDevice(char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
- This method is for Windows and macOS only.
- You need to call enumeratePlaybackDevices or enumerateRecordingDevices to get the device list before calling this method.
Parameters
- deviceName
- Output parameter, the name of the system default audio device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
- deviceId
- Output parameter, the device ID of the the system default audio device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
getDevice
Gets the information of a specified audio device.
virtual int getDevice(int index, char deviceName[MAX_DEVICE_ID_LENGTH], char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- index
- An input parameter. The index of the specified device.
- deviceName
- An output parameter. The device name. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
- deviceId
- An output parameter. The device ID. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
getLoopbackDevice
Gets the current loopback device.
virtual int getLoopbackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
- Since
- v4.0.1
This method applies to Windows only.
Parameters
- deviceId
- Output parameter, the ID of the current loopback device.
Returns
- 0: Success.
- < 0: Failure.
getPlaybackDevice
Retrieves the audio playback device associated with the device ID.
virtual int getPlaybackDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
- Output parameter. The device ID of the audio playback device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
getPlaybackDeviceInfo
Retrieves the audio playback device information associated with the device ID and device name.
virtual int getPlaybackDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
- The device ID of the playback device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
- deviceName
- The device name of the playback device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
getRecordingDevice
Gets the current audio recording device.
virtual int getRecordingDevice(char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
- Output parameter. The device ID of the recording device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
getRecordingDeviceInfo
Retrieves the information of the audio recording device.
virtual int getRecordingDeviceInfo(char deviceId[MAX_DEVICE_ID_LENGTH], char deviceName[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
- The device ID of the recording device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
- deviceName
- The device name of the recording device. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
isApplicationMute
Gets the whether the app is muted.
virtual int isApplicationMute(bool &mute) = 0;
Parameters
- mute
-
Whether the app is muted:
true
: The app is muted.false
: The app is not muted.
Returns
- 0: Success.
- < 0: Failure.
isSpeakerphoneEnabled
Checks whether the speakerphone is enabled.
virtual bool isSpeakerphoneEnabled() = 0;
- This method is for Android and iOS only.
- You can call this method either before or after joining a channel.
Returns
true
: The speakerphone is enabled, and the audio plays from the speakerphone.false
: The speakerphone is not enabled, and the audio plays from devices other than the speakerphone. For example, the headset or earpiece.
release
Releases all the resources occupied by the IAudioDeviceCollection object.
virtual void release() = 0;
release
Releases all the resources occupied by the IAudioDeviceManager object.
virtual void release() = 0;
setApplicationMute
Mutes/Unmutes the app.
virtual int setApplicationMute(bool mute) = 0;
Parameters
- mute
- Whether to mute the app:
true
: Mute the app.false
: Unmute the app.
Returns
- 0: Success.
- < 0: Failure.
setApplicationVolume
Sets the app volume.
virtual int setApplicationVolume(int volume) = 0;
Parameters
- volume
- The volume of the app. The value range is [0,255].
Returns
- 0: Success.
- < 0: Failure.
setDevice
Specifies an audio device.
virtual int setDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
- The device ID. The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
setEnableSpeakerphone
Enables/Disables the audio route to the speakerphone.
virtual int setEnableSpeakerphone(bool speakerOn) = 0;
After a successful method call, the SDK triggers the onAudioRoutingChanged callback.
You can call this method before joining a channel, when in a channel, or after leaving a channel. However, Agora recommends calling this method only when you are in a channel to change the audio route temporarily.
- If you do not have a clear requirement for transient settings, Agora recommends calling setDefaultAudioRouteToSpeakerphone to set the audio route.
- Any user behavior or audio-related API call might change the transient setting of setEnableSpeakerphone. See Audio Route for detailed change principles.
- Due to system limitations, if the user uses an external audio playback device such as a Bluetooth or wired headset on an iOS device, this method does not take effect.
Parameters
- speakerOn
-
Whether to set the speakerphone as the default audio route:
true
: Set the speakerphone as the audio route temporarily.false
: Do not set the speakerphone as the audio route.
Returns
- 0: Success.
- < 0: Failure.
setLoopbackDevice
Sets the loopback device.
virtual int setLoopbackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
- Since
- v4.0.1
The SDK uses the current playback device as the loopback device by default. If you want to specify another audio device as the loopback device, call this method, and set deviceId to the loopback device you want to specify.
This method applies to Windows only.
The scenarios where this method is applicable are as follows:
- If the loopback device is set as the Bluetooth headset, the SDK publishes the music in app A to the remote end.
- If the loopback device is set as the speaker, the SDK does not publish the music in app A to the remote end.
- If you set the loopback device as the Bluetooth headset, and then use a wired headset to play the music in app A, you need to call this method again, set the loopback device as the wired headset, and the SDK continues to publish the music in app A to remote end.
Parameters
- deviceId
-
Specifies the loopback device of the SDK. You can get the device ID by calling enumeratePlaybackDevices. Connecting or disconnecting the audio device does not change the value of deviceId.
The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
setPlaybackDevice
Sets the audio playback device.
virtual int setPlaybackDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
-
The ID of the specified audio playback device. You can get the device ID by calling enumeratePlaybackDevices. Connecting or disconnecting the audio device does not change the value of deviceId.
The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
setRecordingDevice
Sets the audio recording device.
virtual int setRecordingDevice(const char deviceId[MAX_DEVICE_ID_LENGTH]) = 0;
Parameters
- deviceId
-
The ID of the audio recording device. You can get the device ID by calling enumerateRecordingDevices. Plugging or unplugging the audio device does not change the value of deviceId.
The maximum length is MAX_DEVICE_ID_LENGTH_TYPE.
Returns
- 0: Success.
- < 0: Failure.
setRecordingDeviceVolume
Sets the volume of the audio recording device.
virtual int setRecordingDeviceVolume(int volume) = 0;
Parameters
- volume
- The volume of the audio recording device. The value range is [0,255].
Returns
- 0: Success.
- < 0: Failure.
startAudioDeviceLoopbackTest
Starts an audio device loopback test.
virtual int startAudioDeviceLoopbackTest(int indicationInterval) = 0;
This method tests whether the local audio capture device and playback device are working properly. Once the test starts, the audio recording device records the local audio, and the audio playback device plays the captured audio. The SDK triggers two independent onAudioVolumeIndication callbacks at the time interval set in this method, which reports the volume information of the capture device (uid = 0) and the volume information of the playback device (uid = 1) respectively.
- Ensure that you call this method before joining a channel.
- This method tests local audio devices and does not report the network conditions.
Parameters
- indicationInterval
- The time interval (ms) at which the SDK triggers the onAudioVolumeIndication callback. Agora recommends setting a value 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.
startPlaybackDeviceTest
Starts the audio playback device test.
virtual int startPlaybackDeviceTest(const char* testAudioFilePath) = 0;
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.
After calling this method, the SDK triggers the onAudioVolumeIndication callback every 100 ms, reporting uid = 1 and the volume information of the playback device.
Parameters
- testAudioFilePath
-
The path of the audio file. The data format is string 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.
- < 0: Failure.
startRecordingDeviceTest
Starts the audio capture device test.
virtual int startRecordingDeviceTest(int indicationInterval) = 0;
This method tests whether the audio capture 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 information of the capturing device.
- This method is for Windows and macOS only.
- Ensure that you call this method before joining a channel.
Parameters
- indicationInterval
- The time interval (ms) at which the SDK triggers the onAudioVolumeIndication callback. Agora recommends 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
Stops the audio device loopback test.
virtual int stopAudioDeviceLoopbackTest() = 0;
- Ensure that you call this method before joining a channel.
- Ensure that you call this method to stop the loopback test after calling the startAudioDeviceLoopbackTest method.
Returns
- 0: Success.
- < 0: Failure.
stopPlaybackDeviceTest
Stops the audio playback device test.
virtual int stopPlaybackDeviceTest() = 0;
This method stops the audio playback device test. You must call this method to stop the test after calling the startPlaybackDeviceTest method.
Returns
- 0: Success.
- < 0: Failure.
stopRecordingDeviceTest
Stops the audio capture device test.
virtual int stopRecordingDeviceTest() = 0;
This method stops the audio capture device test. You must call this method to stop the test after calling the startRecordingDeviceTest method.
Returns
- 0: Success.
- < 0: Failure.
onAudioDeviceStateChanged
Occurs when the audio device state changes.
virtual void onAudioDeviceStateChanged(const char* deviceId, int deviceType, int deviceState) { (void)deviceId; (void)deviceType; (void)deviceState; }
This callback notifies the application that the system's audio device state is changed. For example, a headset is unplugged from the device.
Parameters
- deviceId
- The device ID.
- deviceType
- The device type. See MEDIA_DEVICE_TYPE.
- deviceState
- Media device states.
onAudioDeviceVolumeChanged
Reports the volume change of the audio device or app.
virtual void onAudioDeviceVolumeChanged(MEDIA_DEVICE_TYPE deviceType, int volume, bool muted) { (void)deviceType; (void)volume; (void)muted; }
Occurs when the volume on the playback device, audio capture device, or the volume in the application changes.
Parameters
- deviceType
- The device type. See MEDIA_DEVICE_TYPE.
- volume
- The volume value. The range is [0, 255].
- muted
-
Whether the audio device is muted:
true
: The audio device is muted.false
: The audio device is not muted.