AudioSwitch

An Android audio management library for real-time communication apps.

Features

Manage audio focus for typical VoIP and Video conferencing use cases.
Manage audio input and output devices.
- Detect changes in available audio devices
- Enumerate audio devices
- Select an audio device

Requirements

Android Studio Version	Android API Version Min
3.6+	16

Documentation

The KDoc for this library can be found here.

Getting Started

To get started using this library, follow the steps below.

Gradle Setup

Ensure that you have mavenCentral listed in your project's buildscript repositories section:

buildscript {
    repositories {
        mavenCentral()
        // ...
    }
}

Add this line as a new Gradle dependency:

implementation 'com.twilio:audioswitch:$version'

Pull requests merged to master result in a snapshot artifact being published to the Maven Central snapshots repository. You can access these snapshots by adding the following to your gradle file repositories:

maven {
    url = uri("https://oss.sonatype.org/content/repositories/snapshots")
}

Add a -SNAPSHOT suffix to the Gradle dependency version:

implementation 'com.twilio:audioswitch:$version-SNAPSHOT'

AudioSwitch Setup

Instantiate an instance of the AudioSwitch class, passing a reference to the application context.

val audioSwitch = AudioSwitch(applicationContext)

Listen for Devices

To begin listening for live audio device changes, call the start function and pass a lambda that will receive AudioDevices when they become available.

audioSwitch.start { audioDevices, selectedDevice ->
    // TODO update UI with audio devices
}

You can also retrieve the available and selected audio devices manually at any time by calling the following properties:

val devices: List<AudioDevice> = audioSwitch.availableAudioDevices
val selectedDevice: AudioDevice? = audioSwitch.selectedAudioDevice

Note: Don't forget to stop listening for audio devices when no longer needed in order to prevent a memory leak.

audioSwitch.stop()

Select a Device

Before activating an AudioDevice, it needs to be selected first.

devices.find { it is AudioDevice.Speakerphone }?.let { audioSwitch.selectDevice(it) }

If no device is selected, then the library will automatically select a device based on the following priority: BluetoothHeadset -> WiredHeadset -> Earpiece -> Speakerphone.

Activate a Device

Activating a device acquires audio focus with voice communication usage and begins routing audio input/output to the selected device.

audioSwitch.activate()

Make sure to revert back to the prior audio state when it makes sense to do so in your app.

audioSwitch.deactivate()

Note: The stop() function will call deactivate() before closing AudioSwitch resources.

Bluetooth Support

Multiple connected bluetooth headsets are supported.

Bluetooth support requires BLUETOOTH_CONNECT or BLUETOOTH permission. These permission have to be added to the application using AudioSwitch, they do not come with the library.
The library will accurately display the up to date active bluetooth headset within the AudioSwitch availableAudioDevices and selectedAudioDevice functions.
- Other connected headsets are not stored by the library at this moment.
In the event of a failure to connecting audio to a bluetooth headset, the library will revert the selected audio device (this is usually the Earpiece on a phone).
- Additionally BluetoothHeadsetConnectionListener can be provided to AudioSwitch constructor to monitor state changes and connection failures.
If a user would like to switch between multiple Bluetooth headsets, then they need to switch the active bluetooth headset from the system Bluetooth settings.
- The newly activated headset will be propagated to the AudioSwitch availableAudioDevices and selectedAudioDevice functions.

Java Compatibility

Audioswitch is compatible with apps written in Java that target Java 8, and follows the recommendations provided in the Kotlin for Java consumption guide. The project includes Java specific unit tests that demonstrate how to use Audioswitch from a Java based application. If you have any Java compatibility questions please open an issue.

Logging

By default, AudioSwitch logging is disabled. Reference the following snippet to enable AudioSwitch logging:

val audioSwitch = AudioSwitch(context, loggingEnabled = true)

audioSwitch.start { _, _ -> }

Permissions

On Android 12 and greater, the application using this library is expected to request the BLUETOOTH_CONNECT permission. Not doing so will disable the use of bluetooth in the audioswitch library. Pre-Android 12, no user permission requests are needed. All other permissions needed are listed in the library's manifest and are automatically merged from the manifest file in this library.

Contributing

We welcome and encourage contributions to AudioSwitch! However, pull request (PR) validation requires access to credentials that we cannot provide to external contributors. As a result, the contribution process is as follows:

Submit a PR from a fork with your changes
Our team will review
If the changes are small enough and do not require validation (eg. documentation typo) we will merge your PR directly.
If the changes require integration testing, then, once approved, our team will close your PR and create a new PR from a branch on the main repository and reference your original work.
Our team will handle merging the final PR and releasing a new version with your changes.
(Optional) Submit a PR that adds you to our CONTRIBUTORS file so you show up on the contributors page.

Usage Examples

License

Apache 2.0 license. See LICENSE.txt for details.

kongpf8848/audioswitch