Android Audio Device Management

AudioManagerUtility (available since LiveSwitch SDK 1.19.2) simplifies managing Android audio devices. It handles automatic/manual selection, ensures the correct audio mode for echo cancellation, lists devices, and verifies compatible Android APIs. Requires AudioRecordSource2 (replaces deprecated AudioRecordSource). See the migration guide for versions before 1.19.2.

Summary of Supported Methods

Method and Functionality	Summary	Supported SDKs
Automatic device switching	Switch audio devices as they are plugged in or unplugged given the priority profile	As of SDK 27 / Android 8.1
Communication Mode management	Automatic management of the device communication mode allowing the device to enable echo cancellation if supported	As of SDK 27 / Android 8.1, device-specific
`setAudioCommunicationDeviceType(AudioDeviceType)`	Manually specify active device type	As of SDK 27 / Android 8.1
`setAudioCommunicationDevice(int id)`	Manually specify a particular active device type by ID	As of SDK 31 / Android 12 Use `setAudioCommunicationDeviceType(AudioDeviceType)` for the legacy SDK
`enumerateDevices()`	List connected audio devices	As of SDK 27 / Android 8.1
`addOnDeviceAdded`, `removeOnDeviceAdded`, `addOnDeviceRemoved`, `removeOnDeviceRemoved`, `addOnDeviceChanged`, `removeOnDeviceChanged`	Audio device event listeners	As of SDK 31 / Android 12 Use `BroadcastReceiver` or periodic device polling for legacy

Setup

Start AudioManagerUtility before the first conference connection starts and stop it after the last connection completes.

A good time to start it is when local or remote media starts by calling startSession()
Define a device preference profile: which device is used by default and which device is used when a device is added or removed during the conference
- Audio/Video Conference: Bluetooth > Wired Headset > Speaker > Earpiece
- Audio-Only Conference: Bluetooth > Wired Headset > Earpiece > Speaker
Override automatic selection with manual options (details below)

Android

AudioDevicePreferenceProfile preference = AudioDevicePreferenceProfile.AUDIO_VIDEO_CONFERENCE;
if (this.audioOnly) {
   preference = AudioDevicePreferenceProfile.AUDIO_ONLY_CONFERENCE;
}
this.audioManager = new AudioManagerUtility(this.context, preference);
this.audioManager.startSession();

Manual Device Selection

By Device Type

LiveSwitch SDK lets you manually choose the active audio device on all supported Android versions, overriding the automatic selection. For example, to switch from a Bluetooth headset to speakerphone during a call:

Android

this.audioManager.setAudioCommunicationDeviceType(AudioDeviceType.BUILTIN_SPEAKER);

Available Device Types:

AudioDeviceType.BLUETOOTH_HEADSET
AudioDeviceType.WIRED_HEADSET
AudioDeviceType.BUILTIN_SPEAKER
AudioDeviceType.BUILTIN_EARPIECE

Convenience Methods: LiveSwitch SDK also provides these methods for easier selection:

setBluetoothOn()
setSpeakerOn()
setWiredHeadsetOn()
setEarpieceOn()

By Device ID

This functionality lets you override the automatic selection. For example, if two Bluetooth devices are connected, you can switch between them by providing the new device ID obtained through device enumeration. A user interface with a dropdown menu can be designed for device selection.

Important

LiveSwitch SDK allows manual selection of the active device by ID on Android 12 (API level 31) and later. Calling this function on earlier versions will cause the promise to be rejected. It's recommended to check the device's SDK version before using this method. For legacy versions, use manual selection by type (explained above).

Android

this.audioManager.setAudioCommunicationDevice(int id)

Caution About Manual Device Selection

Important

Always wait for the promise from setAudioCommunicationDeviceType() and other similar device settings methods to resolve (or fail) before requesting another device change. Multiple simultaneous requests can lead to unexpected behaviour. Device switching typically takes less than a second, but Android documentation allows up to 30 seconds. If an error occurs, the Audio Manager Utility will handle it by clearing the communication device, logging the error, and rejecting the promise. You can retry setting the device after checking for available devices.

Listing Available Audio Devices and Device Serialization

The utility provides a method to list all currently connected audio devices that can function as audio sources, sinks, or both:

Android

AudioDeviceInfo[] enumerateDevices()

This method is available on all Android SDK versions supported by LiveSwitch SDK.

The utility allows serialization of Android's AudioDeviceInfo. This helps to include device information in application logs. However, you can serialize AudioDeviceInfo yourself.

Android

String serializeDevice(AudioDeviceInfo device)

Listening for Device Status Updates

The utility lets you listen for updates on audio device status. This includes notifications when a device is connected, disconnected or the active device changes. This functionality is only available for Android 12 (API level 31) and later. Trying to use these methods on earlier versions will result in a runtime exception.

void addOnDeviceAdded(IAction1<AudioDeviceInfo> value) throws UnsupportedOperationException
void removeOnDeviceAdded(IAction1<AudioDeviceInfo> value)
void addOnDeviceRemoved(IAction1<AudioDeviceInfo> value) throws UnsupportedOperationException
void removeOnDeviceRemoved(IAction1<AudioDeviceInfo> value)
void addOnDeviceChanged(IAction1<AudioDeviceInfo> value) throws UnsupportedOperationException
void removeOnDeviceChanged(IAction1<AudioDeviceInfo> value)

Migration from LiveSwitch SDK 1.19.1 and Earlier

AudioRecordSource2

Upgrade to AudioRecordSource2. If you're currently using Android AudioRecordSource, upgrade to AudioRecordSource2. The class constructor signatures are identical. LocalMedia class changes:

Android

@Override
protected AudioSource createAudioSource(AudioConfig audioConfig) {
   var audioRecordSource = new AudioRecordSource2(context, audioConfig);
   audioRecordSource.setUseAcousticEchoCanceler(true);
   return audioRecordSource;
}

If you're using AudioRecordSource2 from SDK 1.19.1 or earlier, switch to the new constructor that takes two parameters: context and audioConfig. The old constructor with only audioConfig is deprecated. Using it might lead to stream synchronization issues.

AudioManagerUtility Usage

Start the utility:

Start AudioManagerUtility when you begin local or remote media.
Choose the appropriate preference profile (audio-video or audio-only):

Android

public Future<fm.liveswitch.LocalMedia> startLocalMedia(final VideoChatFragment fragment) {
    AudioDevicePreferenceProfile preference = AudioDevicePreferenceProfile.AUDIO_VIDEO_CONFERENCE;
    if (this.audioOnly) {
        preference = AudioDevicePreferenceProfile.AUDIO_ONLY_CONFERENCE;
    }
    this.audioManager = new AudioManagerUtility(this.context, preference);
    this.audioManager.startSession();
    // ...
}

Stop the utility: Stop AudioManagerUtility when the last conference connection ends and local/remote media is shutting down:

Android

public Future<fm.liveswitch.LocalMedia> stopLocalMedia() {
    this.audioManager.endSession();
    this.audioManager = null;
    // ...
}

If you prefer to manage Android's AudioManager directly, use AudioRecordSource2 but don't start AudioManagerUtility.