开发人员控制台

通过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的安卓应用而不是网页应用。您可以将媒体会话API与网页应用集成(通过诸如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不仅提供媒体播放的传输控制(播放、暂停、快进等),还允许用户在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,暂停”,则暂停命令将发送到应用,应用需要将内部状态更改为“已暂停”。 应用重新获得音频焦点后,会查询内部状态,因为它已暂停,不应恢复媒体。