Introduction

This information is intended for developers who want to enable playback of Dolby Atmos content in Android TV media apps. Android TV devices may support Dolby Atmos for on-device playback (e.g., via loudspeakers on a TV), for output over HDMI to a connected Dolby Atmos device such as a sound bar, or both. On Android TV, support for decoding of Dolby formats, including Dolby Atmos, is enabled by offloading the decoding process to the underlying audio hardware. To enable decoding, Dolby Audio and Dolby Atmos bitstreams are passed to the audio hardware using the AudioTrack API. Android applications will often use ExoPlayer for media playback and therefore this page outlines both approaches using:

• ExoPlayer APIs
• Native Android APIs

to offer guidance for the default media player used on Android Platforms while also covering cases that rely on the Android APIs directly. 

Each of the sections below cover:

• Dolby Audio and Dolby Atmos playback capability detection
• Dolby Audio and Dolby Atmos playback

Dolby AC-4

Dolby AC-4 is Dolby's Next Generation Audio format, offering a rich feature set and supporting a wide range of use cases. To realize best possible support on computationally constrained device platforms, Dolby AC-4 has a concept of a maximum presentation complexity called "AC-4 presentation level". Dolby AC-4 decoders on Android TV implementations will either support decoding of presentations up to AC-4 level 3 or AC-4 level 4. Dolby AC-4 bitstreams that contain only level 4 presentations are not compatible with Dolby AC-4 level 3 decoders, and therefore the player application must check for that the Dolby AC-4 decoder on the device supports decoding Dolby AC-4 level 4 presentations before attempting to play Dolby AC-4 level 4 content. This document outlines how to detect the maximum presentation level that is supported by the Dolby AC-4 decoder on the device.

Additionally, Dolby AC-4 supports an encoding profile known as Immersive Stereo (IMS), which encodes surround and immersive audio into a stereo AC-4 bitstream with parametric audio data to optimize playback for headphone and on-device stereo speakers. Unlike formats such as Dolby Digital Plus with Dolby Atmos, it does not require real-time object rendering or metadata during playback, but as the format is specifically designed for stereo devices and endpoints, it does not support multichannel playback, and is not intended for Android TV implementations.

ExoPlayer

Your app should support detection of both on-device and HDMI connected playback of Dolby Audio and Dolby Atmos, and should determine whether the device supports Dolby Audio or Dolby Atmos playback before presenting any Dolby Audio or Dolby Atmos assets for the user to play. This section outlines how to accomplish detection and playback using ExoPlayer APIs

Detecting Dolby Audio and Dolby Atmos playback capability using ExoPlayer APIs

If your app uses ExoPlayer for Dolby Audio and Dolby Atmos playback, ExoPlayer APIs can be used to detect that the device supports Dolby Audio and/or Dolby Atmos playback before presenting Dolby Audio or Dolby Atmos assets for the user to play, as shown in the following code snippet:

import androidx.media3.common.C;
import androidx.media3.exoplayer.audio.AudioCapabilities;
...
AudioCapabilities caps = AudioCapabilities.getCapabilities(context);
if (caps.supportsEncoding(C.ENCODING_E_AC3)) {
	// Device supports AudioTrack playback of Dolby Digital Plus.
}
if (caps.supportsEncoding(C.ENCODING_E_AC3_JOC)) {
	// Device supports AudioTrack playback of Dolby Digital Plus with Dolby Atmos.
}
if (caps.supportsEncoding(C.ENCODING_AC4)) {
	// Device supports AudioTrack playback of Dolby AC-4.
}

It is currently not possible to directly query ExoPlayer for the maximum supported presentation level of an Dolby AC-4 decoder, or whether the device supports Dolby AC-4 presentation selection by index. Dolby is actively working on addressing this gap. In the meantime AudioManager APIs need to be used (see section below).

Playing Dolby Audio and Dolby Atmos content in ExoPlayer

If the device supports Dolby Audio and Dolby Atmos, you can use the basic ExoPlayer player APIs to play back the content, as shown in the following code snippet:

