开发者控制台

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

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

Amazon Fire TV上的某些应用支持通过语音控制播放。例如,当客户在Amazon Video上观看电影时,他们可以说“Alexa,播放”来启动媒体,说“Alexa,暂停”来暂停媒体,或者说“Alexa,快进”在媒体的时间轴中向前跳转。集成Android媒体会话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 6Fire OS 7处理来自遥控器、键盘、耳机、adb等的事件。(其他API可能需要不同的实现,具体取决于Fire OS版本。)
  • 如果在Fire TV应用中集成媒体会话并添加适当的权限,则可以为应用提供语音命令支持。您的应用将支持近场语音命令(通过遥控器上的麦克风说话)和远场语音命令(对着支持Alexa的设备(如与Fire TV配对的Echo)说话)。
  • 媒体会话是所有Fire OS设备上支持语音的播放控件(播放、暂停、快进、倒回、上一个、下一个、重新开始)的推荐实现方式。(Fire OS用于Fire TV和Fire平板电脑)

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

支持的语音命令

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中的任何位置(而不仅仅是在您的应用中)对应用的媒体执行语音搜索。视频技能工具包集成要求在Amazon Catalog中包含您的媒体。您可以在Fire TV应用概述的视频技能工具包(VSK)中了解更多信息。

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

如果应用需要支持媒体会话未涵盖的其他播放控制使用情形,则可以通过PlaybackControllerSeekController指令将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_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,重新开始”

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

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,暂停”,则暂停命令将发送到应用,应用需要将内部状态更改为“已暂停”。 应用重新获得音频焦点后,会查询内部状态,因为它已暂停,不应恢复媒体。


Last updated: 2022年8月18日