通过 MediaSession API 对传输控制启用语音功能


通过 MediaSession API 对传输控制启用语音功能

Amazon Fire TV 上的某些应用支持通过语音控制播放。例如,当客户在 Amazon Video 上观看电影时,他们可以说“Alexa,播放”来启动媒体,说“Alexa,暂停”来暂停媒体,或者说“Alexa,快进”在媒体的时间轴中向前跳转。通过集成安卓媒体会话 API,您可以使用这些语音命令以及更多命令来支持操作您的应用。

视频教程

以下视频提供了在 Fire TV 上集成媒体会话 API 的概述和教程:

该视频包括媒体会话 API 实际应用的演示(用户对 Fire TV 说出传输控制表述,如“快进”和“倒回”),以及从头开始集成媒体会话 API 的详细代码示例。您也可以在这里查看视频幻灯片。代码示例和步骤更加符合本附带博客文章中介绍的从开始到结束的代码详细信息。

以下部分中的介绍更加精简,并假定您已经在应用中实现了媒体会话 API。如果您尚未实现媒体会话,请参阅视频和博客文章中更详尽的代码示例。

支持语音的媒体播放要求

要将安卓媒体会话集成到应用中并启用语音命令,您必须拥有支持 API 级别 21 或更高版本的 Fire TV 或 Fire 平板电脑的媒体应用。

请注意,此处的文档提供了基于 Java 的安卓应用,而不是 Web 应用的说明。您可以将媒体会话 API 与 Web 应用集成(通过诸如 Cordova 之类的安卓包装器),但此操作的说明不在本文档的讨论范围之内。

此外,本文档假定您是编写代码的安卓开发者。如果您需要一种更简单的方法在应用中通过语音控制媒体播放,则可以探索 Fire App Builder默认情况下它包括媒体会话集成)。(Fire App Builder 是构建在线直播媒体应用的框架。)

关于安卓媒体会话

安卓提供了一个称为媒体会话的 API,允许应用接收媒体命令。Fire TV 上的 Alexa 使用媒体会话 API 向本地媒体应用发送命令。来自遥控器、键盘、耳机、adb 等的事件也会通过媒体会话 API 发送到应用(如果应用实现了这些 API)。

将媒体会话集成到您的 Fire TV 应用中为您的应用提供了许多优势:

  • 媒体会话为您的媒体提供强大的支持语音的播放控制。
  • 媒体会话允许开发者在一个应用中对 Fire OS 5 和 Fire OS 6 处理来自遥控器、键盘、耳机、adb 等的事件。(其他 API 对于 Fire OS 5 和 Fire OS 6 需要不同的实现方式。)
  • 如果您将媒体会话集成到 Fire TV 应用中并添加适当的权限,则您的应用序将会支持语音命令。您的应用将支持近场语音命令(通过遥控器上的麦克风说话)和远场语音命令(对着支持 Alexa 的设备(如与 Fire TV 配对的 Echo)说话)。
  • 媒体会话是所有 Fire OS 设备上支持语音的播放控件(播放、暂停、快进、倒回、上一个、下一个、重新开始)的推荐实现。(Fire OS 用于 Fire TV 和 Fire 平板电脑)

有关媒体会话的更多背景,请参阅安卓文档中的以下主题:

支持的语音命令

Fire TV 设备上的媒体会话支持以下语音命令。

命令类型 示例语音命令 描述
播放 “Alexa,播放”

“Alexa,继续”
播放/恢复媒体。
暂停 “Alexa,暂停”

“Alexa,停止”
暂停媒体。
快进 “Alexa,快进 30 秒”

“Alexa,快进”
按给定时间段快进媒体。如果未提供时间段,则默认为 10 秒。
倒回 “Alexa,倒回 30 秒”

“Alexa,倒回”
按给定时间段倒回媒体。如果未提供时间段,则默认为 10 秒。
下一个 “Alexa,下一个” 触发下一个命令并播放播放列表中的下一个媒体。
上一个 “Alexa,上一个” 触发上一个命令并播放播放列表中的上一个媒体。
重新开始 “Alexa,重新开始” 回到媒体的开头。

媒体会话集成与 Video Skill API

通过 Video Skill API 集成,可以与您的应用进行更深入的语音集成。Video Skill API 不仅提供媒体播放的传输控制(播放、暂停、快进等),还允许用户在 Fire TV 中的任何位置(而不仅仅是在您的应用中)对应用的媒体执行语音搜索。Video Skill API 集成要求您的媒体位于 Amazon Catalog 中。您可以在对您的应用和内容启用语音功能中了解更多信息。

稍后转换到 Video Skill API 不需要您删除此处执行的媒体会话集成步骤。当媒体会话和 Video Skill API 集成到同一应用中时,Fire TV 会将媒体会话代码用于传输控制命令,并使用 Video Skill API 命令进行内容搜索和频道更改。

