开发人员控制台
登录
登录
开发人员控制台

杜比集成指南


杜比集成指南

本文档为需要在其应用中支持 Dolby Digital 或 Dolby Digital Plus 音频内容的应用开发者提供了集成指南。

通过转至设置 > 显示和声音 > 音频 > 杜比数字输出，您可以在 Amazon Fire TV 中查看杜比设置。

术语

请注意本文档中使用的以下缩写：

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

播放杜比音频的四种方法

您可以通过四种方式在应用中播放杜比（DD 或 DDP）音频内容：

  1. 自定义媒体播放器方法
  2. ExoPlayer
  3. 其他支持的媒体播放器
  4. 安卓媒体播放器

方法 1： 自定义媒体播放器方法

实施一个自定义播放器，该播放器使用 AudioManager、AudioTrack 和（可选）MediaCodec API。本部分介绍了如何使用 AudioManager、AudioTrack 和可选的 MediaCodec API 来播放杜比音频内容，这是安卓推荐的方法。

AudioManager 概述

Android L 增强了 AudioManager 中的 ACTION_HDMI_AUDIO_PLUG 意图，以报告 Lollipop 中的接收器功能。每当 HDMI 插入或拔出设备时，都会广播此意图。

此意图还规定应用应通过意图中提供的 EXTRA_ENCODINGS 来检测连接端点（AVR 或 TV）的功能。可能的值是 ENCODING_XXXX 值之一。例如：

AudioTrack 概述

Android L 向 AudioFormat 中添加了对 ENCODING_AC3 和 ENCODING_E_AC3 编码格式的支持。如果 AudioTrack 配置为杜比编码格式，并且连接的端点支持该编码格式，则 AudioTrack 接受杜比原始位流作为输入，并在 IEC61937 封包化后将位流传递到端点。AudioTrack 仅支持明文（未加密）输入位流。

此外，如果连接的端点不支持该编码格式，AudioTrack 的创建将失败。

应用可以使用 ACTION_HDMI_AUDIO_PLUG 意图查找连接的设备支持的杜比编码格式列表，使用支持的杜比编码格式创建 AudioTrack，并将相应的杜比原始位流（明文）作为输入传递到 AudioTrack，以实现杜比直通播放。

或者，如果连接的端点仅支持 DD，AudioTrack 也支持将 DDP 位流转码为 DD。如果端点仅支持 DD，则可以通过将 ENCODING_E_AC3 添加到 ACTION_HDMI_AUDIO_PLUG 意图的 EXTRA_ENCODINGS 额外信息中，向应用提供此功能。

因此，从应用的角度来看，支持 DD 的端点也支持 DDP，并且可以继续将 DDP 位流发送到 AudioTrack，AudioTrack 会在传递之前将位流转码为 DD。

MediaCodec（可选）概述

AudioTrack 不支持使用 DRM 密钥加密的杜比音频内容。因此，对于加密的杜比音频位流，必须使用 MediaCodec API 来解密位流，然后将解密的位流传递给 AudioTrack。

Android 通过名为“OMX.google.raw.dec”的 MediaCodec 接口提供了一个通用的原始音频解码器，它本质上是一个无操作 (no-op) 复制解码器。如果位流被加密，它使用 MediaCrypto API 来解密位流并输出它。应用必须使用此解码器来解密加密的杜比位流，并将明文杜比位流传递给 AudioTrack。

或者，一个平台可以通过 MediaCodec 接口支持杜比解码器。该解码器将杜比音频位流解码为 PCM。应用可以使用 findDecoderForFormat 来检测是否存在支持杜比 MIME 类型的解码器。

下表总结了典型 Android TV 中 AudioTrack 中不支持 DDP 到 DD 转码的各种杜比播放场景。

连接的端点功能（AVR 或电视） EXTRA_ENCODINGS in ACTION_HDMI_
AUDIO_PLUG 意图		 源音频流 MediaCodec（可选） AudioTrack 编码格式 情景
EAC3、AC3 和 PCM ENCODING_E_AC3、ENCODING_AC3、ENCODING_PCM_16BIT 明文 EAC3 或 AC3 无 ENCODING_E_AC3 或 ENCODING_AC3 DDP 或 DD 直通
加密的 EAC3 或 AC3 OMX.google.raw.dec
AC3 和 PCM ENCODING_AC3、ENCODING_PCM_16BIT 明文 AC3 无 ENCODING_AC3 DD 直通
加密 AC3 OMX.google.raw.dec
PCM ENCODING_PCM_16BIT AAC 或任何非杜比格式（推荐） OMX.google.aac.decoder ENCODING_PCM_16BIT PCM 播放
AC3 或 EAC3（仅当非杜比流不可用且平台中有可用的杜比解码器时） OMX.google.aac.decoder、OMX.dolby.eac3.decoder ENCODING_PCM_16BIT DD 或 DDP 解码

