IAudioDeviceManager

Audio device management methods.

enumeratePlaybackDevices

Gets the list of all playback devices in the system.

abstract enumeratePlaybackDevices(): AudioDeviceInfo[];

Return Values

  • If the method call succeeds, returns an array of AudioDeviceInfo, containing the device ID and device name of all audio playback devices.
  • If the method call fails: returns an empty list.

enumerateRecordingDevices

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

abstract enumerateRecordingDevices(): AudioDeviceInfo[];

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 device follows the system default playback device.

abstract followSystemLoopbackDevice(enable: boolean): number;

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

Return Values

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

followSystemPlaybackDevice

Sets whether the SDK's playback device follows the system default playback device.

abstract followSystemPlaybackDevice(enable: boolean): number;

Parameters

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

Return Values

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

followSystemRecordingDevice

Sets whether the SDK's recording device follows the system default recording device.

abstract followSystemRecordingDevice(enable: boolean): number;

Parameters

enable
Whether to follow the system default 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

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

getLoopbackDevice

Gets the current loopback device.

abstract getLoopbackDevice(): string;

This method is applicable only to Windows and macOS.

Return Values

The ID of the current loopback device.

getPlaybackDefaultDevice

Gets the system default playback device.

abstract getPlaybackDefaultDevice(): AudioDeviceInfo;
Note: This method is applicable only to Windows and macOS.

Return Values

Information of the default playback device. See AudioDeviceInfo.

getPlaybackDevice

Gets the current playback device.

abstract getPlaybackDevice(): string;

Return Values

The current playback device.

getPlaybackDeviceInfo

Gets playback device information.

abstract getPlaybackDeviceInfo(): AudioDeviceInfo;

Return Values

The AudioDeviceInfo object containing the device ID and name of the playback device.

getPlaybackDeviceMute

Gets the mute status of the current playback device.

abstract getPlaybackDeviceMute(): boolean;

Return Values

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

getPlaybackDeviceVolume

Gets the playback device volume.

abstract getPlaybackDeviceVolume(): number;

Return Values

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

getRecordingDefaultDevice

Gets the system default audio recording device.

abstract getRecordingDefaultDevice(): AudioDeviceInfo;
Note: (Windows and macOS only)

Return Values

Information about the default recording device. See AudioDeviceInfo.

getRecordingDevice

Gets the current audio recording device.

abstract getRecordingDevice(): string;

Return Values

Current audio recording device.

getRecordingDeviceInfo

Gets audio recording device information.

abstract getRecordingDeviceInfo(): AudioDeviceInfo;

Return Values

AudioDeviceInfo object containing the device ID and device name of the recording device.

getRecordingDeviceMute

Gets the mute status of the current recording device.

abstract getRecordingDeviceMute(): boolean;

Return Values

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

getRecordingDeviceVolume

Gets the volume of the recording device.

abstract getRecordingDeviceVolume(): number;
Note: (Windows only)

Return Values

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

setLoopbackDevice

Specifies the loopback capture device.

abstract setLoopbackDevice(deviceId: string): number;

By default, the SDK uses the current playback device as the loopback capture device. To specify another audio device as the loopback 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 before joining a channel to set the current audio route to Sound Card 1, 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.

Note: (Windows and macOS only) Applicable scenarios: App A plays music through a Bluetooth headset; App B conducts a video conference through a speaker.
  • If the loopback capture device is set to the Bluetooth headset, the SDK will publish the music from App A to the remote end.
  • If the loopback capture device is set to the speaker, the SDK will 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 capture device for the SDK. Obtained via enumeratePlaybackDevices. Plugging/unplugging devices does not affect deviceId. Maximum length: MaxDeviceIdLengthType.

Return Values

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

setPlaybackDevice

Specifies the playback device.

abstract setPlaybackDevice(deviceId: string): number;

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 current audio route to Speaker 2, 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/unplugging devices does not affect deviceId. Maximum length: MaxDeviceIdLengthType.

Return Values

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

setPlaybackDeviceMute

Sets the playback device to mute.

abstract setPlaybackDeviceMute(mute: boolean): number;

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.

abstract setPlaybackDeviceVolume(volume: number): number;
Note: (Windows only)

Parameters

volume
Volume of the playback device. The value range is [0,255].

Return Values

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

setRecordingDevice

Specifies the audio recording device.

abstract setRecordingDevice(deviceId: string): number;

This method changes the current audio recording device without changing the system default audio recording device. Suppose the system default audio recording device is Microphone 1. If you call this method before joining a channel and set the current audio route to Bluetooth Headset 1, the SDK will test Bluetooth Headset 1 during device testing. After testing, when you join a channel, the SDK still uses the system default audio 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. Maximum length is MaxDeviceIdLengthType.

Return Values

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

setRecordingDeviceMute

Mutes the current audio recording device.

abstract setRecordingDeviceMute(mute: boolean): number;

Parameters

mute
Whether to mute the audio recording device:
  • true: The device is muted.
  • false: The 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.

abstract setRecordingDeviceVolume(volume: number): number;

(Windows and macOS only)

Parameters

volume
Volume of the audio recording device. Range: [0,255]. 0 means mute, 255 means maximum volume.

Return Values

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

startAudioDeviceLoopbackTest

Starts the audio device loopback test.

abstract startAudioDeviceLoopbackTest(indicationInterval: number): number;

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 to report the volume levels of the recording device (uid = 0) and the playback device (uid = 1).

Note:
  • This method can be called before or after joining a channel.
  • This method is only available to hosts.
  • This method only performs local audio device testing and does not involve network connections.
  • After the test is complete, you must call stopAudioDeviceLoopbackTest to stop the loopback test.

Parameters

indicationInterval
The interval at which the SDK triggers the onAudioVolumeIndication callback, in milliseconds. It is recommended to set it to greater than 200 ms. Must not be less than 10 ms, otherwise the onAudioVolumeIndication callback will not be received.

Return Values

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

startPlaybackDeviceTest

Starts the audio playback device test.

abstract startPlaybackDeviceTest(testAudioFilePath: string): number;

This method tests whether the local audio playback device is working properly. After the test starts, the SDK plays the specified audio file. If the tester 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 tests whether the local audio playback device is working properly, while the latter tests whether the audio/video devices and network are functioning correctly.

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

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 sampling rates: 8000, 16000, 32000, 44100, 48000.

Return Values

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

startRecordingDeviceTest

Starts the audio recording device test.

abstract startRecordingDeviceTest(indicationInterval: number): number;

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

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

Parameters

indicationInterval
The 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 will return error code -2. Agora recommends setting this value to 100.

Return Values

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

stopAudioDeviceLoopbackTest

Stops the audio device loopback test.

abstract stopAudioDeviceLoopbackTest(): number;
Note:
  • This method can be called before or after joining a channel.
  • This method is only available to hosts.
  • After calling startAudioDeviceLoopbackTest, you must call this method to stop the audio device loopback test.

Return Values

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

stopPlaybackDeviceTest

Stops the audio playback device test.

abstract stopPlaybackDeviceTest(): number;

This method stops the audio 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 resolution suggestions.

stopRecordingDeviceTest

Stops the audio recording device test.

abstract stopRecordingDeviceTest(): number;

This method stops the audio 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 resolution suggestions.