Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

实现电台功能

电台控制的实现基于 MediaSession 和 MediaBrowse，媒体和语音助理应用可以利用这两个方法实现对电台的控制。如需了解详情，请参阅 developer.android.com 上的构建车载媒体应用。

packages/apps/Car/libs 中的 car-broadcastradio-support 库中提供了一个媒体浏览树实现。此库中还包含 ProgramSelector 的扩展，用于实现与 URI 之间的来回转换。建议电台实现使用此库构建关联的浏览树。

媒体来源切换器

为在电台和媒体中显示的其他应用之间顺畅切换，car-media-common 库包含了应集成到电台应用中的类。MediaAppSelectorWidget 可添加到电台应用的 XML 中（参考媒体和电台应用中使用的图标或下拉列表）：

<com.android.car.media.common.MediaAppSelectorWidget
     android:id="@+id/app_switch_container"
     android:layout_width="@dimen/app_switch_widget_width"
     android:layout_height="wrap_content"
     android:background="@drawable/app_item_background"
     android:gravity="center" />

此微件会启动 AppSelectionFragment，以显示可切换到的媒体来源列表。除了提供的界面之外，如果还需要其他界面，则可以创建自定义微件，以在应显示切换器时启动 AppSelectionFragment。

AppSelectionFragment newFragment = AppSelectionFragment.create(widget,
            packageName, fullScreen);
    newFragment.show(mActivity.getSupportFragmentManager(), null);

在参考电台应用实现中提供了一个实现示例，它位于 packages/apps/Car/Radio 中。

详细控制规范

MediaSession（通过 MediaSession.Callback）接口提供了适用于当前正在播放的电台节目的控制机制：

onPlay、onStop。将电台播放（取消）静音。
onPause。时移暂停（如果支持）。
onPlayFromMediaId。播放顶层文件夹中的任何内容。例如“播放 FM”或“播放电台”。
onPlayFromUri。播放特定频率。例如，“播放 88.5 FM”。
onSkipToNext、onSkipToPrevious。调到下一个或上一个电台。
onSetRating。向收藏夹中添加或从收藏夹中移除。

MediaBrowser 在三种类型的顶层目录上提供可收听的 MediaItem：

（可选）节目（电台）。这种模式通常供双调谐器电台使用，以指示用户位置的所有可用的可收听电台。
收藏夹。添加到“收藏夹”列表的电台节目，有些节目可能无法收到（超出接收范围）。
频段频道。当前区域中所有可实际收到的频道（例如 87.9、88.1、88.3、88.5、88.7、88.9、89.1 等）。每个频段都有一个单独的顶层目录。

其中每个文件夹 (AM/FM/Programs) 中的每个元素都是一个具有 URI 的 MediaItem，该 URI 可与 MediaSession 配合调谐。每个顶层文件夹 (AM/FM/Programs) 都是具有 mediaId 的 MediaItem，mediaId 可与 MediaSession 配合使用以触发播放，且 mediaId 由原始设备制造商 (OEM) 自行决定。例如，“播放 FM”、“播放 AM”和“播放电台”都是使用 mediaId 发送到 OEM 电台应用的非具体电台查询。由电台应用决定根据通用请求和 mediaId 播放的内容。

MediaSession

由于实时广播是无法暂停的，因此播放、暂停和停止操作并不总是适用于电台。对电台而言，“停止”操作与关闭在线播放的声音有关，而“播放”操作则与取消静音有关。

某些电台调谐器（或应用）支持通过缓存内容并在稍后播放来模拟实时广播暂停。在这种情况下，请使用 onPause。

根据 mediaId 和 URI 进行播放的操作用于调到从 MediaBrowser 接口中提取的电台。mediaId 是电台应用提供的任意字符串，用于指定唯一（一个指定 ID 仅指向一项内容）且稳定的（一项指定内容在整个会话中将具有相同的 ID）值来标识给定的电台。URI 将是具有明确定义的架构。简言之，就是 ProgramSelector 的 URI 化形式。虽然这可以使 URI 保持唯一性，但它无需保持稳定性。当电台调到其他频率时，URI 可以改变。