如果您的应用需要支持媒体会话未涵盖的其他播放控制使用情形,则您可以通过 PlaybackControllerSeekController 指令将 Video Skill API 用于播放控制。在这种情况下,播放控件将绕过媒体会话代码。(有关将 Video Skill API 与 Fire TV 集成的文档即将提供。)

与媒体会话集成,实现支持语音的媒体播放

有关如何使用媒体会话构建视频应用音频应用的信息,必须主要参考安卓媒体会话文档

以下详细信息重点介绍了 Fire TV 应用中支持语音的媒体播放功能的媒体会话集成的重要方面。

添加媒体会话权限

要启用语音命令和控制以便与您的应用一起使用,请将权限 com.amazon.permission.media.session.voicecommandcontrol 添加到您的应用清单中:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"android:versionCode="2147483647"android:versionName="1.0" >

.....
<uses-permission android:name="com.amazon.permission.media.session.voicecommandcontrol" />
......

设置播放功能

为了让 Alexa 知道应用的媒体会话支持哪些内容,必须通过媒体会话提供一组操作。标准受支持操作列在安卓的 PlaybackState 文档下。

Alexa 支持的语音控制操作如下所示。

操作 描述
ACTION_PLAY_PAUSE 包括 ACTION_PLAY 和 ACTION_PAUSE 操作。请参阅下面的描述。提示: 为简单起见,请考虑使用此单个命令,而不是单独的 ACTION_PLAYACTION_PAUSE 命令。(但这不是必需的,这两种方法都可行。)
ACTION_PLAY 恢复播放
ACTION_PAUSE 暂停播放
ACTION_SEEK_TO 跳转到播放中的特定时间。如果时间为负,则默认时间为 0。
ACTION_SKIP_TO_NEXT 跳到下一个“剧集”或“曲目”
ACTION_SKIP_TO_PREVIOUS 跳到上一个“剧集”或“曲目”

如果没有提供操作,并且用户触发了不受支持的命令(例如“跳转到最后一集”),Alexa 会以类似“抱歉,不支持该命令”的内容进行响应。

设置媒体会话回调操作

当语音命令启动以下操作之一时,将触发以下媒体会话回调命令。

请注意,这些是 Alexa 语音命令使用的回调,但强烈建议为所有其他适用的用例实施额外回调(倒回、快进等)。

操作 MediaSession.Callback Signature 描述 支持的语音命令
播放 onPlay() 恢复播放。 “Alexa,播放”

“Alexa,继续”
暂停 onPause() 暂停播放。 “Alexa,暂停”

“Alexa,停止”
跳至下一个 onSkipToNext() 跳到下一个媒体单元。这可能是电视剧集或歌曲。 “Alexa,下一个”
跳至上一个 onSkipToPrevious() 跳到上一个媒体单元。 “Alexa,上一个”
移至 onSeekTo(long pos) 移至给定时间(以毫秒为单位)。如果用户说出相对时间,则计算要搜索的时间并传回此回调。请注意,不支持绝对时间。(例如,“Alexa,快进到 2 小时 15 分钟”不会将当前播放位置设置为 2 小时 15 分钟。)

对于重新开始事件,将在回调中传递时间 0。
“Alexa,倒回 5 分钟”

“Alexa,快进 5 分钟”

“Alexa,快进”(默认为 10 秒)

“Alexa,倒回”(默认为 10 秒)

“Alexa,重新开始”

使用媒体会话实现支持语音的播放控制的增强体验(可选)

安卓媒体会话文档建议应用仅在具有音频焦点时遵守媒体会话命令。这意味着,如果媒体正在播放并且用户说“Alexa,暂停”,在语音镶边关闭后,媒体会恢复一秒钟,然后再获取媒体会话暂停命令,随后暂停。这会导致当播放状态通过语音发生更改时出现一个斑点(在本例中为瞬间播放体验)。

Fire TV 媒体会话语音命令实现允许您选择加入并匹配不显示斑点的内部 Fire TV 应用的体验。以下详细信息提供了有关如何实现这一目标的信息。

添加选择加入权限

要选择加入 Fire TV 媒体会话语音命令实现,请将权限 com.amazon.voice.supports_background_media_session 添加到您的应用清单中。

<manifest>
    ...
    <application>
        ...
        <meta-data android:name="com.amazon.voice.supports_background_media_session" android:value="true" />
        ...
    </application>
    ...
</manifest>

在获得音频焦点之前更新应用以遵守媒体会话命令

在您选择使用 Fire TV 媒体会话语音命令实施后,媒体会话命令将在语音镶边(当您说出“Alexa”时显示在屏幕顶部的蓝线)失去音频焦点之前发送到您的应用。应用将需要处理接收到的媒体会话命令,然后才能获得音频焦点。

例如,如果在调用语音镶边之前应用处于“正在播放媒体”内部状态,并且您说“Alexa,暂停”,则暂停命令将发送到应用,应用需要将内部状态更改为“已暂停”。 应用重新获得音频焦点后,会查询内部状态,因为它已暂停,不应恢复媒体。