Amazon Fire TV（第 2 代）和 Fire TV Edition 中的杜比支持

Fire TV（第 2 代）中对 4K 的支持随基于 Android L 的 Fire OS 5 推出，并完全符合 Android L 推荐杜比架构。本节介绍 Fire TV（第 2 代）中的杜比支持。

AudioTrack – Amazon Fire TV（第 2 代）和 Fire TV Edition

AudioTrack 支持 DDP/DD 直通以及 DDP 到 DD 转码器。AudioTrack 接受杜比原始位流，并根据端点的杜比功能，决定执行 DD/DDP 直通还是 DDP 到 DD 转码和直通。

AudioManager – Amazon Fire TV（第 2 代）和 Fire TV Edition

由于当连接的端点仅支持 DD 时 AudioTrack 还支持将 DDP 位流转码为 DD，因此 AudioManager 通过将 ENCODING_E_AC3 添加到 ACTION_HDMI_AUDIO_PLUG 意图的 EXTRA_ENCODINGS 额外信息中来指示这一点。

因此，从应用的角度来看，支持 DD 的端点也支持 DDP，并且可以继续将 DDP 位流发送到 AudioTrack，AudioTrack 会在传递之前将位流转码为 DD。

MediaCodec – Amazon Fire TV（第 2 代）和 Fire TV Edition

杜比解码器的 MediaCodec（OMX.dolby.ac3.decoder 和 OMX.dolby.eac3.decoder）只支持解码到 PCM。此外，杜比解码器还将多声道输出向下混音为立体声。因此，无论内容的输入通道数量如何，输出始终是立体声 PCM。下表总结了 Fire TV（第 2 代）中的各种杜比播放场景：

连接的端点功能（AVR 或电视） ACTION_HDM_AUDIO_PLUG 意图中的
EXTRA_ENCODINGS		 源音频流 MediaCodec MediaCodec 的输出 Mime 类型 AudioTrack 编码格式 情景
EAC3、AC3 和 PCM ENCODING_E_AC3、ENCODING_AC3、ENCODING_PCM_16BIT EAC3 或 AC3 OMX.google.raw.dec** audio/eac3 或 audio/ac3 ENCODING_E_AC3 或 ENCODING_AC3 DDP/DD 直通
AC3 和 PCM ENCODING_E_AC3*、ENCODING_AC3、ENCODING_PCM_16BIT EAC3 或 AC3 OMX.google.raw.dec** audio/eac3 或 audio/ac3 ENCODING_E_AC3 或 ENCODING_AC3 DDP 到 DD 转码或 DD 直通
仅 PCM ENCODING_PCM_16BIT AAC
（推荐）		 OMX.google.raw.dec** audio/raw ENCODING_PCM_16BIT AAC 解码
EAC3 OMX.dolby.eac3.decoder audio/raw ENCODING_PCM_16BIT DDP 解码
AC3 OMX.dolby.ac3.decoder audio/raw ENCODING_PCM_16BIT DDP 解码

* 因为支持从 DDP 转码到 DD。
** 如果内容未加密，则可选。

Fire TV Stick（第 1 代）中的杜比支持

Fire TV Stick（第 1 代），它基于 JellyBean Android OS，在 Android L 发布之前推出。Android L 正式推出了对 Android TV 中杜比直通音频的支持。

Android L 在平台中提供了一个推荐的杜比集成架构，遗憾的是，该架构与 Fire TV Stick（第 1 代）上的杜比集成架构不匹配。本节介绍 Fire TV Stick（第 1 代）中的杜比支持。

MediaCodec – Fire TV Stick（第 1 代）

处理杜比位流的 MediaCodec 支持所有场景： 杜比直通、转码和解码。MediaCodec 依赖于连接端点的杜比功能和系统的杜比设置，来选择处理传入杜比位流的适当模式。

  • 对于杜比直通或转码模式，解码器将原始输入杜比位流转换为 IEC61937 封包化格式。
  • 对于杜比解码模式，杜比解码器还将多声道输出向下混音为立体声 PCM。因此，无论内容的输入通道数量如何，输出始终是立体声 PCM。可用的解码器是用于处理 DDP 位流的 OMX.dolby.ec3.decoder 和用于处理 DD 位流的 OMX.dolby.ac3.decoder。

下表说明了 MediaCodec 的功能。

