# 音频播放器

消息类型	名称	必须实现
response	audio_out	是
request	playback.progress_sync	是
	tts.progress_sync	是
	ring.progress_sync	否
	tts.text_in	否，若需开通权限请联系商务：+86 19927478824

版本说明

版本	说明	更新日期
1.0	基础实现	2019-07-01
1.1	新增`audio_player.audio_out`中`TTS`类型的`behavior`和`metadata`	2019-08-28
1.2	`audio_player.audio_out`中`TTS`类型中，新增`secure_url`	2019-12-06

# context

"iflyos_context": {
  ....
  "audio_player": {
    "version": "1.2",
    "playback": {
      "state": "PLAYING",
      "resource_id": "xxx",
      "offset": 60000,
    }
  },
  ... 
}

参数	类型	说明	必填
version	String	模块版本，现在是1.2	是
playback	Object	音频播放器中，内容音频播放的状态	是
playback. state	String	内容播放器的状态，取值： - PLAYING: 播放中 - IDLE: 空闲中。刚开机时或设备没有播放列表时上报这个状态 - PAUSED: 已暂停。设备有播放列表，但没有在播放时，上报这个状态	是
playback. resource_id	String	当前播放器中播放/可播放的音频的唯一标识。`state`取值为IDLE时该项可不出现	否
playback. offset	Int	当前播放器中的资源的播放进度，以毫秒为单位；`state`取值为IDLE时该项可不出现。如果设备不支持，可不上传（有可能影响设备的体验）	否

# response

# 音频播放

当你接收到音频播放指令的时候，你需要使用合适的播放器来播放里面的内容。

回复示例

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "type": "PLAYBACK",
        "url": "http://music.iflyos.cn/tts/sadf.mp3?token=xxxxxxxx",
        "secure_url": "https://music.iflyos.cn/cn/tts/sadf.mp3?token=xxxxxxxx",
        "control": "PLAY",
        "behavior": "UPCOMING",
        "resource_id": "e52e7xxxxxxxxxxxe52e7",
        "offset": 3000,
        "duration": 28379000,
        "metadata": {
          "text": "xxxx"
        }
      }
    }
  ]
}

参数	类型	说明	必有
type	String	播放器类型，取值： - TTS: 语音回复 - PLAYBACK: 音频播放器，常见于播放内容 - RING: 铃声，常见于闹钟	是
control	String	播放器控制，取值： - PLAY: 播放 - PAUSE: 暂停 - RESUME: 继续播放，当`type`值为`PLAYBACK`才会出现	否
behavior	String	资源播放方式。当`type`取值为`PLAYBACK`时，`behavior`取值： - IMMEDIATELY: 时·马上播放，收到资源资源之后必须马上播放 - UPCOMING: 即将播放，收到资源后必须在当前设备播放队列播放完毕之后播放，可以先行预加载。当设备已有预加载内容的情况下，再次收到UPCOMING的内容时，需要把设备已预加载的内容清除，再预加载。当`type`取值为`TTS`时，`behavior`取值： - SERIAL：串行TTS，执行时阻塞，播完TTS才可以执行下一个指令） - PARALLEL：并行，执行不阻塞，开始播放TTS时可以同时执行后续指令。若该字段未出现，默认为SERIAL	否
url	String	内容播放地址，当`type`值为`PLAYBACK`，且`control`为`RESUME`时不会出现	否
secure_url	String	内容播放的安全地址，`url`中可能放的是http的链接，设备解析速度会更快，但有可能会被劫持。`secure_url`中放的是不会被劫持的https链接，但设备解析速度可能会相对慢一些	否
resource_id	String	内容ID，当`type`值为`PLAYBACK`，且`control`为`RESUME`时不会出现	否
offset	Long	播放位置，常见于快进快退，和某些暂停播放，单位为毫秒，当`type`值为`PLAYBACK`，且`control`为`PLAY`才会出现	否
duration	Long	音频长度，单位为毫秒。当`type`值为`PLAYBACK`，且`control`为`PLAY`才会出现，但不是所有音频都能够获取到长度	否
metadata.text	String	TTS音频的原始文本。当`type`值为`TTS`时该项才会出现	否

