IAudioDeviceManager

Audio device management methods.

IAudioDeviceManager provides methods for audio device testing. You can call the QueryInterface method to get the IAudioDeviceManager interface.

EnumeratePlaybackDevices

Enumerates the audio playback devices.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	UIAudioDeviceCollection* EnumeratePlaybackDevices();

Details

Attention: This method is for Windows and macOS only.

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.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	UIAudioDeviceCollection* EnumerateRecordingDevices();

Details

Attention: This method is for Windows and macOS only.

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

FollowSystemPlaybackDevice

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

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int FollowSystemPlaybackDevice(bool enable);

Details

Attention: This method is for Windows and macOS only.

Parameters

enable
Whether to follow the system default audio playback device:
  • true: Follow the system default audio playback device. The SDK immediately switches the audio playback device when the system default audio playback device changes.
  • false: Do not follow the system default audio playback device. 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.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int FollowSystemRecordingDevice(bool enable);

Details

Attention: This method is for Windows and macOS only.
Parameters
enable
Whether to follow the system default audio recording device:
  • true: Follow the system default audio playback device. The SDK immediately switches the audio recording device when the system default audio recording device changes.
  • false: Do not follow the system default audio playback device. 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.

GetPlaybackDevice

Retrieves the audio playback device associated with the device ID.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int GetPlaybackDevice(FString& deviceId);

Details

Attention: This method is for Windows and macOS only.

Parameters

deviceId
Output parameter. The device ID of the audio playback device. The maximum length is 512 字符.

Returns

  • 0: Success.
  • < 0: Failure.

GetPlaybackDeviceInfo

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

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int GetPlaybackDeviceInfo(FString& deviceId, FString& deviceName);

Details

Attention: This method is for Windows and macOS only.

Parameters

deviceId
The device ID of the playback device. The maximum length is 512 字符.
deviceName
The device name of the playback device. The maximum length is 512 字符.

Returns

  • 0: Success.
  • < 0: Failure.

GetRecordingDevice

Gets the current audio recording device.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int GetRecordingDevice(FString& deviceId);

Details

Attention: This method is for Windows and macOS only.

Parameters

deviceId
An output parameter. The device ID of the recording device. The maximum length is 512 字符.

Returns

  • 0: Success.
  • < 0: Failure.

GetRecordingDeviceInfo

Retrieves the information of the audio recording device.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int GetRecordingDeviceInfo(FString& deviceId, FString& deviceName);

Details

Attention: This method is for Windows and macOS only.

Parameters

deviceId
The device ID of the playback device. The maximum length is 512 字符.
deviceName
The device name of the playback device. The maximum length is 512 字符.

Returns

  • 0: Success.
  • < 0: Failure.

Release

Releases all the resources occupied by the IAudioDeviceManager object.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	void Release();

SetPlaybackDevice

Sets the audio playback device.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int SetPlaybackDevice(FString deviceId);

Details

Attention: This method is for Windows and macOS only.

You can call this method to change the audio route currently being used, but this does not change the default audio route. For example, if the default audio route is speaker 1, you call this method to set the audio route as speaker 2 before joinging a channel and then start a device test, the SDK conducts device test on speaker 2. After the device test is completed and you join a channel, the SDK still uses speaker 1, the default audio route.

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 512 字符.

Returns

  • 0: Success.
  • < 0: Failure.

SetRecordingDevice

Sets the audio capture device.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int SetRecordingDevice(FString deviceId);

Details

Attention: This method is for Windows and macOS only.

You can call this method to change the audio route currently being used, but this does not change the default audio route. For example, if the default audio route is microphone, you call this method to set the audio route as bluetooth earphones before joinging a channel and then start a device test, the SDK conducts device test on the bluetooth earphones. After the device test is completed and you join a channel, the SDK still uses the microphone for audio capturing.

Parameters

deviceId

The ID of the audio capture device. You can get the Device ID by calling EnumerateRecordingDevices. Connecting or disconnecting the audio device does not change the value of deviceId.

The maximum length is 512 字符.

Returns

  • 0: Success.
  • < 0: Failure.

SetRecordingDeviceVolume

Sets the volume of the audio capture device.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int SetRecordingDeviceVolume(int volume);

Details

This method is for Windows and macOS only.

Parameters

volume
The volume of the audio recording device. The value range is [0,255]. 0 means no sound, 255 means maximum volume.

Returns

  • 0: Success.
  • < 0: Failure.

StartAudioDeviceLoopbackTest

Starts an audio device loopback test.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int StartAudioDeviceLoopbackTest(int indicationInterval);

Details

This method tests whether the local audio capture device and playback device are working properly. After starting the test, the audio capture device records the local audio, and the audio playback device plays the captured audio. The SDK triggers two independent FOnAudioVolumeIndication 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.

Attention:
  • This method is for Windows and macOS only.
  • You can call this method either before or after joining a channel.
  • This method only takes effect when called by the host.
  • This method tests local audio devices and does not report the network conditions.
  • When you finished testing, call StopAudioDeviceLoopbackTest to stop the audio device loopback test.

Parameters

indicationInterval
The time interval (ms) at which the SDK triggers the FOnAudioVolumeIndication 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 FOnAudioVolumeIndication callback.

Returns

  • 0: Success.
  • < 0: Failure.

StartPlaybackDeviceTest

Starts the audio playback device test.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int StartPlaybackDeviceTest(FString testAudioFilePath);

Details

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 FOnAudioVolumeIndication callback every 100 ms, reporting uid = 1 and the volume information of the playback device.

Attention:
  • Ensure that you call this method before joining a channel.
  • This method is for Windows and macOS only.

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.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int StartRecordingDeviceTest(int indicationInterval);

Details

This method tests whether the audio capture device works properly. After calling this method, the SDK triggers the FOnAudioVolumeIndication callback at the time interval set in this method, which reports uid = 0 and the volume information of the capturing device.

Note:
  • 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 FOnAudioVolumeIndication 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 FOnAudioVolumeIndication callback.

Returns

  • 0: Success.
  • < 0: Failure.

StopAudioDeviceLoopbackTest

Stops the audio device loopback test.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int StopAudioDeviceLoopbackTest();

Details

Attention:
  • This method is for Windows and macOS only.
  • You can call this method either before or after joining a channel.
  • This method only takes effect when called by the host.
  • 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.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int StopPlaybackDeviceTest();

Details

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

Attention:
  • This method is for Windows and macOS only.
  • Ensure that you call this method before joining a channel.

Returns

  • 0: Success.
  • < 0: Failure.

StopRecordingDeviceTest

Stops the audio capture device test.

UFUNCTION(BlueprintCallable, Category = "Agora|IAudioDeviceManager")
	int StopRecordingDeviceTest();

Details

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

Note:
  • This method is for Windows and macOS only.
  • Ensure that you call this method before joining a channel.

Returns

  • 0: Success.
  • < 0: Failure.