端点功能 输入流类型 编解码器 杜比设置 输出格式 MIME 类型 备注
DDP、DD 和 PCM DDP OMX.dolby.ec3.decoder DDP over HDMI 或 DDP Auto audio/ec3* DDP 直通
DDP OFF audio/raw DDP 解码
DD OMX.dolby.ac3.decoder DDP over HDMI 或 DD over HDMI 或 DDP Auto audio/ac3 DD 直通
DD 和 PCM DDP OMX.dolby.ec3.decoder DDP over HDMI、DD over HDMI、DDP Auto audio/ec3* DDP > DD 转码
DDP OFF audio/raw DDP 解码
DD OMX.dolby.ac3.decoder DDP over HDMI、DD over HDMI 或 DDP Auto audio/ac3 DD 直通
DDP OFF audio/raw DD 解码
PCM DDP OMX.dolby.ec3.decoder 不适用 audio/raw DDP 解码
DD OMX.dolby.ac3.decoder 不适用 audio/raw DDP 解码

* eac3 中缺少“a”是有意为之。这是 Fire TV Stick（第 1 代）和 Amazon Fire TV 之间的微妙差别。

AudioTrack – Fire TV Stick（第 1 代）

Fire TV Stick（第 1 代）中的 AudioTrack 有一定的限制 - 它不支持杜比转码或杜比解码，只支持杜比直通。此外，输入杜比位流必须采用 IEC61937 封包化格式，这与杜比 MediaCodec 解码器的输出相同。

由于 Fire TV Stick（第 1 代）和 Android L 之间的这些架构差异，应用开发者需要对其应用进行重大更改，以支持杜比音频内容播放。应用必须始终使用 MediaCodec（即使内容未加密）来处理杜比位流，并且必须根据 MediaCodec 指示的输出 MIME 类型配置 AudioTrack。以下步骤提供有关此过程的更多详细信息。

A.按 MIME 类型创建解码器

按 MIME 类型（audio/eac3、audio/ec3 或 audio/ac3）创建 MediaCodec。这是创建编解码器的通用安卓方式 — 不需要自定义更改。

B.处理 MediaCodec 输出格式更改通知

当应用开始使用 MediaCodec 来处理输入位流时，它会检测输出格式更改，并在 dequeueOutputBuffer API 调用中返回 INFO_OUTPUT_FORMAT_CHANGED。应用必须处理此响应，并使用 getOutputFormat API 找出输出格式 MIME 类型。它应该使用此 MIME 类型来配置 AudioTrack，如下表所示：

MIME 类型音频格式值  
audio/eac3 ENCODING_E_AC3
audio/ac3 ENCODING_AC3
audio/raw ENCODING_PCM_16BIT

C.AudioTrack 的杜比编码格式限制

杜比编码格式 ENCODING_E_AC3 和 ENCODING_AC3 的 AudioTrack 有以下限制和已知问题：

  • AudioTrack 开始/暂停 API 无效。您的应用可能会在创建之后开始向 AudioTrack 写入数据，因此它将开始播放，而不会等待开始 API 被调用。
  • AudioTrack 的 getTimeStamp API（这是在 KitKat 中引入的）向后移植到基于 Jelly-Bean 的 Amazon Fire TV（第 1 代）和 Fire TV Stick（第 1 代），并可用于 A/V 同步逻辑。

Amazon Fire TV（第 1 代）中的杜比支持

Fire TV（第 1 代）最初建立在基于 Jelly-Bean 的操作系统之上，并在 Android L 推出之前很早就已推出 - 后者在 Android TV 中正式推出对杜比音频直通的支持。

Android L 在平台中提供了一个推荐的杜比集成架构，遗憾的是，该架构与 Fire TV（第 1 代）上的杜比集成架构不完全匹配。本节介绍 Fire TV（第 1 代）中的杜比架构。

MediaCodec – Amazon Fire TV（第 1 代）

Fire TV（第 1 代）中提供的杜比 MIME 类型的默认 MediaCodec 为仅直通解码器。它将输入数据复制到输出数据，而不更改 MIME 类型。因此，输出格式具有与输入格式相同的 MIME 类型。

可用的解码器包括用于处理 DDP 位流的 OMX.qcom.audio.decoder.passthrougheac3，以及用于处理 DD 位流的 OMX.qcom.audio.decoder.passthroughac3。此外，这些解码器也会解密通过 DRM 方案加密的数据。因此，如果内容由 DRM 加密，应用必须使用此解码器。否则，此解码器的使用是可选的，杜比位流可以直接传递到 AudioTrack。

AudioTrack – Amazon Fire TV（第 1 代）

AudioTrack 在内部处理杜比直通、杜比解码和杜比转码。这意味着，根据所连接端点的杜比功能和系统杜比设置，AudioTrack 会选择处理传入杜比位流的适当模式。

