视频播放指令

注意

该指令只适用于技能协议v2.1,v2.0中没有该指令

视频播放指令为Response中的一部分,代表你的技能服务对设备端的操作,提供关于视频播放的指令,并管理视频播放进度。你的技能可以发送directives来播放和暂停视频。

何时需要使用VideoPlayer指令

在你使用视频指令时,你必须:实现暂停和恢复视频所需的系统意图:ivs_pause_intentivs_resume_intent

除此之外,如果你的技能未使用视频托管(暂未开放)服务,你的技能还应该优雅地处理以下系统意图:

  • ivs_cancel_intent
  • ivs_next_intent
  • ivs_previous_intent

注意

即使你的技能session已经退出,但如果你的技能正在播放视频,或者是最近播放视频的技能,用户也可以通过不访问你的技能而进行视频控制。届时视频控制的系统意图会自动发送给你的技能。你的代码需要实现它们,不能返回错误。

在搭载iFLYOS的有屏设备正在播放你的技能的视频时,用户可通过界面按钮控制视频播放,包括:上一首、下一首、暂停/播放。用户点击后,你的技能会收到以下请求:PlaybackController.NextCommandIssuedPlaybackController.PreviousCommandIssuedPlaybackController.PauseCommandIssuedPlaybackController.PlayCommandIssued。你的技能也需要优雅地处理这些请求。

注意

在用户点击【暂停】按钮时,设备会在发送请求给你之前自动暂停视频播放。你的技能依旧需要处理PlaybackController.PauseCommandIssued

VideoPlayer类指令

指令 说明
VideoPlayer.Play 播放特定VideoItem的视频
VideoPlayer.Stop 停止视频播放器正在播放的视频
VideoPlayer.Exit 关闭视频播放器

Play 指令

该指令用于播放特定的VideoItem,通过指令中的playBehavior参数决定立即开始播放还是放在队尾。

注意

在一个回复中,你只能回复一个Play指令。

{     
  "type": "VideoPlayer.Play",     
  "playBehavior": "ENQUEUE",     
  "videoItem": {       
    "stream": {         
      "url": "https://example.com/audiofile.mp3",         
      "token": "S0wiXQZ1rVBkov...",         
      "expectedPreviousToken": "f78b7d68...",         
      "offsetInMilliseconds": 0       
    },       
    "metadata": {         
      "title": "武林外传第8集",                
      "album": "武林外传",         
      "duration": 265000,//单位为毫秒 
      "art": {
        "sources": [
          {
            "url": "https://example.com/brie-album-art.png"
          }
        ]
      },     
    }     
  }   
} 

参数说明

参数名 说明 类型 必须出现
type 取值VideoPlayer.Play String
playBehavior 用来决定客户端怎么处理播放队列。可取值如下:

REPLACE_ALL: 立即停止当前播放的视频(发送PlaybackStopped事件至服务端)并清除当前播放队列,立即播放指令中的包含的Video item。
ENQUEUE: 将指令中的Video item添加到当前播放队列的尾部。
REPLACE_ENQUEUED: 替换播放队列中的所有Video item,但不影响当前正在播放的Video item。
String
VideoItem 包含所要播放的视频资源,一次只能下发一个文件 Object
VideoItem.stream 云端视频流信息 Object
VideoItem.metadata 视频播放时展示在有屏设备上的数据,所以你在发送Play指令时,你可以提供视频封面,播放器背景图片,视频标题,艺术家和专辑以供展示,如果你不提供这些数据,视频播放器的界面上将只会展示灰色背景和你的技能名称。 Object

stream 参数说明

参数名 说明 类型 必须出现
url 视频文件的播放地址。一般情况下是http/https地址 String
token 代表该资源的 token,技能方维护 String
expectedPreviousToken 代表前一个视频资源的token。若该参数存在时,需要进行校验:
- 在playBehaviorENQUEUE时,该参数应该与当前播放队列末尾VideoItem的token一致
- 在playBehaviorREPLACE_ENQUEUED时,该参数应该与当前正在播放的VideoItem的token一致
若不一致则不执行本Play指令。
String
offsetInMilliseconds 客户端从指定的offset开始进行播放 Long

metadata 参数说明

参数名 说明 类型 必须出现
title 视频文件的标题 String
album 专辑信息 String
duration 视频文件的长度,以毫秒为单位 String
art 视频文件封面 Image Object

播放列表处理

playBehaviorENQUEUE时,VideoItem.stream.expectedPreviousToken必填,这个参数主要用于处理请求通过播放列表和播放的视频切换同时发生的情况。例如:

  1. 技能正在播放你的列表中的第2首视频。
  2. 用户说:“播放上一首”,发送ivs_previous_intent.
  3. 同时,第2首视频快要播放完了,所以发送了PlaybackNearlyFinished请求。
  4. 技能先处理了ivs_previous_intent,发送了一个新的Play第1首的指令。第1首视频开始播放,收到的PlaybackNearlyFinished请求就过期了,因为他假定第2首歌正在播放。
  5. 技能处理过期的PlaybackNearlyFinished请求,发送了一个Play第3首的指令,因为这是原本在播放的第2首的下一首。此时要求expectedPreviousToken设置为第2首。
  6. 指令中包含的expectedPreviousToken和正在播放的(第1首)视频不一致,这个指令将会被忽略。
  7. 在第1首播放完成后,Alexa发送PlaybackNearlyFinished请求,技能回复新的Play第2首的指令,这个视频将在第1首播完的时候开始播放。

如果检查不到位,步骤5中发送的指令将把第3首放到队列中,这将导致第1首结束时视频从第1首跳到第3首。

Stop 指令

{
  "type": "VideoPlayer.Stop"
}

Exit 指令

{
  "type": "VideoPlayer.Exit"
}