IAudioDeviceManager

Audio device management methods.

EnumeratePlaybackDevices

Gets the list of all playback devices in the system.

public abstract DeviceInfo[] EnumeratePlaybackDevices();
Note: (Windows and macOS only)

Return Values

  • If the method call succeeds, returns a DeviceInfo array containing the device ID and device name of all audio playback devices.
  • If the method call fails: null.

EnumerateRecordingDevices

Gets the list of all audio recording devices in the system.

abstract DeviceInfo[] EnumerateRecordingDevices();
Note: (Windows and macOS only)

Return Values

  • If the method call succeeds, returns a DeviceInfo array containing the device ID and device name of all audio recording devices.
  • If the method call fails: null.

FollowSystemLoopbackDevice

Sets whether the loopback capture device follows the system default playback device.

public abstract int FollowSystemLoopbackDevice(bool enable);

This method is only applicable to Windows and macOS.

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 capture device accordingly.
  • false: Do not follow. The SDK switches to the system default playback device only when the current loopback capture device is removed.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

FollowSystemPlaybackDevice

Sets whether the audio playback device used by the SDK follows the system default audio playback device.

public abstract int FollowSystemPlaybackDevice(bool enable);
Note: (Windows and macOS only)

Parameters

enable
Whether to follow the system default audio playback device:
  • true: Follow. When the system default audio playback device changes, the SDK immediately switches to it.
  • false: Do not follow. The SDK switches to the system default audio playback device only when the current device used by the SDK is removed.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

FollowSystemRecordingDevice

Sets whether the audio recording device used by the SDK follows the system default audio recording device.

public abstract int FollowSystemRecordingDevice(bool enable);
Note: (Windows and macOS only)

Parameters

enable
Whether to follow the system default audio recording device:
  • true: Follow. When the system default audio recording device changes, the SDK immediately switches to it.
  • false: Do not follow. The SDK switches to the system default audio recording device only when the current device used by the SDK is removed.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetLoopbackDevice

Gets the current loopback capture device.

public abstract int GetLoopbackDevice(ref string deviceId);

This method is for Windows and macOS only.

Parameters

deviceId
Output parameter. The ID of the current loopback capture device.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetPlaybackDefaultDevice [1/2]

Gets the system default audio playback device.

public abstract int GetPlaybackDefaultDevice(ref string deviceId, ref string deviceName);
Note: (Windows and macOS only)

Parameters

deviceId
Output parameter. The ID of the system default audio playback device.
deviceName
Output parameter. The name of the system default audio playback device.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetPlaybackDefaultDevice [2/2]

Gets the system default audio playback device and its type.

public abstract int GetPlaybackDefaultDevice(ref string deviceId, ref string deviceTypeName, ref string deviceName);
Note: (macOS only)

Parameters

deviceId
Output parameter. The ID of the system default audio playback device.
deviceName
Output parameter. The name of the system default audio playback device.
deviceTypeName
Output parameter. The type of the audio device, such as: built-in, USB, HDMI, etc.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetPlaybackDevice

Gets the current audio playback device.

public abstract int GetPlaybackDevice(ref string deviceId);
Note: (Windows and macOS only)

Parameters

deviceId
Output parameter. The device ID of the current audio playback device.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetPlaybackDeviceInfo [1/2]

Retrieves information about the audio playback device.

public abstract int GetPlaybackDeviceInfo(ref string deviceId, ref string deviceName);
Note: (Windows and macOS only)

Parameters

deviceId
Output parameter. The device ID of the playback device.
deviceName
Output parameter. The device name of the playback device.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetPlaybackDeviceInfo [2/2]

Retrieves information about the audio playback device and its type.

public abstract int GetPlaybackDeviceInfo(ref string deviceId, ref string deviceName, ref string deviceTypeName);

(macOS only)

Parameters

deviceId
Output parameter. The device ID of the playback device.
deviceName
Output parameter. The device name of the playback device.
deviceTypeName
Output parameter. The type of the audio playback device, such as built-in, USB, HDMI, etc.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetPlaybackDeviceVolume

Retrieves the volume of the playback device.

public abstract int GetPlaybackDeviceVolume();

Return Values

Playback device volume. Value range: [0,255].

GetRecordingDefaultDevice [1/2]

Retrieves the system default audio recording device.

