Introduction

This information is intended for developers of third-party car media apps who want to enable playback of Dolby Atmos or Dolby Audio content on Android Automotive OS.

Detecting Dolby Atmos and Dolby Audio playback capability

Your app should detect that the device supports Dolby Atmos or Dolby Audio playback before presenting any Dolby Atmos or Dolby Audio assets for the user to play, respectively.

Android Automotive OS devices implement Dolby Atmos and Dolby Audio decoding and rendering as either a MediaCodec decoder within the head unit in-vehicle infotainment system (hereafter referred to as a MediaCodec integration) or as a decoder in the car's DSP-enabled audio amplifier (hereafter referred to as a pass-through integration).

Your app should detect whether a MediaCodec or pass-through integration is implemented for Dolby Atmos and Dolby Audio on the device, and then utilize the appropriate playback APIs for that integration. If you are using ExoPlayer as your playback engine, ExoPlayer automatically detects which of these two playback paths are supported on the device and uses the appropriate path. If you are not using ExoPlayer as your playback engine, you will need to implement support for both playback paths, and use the appropriate playback path detected as supported on the device.

NOTE: Dolby Atmos decoders in Android Automotive OS systems do not support Dolby AC-4 Immersive Stereo (IMS) decoding. Use PackageManager#FEATURE_AUTOMOTIVE to detect whether your app is running on an Android Automotive OS system, and filter asset availability accordingly.

Dolby Atmos and Dolby Audio playback capability detection using ExoPlayer APIs

If your app uses ExoPlayer for Dolby Atmos and Dolby Audio playback, use the following ExoPlayer APIs to detect that the device supports Dolby Atmos and Dolby Audio playback before presenting Dolby Atmos and Dolby Audio assets for the user to play.

NOTE: You should check for both pass-through and media codec capabilities. If the device supports either playback method, you can use ExoPlayer to play back the Dolby Atmos or Dolby Audio content. If a device supports both pass-through and media codec playback for Dolby Atmos or Dolby Audio, by default the ExoPlayer player engine will prioritize and use the pass-through path.

Detecting Dolby Atmos and Dolby Audio AudioTrack pass-through playback support using ExoPlayer APIs

To detect pass-through playback support for Dolby Atmos and Dolby Audio using ExoPlayer APIs, you can use the following code snippet:

import android.media.AudioManager;
import androidx.media3.common.C;
import androidx.media3.exoplayer.audio.AudioCapabilities;

...
AudioCapabilities caps = AudioCapabilities.getCapabilities(context);

if (caps.supportsEncoding(C.ENCODING_AC4)) {
    // Device supports AudioTrack pass-through playback of Dolby AC-4 (levels 0-3)

    AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
    String result = audioManager.getParameters("isAc4Level4Supported");    
    if ("isAc4Level4Supported=1".equals(result)) {
        // Device supports AudioTrack pass-through playback of Dolby AC-4 (levels 0-4)
    }
}
if (caps.supportsEncoding(C.ENCODING_E_AC3_JOC)) {
    // Device supports AudioTrack pass-through playback of Dolby Digital Plus with Dolby Atmos
}
if (caps.supportsEncoding(C.ENCODING_E_AC3)) {
    // Device supports AudioTrack pass-through playback of Dolby Digital Plus
}
if (caps.supportsEncoding(C.ENCODING_AC3)) {
    // Device supports AudioTrack pass-through playback of Dolby Digital
}

Detecting Dolby Atmos and Dolby Audio MediaCodec decoding support using ExoPlayer APIs

To detect MediaCodec decoding support for Dolby Atmos and Dolby Audio using ExoPlayer APIs, you can use the following code snippet:

import androidx.media3.common.MimeTypes;
import androidx.media3.exoplayer.mediacodec.MediaCodecInfo;
import androidx.media3.exoplayer.mediacodec.MediaCodecUtil;
...
MediaCodecInfo mediaCodecInfo = null;
try {
    mediaCodecInfo =
            MediaCodecUtil.getDecoderInfo(MimeTypes.AUDIO_E_AC3_JOC,
                                          false /* secure decryption required */,
                                          false /* tunnel mode decoding required */);
} catch (MediaCodecUtil.DecoderQueryException e) {
    // handle exception
}
 
if (mediaCodecInfo != null) {
     // Device supports MediaCodec decoding of Dolby Digital Plus with Dolby Atmos.
}

The mime types MimeTypes.AUDIO_E_AC3 and MimeTypes.AUDIO_AC3 can be used in a similar way as above to detect MediaCodec decoding support for Dolby Digital Plus and Dolby Digital respectively.

For Dolby AC-4, use the following:

MediaCodecInfo ac4MediaCodecInfo = null

try {
    ac4MediaCodecInfo =
            MediaCodecUtil.getDecoderInfo(MimeTypes.AUDIO_AC4,
                                          false /* secure decryption required */,
                                          false /* tunnel mode decoding required */);
} catch (MediaCodecUtil.DecoderQueryException e) {
    // handle exception
}
 
if (ac4MediaCodecInfo != null) {
    // Device supports MediaCodec decoding of Dolby AC-4 (levels 0-3)
    final int ac4Level4MaxChannelCount = 21;
    if (ac4MediaCodecInfo.isAudioChannelCountSupportedV21(ac4Level4MaxChannelCount) {
           // Device supports MediaCodec decoding of Dolby AC-4 (levels 0-4)
    }
}

Dolby Atmos playback capability detection 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 Atmos and Dolby Audio pass-through and/or MediaCodec decoding support.

Detecting Dolby Atmos and Dolby Audio AudioTrack pass-through support using Android Platform APIs

On devices running Android 10 and above, you can use AudioTrack.isDirectPlaybackSupported() to detect Dolby Atmos and Dolby Audio pass-through support, as shown in the following code snippet:

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_JOC)
        .setSampleRate(48000)
        .build();
 
AudioAttributes attr = new AudioAttributes.Builder()
        .setUsage(AudioAttributes.USAGE_MEDIA)
        .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
        .build();
 
if (AudioTrack.isDirectPlaybackSupported(format, attr)) {
    // Device supports AudioTrack pass-through playback of Dolby Digital Plus with Dolby Atmos.
}

Repeat the above, replacing AudioFormat.ENCODING_E_AC3_JOC with AudioFormat.ENCODING_E_AC3, AudioFormat.ENCODING_AC3 and AudioFormat.Encoding_AC4 to detect AudioTrack pass-through playback support for Dolby Digital Plus, Dolby Digital and Dolby AC-4 (levels 0-3) respectively.

For Dolby AC-4 Level 4, use the above with AudioFormat.ENCODING_AC4 to check for AC-4 Level 3 passthrough capability, in addition to the below:

AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
String result = audioManager.getParameters("isAc4Level4Supported");

if ("isAc4Level4Supported=1".equals(result)) { 
   // Device supports AudioTrack pass-through playback of Dolby AC-4 (levels 0-4) 
}

Detecting Dolby Atmos and Dolby Audio MediaCodec decoding capability using Android Platform APIs

On devices running Android 10 and above, you can use MediaCodec APIs to determine if a Dolby Atmos or Dolby Audio MediaCodec decoder is available on the device, as shown in the following code snippet:

import android.media.MediaCodec;
import android.media.MediaCodecList;
import android.media.MediaFormat;
...
MediaCodecList mediaCodecList = new MediaCodecList(MediaCodecList.ALL_CODECS);
final MediaFormat format =
        MediaFormat.createAudioFormat(MediaFormat.MIMETYPE_AUDIO_EAC3_JOC,
                                      48000 /* sample rate */,
                                      2 /* channels */);
final String decoderName = mediaCodecList.findDecoderForFormat(format);
 
if (decoderName == null) {
    // Unable to find Dolby Digital Plus with Dolby Atmos MediaCodec decoder component
}
 
// Device supports MediaCodec decoding of Dolby Digital Plus with Dolby Atmos

Repeat the above, replacing MediaFormat.MIMETYPE_AUDIO_EAC3_JOC with MediaFormat.MIMETYPE_AUDIO_EAC3 and MediaFormat.MIMETYPE_AUDIO_AC3 to detect MediaCodec decoding support for Dolby Digital Plus and Dolby Digital respectively.

For Dolby AC-4 Level 4, use the following:

import android.media.MediaCodecInfo;
import android.media.MediaCodecList;
import android.media.MediaFormat;

// Create MediaFormat for AC-4 Level 4
final MediaFormat ac4Level4Format = 
        MediaFormat.createAudioFormat(MediaFormat.MIMETYPE_AUDIO_AC4,
                                      48000 /* Sample rate */,
                                      21  /* Channel count (used as a proxy for Level 4) */ );
// Find decoder name for the format
final String ac4Level4DecoderName = MediaCodecList.findDecoderForFormat(ac4Level4Format);