# 举例

当用户请求播放音频资源时，你收到的iflyos_response如下：

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "type": "PLAYBACK",
        "url": "https://music.iflyos.cn/tts/sadf.mp3?token=xxxxxxxx",
        "control": "PLAY",
        "behavior": "UPCOMING",
        "resource_id": "e52e7xxxxxxxxxxxe52e7",
        "offset": 3000
      }
    }
  ]
}

当云端要通过TTS回复用户的请求时，你收到的iflyos_response如下：

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "type": "TTS",
        "url": "http://tts.iflyos.cn/tts/sadf.mp3?token=xxxxxxxx",
        "secure_url": "https://tts.iflyos.cn/tts/sadf.mp3?token=xxxxxxxx",
        "behavior": "SERIAL",
        "resource_id": "e52e7xxxxxxxxxxxe52e7"
      }
    }
  ]
}

提示

当你收到SERIAL的TTS时，代表这个TTS需要阻塞其他的指令，你需要在这个TTS播放完成后，才可以执行后续的指令。
当你收到PARALLEL的TTS时，代表这个TTS不需要阻塞，当你开始播放这个TTS后，就可以开始执行后续的指令。
为了更好的交互体验，建议设备优先使用url中的链接进行播放。如果播放失败，可更换使用secure_url中的链接。

当你启用云端闹钟，闹钟时间到时，你收到的iflyos_response如下：

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "type": "RING",
        "url": "https://ring.iflyos.cn/tts/sadf.mp3?token=xxxxxxxx",
        "resource_id": "e52e7xxxxxxxxxxxe52e7"
      }
    }
  ]
}

当用户说“继续播放”时：若你的设备上报offset等于-1，你收到的iflyos_response如下：

{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "type": "PLAYBACK",
        "control": "RESUME"
      }
    }
  ]
}

当用户说“继续播放”时，若你的设备上报offset大于-1，你收到的iflyos_resposne如下：

{
  "iflyos_responses": [
    ...,
    {//表示从`offset`指定的位置开始播放音频
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "type": "PLAYBACK",
        "url": "https://music.iflyos.cn/tts/sadf.mp3?token=xxxxxxxx",//音频播放链接
        "control": "PLAY",
        "behavior": "IMMEDIATELY",
        "resource_id": "e52e7xxxxxxxxxxxe52e7",//音频内容ID
        "offset": 3000//设备上报的当前音频的播放进度
      }
    }
  ]
}

# 播放器信息同步

在 iFLYOS 中我们使用播放器信息同步来同步多端信息，并在某些业务场景中能够正确处理。所以你必须实现好本接口如：

在手机APP中显示播放的PLAYBACK的信息，和PLAYBACK的播放进度；使用播放信息同步的方式来获取音乐的下一首资源
云端知晓TTS和RING的播放情况，判断响应是否被正确执行，从而进行下一步处理。

# 音频资源播放进度同步

请求示例

{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {
    "header": {
      "name": "audio_player.playback.progress_sync",
      "request_id": "xxxxxxxx"
    },
    "payload": {
      "type": "STARTED",
      "resource_id": "xxxxx",
      "offset": 60000,
      "failure_code": 1001
    }
  }
}

参数	类型	说明	必填
iflyos_header	Object	构建的通用 iflyos_header	是
iflyos_context	Object	构建的通用 iflyos_context	是
type	String	状态类型，详细信息见下表	是
resource_id	String	该请求对应的内容ID。若为播放失败，则此处为失败的内容ID	是
offset	String	内容的播放进度，若你的设备无法获取该字段，可不传。	否
failure_code	Long	错误代码，，type为 FAILED 时，必填。取值1001~1005，代码含义见下表	否

type 取值说明：

