AudioDeviceManager
Methods for managing audio devices.
enumeratePlaybackDevices
Gets a list of all playback devices in the system.
List<AudioDeviceInfo> enumeratePlaybackDevices();
Return Values
- If the method call succeeds, returns an array of AudioDeviceInfo containing the device ID and name of all playback devices.
- If the method call fails: returns an empty list.
enumerateRecordingDevices
Gets the list of all audio recording devices in the system.
List<AudioDeviceInfo> enumerateRecordingDevices();
Return Values
- If the method call succeeds, returns an array of AudioDeviceInfo containing the device ID and device name of all audio recording devices.
- If the method call fails: returns an empty list.
followSystemLoopbackDevice
Sets whether the loopback recording device follows the system default playback device.
Future<void> followSystemLoopbackDevice(bool enable);
This method is applicable to Windows and macOS only.
Parameters
- enable
- Whether to follow the system default playback device:
- true: Follow. When the system default playback device changes, the SDK immediately switches the loopback recording device.
- false: Do not follow. The SDK switches to the system default playback device only when the current loopback recording device is removed.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
followSystemPlaybackDevice
Sets whether the audio playback device used by the SDK follows the system default playback device.
Future<void> followSystemPlaybackDevice(bool enable);
Parameters
- enable
- Whether to follow the system default audio playback device:
- true: Follow. When the system default playback device changes, the SDK immediately switches the audio playback device.
- false: Do not follow. The SDK switches to the system default playback device only when the current audio playback device is removed.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
followSystemRecordingDevice
Sets whether the audio recording device used by the SDK follows the system default recording device.
Future<void> followSystemRecordingDevice(bool enable);
Parameters
- enable
- Whether to follow the system default audio recording device:
- true: Follow. When the system default recording device changes, the SDK immediately switches the recording device.
- false: Do not follow. The SDK switches to the system default recording device only when the current recording device is removed.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
getLoopbackDevice
Gets the current sound card capture device.
Future<String> getLoopbackDevice();
This method is applicable to Windows and macOS only.
Return Values
The ID of the current sound card capture device.
getPlaybackDefaultDevice
Gets the system default audio playback device.
Future<AudioDeviceInfo> getPlaybackDefaultDevice();
Return Values
Information about the default audio playback device. See AudioDeviceInfo.
getPlaybackDevice
Gets the current audio playback device.
Future<String> getPlaybackDevice();
Return Values
The current audio playback device.
getPlaybackDeviceInfo
Gets audio playback device information.
Future<AudioDeviceInfo> getPlaybackDeviceInfo();
Return Values
An AudioDeviceInfo object containing the device ID and device name of the audio playback device.
getPlaybackDeviceMute
Gets the mute status of the current playback device.
Future<bool> getPlaybackDeviceMute();
Return Values
- true: The playback device is muted.
- false: The playback device is not muted.
getPlaybackDeviceVolume
Gets the playback device volume.
Future<int> getPlaybackDeviceVolume();
Return Values
Playback device volume. Value range: [0,255].
getRecordingDefaultDevice
Gets the system default audio recording device.
Future<AudioDeviceInfo> getRecordingDefaultDevice();
Return Values
Information about the default audio recording device. See AudioDeviceInfo.
getRecordingDevice
Gets the current audio recording device.
Future<String> getRecordingDevice();
Return Values
The current audio recording device.
getRecordingDeviceInfo
Gets information about the audio recording device.
Future<AudioDeviceInfo> getRecordingDeviceInfo();
Return Values
AudioDeviceInfo object containing the device ID and name of the audio recording device.
getRecordingDeviceMute
Gets the mute status of the current recording device.
Future<bool> getRecordingDeviceMute();
Return Values
- true: The recording device is muted.
- false: The recording device is not muted.
getRecordingDeviceVolume
Gets the volume of the audio recording device.
Future<int> getRecordingDeviceVolume();
Return Values
Audio recording device volume. Value range: [0,255].
release
Releases all resources used by the AudioDeviceManager object.
Future<void> release();
setLoopbackDevice
Specifies the sound card capture device.
Future<void> setLoopbackDevice(String deviceId);
By default, the SDK uses the current playback device as the sound card capture device. To specify another audio device as the sound card capture device, call this method and set deviceId to the desired device.
This method changes the current recording device but does not change the system default recording device. For example, if the system default recording device is Microphone 1, and you call this method to set the current audio route to Sound Card 1 before joining a channel, the SDK will test Sound Card 1 during device testing. After testing, when you join the channel, the SDK will still use the system default recording device, i.e., Microphone 1.
- If the sound card capture device is set to the Bluetooth headset, the SDK will publish the music from App A to the remote end.
- If the sound card capture device is set to the speaker, the SDK will not publish the music from App A.
- If you switch from Bluetooth headset to wired headset for App A after setting the sound card capture device to Bluetooth headset, you need to call this method again to set the sound card capture device to wired headset, so that the SDK continues publishing App A's music to the remote end.
Parameters
- deviceId
- Specifies the SDK's sound card capture device. Obtained via enumeratePlaybackDevices. Plugging or unplugging devices does not affect
deviceId. Maximum length is MaxDeviceIdLengthType.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
setPlaybackDevice
Specifies the playback device.
Future<void> setPlaybackDevice(String deviceId);
This method changes the current audio route but does not change the system default audio route. For example, if the system default audio route is Speaker 1, and you call this method to set the current audio route to Speaker 2 before joining a channel, the SDK will test Speaker 2 during device testing. After testing, when you join the channel, the SDK will still use the system default audio route, i.e., Speaker 1.
Parameters
- deviceId
- Specifies the playback device. Obtained via enumeratePlaybackDevices. Plugging or unplugging devices does not affect
deviceId.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
setPlaybackDeviceMute
Sets the playback device to mute.
Future<void> setPlaybackDeviceMute(bool mute);
Parameters
- mute
- Whether to mute the playback device:
- true: Mute the playback device.
- false: Do not mute the playback device.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
setPlaybackDeviceVolume
Sets the playback device volume.
Future<void> setPlaybackDeviceVolume(int volume);
Parameters
- volume
- Playback device volume. Value range: [0,255].
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
setRecordingDevice
Specifies the audio recording device.
Future<void> setRecordingDevice(String deviceId);
This method allows you to change the current audio recording device without changing the system default audio recording device. Suppose the system default recording device is Microphone 1. If you call this method before joining a channel to set the current audio route to Bluetooth Headset 1, the SDK will test Bluetooth Headset 1 during device testing. After the test, when you join a channel, the SDK will still use the system default recording device, i.e., Microphone 1.
Parameters
- deviceId
- The Device ID of the audio recording device. You can get it through enumerateRecordingDevices. Plugging or unplugging the device does not affect the
deviceId.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
setRecordingDeviceMute
Mutes the current audio recording device.
Future<void> setRecordingDeviceMute(bool mute);
Parameters
- mute
- Whether to mute the audio recording device:
- true: Mute the recording device.
- false: Unmute the recording device.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
setRecordingDeviceVolume
Sets the volume of the audio recording device.
Future<void> setRecordingDeviceVolume(int volume);
(Windows and macOS only)
Parameters
- volume
- Volume of the audio recording device. Value range: [0,255]. 0 means muted, 255 means maximum volume.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
startAudioDeviceLoopbackTest
Starts the audio device loopback test.
Future<void> startAudioDeviceLoopbackTest(int indicationInterval);
This method tests whether the audio recording and playback devices are working properly. Once the test starts, the recording device captures local audio and the playback device plays it back. The SDK triggers two onAudioVolumeIndication callbacks at the specified interval, reporting the volume information of the recording device (uid = 0) and the playback device (uid = 1).
- (Windows and macOS only)
- Can be called before or after joining a channel.
- Only supported for the broadcaster role.
- This method only tests local audio devices and does not involve network connection.
- After the test is complete, you must call stopAudioDeviceLoopbackTest to stop the loopback test.
Parameters
- indicationInterval
- The time interval (in milliseconds) at which the SDK triggers the onAudioVolumeIndication callback. It is recommended to set it greater than 200 ms. It must not be less than 10 ms, otherwise the onAudioVolumeIndication callback will not be received.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
startPlaybackDeviceTest
Starts the audio playback device test.
Future<void> startPlaybackDeviceTest(String testAudioFilePath);
This method tests whether the local audio playback device is working properly. After starting the test, the SDK plays the specified audio file. If you can hear the sound, it indicates that the playback device is functioning correctly.
After calling this method, the SDK triggers the onAudioVolumeIndication callback every 100 ms to report the volume information of uid = 1 and the playback device.
The difference between this method and startEchoTest is that this method checks whether the local audio playback device works properly, while the latter checks whether the audio/video devices and network are functioning correctly.
Parameters
- testAudioFilePath
- The absolute path of the audio file. The path string must be encoded in UTF-8.
- Supported file formats: wav, mp3, m4a, aac.
- Supported sample rates: 8000, 16000, 32000, 44100, 48000.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
startRecordingDeviceTest
Starts the audio recording device test.
Future<void> startRecordingDeviceTest(int indicationInterval);
This method tests whether the local audio recording device works properly. After you call this method, the SDK triggers the onAudioVolumeIndication callback at the specified time interval to report the volume information of the recording device with uid = 0.
The difference between this method and startEchoTest is that this method checks whether the local audio recording device works properly, while the latter checks whether the audio and video devices and network are functioning properly.
Parameters
- indicationInterval
- The time interval at which the SDK triggers the onAudioVolumeIndication callback, in milliseconds. The minimum value is 10. Otherwise, the onAudioVolumeIndication callback will not be received, and the SDK returns error code
-2. Agora recommends setting this value to 100.
Return Values
- < 0: Method call failed. See Error Codes for details and resolution suggestions.
- -2: Invalid parameter setting. Please reset the parameter.
stopAudioDeviceLoopbackTest
Stops the audio device loopback test.
Future<void> stopAudioDeviceLoopbackTest();
- This method is only applicable to Windows and macOS.
- You can call this method either before or after joining a channel.
- Only the host role is allowed to call this method.
- After calling startAudioDeviceLoopbackTest, you must call this method to stop the audio device loopback test.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
stopPlaybackDeviceTest
Stops the audio playback device test.
Future<void> stopPlaybackDeviceTest();
This method stops the audio playback device test. After calling startPlaybackDeviceTest, you must call this method to stop the test.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.
stopRecordingDeviceTest
Stops the audio recording device test.
Future<void> stopRecordingDeviceTest();
This method stops the audio recording device test. After calling startRecordingDeviceTest, you must call this method to stop the test.
Return Values
When the method call succeeds, there is no return value; when fails, the AgoraRtcException exception is thrown. You need to catch the exception and handle it accordingly. See Error Codes for details and resolution suggestions.