Dolby Integration Guidelines

This documentation provides integration guidelines for app developers who need to support Dolby Digital or Dolby Digital Plus audio content in their apps.

You can see the Dolby settings in Amazon Fire TV by going to Settings > Display & Sounds > Audio > Dolby Digital Output.

Terms

Note the following abbreviations used in this documentation:

  • EAC3: Dolby Digital Plus (DDP)
  • AC3: Dolby Digital (DD)

Four Ways to Play Dolby Audio

You can play Dolby (DD or DDP) audio content in your app in four ways:

  1. Custom Media Player Approach
  2. ExoPlayer
  3. Other Supported Media Players
  4. Android Media Player

Option 1: Custom Media Player Approach

Implement a custom player that uses AudioManager, AudioTrack, and (optionally) MediaCodec APIs. This section specifies the use of AudioManager, AudioTrack, and optionally MediaCodec APIs to play Dolby audio content as recommended by Android.

AudioManager Overview

Android L enhanced the ACTION_HDMI_AUDIO_PLUG intent in AudioManager to report the capabilities of sinks in Lollipop. This intent is broadcast whenever HDMI is plugged into or unplugged from to the device.

This intent also has a provision for apps to detect the capabilities of the connected endpoint (AVR or TV) via EXTRA_ENCODINGS present in the intent. The possible values are one of the ENCODING_XXXX values. For example:

AudioTrack Overview

Android L added the support of ENCODING_AC3 and ENCODING_E_AC3 encoding formats to AudioFormat. If the AudioTrack is configured with Dolby encoding format, and if the connecting endpoint supports that encoding format, AudioTrack accepts the Dolby raw bitstream as input and passes the bitstream to the endpoint after IEC61937 packetization. AudioTrack supports only clear (not encrypted) input bitstream.

Additionally, the creation of AudioTrack fails if the encoding format is not supported by the connected endpoint.

Applications can use the ACTION_HDMI_AUDIO_PLUG intent to find the list of supported Dolby encoding formats for the connected device, create AudioTrack with one of the supported Dolby encoding formats, and pass the corresponding Dolby raw bitstream (in clear) as input to AudioTrack to achieve Dolby pass-through playback.

Optionally, AudioTrack can also support transcoding DDP bitstream to DD if the connected endpoint only supports DD. This feature is made available to the application by adding ENCODING_E_AC3 to the EXTRA_ENCODINGS extra of the ACTION_HDMI_AUDIO_PLUG intent if the endpoint only supports DD.

Hence, from an application's perspective, an endpoint that supports DD also supports DDP and can continue to send DDP bitstream to AudioTrack, which internally transcodes the bitstream to DD before passing it through.

MediaCodec (Optional) Overview

AudioTrack does not support Dolby audio content that is encrypted with DRM keys. Hence, for an encrypted Dolby audio bitstream, it is mandatory to use MediaCodec APIs to decrypt the bitstream and then pass the decrypted bitstream to AudioTrack.

Android provides a generic raw audio decoder via MediaCodec interface named "OMX.google.raw.dec," which is essentially a no-op (no operation) copy decoder. If the bitstream is encrypted, it uses MediaCrypto APIs to decrypt the bitstream and outputs it. Apps must use this decoder to decrypt the encrypted Dolby bitstream and pass the clear Dolby bitstream to AudioTrack.

Optionally, a platform can support Dolby decoder via MediaCodec interface. This decoder decodes the Dolby audio bitstream to PCM. Applications can use findDecoderForFormat to detect the presence of a decoder that supports Dolby MIME type.

The following table summarizes various Dolby playback scenarios in a typical Android TV that does not support DDP to DD transcode in AudioTrack.

Connected End-Point capabilities (AVR or TV) EXTRA_ENCODINGS in ACTION_HDMI_
AUDIO_PLUG intent
Source Audio Stream MediaCodec (optional) AudioTrack encoding format Scenario
EAC3, AC3 and PCM ENCODING_E_AC3, ENCODING_AC3, ENCODING_PCM_16BIT Clear EAC3 or AC3 None ENCODING_E_AC3 or ENCODING_AC3 DDP or DD pass-through
Encrypted EAC3 or AC3 OMX.google.raw.dec
AC3 and PCM ENCODING_AC3, ENCODING_PCM_16BIT Clear AC3 None ENCODING_AC3 DD passthrough
Encrypted AC3 OMX.google.raw.dec
PCM ENCODING_PCM_16BIT AAC or any non-Dolby (recommended) OMX.google.aac.decoder ENCODING_PCM_16BIT PCM playback
AC3 or EAC3 (only if non-dolby stream is unavailable & Dolby decoder is available in the platform) OMX.google.aac.decoder, OMX.dolby.eac3.decoder ENCODING_PCM_16BIT DD or DDP decode

