# 音频播放器
消息类型 | 名称 | 必须实现 |
---|---|---|
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 | 发音人参数,若不填写,使用企业平台的配置。若填写错误,使用默认发音人。 | 否 |