Developer Console
Gracias por tu visita. Esta página solo está disponible en inglés.

Dolby Integration Guidelines

This documentation provides integration guidelines for application developers who need to support Dolby audio content.

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/DDP/Atmos) audio content in your app in four ways:

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

Option 1: Use ExoPlayer

ExoPlayer is a open source player supported by Google that supports playing Dolby audio stream.

Amazon has developed patches for Exoplayer to enable or enhance playback of Dolby audio content on variuos Amazon devices. These patches are open sourced here: exoplayer-amazon-port. (Note that each "amazon/rx.y.z" branch maps to ExoPlayer version x.y.z.)

Option 2: Custom Media Player Approach

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

Detecting Dolby support

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:

Android L does not have an enumeration type for Atmos(ENCODING_E_AC3_JOC) detection however we have an additional mechinism which exposes the information in the similar manner as EXTRA_ENCODINGS, by querying "hdmi_encodings"

AudioManager.getParameters("hdmi_encodings")

For example, if a sink supports Atmos the string returned will be:

"pcm;ac3;eac3;atmos;" //fireOS6
"pcm|ac3|eac3|atmos| //fireOS7

NOTE: Certain platforms will indicate Dolby support even when the sink does not support decoding Dolby content. In this case the platform will transcode Dolby encoded content to the sink capabilities, for example, if the sink only supports PCM audio, the incoming Dolby audio stream will be transcoded to PCM by the Fire Tv device.

Fire TV Edition TV platforms and sound bars outputting audio using the built in speakers (and not via an HDMI sink) do not have the above described ACTION_HDMI_AUDIO_PLUG boadcast action.
In this case applications shall query the global setting external_surround_sound_enabled to verify if Dolby decoding is supported by the device.

if (Settings.Global.getInt(mContext.getContentResolver(), "external_surround_sound_enabled") == 1) {
   // Platform supports Dolby
} else {
   // Platform does not support Dolby
}

Return value of 1 indicates support.
The recommendation is if Dolby is supported to use passthrough playback, e.g. if using MediaCodec use the "OMX.google.raw.dec" decoder.

For reference see Exoplayer patch (Added support for Surround Sound detection for Optical out)

Android API level 23 added an API getEncodings that can also query sink capabilities

AudioManager audio = (AudioManager) mContext.getSystemService(Context.AUDIO_SERVICE);
AudioDeviceInfo[] devices = audio.getDevices(audio.GET_DEVICES_OUTPUTS);
for (AudioDeviceInfo device : devices) {
    Log.i(TAG, "Supported Encodings" + Arrays.toString(device.getEncodings()));
}

The capabilities reported to applications can farther be effected by the Amazon Audio Settings, e.g. if Dolby is disabled the device will not report support for Dolby. This scenario does allow multichannel PCM when connected to a appropriate AVR.

AudioTrack Overview

Android L added the support of ENCODING_AC3 and ENCODING_E_AC3 encoding formats to AudioFormat. Android P added support for ENCODING_E_AC3_JOC used for Atmos. 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.

Certain platforms transcode DDP bitstream to DD if the connected endpoint only supports DD.

MediaCodec 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.

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.
Note: Android MediaPlayer can only output stereo PCM content and cannot support passthrough playback.

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(Bluetooth). 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 HDMI related scenarios.

When connecting to a non HDMI sink device such as a Bluetooth headset the recommendation is to recreate the AudioTrack and switch to non-Dolby audio content such as 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 audio, applications should use MediaCodec to switch codecs from passthrough(OMX.google.raw.dec) to the appropriate Dolby codec(OMX.dolby.ac3.decoder or OMX.dolby.eac3.decoder).
The MediaCodec decoder decodes the Dolby bitstream, down-mixes to stereo PCM.
The AudioTrack again needs to be recreated 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. 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. Dolby passthrough however is supported and recommended when playback is on TV speakers.
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 supports DD but does not support DDP?
Most Amazon devices have the capability to automatically transcode DDP content to DD and passthrough the content to the DD only sink device.
This assumes the Amazon device reports support for DD as well. In the event DD is not supported as described above an alternate non-Dolby audio track needs to be selected or the DDP content needs to be decoded to PCM.