Dolby Support in Amazon Fire TV (Gen 2) and Fire TV Edition

Support for 4K in Fire TV (Gen 2) was launched with Android L based Fire OS 5 and fully complies with the Android L recommended Dolby architecture. This section describes the Dolby support in Fire TV (Gen 2).

AudioTrack – Amazon Fire TV (Gen 2) and Fire TV Edition

AudioTrack supports both DDP/DD pass-through and DDP-to-DD transcoder. The AudioTrack accepts Dolby raw bitstream and, depending on the Dolby capability of the endpoint, decides to either do a DD/DDP pass-through or DDP-to-DD transcode and pass-through.

AudioManager – Amazon Fire TV (Gen 2) and Fire TV Edition

Since AudioTrack also supports transcoding DDP bitstream to DD when the connected endpoint only supports DD, AudioManager indicates this by adding ENCODING_E_AC3 to the EXTRA_ENCODINGS extra of the ACTION_HDMI_AUDIO_PLUG intent if the endpoint only supports DD.

Hence, from an application's perspective, an endpoint that supports DD also supports DDP and can continue to send DDP bitstream to AudioTrack, which internally transcodes it to DD before passing it through.

MediaCodec – Amazon Fire TV (Gen 2) and Fire TV Edition

The MediaCodec for Dolby Decoder (OMX.dolby.ac3.decoder & OMX.dolby.eac3.decoder) supports decoding to PCM only. Additionally, Dolby decoders also down-mixes the multi-channel output to stereo. So irrespective of the number of input channels of the content, the output is always stereo PCM. The table below summarizes various Dolby playback scenarios in Fire TV (Gen 2):

Connected End-Point capabilities (AVR or TV) EXTRA_ENCODINGS in ACTION_HDM_AUDIO_
PLUG intent
Source Audio Stream MediaCodec Output Mime Type of MediaCodec AudioTrack encoding format Scenario
EAC3, AC3 and PCM ENCODING_E_AC3, ENCODING_AC3, ENCODING_PCM_16BIT EAC3 or AC3 OMX.google.raw.dec** audio/eac3 or audio/ac3 ENCODING_E_AC3 or ENCODING_AC3 DDP / DD pass-through
AC3 and PCM ENCODING_E_AC3*, ENCODING_AC3, ENCODING_PCM_16BIT EAC3 or AC3 OMX.google.raw.dec** audio/eac3 or audio/ac3 ENCODING_E_AC3 or ENCODING_AC3 DDP-to-DD transcode or DD pass-through
PCM only ENCODING_PCM_16BIT AAC (rec-
ommended)
OMX.google.raw.dec** audio/raw ENCODING_PCM_16BIT AAC decode
EAC3 OMX.dolby.eac3.decoder audio/raw ENCODING_PCM_16BIT DDP decode
AC3 OMX.dolby.ac3.decoder audio/raw ENCODING_PCM_16BIT DDP decode

* Because transcoding from DDP to DD is supported.
** Optional if the content is not encrypted.

Dolby Support in Fire TV Stick (Gen 1)

Fire TV Stick (Gen 1), which is based on JellyBean Android OS, was launched before Android L was released. Android L officially introduced support for Dolby pass-through audio in Android TV.

Android L has a recommended architecture for Dolby integration in the platform, which unfortunately does not match with the Dolby integration architecture on Fire TV Stick (Gen 1). This section describes the Dolby support in Fire TV Stick (Gen 1).

MediaCodec – Fire TV Stick (Gen 1)

The MediaCodec that handles Dolby bitstream supports all scenarios: Dolby pass-through, transcode, and decode. The MediaCodec depends on the Dolby capability of the connected endpoint and the system's Dolby settings to select the appropriate mode for handling the incoming Dolby bitstream.

  • For Dolby pass-through or transcode mode, the decoder converts the raw input Dolby bitstream to the IEC61937 packetized format.
  • For Dolby decode mode, Dolby decoders also down-mixes the multi-channel output to stereo PCM. So irrespective of the number of input channels of the content, the output is always stereo PCM. The decoders available are OMX.dolby.ec3.decoder to handle DDP bitstream and OMX.dolby.ac3.decoder to handle DD bitstream.