端点功能 输入流类型 杜比设置 HDMI 输出 备注
DDP、DD 和 PCM DDP DDP over HDMI/Optical 或 DDP Auto DDP DDP 直通
DDP OFF PCM DDP 解码
DD DDP over HDMI/Optical、DD over HDMI 或 DDP Auto DD DD 直通
DD 和 PCM DDP DDP over HDMI/Optical、DD over HDMI 或 DDP Auto DD DDP > DD 转码
DDP OFF PCM DDP 解码
DD DDP over HDMI/Optical、DD over HDMI 或 DDP Auto DD DD 直通
DDP OFF PCM DD 解码
PCM DDP 或 DD 不适用 PCM DD 或 DDP 解码

AudioTrack 的杜比编码格式限制 – Amazon Fire TV（第 1 代）

杜比编码格式 ENCODING_E_AC3 和 ENCODING_AC3 的 AudioTrack 有以下限制和已知问题：

  • 没有实现 AudioTrack 的 getPlaybackHeadPosition API。因此，不要依赖它进行 A/V 同步。您的应用不得调用此 API。调用此 API 可能会导致崩溃。
  • AudioTrack 的开始/暂停 API 无效。您的应用可能会在创建之后开始将数据写入 AudioTrack，并开始播放。而不会等待开始 API 被调用。
  • AudioTrack 的 getTimeStamp API（这是在 KitKat 中引入的）向后移植到基于 Jelly-Bean 的 Fire TV（第 1 代）和 Fire TV Stick（第 1 代），并可通过反射用于 A/V 同步逻辑。

方法 2： 使用 ExoPlayer

ExoPlayer 是由 Google 提供支持的开源播放器，支持播放杜比音频流。但是，由于标准 Android L 设备和 Amazon Fire TV（第 1 代）系列设备之间的杜比支持架构差异（如前面部分所述），ExoPlayer 无法播放杜比音频内容。

亚马逊为 Exoplayer 开发了补丁，以便在 Fire TV（第 1 代）系列设备中播放杜比音频内容。这些补丁在此处开源提供：exoplayer-amazon-port。此端口还包括支持播放 PlayReady DRM 保护内容所需的其他补丁。（请注意，每个“amazon/rx.y.z”分支均映射到 ExoPlayer 版本 x.y.z。）

方法 3： 使用其他支持的媒体播放器

您可以使用 Amazon Fire TV 支持的其他媒体播放器（如 VisualOn 或 NexPlayer）播放杜比音频内容和 DRM 内容。请参阅媒体播放器了解更多详情。

方法 4： 使用安卓媒体播放器

您的应用可以使用安卓媒体播放器播放杜比内容。

处理非杜比端点和专属聆听模式

本节介绍连接到非杜比端点和专属聆听时，在 Amazon Fire TV 系列设备上播放杜比音频内容的建议和最佳实践。遵循这些准则将帮助您创建杜比音频内容播放的最佳用户体验。

如前所述，Android L 在AudioManager 中引入了一个名为 ACTION_HDMI_AUDIO_PLUG 意图的新 API。此意图允许应用检测连接终端（AVR 或 TV）的功能。此检测可用于支持在包括专属聆听在内的各种场景中播放杜比音频内容。

问：对于 Amazon Fire TV 和 Fire TV Stick（第 1 代），应用如何检测连接端点的功能？
应用必须注册一个广播接收器才能接收 ACTION_HDMI_AUDIO_PLUG 意图并读取意图中的 EXTRA_ENCODINGS 额外信息值。此编码值列表将指示端点功能。可能的值是 ENCODING_XXXX 值之一（例如 ENCODING_PCM_16BIT、ENCODING_AC3、ENCODING_E_AC3 等）。
问：对于 Fire TV Edition，应用如何检测连接端点的功能（如上面提到的 ACTION_HDMI_AUDIO_PLUG）？
默认情况下，Fire TV Edition 的扬声器仅支持立体声输出，因此应用默认可以流式播放立体声内容。但是，当电视通过光学音频输出或 HDMI 连接到条形音箱或 AVR（基于用户在 Fire TV Edition 上设置的杜比系统设置）时，应用可以选择以杜比音频格式流式播放环绕声。

为了支持这一点，应用需要读取全局设置 external_surround_sound_enabled，以确定是否支持环绕声（AC3 和 EAC3）。如果值为 1，则支持杜比音频。如果值为 0，则应用可以进一步使用其他方法（例如使用 ACTION_HDMI_AUDIO_PLUG 来确定是否支持环绕声）。请参考此 Exoplayer 补丁（添加了对光学输出的环绕声检测的支持）。