import androidx.media3.exoplayer.Exoplayer;
import androidx.media3.exoplayer.DefaultRenderersFactory;
...
player = new ExoPlayer.Builder(context)
                  .setRenderersFactory(new DefaultRenderersFactory(context))
                  .build();
player.setMediaSources(mediaSource /* corresponding to the Dolby Audio or Dolby Atmos asset */);
player.prepare();
player.play();

Dolby AC-4 IMS

As outlined in the introduction, IMS is a 2-channel audio format that does not support multichannel playback and on Android TV implementations it should not be decoded. To steer the adaptation set selection process in ExoPlayer, Dolby recommends correctly signaling the Audio Channel Configuration using the AudioChannelConfiguration tag. ExoPlayer will prioritize Adaptation sets that signal a higher channel configuration value and will therefore select Dolby AC-4 Adaptation sets with Dolby Audio or Dolby Atmos multichannel audio over a Dolby AC-4 IMS stereo adaptation set.

Android Platform

Your app should support detection of both on-device and HDMI connected playback of Dolby Audio and Dolby Atmos, and should determine whether the device supports Dolby Audio or Dolby Atmos playback before presenting any Dolby Audio or Dolby Atmos assets for the user to play. This section outlines how to accomplish this using Android platform APIs. 

Detecting Dolby Audio and Dolby Atmos playback capability using Android Platform APIs

If your app does not use ExoPlayer, then it can either import ExoPlayer and use the ExoPlayer capability detection APIs, or use Android Platform APIs directly to detect Dolby Audio and/or Dolby Atmos playback support.

Android version 9 / P and newer

Devices that run Android (Android TVs or DMAs) support playback of Dolby Audio and Dolby Atmos experiences through the device's built-in loudspeakers as well as output of Dolby Audio and Dolby Atmos to connected HDMI devices. To handle detection of Dolby Audio and Dolby Atmos in Android 9 / P and newer, the playback application must determine whether audio is decoded and rendered on the device (e.g. using the build in speakers) or if it is connected to a device over HDMI that supports Dolby Audio and/or Dolby Atmos decoding and rendering.

To determine if an HDMI connection is active, use the AudioManager class in Android OS. It provides information on the whether an HDMI audio device is connected via the ACTION_HDMI_AUDIO_PLUG intent. The following sections outline the steps needed to detect support for Dolby Audio and Dolby Atmos, depending if an HDMI connection is present or not.

Detecting on-device support for Dolby Audio and Dolby Atmos

For Android TV devices running OS version 9 / P and newer, the following method can be used to whether a device supports Dolby Audio and Dolby Atmos for on-device loudspeaker playback.

• The playback application should obtain a list of all audio output devices using AudioManager#getDevices(int) (optionally in combination with AudioManager#GET_DEVICES_OUTPUTS).
• If the device "TYPE_BUILTIN_SPEAKER" is included in the list of devices, the playback application should use AudioDeviceInfo.html#getEncodings() to obtain the list of audio formats supported by this device type.
• If this list contains the encoding value ENCODING_E_AC3, the TV supports on-device decoding of the DD+ format used for delivery of Dolby Audio content (e.g. 5.1-ch surround sound).
• If this list contains the encoding value ENCODING_E_AC3_JOC, the TV supports on-device decoding of the DD+ JOC format used for delivery of Dolby Atmos content.
• If this list contains the encoding value ENCODING_AC4, the TV supports on-device decoding of the Dolby AC-4 format used for delivery of Dolby Audio and Dolby Atmos content. The decoder is AC-4 level 3 compatible. The presence of an Dolby AC-4 level 4 compatible decoder can be checked by AudioManager.getParameters("isAc4Level4Supported") == "isAc4Level4Supported=1"

Detecting HDMI support for Dolby Audio and Dolby Atmos

