IAgoraRtcAudioPlaybackDeviceManager

IAgoraRtcAudioPlaybackDeviceManager class, which manages audio playback devices.

EnumeratePlaybackDevices

Enumerates the audio playback devices.

public abstract DeviceInfo[] EnumeratePlaybackDevices();

Returns

  • Success: Returns a DeviceInfo array that contains the device ID and device name of all the audio plauback devices.
  • Failure: NULL.

FollowSystemPlaybackDevice

Sets the audio playback device used by the SDK to follow the system default audio playback device.

public abstract int FollowSystemPlaybackDevice(bool enable);

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.

public abstract int FollowSystemRecordingDevice(bool enable);
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.

SetPlaybackDevice

Sets the audio playback device.

public abstract int SetPlaybackDevice(string deviceId);

Parameters

deviceId

The ID of the audio playback device. You can get the device ID by calling EnumeratePlaybackDevices. Plugging or unplugging the audio device does not change the device ID.

Returns

  • 0: Success.
  • < 0: Failure.

StartPlaybackDeviceTest

Starts the audio playback device test.

public abstract int StartPlaybackDeviceTest(string testAudioFilePath);

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.
Attention:
  • Calling this method after joining a channel tests the audio capturing device that the SDK is using.
  • After calling startRecordingDeviceTest, you must call StopPlaybackDeviceTest to stop the test.

Parameters

testAudioFilePath

The path of the audio file for the audio playback device test in UTF-8.

Returns

  • 0: Success.
  • < 0: Failure.

StopPlaybackDeviceTest

Stops the audio playback device test.

public abstract int StopPlaybackDeviceTest();

This method stops the audio playback device test. You must call this method to stop the test after calling the StartPlaybackDeviceTest method.

Attention: Ensure that you call this method before joining a channel.

Returns

  • 0: Success.
  • < 0: Failure.

SetPlaybackDeviceVolume

Sets the volume of the audio playback device.

public abstract int SetPlaybackDeviceVolume(int volume);

Parameters

volume
The volume of the audio playback device. The value ranges between 0 (lowest volume) and 255 (highest volume).

Returns

  • 0: Success.
  • < 0: Failure.

GetPlaybackDeviceVolume

Retrieves the volume of the audio playback device.

public abstract int GetPlaybackDeviceVolume();

Returns

The volume of the audio playback device. The value ranges between 0 (lowest volume) and 255 (highest volume).

SetPlaybackDeviceMute

Mutes the audio playback device.

public abstract int SetPlaybackDeviceMute(bool mute);

Parameters

mute
Whether to mute the audio playback device:
  • true: Mute the audio playback device.
  • false: Unmute the audio playback device.

Returns

  • 0: Success.
  • < 0: Failure.

GetPlaybackDeviceMute

Retrieves whether the audio playback device is muted.

public abstract bool GetPlaybackDeviceMute();

Returns

  • true: The audio playback device is muted.
  • false: The audio playback device is unmuted.

GetPlaybackDevice

Retrieves the audio playback device associated with the device ID.

public abstract string GetPlaybackDevice();

Returns

The current audio playback device.

GetPlaybackDeviceInfo

Retrieves the audio playback device information associated with the device ID and device name.

public abstract DeviceInfo GetPlaybackDeviceInfo();

Returns

The information of the audio playback device, which includes the device ID and the device name.

StartAudioDeviceLoopbackTest

Starts an audio device loopback test.

public abstract int StartAudioDeviceLoopbackTest(int indicationInterval);

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 OnAudioVolumeIndication.
  • 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.
Attention:
  • 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.
  • This method tests local audio devices and does not report the network conditions.
  • After calling startRecordingDeviceTest, you must call StopAudioDeviceLoopbackTest to stop the test.

Parameters

indicationInterval

The time interval (ms) at which the SDK triggers the OnAudioVolumeIndication or OnAudioDeviceTestVolumeIndication callback. Agora recommends a setting greater than 200 ms. This value must not be less than 10 ms; otherwise, you can not receive these callbacks.

Returns

  • 0: Success.
  • < 0: Failure.

StopAudioDeviceLoopbackTest

Stops the audio device loopback test.

public abstract int StopAudioDeviceLoopbackTest();
Attention:
  • 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.