public abstract int GetRecordingDefaultDevice(ref string deviceId, ref string deviceName);
Note: (Windows and macOS only)

Parameters

deviceId
Output parameter. The ID of the system default audio recording device.
deviceName
Output parameter. The name of the system default audio recording device.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetRecordingDefaultDevice [2/2]

Retrieves the system default audio recording device and its type.

public abstract int GetRecordingDefaultDevice(ref string deviceId, ref string deviceTypeName, ref string deviceName);
Note: (macOS only)

Parameters

deviceId
Output parameter. The ID of the system default audio recording device.
deviceName
Output parameter. The name of the system default audio recording device.
deviceTypeName
Output parameter. The type of the audio device, such as built-in, USB, HDMI, etc.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetRecordingDevice

Retrieves the current audio recording device.

public abstract int GetRecordingDevice(ref string deviceId);
Note: (Windows and macOS only)

Parameters

deviceId
Output parameter. The device ID of the current recording device.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetRecordingDeviceInfo [1/2]

Retrieves information about the audio recording device.

public abstract int GetRecordingDeviceInfo(ref string deviceId, ref string deviceName);
Note: (Windows and macOS only)

Parameters

deviceId
Output parameter. The device ID of the playback device.
deviceName
Output parameter. The device name of the playback device.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetRecordingDeviceInfo [2/2]

Retrieves information about the audio recording device and its type.

public abstract int GetRecordingDeviceInfo(ref string deviceId, ref string deviceName, ref string deviceTypeName);

(macOS only)

Parameters

deviceId
Output parameter. The device ID of the playback device.
deviceName
Output parameter. The device name of the playback device.
deviceTypeName
Output parameter. The type of the audio recording device, such as built-in, USB, HDMI, etc.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

GetRecordingDeviceMute

Gets the mute status of the current recording device.

public abstract bool GetRecordingDeviceMute();

Return Values

  • true: The recording device is muted.
  • false: The recording device is not muted.

GetRecordingDeviceVolume

Gets the volume of the recording device.

public abstract int GetRecordingDeviceVolume();
Note: This method applies to Windows only.

Return Values

The volume of the recording device. Value range: [0,255].

SetLoopbackDevice

Specifies the loopback device.

public abstract int SetLoopbackDevice(string deviceId);

By default, the SDK uses the current playback device as the loopback device. To specify another audio device as the loopback device, call this method and set deviceId to the desired loopback device. This method changes the current recording device used by the SDK 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 before joining a channel to set the current audio route to Soundcard 1, the SDK performs device testing on Soundcard 1. After testing, when you join a channel, the SDK still uses the system default recording device, which is Microphone 1.

Note: This method applies to Windows and macOS only. Applicable scenario: App A plays music through a Bluetooth headset; App B is used for video conferencing through a speaker.
  • If the loopback device is set to the Bluetooth headset, the SDK publishes the music from App A to the remote end.
  • If the loopback device is set to the speaker, the SDK does not publish the music from App A to the remote end.
  • If you switch from Bluetooth headset to wired headset for App A after setting the loopback device to Bluetooth headset, you need to call this method again to set the loopback device to the wired headset. The SDK will then continue to publish the music from App A to the remote end.

Parameters

deviceId
Specifies the loopback device used by the SDK. Obtained via EnumeratePlaybackDevices. Plugging or unplugging devices does not affect deviceId.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

SetPlaybackDevice

Specifies the playback device.

public abstract int 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 before joining a channel to set the audio route to Speaker 2, the SDK performs device testing on Speaker 2. After testing, when you join a channel, the SDK still uses the system default audio route, which is Speaker 1.

Note: This method applies to Windows and macOS only.

Parameters

deviceId
Specifies the playback device. Obtained via EnumeratePlaybackDevices. Plugging or unplugging devices does not affect deviceId.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

SetPlaybackDeviceMute

Sets the playback device to mute.

public abstract int 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

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

SetPlaybackDeviceVolume

Sets the playback device volume.

public abstract int SetPlaybackDeviceVolume(int volume);
Note: This method applies to Windows only.

Parameters

volume
Playback device volume. Value range: [0,255].

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

SetRecordingDevice

Specifies the recording device.

public abstract int SetRecordingDevice(string deviceId);