根据设计，不使用 onPlayFromSearch。客户端（配套应用）将负责从 MediaBrowser 树中选择搜索结果。将这项责任转移到电台应用会增加复杂性，需要就字符串查询的显示方式达成正式协定，并且会导致不同硬件平台上的用户体验不一致。

注意：电台应用不包含有助于搜索未通过 MediaBrowser 接口向客户端提供的电台名称的额外信息。

转到下一个或上一个电台时，具体会转到哪个电台取决于当前上下文：

如果应用调到“收藏夹”列表中的某个电台，则应用可以调到“收藏夹”列表中的下一个电台。
如果收听的是节目列表中的电台，可能会调到下一个可播放的电台（根据频道编号排序）。
如果收听的是任意频道，则即使没有广播信号，也可能会调到下一个实际频道。

电台应用会处理这些操作。

错误处理

TransportControls 操作（播放、停止和下一个）不会提供有关操作是否成功的反馈。要指示错误，唯一的方法就是将 MediaSession 状态设置为 STATE_ERROR，并提供错误消息。

电台应用必须处理这些操作，然后予以执行或设置错误状态。如果“播放”命令不会立即执行，那么在执行该命令时，播放状态应变为 STATE_CONNECTING（如果是直接调谐）或 STATE_SKIPPING_TO_PREVIOUS/NEXT。

客户端应监视 PlaybackState，并确认会话是已将当前节目更改为所请求的节目，还是已进入错误状态。STATE_CONNECTING 不能超过 30 秒。但是，直接调谐到指定 AM/FM 频率的执行速度应该会快得多。

添加和移除收藏夹

MediaSession 支持评分功能，可用于控制收藏夹。使用 RATING_HEART 类型的评分调用 onSetRating 时，会在“收藏夹”列表中添加或移除当前调到的电台。

与传统预设相反，如果将每个保存的收藏电台分配给一个数字槽位（通常为 1 到 6），此模型会假设“收藏夹”列表是无序且无界的。因此，基于预设的系统与 onSetRating 操作不兼容。

MediaSession API 的局限性在于只能添加或移除当前调到的电台。例如，要移除项目，就必须先选择项目。该限制仅适用于 MediaBrowser 客户端（例如配套应用）。电台应用没有类似的限制。当应用不支持“收藏夹”时，此部分为可选内容。

MediaBrowser

为了说明在给定的区域中哪些频率或实际频道名称（如果给定的电台技术支持调到任意频道）有效，我们列出了每个频段的所有有效频道（频率）。在美国地区，在 87.8 MHz 至 108.0 MHz 的频率范围内（间隔为 0.2MHz），有 101 个 FM 频道；在 530 kHz 至 1700 kHz 的频率范围内（间隔为 10kHz），有 117 个 AM 频道。HD 电台使用相同的频道空间，因此没有单独列出。

当前可供播放的电台节目列表是一种简单列表，它不支持按数字音频广播 (DAB) 集合进行分组等显示方案。

“收藏夹”列表中的条目可能无法正常播放。例如，当指定节目超出频率范围时。电台应用不一定会事先检测条目是否可以播放。在这种情况下，电台应用可能不会将条目标记为可播放。

为了标识顶层文件夹，将应用蓝牙所使用的相同机制。也就是说，MediaDescription 对象的 Extra 捆绑包包含一个调谐器专属字段，其等效于蓝牙的 EXTRA_BT_FOLDER_TYPE。如果是广播电台，则需要在公共 API 中定义以下新字段：

EXTRA_BCRADIO_FOLDER_TYPE = "android.media.extra.EXTRA_BCRADIO_FOLDER_TYPE"。以下值之一：

BCRADIO_FOLDER_TYPE_PROGRAMS = 1。当前可供播放的节目。
BCRADIO_FOLDER_TYPE_FAVORITES = 2。收藏夹。
BCRADIO_FOLDER_TYPE_BAND = 3。给定频段的所有实际频道。