The following table illustrates the functionality of MediaCodec.

Endpoint capability Input stream type Codec Dolby Setting Output format MimeType Comments
DDP, DD and PCM DDP OMX.dolby.ec3.decoder DDP over HDMI or DDP Auto audio/ec3* DDP Pass-through
DDP OFF audio/raw DDP Decode
DD OMX.dolby.ac3.decoder DDP over HDMI or DD over HDMI or DDP Auto audio/ac3 DD Pass-through
DD and PCM DDP OMX.dolby.ec3.decoder DDP over HDMI, DD over HDMI, DDP Auto audio/ec3* DDP > DD Transcode
DDP OFF audio/raw DDP Decode
DD OMX.dolby.ac3.decoder DDP over HDMI, DD over HDMI, or DDP Auto audio/ac3 DD Pass-through
DDP OFF audio/raw DD Decode
PCM DDP OMX.dolby.ec3.decoder N/A audio/raw DDP decode
DD OMX.dolby.ac3.decoder N/A audio/raw DDP decode

* The missing "a" in eac3 is intentional. This is a subtle difference between Fire TV Stick (Gen 1) and Amazon Fire TV.

AudioTrack – Fire TV Stick (Gen 1)

AudioTrack in Fire TV Stick (Gen 1) has certain limitations — it does not support Dolby Transcode or Dolby Decode, and only supports Dolby Pass-through. Additionally,the input Dolby bitstream must be in IEC61937 packetized format — which is same as the output of Dolby MediaCodec decoders.

Due to these architectural differences between Fire TV Stick (Gen 1) and Android L, app developers need to do major changes in their app to support Dolby audio content playback. The application must always use MediaCodec (even if the content is not encrypted) to process the Dolby bitstream and must configure the AudioTrack based on the output MIME type indicated by MediaCodec. The following steps provide more detail about this process.

A. Create the Decoder by MimeType

Create the MediaCodec by MIME Type (audio/eac3, audio/ec3, or audio/ac3). This is a generic Android way of creating a codec — no custom changes are required.

B. Handle MediaCodec Output Format Change Notification

When the app starts using MediaCodec to process the input bit stream, it detects an output format change and returns INFO_OUTPUT_FORMAT_CHANGED in the dequeueOutputBuffer API call. The application must handle this response and use the getOutputFormat API to find out the output format MIME type. It should use this MIME type to configure AudioTrack as per the following table:

MimeType AudioFormat value  
audio/eac3 ENCODING_E_AC3
audio/ac3 ENCODING_AC3
audio/raw ENCODING_PCM_16BIT

C. Limitations of AudioTrack for Dolby encoding formats

AudioTrack for Dolby encoding formats ENCODING_E_AC3 and ENCODING_AC3 has following limitations and known issues:

  • The AudioTrack start/pause API is not effective. Your app might start writing data to the AudioTrack just after creation, and as a result, it will start playing. It does not wait for start API to be called.
  • AudioTrack’s getTimeStamp API (which was introduced in KitKat) is back-ported to Jelly-Bean-based Amazon Fire TV (Gen 1) and Fire TV Stick (Gen 1) and can be used for A/V Sync logic.

Dolby Support in Amazon Fire TV (Gen 1)

Fire TV (Gen 1) was initially built on a Jelly-Bean-based OS and launched much before Android L — which officially introduced support for Dolby audio pass-through in Android TV.

Android L has a recommended architecture for Dolby integration in the platform, which unfortunately does not fully match with the Dolby integration architecture on Fire TV (Gen 1). This section describes the Dolby architecture in Fire TV (Gen 1).

MediaCodec – Amazon Fire TV (Gen 1)

The default MediaCodec for Dolby MIME type available in Fire TV (Gen 1) is a pass-through decoder only. It copies input data to output data without changing the MIME type. Hence, the output format has same MIME type as that of the input format.

The decoders available are OMX.qcom.audio.decoder.passthrougheac3 to handle DDP bitstream and OMX.qcom.audio.decoder.passthroughac3 to handle DD bitstream. In addition, these decoders also decrypt the data if it is encrypted by a DRM scheme. Hence, if the content is encrypted by DRM, applications must use this decoder. Otherwise, the usage of this decoder is optional and the Dolby bitstream can be passed to AudioTrack directly.

