音频播放指令

注意

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

• 何时需要使用AudioPlayer指令
• AudioPlayer类指令
  • Play 指令
  • Stop 指令
  • ClearQueue 指令

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

何时需要使用AudioPlayer指令

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

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

• ivs_next_intent
• ivs_previous_intent
• ivs_select_intent
• ivs_cancel_intent
• ivs_stop_intent
• ivs_pause_intent
• ivs_fast_forward_intent
• ivs_fast_backward_intent
• ivs_set_offset_intent
• ivs_inquire_artist_intent
• ivs_inquire_album_intent
• ivs_inquire_media_intent
• ivs_inquire_duration_intent
• ivs_collect_intent
• ivs_cancel_collect_intent
• ivs_dislike_intent 等

注意

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

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

注意

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

AudioPlayer类指令

指令	说明
AudioPlayer.Play	播放特定audioItem的音频
AudioPlayer.Stop	停止音频播放器正在播放的音频
AudioPlayer.ClearQueue	清空音频播放器中的音频流列表

Play 指令

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

注意

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

 {
  "type": "AudioPlayer.Play",
  "playBehavior": "ENQUEUE",
  "audioItem": {
    "stream": {
      "type": "AUDIO",
      "url": "https://example.com/audiofile.mp3",
      "token": "S0wiXQZ1rVBkov...",
      "expectedPreviousToken": "f78b7d68...",
      "offsetInMilliseconds": 0
    },
    "metadata": {
      "title": "小幸运",
      "artist": "田馥甄",
      "album": "小幸运",
      "albumId": "xxxxxx",
      "source": "kugou",
      "service": "music",
      "mediaSource": "我的少女时代",
      "duration": 265000,//单位为毫秒
      "art": {
        "sources": [
          {
            "url": "https://example.com/brie-album-art.png"
          }
        ]
      },
      "backgroundImage": {
        "sources": [
          {
            "url": "https://url-of-the-skill-image.com/brie-background.png"
          }
        ]
      }
    },
    "provider": {
        "name": "酷狗音乐",
        "logo": "https://logo.kugou.com"
    },
    "lyric": {
      "url": "https://url-of-the-lyric.iflyos.cn/xiaoxingyun.lrc",
      "format": "lrc"
    }
  }
}

参数说明

参数名	说明	类型	必须出现
type	取值AudioPlayer.Play	String	是
playBehavior	用来决定客户端怎么处理播放队列。可取值如下： REPLACE_ALL: 立即停止当前播放的音频（发送PlaybackStopped事件至服务端）并清除当前播放队列，立即播放指令中的包含的audio item。 ENQUEUE: 将指令中的audio item添加到当前播放队列的尾部。 REPLACE_ENQUEUED: 替换播放队列中的所有audio item，但不影响当前正在播放的audio item。	String	是
audioItem	包含所要播放的音频资源，一次只能下发一个文件	Object	是
audioItem.stream	云端音频流信息	Object	是
audioItem.metadata	音频播放时展示在有屏设备上的数据，所以你在发送Play指令时，你可以提供音频封面，播放器背景图片，音频标题，艺术家和专辑以供展示，如果你不提供这些数据，音频播放器的界面上将只会展示灰色背景和你的技能名称。	Object	否
audioItem.provider	内容提供方的信息	Object	否
audioItem.provider. name	内容提供方名称	String	是
audioItem.provider. logo	内容提供方logo的url	String	是
audioItem.lyric	音频歌词信息	Object	否
audioItem.lyric.url	歌词文件链接	String	是
audioItem.lyric. format	歌词文件格式，可取值：lrc，txt	String	是

stream 参数说明

参数名	说明	类型	必须出现
type	音频文件的类型，可取值 - AUDIO，音频文件 - SPEECH，合成文本	String	是
url	当type取值为AUDIO时，此项必填，音频文件的播放地址。一般情况下是http/https地址，当音频内容是二进制音频附件时，格式为cid:{id}	String	否
text	当type取值为SPEECH时，此项必填。此处填写需要使用TTS合成为音频文件的文本。	String	否
token	代表该资源的 token，技能方维护	String	是
expectedPreviousToken	代表前一个音频资源的token。若该参数存在时，需要进行校验： - 在playBehavior为ENQUEUE时，该参数应该与当前播放队列末尾audioItem的token一致 - 在playBehavior为REPLACE_ENQUEUED时，该参数应该与当前正在播放的audioItem的token一致 若不一致则不执行本Play指令。	String	否
offsetInMilliseconds	客户端从指定的offset开始进行播放	Long	是

metadata 参数说明

参数名	说明	类型	必须出现
title	音频文件的标题	String	是
artist	作者/艺术家等信息	String	否
album	专辑信息	String	否
albumId	专辑的唯一标识	String	否
source	音频资源的来源，建议填写版权方	String	否
service	该信源所处的业务或技能	String	否
mediaSource	音频文件出现的影视作品信息，比如电影、电视、综艺的名称	String	否
duration	音频文件的长度，以毫秒为单位	Long	否
art	音频文件封面，尺寸 960 x 960px	Image Object	是
backgroundImage	播放器背景图片，尺寸 1024 x 768	Image Object	否

播放列表处理

当playBehavior是ENQUEUE时，audioItem.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首播放完成后，设发送PlaybackNearlyFinished请求，技能回复新的Play第2首的指令，这个音频将在第1首播完的时候开始播放。

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

屏幕展示的图片规范

如果你在 audioItem.metadata.art 和 audioItem.metadata.backgroundImage中提供了图片，需要注意一下规范：

• audioItem.metadata.art最好使用正方形。如果图片不是正方形，图片将会被居中裁剪。
• 我们建议你按照技能规范（///缺图片标准）提供推荐尺寸的图片，以确保图像不会缩放，从而造成显示效果不好。
• Image对象允许你在数组中提供多个图像url。设备选择显示分辨率最高的图像。
• 在显示背景图片和音频封面图片时，下列属性不使用：
  • contentDescription
  • size
  • widthPixels
  • heightPixels

Stop 指令

{
  "type": "AudioPlayer.Stop"
}

ClearQueue 指令

{
  "type": "AudioPlayer.ClearQueue",
  "clearBehavior" : "CLEAR_ALL"
}

参数说明

参数名	说明	类型	必须出现
type	取值AudioPlayer.ClearQueue	String	是
clearBehavior	用来决定设备端怎么清除队列。 - CLEAR_ENQUEUED: 清除队列并继续播放当前歌曲。 - CLEAR_ALL: 清除队列并停止播放当前歌曲。	String	是