您无需定义任何特定于电台的自定义元数据字段，因为所有相关数据都适合现有的 MediaBrowser.MediaItem 架构：

节目名称（RDS PS、DAB 服务名称）。MediaDescription.getTitle。
FM 频率。URI（请参阅 ProgramSelector）或 MediaDescription.getTitle（如果条目位于 BROADCASTRADIO_FOLDER_TYPE_BAND 文件夹中）。
电台专属标识符（RDS PI、DAB SId）。MediaDescription.getMediaUri 解析为 ProgramSelector。

通常，无需为当前节目或“收藏夹”列表中的条目提取 FM 频率（因为客户端应根据媒体 ID 进行操作）。但是，如果确实出现了这种需求（例如，出于显示目的），可在 URI 中找到，并可解析为 ProgramSelector。也就是说，建议不要使用 URI 来选择当前会话中的内容。有关详情，请参阅 ProgramSelector。

为避免发生性能或 binder 相关的问题，MediaBrowser 服务必须支持分页：

EXTRA_PAGE
EXTRA_PAGE_SIZE
subscribe() 的额外参数

注意：默认情况下，分页在 onLoadChildren() 变体中默认实现，无需进行选项处理。

所有类型列表（原始频道、找到的节目以及收藏夹）中的相关条目可能具有不同的 mediaId（这取决于电台应用；支持库会有不同的 mediaId）。在大多数情况下，原始频道的 URI 与找到的节目的 URI（采用 ProgramSelector 形式）是不同的（但没有 RDS 的 FM 除外）；但找到的节目与收藏夹之间的 URI 基本相同（AF 已更新等情况除外）。

通过对来自不同类型列表的条目使用不同的 mediaId，可以对它们执行不同的操作。您可以在 onSkipToNext 上遍历“收藏夹”列表或“所有节目”列表，具体取决于最近选择的 MediaItem 文件夹（请参阅 MediaSession）。

特殊调谐操作

通过节目列表，用户可以调到特定的电台，但无法提出一般的要求，例如“调到 FM”，这可能会导致调到 FM 频段上最近收听的电台。

为了支持这样的操作，一些顶层目录设置了 FLAG_PLAYABLE 标志（并针对文件夹设置了 FLAG_BROWSABLE）。

操作	调谐目标	如何发出
播放电台	任意电台频道	`startService(ACTION_PLAY_BROADCASTRADIO)` 或 `playFromMediaId(MediaBrowser.getRoot())`
播放 FM	任意 FM 频道	根据 FM 频段的 mediaId 播放

具体调到哪个节目取决于应用。这通常是给定列表中最近调到的频道。如需详细了解 ACTION_PLAY_BROADCASTRADIO，请参阅常规播放 intent。

发现和服务连接

PackageManager 可以直接找到提供广播电台树的 MediaBrowserService。为此，请使用 ACTION_PLAY_BROADCASTRADIO intent（请参阅常规播放 intent）和 MATCH_SYSTEM_ONLY 标志调用 resolveService。如需查找所有提供电台的服务（可能有多个，例如单独的 AM/FM 和卫星），请使用 queryIntentServices。

已解析的服务也将处理 android.media.browse.MediaBrowserService 绑定 intent。此操作已通过 GTS 验证。

如需连接到选定的 MediaBrowserService，请为给定服务组件创建 MediaBrowser 实例并执行 connect 操作。建立连接后，可以通过 getSessionToken 获取 MediaSession 的句柄。

电台应用可以限制允许在其服务的 onGetRoot 实现中连接的客户端软件包。该应用应允许系统应用在没有加入白名单的情况下连接。如需了解有关加入白名单的详细信息，请参阅接受 Google 助理应用软件包和签名。

如果特定于来源的应用（例如，电台应用）安装在不支持此类来源的设备上，则它仍然会在自己处理 ACTION_PLAY_BROADCASTRADIO intent 时发出通告，但其 MediaBrowser 树不会包含特定于电台的标记。因此，如果客户端想要检查给定来源在设备上是否可用，其必须：