if (ac4Level4DecoderName != null) {
   MediaCodecList codecList = new MediaCodecList(MediaCodecList.ALL_CODECS);
   MediaCodecInfo[] codecInfos = codecList.getCodecInfos();
 
   for (MediaCodecInfo codecInfo : codecInfos) {
      if (codecInfo.getName().equals(ac4Level4DecoderName)) {
         // Found AC-4 decoder
         MediaCodecInfo.CodecCapabilities codecCaps =
                   codecInfo.getCapabilitiesForType(MediaFormat.MIMETYPE_AUDIO_AC4);
         if (codecCaps.profileLevels.length == 0) {
            // No profile-level info; assume Dolby AC-4 Level 4 support based on channel count
         } else {
            // Check profile-level capabilities explicitly
            for (MediaCodecInfo.CodecProfileLevel pl : codecCaps.profileLevels) {
               if (pl.profile == MediaCodecInfo.CodecProfileLevel.AC4Profile21 &&
                                    pl.level >= MediaCodecInfo.CodecProfileLevel.AC4Level4) {
                  // Dolby AC-4 (levels 0-4) supported
               }
            }
         }
      }
   }
} else {
   Log.d("AC4Check", "No decoder found for AC-4 Level 4 format.");
}

For Dolby AC-4 Level 3, use the above but with a channel count of 6 when constructing the MediaFormat and check for CodecProfileLevel.AC4Level3 in the MediaCodecInfo.CodecProfileLevel check.

Playing Dolby Atmos and Dolby Audio content

Dolby Atmos and Dolby Audio content can be played using either ExoPlayer or Android Platform APIs.

Playing Dolby Atmos and Dolby Audio content in ExoPlayer

If the device supports Dolby Atmos or Dolby Audio pass-through or MediaCodec decoding capability, 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 asset */);
player.prepare();
player.play();

ExoPlayer handles demultiplexing, decoding and playback, including converting Dolby AC-4 raw frames from MPEG DASH containers into Dolby AC-4 sync frames for usage by Dolby AC-4 MediaCodec decoders and AudioTracks.

Demultiplexing Dolby AC-4 frames from ISO BMFF content

MediaCodec decoders with MediaFormat.MIMETYPE_AUDIO_AC4 and AudioTrack instances using AudioFormat.ENCODING_AC4 expect AC‑4 data in sync frame transport format. In contrast, the ISO Base Media File Format (the basis of common streaming formats including MPEG DASH) stores AC‑4 as raw frames without sync headers. Therefore, when extracting AC‑4 from ISO Base Media File Format content for playback via an AC‑4 MediaCodec decoder or an AC‑4 AudioTrack, each raw AC‑4 frame must be prefixed with an AC‑4 sync frame header to form a valid sync frame. These sync frames are then supplied to the decoder or AudioTrack.

The example below shows a Java method that generates the required 7‑byte AC‑4 sync frame header for a given raw frame size:

/**
 * Build the 7-byte AC-4 sync header (simple transport, no CRC) for a raw AC-4 frame.
 * Header format: [0xAC, 0x40, 0xFF, 0xFF, size24_hi, size24_mid, size24_lo]
 *
 * @param rawFrameSize Size of the raw AC-4 frame in bytes.
 * @return A 7-byte header as a byte[].
 */
public static byte[] buildAc4SyncHeaderNoCrc(int rawFrameSize) {
    if (rawFrameSize <= 0) {
        throw new IllegalArgumentException("Frame size must be > 0");
    }
    byte[] header = new byte[7];
    header[0] = (byte) 0xAC;
    header[1] = (byte) 0x40; // Sync word for no CRC
    header[2] = (byte) 0xFF; // Extended size marker
    header[3] = (byte) 0xFF;
    header[4] = (byte) ((rawFrameSize >>> 16) & 0xFF);
    header[5] = (byte) ((rawFrameSize >>> 8) & 0xFF);
    header[6] = (byte) (rawFrameSize & 0xFF);
    return header;
}

Playing Dolby Atmos and Dolby Audio content using Android Platform APIs

Dolby Atmos and Dolby Audio content can be played on devices that support Dolby Atmos or Dolby Audio pass-through or MediaCodec decoding using Android Platform APIs.

Playing Dolby Atmos or Dolby Audio content on devices with Dolby Atmos or Dolby Audio pass-through decoders using Android Platform APIs

After detecting Dolby Atmos or Dolby Audio pass-through support using Android Platform APIs, you can play back using the AudioTrack API. The example of Dolby Digital Plus with Dolby Atmos is shown in the following code snippet:

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_JOC)
        .setSampleRate(48000)
        .build();
 
AudioAttributes attr = new AudioAttributes.Builder()
        .setUsage(AudioAttributes.USAGE_MEDIA)
        .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
        .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.