This method changes the current recording device used by the SDK 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 before joining a channel to set the current audio route to Bluetooth Headset 1, the SDK performs device testing on Bluetooth Headset 1. After testing, when you join a channel, the SDK still uses the system default recording device, which is Microphone 1.

Note: This method applies to Windows and macOS only.

Parameters

deviceId
Device ID of the recording device. You can obtain it via EnumerateRecordingDevices. Plugging or unplugging devices does not affect deviceId.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

SetRecordingDeviceMute

Sets the current recording device to mute.

public abstract int SetRecordingDeviceMute(bool mute);

Parameters

mute
Whether to mute the recording device:
  • true: The recording device is muted.
  • false: The recording device is not muted.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and resolution suggestions.

SetRecordingDeviceVolume

Sets the volume of the audio recording device.

public abstract int SetRecordingDeviceVolume(int volume);

This method is only available on Windows and macOS.

Parameters

volume
The volume of the audio recording device. The range is [0,255]. 0 means mute, and 255 means the maximum volume.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and troubleshooting.

StartAudioDeviceLoopbackTest

Starts an audio device loopback test.

public abstract int 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 plays it back through the playback device. The SDK triggers two OnAudioVolumeIndication callbacks at the specified time interval to report the volume levels of the recording device (uid = 0) and the playback device (uid = 1).

Note:
  • This method is only available on Windows and macOS.
  • You can call this method before or after joining a channel.
  • Only the host role can call this method.
  • This method only tests local audio devices and does not involve network connections.
  • 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 this to more than 200 ms. If set to less than 10 ms, the OnAudioVolumeIndication callback will not be received.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and troubleshooting.

StartPlaybackDeviceTest

Starts a playback device test.

public abstract int StartPlaybackDeviceTest(string testAudioFilePath);

This method tests whether the local playback device is working properly. After starting the test, the SDK plays the specified audio file. If the tester hears sound, the playback device is functioning properly. After calling this method, the SDK triggers the OnAudioVolumeIndication callback every 100 milliseconds 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 playback device is working, while the latter checks whether the audio/video devices and network are functioning properly.

Note: You must call this method before joining a channel. After the test is complete, if you want to join a channel, make sure to call StopPlaybackDeviceTest to stop the test first.

Parameters

testAudioFilePath
The absolute path of the audio file. The path string must be in UTF-8 encoding.
  • Supported file formats: wav, mp3, m4a, aac.
  • Supported sampling rates: 8000, 16000, 32000, 44100, 48000.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and troubleshooting.

StartRecordingDeviceTest

Starts a recording device test.

public abstract int StartRecordingDeviceTest(int indicationInterval);

This method tests whether the local recording device is working properly. After calling this method, the SDK triggers the OnAudioVolumeIndication callback at the specified time interval to report the volume information of uid = 0 and the recording device. The difference between this method and StartEchoTest is that this method checks whether the local recording device is working, while the latter checks whether the audio/video devices and network are functioning properly.

Note: You must call this method before joining a channel. After the test is complete, if you want to join a channel, make sure to call StopRecordingDeviceTest to stop the test first.

Parameters

indicationInterval
The time interval in milliseconds at which the SDK triggers the OnAudioVolumeIndication callback. The minimum value is 10. Otherwise, the OnAudioVolumeIndication callback will not be received and the SDK will return error code -2. Agora recommends setting this value to 100.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and troubleshooting.
    • -2: Invalid parameter. Please reset the parameter.

StopAudioDeviceLoopbackTest

Stops the audio device loopback test.

public abstract int StopAudioDeviceLoopbackTest();
Note:
  • This method is only available on Windows and macOS.
  • You can call this method before or after joining a channel.
  • Only the host role can call this method.
  • After calling StartAudioDeviceLoopbackTest, you must call this method to stop the loopback test.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and troubleshooting.

StopPlaybackDeviceTest

Stops the playback device test.

public abstract int StopPlaybackDeviceTest();

This method stops the playback device test. After calling StartPlaybackDeviceTest, you must call this method to stop the test.

Note: You must call this method before joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and troubleshooting.

StopRecordingDeviceTest

Stops the recording device test.

public abstract int StopRecordingDeviceTest();

This method stops the recording device test. After calling StartRecordingDeviceTest, you must call this method to stop the test.

Note: You must call this method before joining a channel.

Return Values

  • 0: Success.
  • < 0: Failure. See Error Codes for details and troubleshooting.