发现电台服务（为 ACTION_PLAY_BROADCASTRADIO 调用 resolveService）。
为该服务创建 MediaBrowser，然后连接到该 MediaBrowser。
使用 EXTRA_BCRADIO_FOLDER_TYPE extra 确定 MediaItem 是否存在。

注意：在大多数情况下，客户端必须扫描所有可用的 MediaBrowser 树，以检测可在给定设备上使用的所有来源。

频段名称

频段列表由一组顶层目录表示，文件夹类型标记设置为 BCRADIO_FOLDER_TYPE_BAND。其 MediaItem 的标题是表示频段名称的本地化字符串。在大多数情况下，这与英语译文相同，但客户端不能依赖该假设。

为提供查找特定频段的可靠机制，为频段文件夹添加了一个 extra 标记：EXTRA_BCRADIO_BAND_NAME_EN。该标记是频段的非本地化名称，只能接受以下某个预定义值：

AM
FM
DAB
SXM

如果频段不在此列表中，则不应设置相应的频段名称标记。而如果频段在列表中，则必须设置标记。HD 电台不会列出单独的频段，因为它使用与 AM/FM 相同的底层媒体。

常规播放 intent

每个专用于播放给定来源（例如电台或 CD）的应用都必须处理一个常规播放 intent，才能开始播放一些可能来自非活动状态的内容（例如，启动后）。如何选择要播放的内容由应用决定，但通常会选择最近播放过的电台节目或 CD 曲目。
每个音频来源都定义了一个单独的 intent：

android.car.intent.action.PLAY_BROADCASTRADIO
android.car.intent.action.PLAY_AUDIOCD：CD-DA 或 CD-Text
android.car.intent.action.PLAY_DATADISC：诸如 CD/DVD 之类的光盘，但不是 CD-DA（可能是混合模式 CD）
android.car.intent.action.PLAY_AUX：不指定 AUX 端口
android.car.intent.action.PLAY_BLUETOOTH
android.car.intent.action.PLAY_USB：不指定 USB 设备
android.car.intent.action.PLAY_LOCAL：本地媒体存储（内置闪存）

之所以选择将 intent 用于常规播放命令，是因为它们同时解决了两个问题：常规播放命令本身和服务发现。使用此类 intent 的另一个好处是，可以在不开启 MediaBrowser 会话的情况下执行此类简单操作。

在使用这些 intent 解决的问题中，服务发现实际更为重要。通过这种方式，服务发现的过程简单而明确（请参阅发现和服务连接）。

为了简化某些客户端实现，可以采用另一种方式来发出此类“播放”命令（也必须由电台应用实现）：使用根节点的 rootId（用作 mediaId）发出 playFromMediaId。虽然根节点是不可播放的，但它的 rootId 是一个任意字符串，可作为 mediaId 使用。但是，客户端不需要了解这种细微差别。

ProgramSelector

虽然使用 mediaId 足以从 MediaBrowserService 中选择频道，但它会绑定到一个会话，并且在各 provider 之间不一致。在某些情况下，客户端可能需要一个绝对指针（如绝对频率）以在会话和设备之间保持 mediaId 不变。

在数字电台广播时代，单靠频率不足以调到特定电台。因此，请使用 ProgramSelector 调到模拟频道或数字频道。ProgramSelector 由两部分组成：

主要标识符。给定电台的唯一且稳定的标识符，它不会改变，但可能不足以调到该电台。例如，RDS PI 代码，在美国可以转换为呼号。
辅助标识符。用于调到该电台的其他标识符（例如频率），可能包括来自其他电台技术的标识符。例如，DAB 电台可能具有模拟广播回退。

如需使 ProgramSelector 适合于基于 MediaBrowser/MediaSession 的解决方案，请定义一个 URI 架构来对其进行序列化。架构定义如下：

broadcastradio://program/<primary ID type>/<primary ID>?
<secondary ID type>=<secondary ID>&<secondary ID type>=<secondary ID>

在此示例中，辅助标识符部分（位于问号 (?) 之后）是可选的，可以将其移除以提供稳定的标识符作为 mediaId 使用。例如：