For Android TV devices running OS version 9 / P and newer, the following method can be used to whether a device connected via HDMI supports Dolby Audio and Dolby Atmos. In this case, the playback application must determine whether the device it is running on (the HDMI source) is connected to a device (the HDMI sink) that supports Dolby Audio and/or Dolby Atmos decoding and rendering.

To determine this, the following process is used.

1. The AudioManager class in Android OS provides information on the whether an HDMI audio device is connected via the ACTION_HDMI_AUDIO_PLUG intent. The ACTION_HDMI_AUDIO_PLUG intent uses an extra value, EXTRA_ENCODINGS to obtain the audio formats supported by the HDMI audio device when the extra value EXTRA_AUDIO_PLUG_STATE is equal to "1". The supported audio formats are returned in an array of encodings, using the values defined for the AudioFormat class.
2. If this list contains the encoding value ENCODING_AC4, the device reports the capabilities of the decoders implemented on the device as Dolby AC-4 is not supported as HDMI transmission format. In this case it is still safe to use any formats that are supported on-device (see section above) as audio will be transcoded to a format that is supported by the connected HDMI sink. Dolby recommends to use the best available experience (e.g. 5.1 surround sound or Dolby Atmos) in this case.
3. If this list contains the encoding value ENCODING_E_AC3, the connected HDMI audio device supports the DD+ format used for delivery of 5.1-ch surround sound content.
4. If this list contains the encoding value ENCODING_E_AC3_JOC, the connected HDMI audio device supports the DD+ JOC format used for delivery of Dolby Atmos content.

Detecting Dolby AC-4 presentation selection by index support

Apps may query whether the Dolby AC‑4 decoder on an Android TV device supports presentation selection by index. This capability enables applications to specify which AC‑4 presentation should be decoded when multiple presentations are available in the bitstream.

To determine whether the AC‑4 decoder supports presentation selection by index, the playback application can use the AudioManager.getParameters(...) API with the key "isAc4PresentationSelectionByIndexSupported". If this call returns “isAc4PresentationSelectionByIndexSupported=1” then presentation selection by index is supported on the device's integrated Dolby AC‑4 decoder.

When this capability is present, applications decoding AC‑4 using the AudioTrack API may specify the desired AC‑4 presentation through AudioTrack.setPresentation(AudioPresentation). This is supported for AudioTrack instances whose AudioFormat uses AudioFormat.ENCODING_AC4. This enables applications to select a specific AC‑4 presentation (e.g., alternate languages, accessibility tracks, commentary tracks, or alternative mixes) directly in the audio decoder.

Android versions prior to Android 9 / P

