Play audio on wearables

keywords: wear, media, collection_guideslandingwear

This guide describes how apps on Wear OS can use familiar Android APIs to play audio.

Detect audio devices

A Wear OS app must first detect whether the wearable device has an appropriate audio output. Developers can expect wearables to have at least one of the following audio outputs available:

In the following example, the app uses the getDevices() method in conjunction with the value of FEATURE_AUDIO_OUTPUT to enumerate all audio outputs. 

AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);

fun audioOutputAvailable(type: Int): Boolean {
    if (!packageManager.hasSystemFeature(PackageManager.FEATURE_AUDIO_OUTPUT)) {
        return false
    }
    return audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS).any { it.type == type }
}

// True if the device has a speaker
audioOutputAvailable(AudioDeviceInfo.TYPE_BUILTIN_SPEAKER)

// True if a Bluetooth headset is paired and connected
audioOutputAvailable(AudioDeviceInfo.TYPE_BLUETOOTH_A2DP)

// True if a BLE broadcast group device is paired and connected
audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_BROADCAST)

// True if a BLE headset is paired and connected
audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_HEADSET)

// True if a BLE speaker is paired and connected
audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_SPEAKER)

To give the best user experience, your app should make sure to only play media when Bluetooth headphones or speakers are connected to the watch.

Choose preferred device for audio output

Depending on your app's use case, and the importance of audio to your app's core experience, choose how you'd like users to engage with your app's audio output.

Let user choose media output device

Starting in Wear OS 5, the system provides a UI that lets users choose which device should play media and show information about the currently-playing media content.

If your app detects that there isn't a Bluetooth headset connected when you want to provide audio playback on devices running Wear OS 5 or higher, offer to take the user directly to media output switcher. On devices that don't support the media output switcher, invoke the ACTION_BLUETOOTH_SETTINGS intent action, which takes the user to the Bluetooth page in system settings.

The launchOutputSelection() method, part of the Horologist library on GitHub, demonstrates how to let the user choose their media output device.

Bluetooth headset

Unlike built-in speakers, which are always available if present on the device, a Bluetooth headset can be paired or unpaired while an app runs. If the app requires a headset to continue, register a callback to detect when the user connects and disconnects a Bluetooth headset using registerAudioDeviceCallback: 

audioManager.registerAudioDeviceCallback(object : AudioDeviceCallback() {
    override fun onAudioDevicesAdded(addedDevices: Array<out AudioDeviceInfo>?) {
        super.onAudioDevicesAdded(addedDevices)
        if (audioOutputAvailable(AudioDeviceInfo.TYPE_BLUETOOTH_A2DP)
          || audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_BROADCAST)
          || audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_HEADSET)
          || audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_SPEAKER)) {
            // A Bluetooth or BLE device is connected and available for playback.
        }
    }
    override fun onAudioDevicesRemoved(removedDevices: Array<out AudioDeviceInfo>?) {
        super.onAudioDevicesRemoved(removedDevices)
        if (!(audioOutputAvailable(AudioDeviceInfo.TYPE_BLUETOOTH_A2DP))
          && !(audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_BROADCAST))
          && !(audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_HEADSET))
          && !(audioOutputAvailable(AudioDeviceInfo.TYPE_BLE_SPEAKER))) {
            // No Bluetooth or BLE devices are connected anymore.
        }
    }
}, null)

If your app detects that there isn't a Bluetooth headset connected when you want to provide audio output, don't show an error message. Instead, offer to take the user directly to Bluetooth settings to make it easier for them to connect. This can be done by sending an intent with ACTION_BLUETOOTH_SETTINGS: 

  val intent = with (Intent(Settings.ACTION_BLUETOOTH_SETTINGS)) {
      addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK)
      putExtra("EXTRA_CONNECTION_ONLY", true)
      putExtra("EXTRA_CLOSE_ON_CONNECT", true)
      putExtra("android.bluetooth.devicepicker.extra.FILTER_TYPE", 1)
  }
  startActivity(intent)

Speakers

Most Wear OS devices have speakers. If your app offers a non-media use case that incorporates sound, consider using speakers to offer an extra dimension of engagement with the user. For example, a speaker-equipped Wear OS device might trigger a clock or timer alarm, complete with audio notification, and fitness apps might use the speaker to provide exercise instructions.

Note: Speakers don't deliver the best experience for listening to media content as they aren't designed for this purpose.

Refer to the WearSpeakerSample for details.

Play audio

Once you detect and choose a suitable audio output, the process for playing audio on Wear OS is the same as on mobile or other devices. For more information, see MediaPlayer overview. For easier access to more advanced features, such as streaming and downloading media, use ExoPlayer. Make sure to follow best practices for Audio apps such as Managing Audio focus.

Prevent unintended media playback through speakers

Media apps can follow the following guidance to make sure the app does not unintentionally play media content on built-in watch speakers. The guidance is different based on which player the app is using.

ExoPlayer

If your app is using ExoPlayer:

  1. Call setSuppressPlaybackOnUnsuitableOutput(true) while building the ExoPlayer instance:

      ExoPlayer exoplayer = ExoPlayer.Builder(context)
          .setAudioAttributes(...)
          .setSuppressPlaybackWhenUnsuitableOutput(true)
          // ...
          .build()

  2. React to the playback suppression event by registering WearUnsuitableOutputPlaybackSuppressionResolverListener as a listener of the ExoPlayer instance:

    3.   exoPlayer.addListener(WearUnsuitableOutputPlaybackSuppressionResolverListener(context))

Horologist Media toolkit

The Horologist MediaToolkit already contains logic to prevent unintended media playback on built-in watch speakers.

Other media players