type 类型	说明	是否有回复	必须发送
STARTED	播放开始播放的时候，发送此类型并告知 `resource_id`，手机端可获得播放内容信息	否	是
FAILED	播放失败的时候，发送此类型并告知播放失败的 `resource_id`，云端会下发其他内容	可能得到一个新的内容	是
NEARLY_ FINISHED	音频播放即将结束，一般取内容的1/3的时间长度，如果在小内存系统中，可以选择结束前10秒或者播放开始后30秒	可能回复下一首的资源	否
FINISHED	播放结束时候发送此类型，发送此类型并告知 `resource_id`	否	是
PAUSED	正在播放的内容被暂停时（被用户按键暂停，或收到了云端下发的`PAUSE`类型的`audio_player.audio.out`的`response`），发送此类型并告知`resource_id`	否	是

failure_code 取值说明：

code	错误类型值	描述
1001	MEDIA_ERROR_UNKNOWN	发生了未知错误
1002	MEDIA_ERROR_INVALID_REQUEST	请求无效。可能的情况有：bad request, unauthorized, forbidden, not found等。
1003	MEDIA_ERROR_SERVICE_UNAVAILABLE	设备端无法获取音频文件
1004	MEDIA_ERROR_INTERNAL_SERVER_ERROR	服务端接收了请求但未能正确处理
1005	MEDIA_ERROR_INTERNAL_DEVICE_ERROR	设备端内部错误

# TTS资源播放进度同步

请求示例

{ 
  "iflyos_header": {...}, 
  "iflyos_context": {...}, 
  "iflyos_request": { 
    "header": { 
      "name": "audio_player.tts.progress_sync", 
      "request_id": "xxxxxxxx" 
    }, 
    "payload": { 
      "type": "STARTED", 
      "resource_id": "xxxxx" 
    } 
  } 
}

注意

当TTS开始播放，但在播放完成被打断的时候，无需发送请求告知云端。

参数	类型	说明	必填
iflyos_header	Object	构建的通用 iflyos_header	是
iflyos_context	Object	构建的通用 iflyos_context	是
type	String	状态类型，取值： - STARTED：TTS开始播放 - FINISHED：TTS播放完成。	是
resource_id	String	TTS音频文件的唯一标识	是

# 云端闹钟资源播放进度同步

请求示例

{ 
  "iflyos_header": {...}, 
  "iflyos_context": {...}, 
  "iflyos_request": { 
    "header": { 
      "name": "audio_player.ring.progress_sync", 
      "request_id": "xxxxxxxx" 
    }, 
    "payload": { 
      "type": "STARTED", 
      "resource_id": "xxxxx" 
    } 
  } 
}

参数	类型	说明	必填
iflyos_header	Object	构建的通用 iflyos_header	是
iflyos_context	Object	构建的通用 iflyos_context	是
type	String	状态类型，取值： - STARTED：RING开始播放 - STOPPED：RING播放停止，无论是自然播放完成还是用户操作（唤醒或按键）停止了闹钟，均发送该请求。	是
resource_id	String	RING音频文件的唯一标识	是

# 文本合成

有的时候，你的设备需要生成TTS来回复用户，此时设备可以发送文本请求，iFLYOS 将会把文本合成音频，然后通过iflyos_response返回给你一条能够播放的TTS。

注意：

本权限为专业版权限，需要的请联系商务进行开通

请求示例

{
  "iflyos_header": {...},
  "iflyos_context": {...},
  "iflyos_request": {
    "header": {
      "name": "audio_player.tts.text_in",
      "request_id": "xxxxxxxx"
    },
    "payload": {
      "text": "请求的文本",
      "speed": 1.08,
      "volume": 5,
      "vcn": "x2_yezi"
    }
  }
}

参数	类型	说明	必填
iflyos_header	Object	构建的通用 iflyos_header	是
iflyos_context	Object	构建的通用 iflyos_context	是
text	String	需要合成的文本	是
speed	Number	合成语速，取值范围0.5~1.5。若不填写，使用企业平台的配置。	否
volume	Number	合成音量，取值范围1~10。若不填写，使用企业平台的配置。	否
vcn	String	发音人参数，若不填写，使用企业平台的配置。若填写错误，使用默认发音人。	否

← 语音识别器系统相关 →