问：当连接的端点不支持 DD 或 DDP 时，应选择哪个音频流进行播放？
在这些情况下，让您的应用选择非杜比音频内容（例如，AAC）进行播放。与杜比音频内容相比，此选项的优势是减少带宽使用。

但是，如果应用无法选择其他非杜比音频内容，而是选择继续流式播放杜比（DD 或 DDP）音频，则它必须为每台设备执行以下操作。

  • Amazon Fire TV（第 1 代）： 将杜比原始位流发送到 AudioTrack，AudioTrack 会在内部解码并向下混音为立体声 PCM。
  • Fire TV Stick（第 1 代）和 Amazon Fire TV（第 2 代）： 使用杜比的 MediaCodec（OMX.dolby.ac3.decoder 或 OMX.dolby.eac3.decoder）。该 MediaCodec 解码杜比位流，向下混音为立体声 PCM，并使用 ENCODING_PCM_16BIT 音频格式配置 AudioTrack，以渲染 PCM 数据。由于所有平台中的杜比解码器都将多声道内容向下混音为立体声，因此在端点不支持 DD 或 DDP 时，选择杜比音频内容并无真正的优势。
问：当连接的端点支持 DD 但不支持 DDP 时，应选择哪个音频流进行播放？
答案取决于 Fire TV 设备：
  • Amazon Fire TV（第 1 代）和 Amazon Fire TV（第 2 代）： AudioTrack 支持将 DDP 位流转码为 DD。因此，即使端点仅支持 DD，AudioManager 也会将 DDP 作为支持的功能附加到 ACTION_HDMI_AUDIO_PLUG 意图中。因此，从应用的角度来看，支持 DD 的端点也支持 DDP（通过在 AudioTrack 中进行转码）。
  • Fire TV Stick（第 1 代）： 应用可以选择任何音频内容进行播放，因为 MediaCodec 会根据端点功能确定是进行直通、转码还是解码。在这种使用情形中，它会传递 DD 或将 DDP 转码为 DD 然后传递 DD。
问：当连接的端点支持 DDP 和 DD 时，应选择哪个音频流进行播放？
Amazon Fire TV（第 1 代）和 Amazon Fire TV（第 2 代）： 应用可以选择 DDP 或 DD 音频内容进行播放。如果音频未加密，应用可以将此明文 DD/DDP 位流数据按原样发送到 AudioTrack。在内部，AudioTrack 会将 DD/DDP 位流传递到连接的端点。

如果音频内容受 DRM 保护，应用必须实例化以下 MediaCodec 来解密位流：

  • 在 Amazon Fire TV（第 1 代）中为 OMX.qcom.audio.decoder.passthrougheac3 或 OMX.qcom.audio.decoder.passthroughac3。这个特殊的解码器是一个支持解密的无操作直通解码器（即，如果需要，它会在解密后将输入位流复制到输出中）。

  • 在 Amazon Fire TV（第 2 代）中为 OMX.google.raw.dec（按名称）。这个特殊的解码器是一个支持解密的无操作直通解码器（即，如果需要，它会在解密后将输入位流复制到输出中）。

Fire TV Stick（第 1 代）： 应用可以选择任何音频内容进行播放，因为 MediaCodec 会根据端点功能确定是进行直通、转码还是解码。在这个使用情形中，它会传递杜比音频内容。

问：在杜比直通播放期间，应用如何处理涉及音频耳机或蓝牙 A2DP 耳机的专属聆听使用情形？
Amazon Fire TV（第 1 代）： 应用不需要做任何特别的事情来处理专属聆听使用情形。这在 AudioTrack 内部自动处理（它从直通切换到解码操作模式）。

Fire TV Stick（第 1 代）和 Amazon Fire TV（第 2 代）： 在杜比直通播放期间，当音频耳机（通过游戏控制器）或蓝牙耳机连接到设备时，操作系统会通过修改后的额外信息值重新广播 ACTION_HDMI_AUDIO_PLUG 意图。

由于通过游戏控制器连接的音频耳机或蓝牙耳机不支持杜比直通，因此对额外信息值进行编码现在仅编码为 ENCODING_PCM_16BIT。应用必须注册才能在播放期间接收此意图，并重新配置音频管道以执行以下操作之一：

  • 切换到备用的非杜比音频内容位流（例如 AAC）
  • 如果备用音频内容不可用，请重新配置音频管道以使用 MediaCodec 杜比解码器将杜比内容解码为立体声 PCM。对于 Fire TV Stick（第 1 代），在重新创建音频管道的过程中需要重新创建 MediaCodec。