电台控制实现

电台控制的实现基于 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" />

此 widget 会启动 AppSelectionFragment，以显示可切换到的媒体来源列表。除了提供的界面之外，如果还需要其他界面，则可以创建自定义 widget，以在应显示切换器时启动 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 等）。每个频段都有一个单独的顶层目录。
MediaBrowserService 树结构
图 2. MediaBrowserService 树结构

其中每个文件夹 (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 - 108.0 MHz 的频率范围内（间隔为 0.2 MHz），有 101 个 FM 频道；在 530 - 1700 kHz 的频率范围内（间隔为 10 kHz），有 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 服务必须支持分页：

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

    所有类型列表（原始频道、找到的节目以及收藏夹）中的相关条目可能具有不同的 mediaId（这取决于电台应用；支持库会有不同的 mediaId）。在大多数情况下，原始频道与找到的节目的 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 树不会包含针对特定电台的标记。因此，如果客户端想要检查给定来源在设备上是否可用，其必须：

    1. 发现电台服务（为 ACTION_PLAY_BROADCASTRADIO 调用 resolveService）。
    2. 创建 MediaBrowser，然后与其连接。
    3. 通过 EXTRA_BCRADIO_FOLDER_TYPE extra 确定是否存在 MediaItem。

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

    频段名称

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

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

    • AM
    • FM
    • DAB

    如果频段不在此列表中，则不应设置相应的频段名称标记。 但是，如果频段在列表中，则必须设置标记。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 中选择频道，但它会绑定到一个会话，并且不能在各提供程序之间保持一致。在某些情况下，客户端可能需要一个绝对指针（如绝对频率），以便在会话和设备之间保持 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（但每个槽位必须始终存在于树中。）

    音频 CD 树结构
    图 3. 音频 CD 树结构。

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

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

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

    辅助输入

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

    AUX 树结构
    图 4. AUX 树结构。

    每个 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_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_BANDEXTRA_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_BANDEXTRA_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_BANDEXTRA_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 front（可播放）EXTRA_AUX_PORT_NAME="front"
    • AUX rear（可播放）EXTRA_AUX_PORT_NAME="rear"