通过Media Session API在Fire TV上对传输控制启用语音功能

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

视频教程
语音控制进行媒体播放的要求
关于Android媒体会话
支持的语音命令
媒体会话集成与Video Skill API
与媒体会话集成，实现支持语音的媒体播放
使用媒体会话实现支持语音的播放控制的增强体验（可选）
- 添加选择加入权限
- 在获得音频焦点之前更新应用以遵守媒体会话命令

视频教程

以下视频提供了在Fire TV上集成媒体会话API的概述和教程(附带中文字幕)。

该视频包括媒体会话API实际应用的演示（用户对Fire TV说出传输控制表述，如“快进”和“倒回”），以及从头开始集成媒体会话API的详细代码示例。还可以在这里查看视频幻灯片。

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

语音控制进行媒体播放的要求

要在应用中集成Android媒体会话并启用语音命令，则必须拥有支持API级别21或更高版本的Fire TV或Fire平板电脑的媒体应用。

请注意，此处的文档提供的说明针对基于Java的Android应用而不是网页应用。可以在网页应用中集成媒体会话API（通过Android包装器，比如Cordova），但此操作的说明不在本文档讨论范围之内。

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

关于Android媒体会话

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

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

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

有关媒体会话的更多背景，请参阅Android文档中的以下主题：

注意： 媒体会话在提供输入播放方面具有更广泛的功能，例如处理遥控器上的按钮按下事件。本文并非旨在解释一般的媒体会话，而是展示如何将Alexa的输入转换为媒体会话Android API。无论是否要为媒体播放控制项启用语音功能，在应用中集成媒体会话都是最佳实践。

支持的语音命令

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

命令类型	示例语音命令	描述
播放	“Alexa，播放” “Alexa，继续”	播放/恢复媒体。
暂停	“Alexa，暂停” “Alexa，停止”	暂停媒体。
快进	“Alexa，快进30秒” “Alexa，快进”	按给定时间段快进媒体。如果未提供时间段，则默认为10秒。
倒回	“Alexa，倒回30秒” “Alexa，倒回”	按给定时间段倒回媒体。如果未提供时间段，则默认为10秒。
下一个	“Alexa，下一个”	触发下一个命令并播放播放列表中的下一个媒体。
上一个	“Alexa，上一个”	触发上一个命令并播放播放列表中的上一个媒体。
重新开始	“Alexa，重新开始”	回到媒体的开头。

媒体会话集成与Video Skill API

通过视频技能工具包，可以与您的应用进行更深入的语音集成。Video Skill API不仅为媒体播放提供传输控制（播放、暂停、快进等），还允许用户在Fire TV中的任何位置（而不仅仅是在您的应用中）对应用的媒体执行语音搜索。视频技能工具包集成要求在HAQM Catalog中包含您的媒体。您可以在Fire TV应用概述的视频技能工具包(VSK)中了解更多信息。

注意： 如果计划稍后集成Video Skill API，现在仍然可以进行媒体会话集成。实现应用及其媒体更彻底的语音集成时，媒体会话集成可以被视为第一步。

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

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

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

有关如何使用媒体会话构建视频应用和音频应用的信息，必须主要参考Android媒体会话文档。

以下详细信息重点介绍了媒体会话集成的重要方面，这些方面可在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知道应用的媒体会话支持哪些内容，必须通过媒体会话提供一组操作。支持的标准操作在Android的PlaybackState文档中列出。

下面列出了Alexa支持的语音控制操作。

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

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

警告： 没有STOP操作。这是因为Alexa将STOP和PAUSE视为同一命令，每当用户分配PAUSE或STOP命令时，Alexa都会暂停媒体。要通过未启用语音的传输控制来支持操作，您仍应在媒体会话回调中实现onStop()方法。

设置媒体会话回调操作

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

请注意，这些是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，重新开始”

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

Android媒体会话文档建议应用仅在具有音频焦点时才应遵守媒体会话命令。这意味着，如果媒体正在播放并且用户说“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，暂停”，则暂停命令将发送到应用，应用需要将内部状态更改为“已暂停”。应用重新获得音频焦点后，会查询内部状态，因为它已暂停，不应恢复媒体。

注意： Fire TV实现会将媒体会话命令发送到最近使用的应用。但是，由于应用现在即使没有音频焦点，也需要遵守媒体会话命令，因此应用必须完全遵守管理音频焦点和Fire TV上多媒体应用的要求中列出的音频焦点指南。

Last updated: 2022年8月18日