broadcastradio://program/RDS_PI/1234? AMFM_FREQUENCY=88500&AMFM_FREQUENCY=103300
broadcastradio://program/AMFM_FREQUENCY/102100
broadcastradio://program/DAB_SID_EXT/14895264?RDS_PI=1234

program 的 authority 部分（也就是 host）为将来扩展该架构提供了一些空间。标识符类型字符串在 IdentifierType 的 HAL 2.x 定义中被精确指定为其名称，值的格式为十进制或十六进制（带有 0x 前缀）数字。

所有供应商专用标识符均由 VENDOR_ 前缀表示。例如，VENDOR_0 对应 VENDOR_START，VENDOR_1 对应 VENDOR_START + 1。此类 URI 只能在生成它们的电台硬件上使用，不能在其他 OEM 制造的设备之间转移。

必须将这些 URI 分配给顶层电台文件夹下的每个 MediaItem。此外，MediaSession 必须同时支持 playFromMediaId 和 playFromUri。但是，URI 主要用于电台元数据提取（例如 FM 频率）和永久性存储。不能保证 URI 可用于所有媒体内容（例如，当框架尚不支持主要 ID 类型时）。另一方面，媒体 ID 始终有效。不建议客户端使用 URI 从当前 MediaBrowser 会话中选择项目。相反，应使用 playFromMediaId。也就是说，它对于提供应用来说不是可选的，并且在合理情况下会保留缺失的 URI。

初始设计使用了一个冒号来代替 :// 序列，放在架构部分后面。但是，为实现绝对分层 URI 引用，android.net.Uri 不支持前者。

其他来源类型

其他音频来源也可以通过类似方式处理。例如，辅助输入和音频 CD 播放器。

单个应用可以提供多种类型的来源。在这类情况下，建议为每种来源创建一个 MediaBrowserService。即使在具有多个提供的来源/MediaBrowserService 的设置中，也强烈建议在一个应用中使用一个 MediaSession。

音频 CD

与音频 CD 类似，提供此类磁盘的应用将提供具有一个（或多个，如果系统有 CD 换碟机）可浏览条目的 MediaBrowser，该 MediaBrowser 将包含给定 CD 的所有曲目。如果系统未读取到每张 CD 上的曲目（例如，一次性将所有磁盘插入磁盘盒，而系统未读取到所有磁盘的内容），则整个磁盘的 MediaItem 将为 PLAYABLE，而不是 BROWSABLE+PLAYABLE。如果指定槽位中没有磁盘，则相关内容既非 PLAYABLE，也非 BROWSABLE（但每个槽位必须始终存在于树中。）

这些条目将以类似于广播电台文件夹的方式进行标记，它们将包含 MediaDescription API 中定义的其他 extra 字段：

EXTRA_CD_TRACK：对于音频 CD 上的每个 MediaItem，从 1 开始的曲目编号。
EXTRA_CD_DISK：从 1 开始的磁盘编号。

对于启用 CD-Text 的系统和兼容磁盘，顶层 MediaItem 将具有磁盘的标题。类似地，曲目的 MediaItem 将具有曲目的标题。

辅助输入

提供辅助输入的应用将提供一个 MediaBrowser 树，其中包含单个（或多个，如果存在多个端口）表示端口中的 AUX 的条目。相应的 MediaSession 会接受其 mediaId，并在收到 playFromMediaId 请求后切换到该来源。

每个 AUX MediaItem 条目都有一个 extra 字段 EXTRA_AUX_PORT_NAME，设置为端口的非本地化名称（不包含“AUX”字样）。例如，“AUX 1”会设置为“1”，“AUX front”会设置为“front”，“AUX”会设置为空字符串。在非英语语言区域，名称标记将保留为英文字符串。与 EXTRA_BCRADIO_BAND_NAME_EN 不同，这些值由 OEM 定义，不受预定义列表的约束。

如果硬件可以检测到连接到 AUX 端口的设备，则硬件仅在已连接输入的情况下才应将 MediaItem 标记为 PLAYABLE。如果没有任何输入连接到此端口，则仍应列出硬件（但不为 PLAYABLE）。如果硬件没有此类功能，则 MediaItem 必须始终设置为 PLAYABLE。