AudioTrack – Amazon Fire TV (Gen 1)

AudioTrack handles Dolby pass-through, Dolby Decode, and Dolby transcode internally. This means that depending on the Dolby capability of the connected endpoint and the system Dolby setting, AudioTrack selects the appropriate mode of handling the incoming Dolby bitstream.

endpoint capability Input stream type Dolby Setting HDMI Output Comments
DDP, DD, and PCM DDP DDP over HDMI/Optical or DDP Auto DDP DDP Passthrough
DDP OFF PCM DDP Decode
DD DDP over HDMI/Optical, DD over HDMI, or DDP Auto DD DD Passthrough
DD and PCM DDP DDP over HDMI/Optical, DD over HDMI, or DDP Auto DD DDP > DD Transcode
DDP OFF PCM DDP Decode
DD DDP over HDMI/Optical, DD over HDMI, or DDP Auto DD DD Passthrough
DDP OFF PCM DD Decode
PCM DDP or DD NA PCM DD or DDP decode

Limitations of AudioTrack for Dolby Encoding Formats – Amazon Fire TV (Gen 1)

AudioTrack for Dolby encoding formats ENCODING_E_AC3 and ENCODING_AC3 has following limitations and known issues:

  • The getPlaybackHeadPosition API of AudioTrack is not implemented. Consequently, do not depend on it for A/V sync. Your app must not call this API. Calling this API may result into a crash.
  • AudioTrack's start/pause API is not effective. You app might start writing data to the AudioTrack just after creation and it will start playing. It does not wait for start API to be called.
  • AudioTrack’s getTimeStamp API (which was introduced in KitKat) is back-ported to Jelly-Bean-based Fire TV (Gen 1) and Fire TV Stick (Gen 1) and can be used for A/V Sync logic via reflection.

Option 2: Use ExoPlayer

ExoPlayer is a open source player backed by Google that supports playing Dolby audio stream. However, due to the architectural differences in Dolby support between a standard Android L device and Amazon Fire TV (Gen 1) family of devices (as described in preceding sections), ExoPlayer fails to play Dolby audio content.

Amazon has developed patches for Exoplayer to enable playback of Dolby audio content in Fire TV (Gen 1) family of devices. These patches are open sourced here: exoplayer-amazon-port. This port also includes other patches required to enable playback of PlayReady DRM protected content. (Note that each "amazon/rx.y.z" branch maps to ExoPlayer version x.y.z.)

Option 3: Use Other Supported Media Players

You can use other supported media players for Amazon Fire TV, such as VisualOn or NexPlayer, to play Dolby audio content and DRM content. Refer to Media Players for further details.

Option 4: Use Android Media Player

Your app can use Android MediaPlayer to play Dolby content.

Handling non-Dolby End-Points and Private Listening Modes

This section describes recommendations and best practices for Dolby audio content playback on the Amazon Fire TV family of devices when connected to a non-Dolby endpoint and private listening. Following these guidelines will help you create the best user experience for Dolby audio content playback.

As described previously, Android L introduced a new API in AudioManager called ACTION_HDMI_AUDIO_PLUG intent. This intent allows apps to detect the capabilities of the connected endpoint (AVR or TV). This detection can be used to support Dolby audio content playback in various scenarios including private listening.

Q. For Amazon Fire TV and Fire TV Stick (Gen 1), how does an app detect the capabilities of the connected endpoint?
The app must register a broadcast receiver to receive the ACTION_HDMI_AUDIO_PLUG intent and read the EXTRA_ENCODINGS extra values in the intent. This list of encoding values will indicate the endpoint capabilities. The possible values are one of the ENCODING_XXXX values (for example, ENCODING_PCM_16BIT, ENCODING_AC3, ENCODING_E_AC3, and so on).
Q. For Fire TV Edition, how does an app detect the capabilities of the connected endpoint (such as ACTION_HDMI_AUDIO_PLUG as mentioned above)?
By default, the speakers of Fire TV Edition support stereo output only, and hence apps can stream stereo content by default. But when the TV is connected to a sound bar or AVR via Optical audio output or HDMI (based on the Dolby system settings set by the user on Fire TV Edition), an app can choose to stream surround sound in Dolby audio format.

