# 视频播放指令

注意

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

何时需要使用VideoPlayer指令
VideoPlayer类指令

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

# 何时需要使用VideoPlayer指令

在你使用视频指令时，你必须：实现暂停和恢复视频所需的系统意图:ivs_pause_intent，ivs_resume_intent。

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

ivs_cancel_intent
ivs_next_intent
ivs_previous_intent

注意

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

在搭载iFLYOS的有屏设备正在播放你的技能的视频时，用户可通过界面按钮控制视频播放，包括：上一首、下一首、暂停/播放。用户点击后，你的技能会收到以下请求：PlaybackController.NextCommandIssued，PlaybackController.PreviousCommandIssued，PlaybackController.PauseCommandIssued，PlaybackController.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。若该参数存在时，需要进行校验： - 在`playBehavior`为`ENQUEUE`时，该参数应该与当前播放队列末尾VideoItem的token一致 - 在`playBehavior`为`REPLACE_ENQUEUED`时，该参数应该与当前正在播放的VideoItem的token一致若不一致则不执行本Play指令。	String	否
offsetInMilliseconds	客户端从指定的offset开始进行播放	Long	是

metadata 参数说明

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

# 播放列表处理

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

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

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

# Stop 指令

{
  "type": "VideoPlayer.Stop"
}

# Exit 指令

{
  "type": "VideoPlayer.Exit"
}

← 界面模板渲染指令 APP控制指令 →