Support for the encoding value ENCODING_E_AC3_JOC was added in API level 28 (Android P / 9.0). If the Dolby Atmos playback application is running on an earlier versions of Android, it should first attempt to determine support for the encoding value ENCODING_E_AC3_JOC, and if this is not supported, it should then attempt to determine support for the encoding value ENCODING_E_AC3 (supported from API level 21 (Android L / 5.0). If ENCODING_E_AC3 is supported, it is recommended to transmit DD+ JOC audio to the connected HDMI device for the following reasons:

• There is a fairly high probability that a connected HDMI device indicating support for Dolby Digital Plus also supports Dolby Digital Plus with Dolby Atmos, so a full Dolby Atmos experience can be delivered.
• If the connected HDMI device only supports Dolby Digital Plus, the device will still output a 5.1-ch render of the Dolby Atmos content.

Android version 13 and newer

For Android TV devices running OS version 13 / T and newer, an alternative method can be used to determine whether a device supports Dolby Audio and Dolby Atmos decoding on-device or HDMI playback. In this case the application must evaluate the audio format dependent flags returned by the getDirectPlaybackSupport API call. Besides detecting general support, this API will also allow detection if and how decoding can be performed:

• on the Application host processor
• by dedicated hardware e.g. an audio DSP
• by a connected HDMI device

Example usage is shown in the following code snippet:

import android.media.AudioAttributes
import android.media.AudioFormat
import android.media.AudioManager

val audioAttributes = AudioAttributes.Builder()
    .setUsage(AudioAttributes.USAGE_MEDIA)
    .setContentType(AudioAttributes.CONTENT_TYPE_MOVIE)
    .build()

val audioFormat = AudioFormat.Builder()
   .setEncoding(AudioFormat.ENCODING_E_AC3)
   .setChannelMask(AudioFormat.CHANNEL_OUT_STEREO)
   .setSampleRate(48000)
   .build()

val directPlaybackFlags = AudioManager.getDirectPlaybackSupport(audioFormat, audioAttributes)

// Device supports AudioTrack playback of Dolby Digital Plus and offloads decoding to the DSP
val usesOffload = (directPlaybackFlags and AudioManager.DIRECT_PLAYBACK_OFFLOAD_SUPPORTED) == AudioManager.DIRECT_PLAYBACK_OFFLOAD_SUPPORTED

// Device supports Gapless AudioTrack playback of Dolby Digital Plus and offloads decoding to the DSP
val usesOffloadIsGapless = (directPlaybackFlags and AudioManager.DIRECT_PLAYBACK_OFFLOAD_GAPLESS_SUPPORTED) == AudioManager.DIRECT_PLAYBACK_OFFLOAD_GAPLESS_SUPPORTED

// Device supports Bitstream passthrough of Dolby Digital Plus
val hasBitstreamPassThrough = (directPlaybackFlags and AudioManager.DIRECT_PLAYBACK_BITSTREAM_SUPPORTED) == AudioManager.DIRECT_PLAYBACK_BITSTREAM_SUPPORTED

// Repeat this check for AudioFormat.ENCODING_E_AC3_JOC and AudioFormat.ENCODING_AC4

import android.media.AudioAttributes;
import android.media.AudioFormat;
import android.media.AudioTrack;
...
AudioFormat format = new AudioFormat.Builder()
        .setChannelMask(AudioFormat.CHANNEL_OUT_STEREO)
        .setEncoding(AudioFormat.ENCODING_E_AC3)
        .setSampleRate(48000)
        .build();
 
AudioAttributes attr = new AudioAttributes.Builder()
        .setUsage(AudioAttributes.USAGE_MEDIA)
        .setContentType(AudioAttributes.CONTENT_TYPE_MOVIE)
        .build();
 
AudioTrack track = new AudioTrack.Builder()
        .setAudioAttributes(attr)
        .setAudioFormat(format)
        .build();
// and playback Dolby Digital Plus elementary stream data using 
// AudioTrack play() and write() APIs.

AudioFormat format = new AudioFormat.Builder()
        .setChannelMask(AudioFormat.CHANNEL_OUT_STEREO)
        .setEncoding(AudioFormat.ENCODING_E_AC3_JOC)
        .setSampleRate(48000)
        .build();
 
AudioAttributes attr = new AudioAttributes.Builder()
        .setUsage(AudioAttributes.USAGE_MEDIA)
        .setContentType(AudioAttributes.CONTENT_TYPE_MOVIE)
        .build();
 
AudioTrack track = new AudioTrack.Builder()
        .setAudioAttributes(attr)
        .setAudioFormat(format)
        .build();
// and playback Dolby Digital Plus with Dolby Atmos elementary stream data
// using AudioTrack play() and write() APIs.

AudioFormat format = new AudioFormat.Builder()
        .setChannelMask(AudioFormat.CHANNEL_OUT_STEREO)
        .setEncoding(AudioFormat.ENCODING_AC4)
        .setSampleRate(48000)
        .build();
 
AudioAttributes attr = new AudioAttributes.Builder()
        .setUsage(AudioAttributes.USAGE_MEDIA)
        .setContentType(AudioAttributes.CONTENT_TYPE_MOVIE)
        .build();
 
AudioTrack track = new AudioTrack.Builder()
        .setAudioAttributes(attr)
        .setAudioFormat(format)
        .build();
// and playback Dolby AC-4 elementary stream data
// using AudioTrack play() and write() APIs.