To support this, the app is required to read a Global setting external_surround_sound_enabled to decide if surround sound (AC3 and EAC3) is supported or not. If the value is 1, Dolby audio is supported. If the value is 0, the app can further use other means (such as ACTION_HDMI_AUDIO_PLUG to decide if surround sound is supported or not. Refer to this Exoplayer patch (Added support for Surround Sound detection for Optical out for reference.

Q. Which audio stream should be selected for playback when the connected endpoint does not support DD or DDP?
In these cases, let your app select a non-Dolby audio content for playback (for example, AAC). This option has the advantage of reduced bandwidth usage as compared to Dolby audio content.

However, if the app cannot select an alternative non-Dolby audio content and chooses to continue to stream Dolby (DD or DDP) audio, it must do the following for each device.

  • Amazon Fire TV (Gen 1): Send Dolby raw bitstream to AudioTrack, which internally decodes and down-mixes to stereo PCM.
  • Fire TV Stick (Gen 1) and Amazon Fire TV (Gen 2): Use the MediaCodec for Dolby (OMX.dolby.ac3.decoder or OMX.dolby.eac3.decoder). This MediaCodec decodes the Dolby bitstream, down-mixes to stereo PCM, and configures AudioTrack with the ENCODING_PCM_16BIT audio format to render the PCM data. Since the Dolby Decoder in all the platforms down-mixes multi-channel content to stereo, there is no real advantage in choosing Dolby audio content when the endpoint does not support DD or DDP.
Q. Which audio stream should be selected for playback when the connected endpoint supports DD but does not support DDP?
The answer depends on the Fire TV device:
  • Amazon Fire TV (Gen 1) and Amazon Fire TV (Gen 2): AudioTrack supports transcoding DDP bitstream to DD. Hence, even if the endpoint supports DD only, AudioManager appends DDP as the supported capability in the ACTION_HDMI_AUDIO_PLUG intent. As a result, from an app's perspective, the endpoint that supports DD also supports DDP (via transcoding in AudioTrack).
  • Fire TV Stick (Gen 1): The app can select any audio content for playback because the MediaCodec decides whether to pass-through, transcode, or decode based on endpoint capabilities. In this use case, it would pass-through DD or transcode DDP to DD and pass-through DD.
Q. Which audio stream should be selected for playback when the connected endpoint supports DDP and DD?
Amazon Fire TV (Gen 1) and Amazon Fire TV (Gen 2): The app can select DDP or DD audio content for playback. If the audio is not encrypted, the app can then send this clear DD/DDP bitstream data as is to AudioTrack. Internally, AudioTrack will pass-through the DD/DDP bitstream to the connected endpoint.

If the audio contend is DRM protected, the app must instantiate the following MediaCodec to decrypt the bitstream:

  • In Amazon Fire TV (Gen 1), OMX.qcom.audio.decoder.passthrougheac3 or OMX.qcom.audio.decoder.passthroughac3. This special decoder is a no-op pass-through decoder that supports decryption (that is, it copies the input bitstream to output after decrypting if needed).

  • In Amazon Fire TV (Gen 2), OMX.google.raw.dec (by name). This special decoder is a no-op pass-through decoder that supports decryption (that is, it copies the input bitstream to output after decrypting if needed).

Fire TV Stick (Gen 1): The app can select any audio content for playback because the MediaCodec decides whether to pass-through, transcode, or decode based on the endpoint capabilities. In this use case it would pass-through the Dolby audio content.

Q. How does the app handle private listening use cases involving audio headsets or Bluetooth A2DP headsets during Dolby pass-through playback?
Amazon Fire TV (Gen 1): The app does not need to do anything special to handle the private listening use cases. This is automatically taken care of internally in AudioTrack (it switches over from pass-through to decode the mode of operating).

Fire TV Stick (Gen 1) and Amazon Fire TV (Gen 2): When either an audio headset (via a game controller) or Bluetooth headset is connected to the device during Dolby pass-through playback, the operating system re-broadcasts the ACTION_HDMI_AUDIO_PLUG intent with modified encoding extra values.

Since the audio headset via a game controller or Bluetooth headset do not support Dolby pass-through, the encoding extra value would now be ENCODING_PCM_16BIT only. The app must register to receive this intent during playback and re-configure the audio pipeline to do one of the following:

  • Switch to an alternate non-Dolby audio content mid-stream (for example AAC)
  • If an alternative audio content is not available, re-configure the audio pipeline to use the MediaCodec Dolby decoder to decode the Dolby content to Stereo PCM. In case of Fire TV Stick (Gen 1), re-creation of the MediaCodec is required as part of re-creating the audio pipeline.