extra 字段

因此，必须定义以下 extra 键：

EXTRA_CD_TRACK = "android.media.extra.CD_TRACK"
EXTRA_CD_DISK = "android.media.extra.CD_DISK"
EXTRA_AUX_PORT_NAME = "android.media.extra.AUX_PORT_NAME"

客户端需要检查顶层 MediaItem，以获取设置了 EXTRA_CD_DISK 或 EXTRA_AUX_PORT_NAME extra 字段的元素。

详细示例

以下示例说明了此设计中包含的来源类型的 MediaBrowser 树结构。

广播电台 MediaBrowserService（处理 ACTION_PLAY_BROADCASTRADIO）：

电台（可浏览）
EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_PROGRAMS
- BBC One（可播放）
  URI：broadcastradio://program/RDS_PI/1234?AMFM_FREQUENCY=90500
- ABC 88.1（可播放）
  URI：broadcastradio://program/RDS_PI/5678?AMFM_FREQUENCY=88100
- ABC 88.1 HD1（可播放）
  URI：broadcastradio://program/HD_STATION_ID_EXT/158241DEADBEEF?AMFM_FREQUENCY=88100&RDS_PI=5678
- ABC 88.1 HD2（可播放）
  URI：broadcastradio://program/HD_STATION_ID_EXT/158242DEADBEFE
- 90.5 FM（可播放） - 没有 RDS 的 FM
  URI：broadcastradio://program/AMFM_FREQUENCY/90500
- 620 AM（可播放）
  URI：broadcastradio://program/AMFM_FREQUENCY/620
- BBC One（可播放）
  URI：broadcastradio://program/DAB_SID_EXT/1E24102?RDS_PI=1234
收藏夹（可浏览、可播放）
EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_FAVORITES
- BBC One（可播放）
  URI：broadcastradio://program/RDS_PI/1234?AMFM_FREQUENCY=101300
- BBC Two（不可播放）
  URI：broadcastradio://program/RDS_PI/1300?AMFM_FREQUENCY=102100
AM（可浏览、可播放）
EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_BAND EXTRA_BCRADIO_BAND_NAME_EN="AM"
- 530 AM（可播放）
  URI：broadcastradio://program/AMFM_FREQUENCY/530
- 540 AM（可播放）
  URI：broadcastradio://program/AMFM_FREQUENCY/540
- 550 AM（可播放）
  URI：broadcastradio://program/AMFM_FREQUENCY/550
FM（可浏览、可播放）
EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_BAND EXTRA_BCRADIO_BAND_NAME_EN="FM"
- 87.7 FM（可播放）
  URI：broadcastradio://program/AMFM_FREQUENCY/87700
- 87.9 FM（可播放）
  URI：broadcastradio://program/AMFM_FREQUENCY/87900
- 88.1 FM（可播放）
  URI：broadcastradio://program/AMFM_FREQUENCY/88100
DAB（可播放）
EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_BAND EXTRA_BCRADIO_BAND_NAME_EN="DAB"

音频 CD MediaBrowserService（处理 ACTION_PLAY_AUDIOCD）：

磁盘 1（可播放）
EXTRA_CD_DISK=1
磁盘 2（可浏览、可播放）
EXTRA_CD_DISK=2
- 曲目 1（可播放）
  EXTRA_CD_TRACK=1
- 曲目 2（可播放）
  EXTRA_CD_TRACK=2
我的音乐 CD（可浏览、可播放）
EXTRA_CD_DISK=3
- All By Myself（可播放）
  EXTRA_CD_TRACK=1
- Reise, Reise（可播放）
  EXTRA_CD_TRACK=2
空槽位 4（不可播放）
EXTRA_CD_DISK=4

AUX MediaBrowserService（处理 ACTION_PLAY_AUX）：

前置 AUX（可播放）
EXTRA_AUX_PORT_NAME="front"
后置 AUX（可播放）
EXTRA_AUX_PORT_NAME="rear"