Repeat the above, replacing AudioFormat.ENCODING_E_AC3_JOC with AudioFormat.ENCODING_E_AC3, AudioFormat.ENCODING_AC3 or AudioFormat.ENCODING_AC4 for playing back Dolby Digital Plus, Dolby Digital or Dolby AC-4 respectively.

Playing Dolby Atmos or Dolby Audio content on devices with Dolby Atmos or Dolby Audio MediaCodec decoding support using Android Platform APIs

Once support for Dolby Atmos or Dolby Audio MediaCodec decoding is detected using Android Platform APIs, then playback of Dolby Atmos or Dolby Audio content is possible. It is important that Dolby Atmos and Dolby Audio content is decoded and output to the audio subsystem as multi-channel PCM, for example as shown in the following code snippet:

import android.media.AudioAttributes;
import android.media.AudioFormat;
import android.media.AudioTrack;
import android.media.MediaCodec;
import android.media.MediaFormat;
 
...
// Different device implementations will decode to different channel counts (and masks)
// Construct the AudioTrack appropriately so that the multi-channel Dolby Atmos decoded content can
// be played back and rendered by the device's audio subsystem.

public static int getAudioTrackChannelMask(int channelCount) {
    switch (channelCount) {
      case 2:
        return AudioFormat.CHANNEL_OUT_STEREO;
      case 4:
        return AudioFormat.CHANNEL_OUT_QUAD;
      case 5:
        return AudioFormat.CHANNEL_OUT_QUAD | AudioFormat.CHANNEL_OUT_FRONT_CENTER;
      case 6:
        return AudioFormat.CHANNEL_OUT_5POINT1;
      case 8:
        return AudioFormat.CHANNEL_OUT_7POINT1_SURROUND;
      case 10:
        return AudioFormat.CHANNEL_OUT_5POINT1POINT4;
      case 12:
        return AudioFormat.CHANNEL_OUT_7POINT1POINT4;
      default:
        return AudioFormat.CHANNEL_INVALID;
    }
}
 
AudioTrack track;
dec.setCallback(new MediaCodec.Callback() {
    @Override
    void onOutputBufferAvailable(MediaCodec mc, int id, ...) {
        MediaFormat bufFmt = mc.getOutputFormat(id);
        int mask;
        try {
            mask = bufFmt.getInteger(MediaFormat.KEY_CHANNEL_MASK);
        } catch (NullPointerException e) {
            int channelCount = bufFmt.getInteger(MediaFormat.KEY_CHANNEL_COUNT);
            mask = getAudioTrackChannelMask(channelCount);
        }
        int pcmEncoding = bufFmt.getInteger(MediaFormat.KEY_PCM_ENCODING);
        int sampleRate = bufFmt.getInteger(MediaFormat.KEY_SAMPLE_RATE);
        // On first buffer build AudioTrack with appropriate audio format based on decoded buffer format
        track = new AudioTrack.Builder()
                .setAudioFormat(new AudioFormat.Builder()
                        .setChannelMask(mask)
                        .setEncoding(pcmEncoding)
                        .setSampleRate(sampleRate)
                        .build())
                .setAudioAttributes(new AudioAttributes.Builder()
                        .setUsage(AudioAttributes.USAGE_MEDIA)
                        .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
                        .build())
                .build();
    }
}

Indicating Dolby Atmos and Dolby Audio Content

To display an indicator for Dolby Atmos or Dolby Audio content that will appear while the user is browsing the media browse tree, create an extras bundle and put a parcelable array list with key KEY_TINTABLE_INDICATOR_ICON_URI_LIST and a value list containing the URI for the vector drawable Dolby Atmos DD glyph logo dlb_dd_glyph.xml and then pass that bundle to the MediaDescription.Builder.setExtras method.

To indicate that media currently playing asset is Dolby Atmos or Dolby Audio, you can specify icons that are rendered on in-vehicle infotainment displays in cars that support this feature:

1. For Dolby Atmos, but not Dolby Audio, set the KEY_IMMERSIVE_AUDIO extra to value METADATA_VALUE_ATTRIBUTE_PRESENT in the extras bundle passed into MediaSession.setMetadata() of the currently playing media item.
2. For Dolby Atmos, set the KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI to a universal resource identifier (URI) pointing to the vector drawable Dolby Atmos horizontal logo dlb_atms_horz.xml.
3. For Dolby Audio, set the KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI to a universal resource identifier (URI) pointing to the vector drawable Dolby Audio horizontal logo dlb_audio_horz.xml, respectively.
4. For Dolby Atmos or Dolby Audio, set the KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI to a URI pointing to the vector drawable Dolby "Double-D" glyph logo dlb_dd_glyph.xml.

See https://developer.android.com/training/cars/media/enable-playback#format-attribution for more details.