# 音频播放器

消息类型 名称 必须实现
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_outTTS类型的behaviormetadata 2019-08-28
1.2 audio_player.audio_outTTS类型中,新增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,且controlRESUME时不会出现
secure_url String 内容播放的安全地址,url中可能放的是http的链接,设备解析速度会更快,但有可能会被劫持。secure_url中放的是不会被劫持的https链接,但设备解析速度可能会相对慢一些
resource_id String 内容ID,当type值为PLAYBACK,且controlRESUME时不会出现
offset Long 播放位置,常见于快进快退,和某些暂停播放,单位为毫秒,当type值为PLAYBACK,且controlPLAY才会出现
duration Long 音频长度,单位为毫秒。当type值为PLAYBACK,且controlPLAY才会出现,但不是所有音频都能够获取到长度
metadata.text String TTS音频的原始文本。当type值为TTS时该项才会出现

# 举例

  1. 当用户请求播放音频资源时,你收到的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
      }
    }
  ]
}
  1. 当云端要通过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中的链接。
  1. 当你启用云端闹钟,闹钟时间到时,你收到的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"
      }
    }
  ]
}
  1. 当用户说“继续播放”时:若你的设备上报offset等于-1,你收到的iflyos_response如下:
{
  "iflyos_responses": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "type": "PLAYBACK",
        "control": "RESUME"
      }
    }
  ]
}
  1. 当用户说“继续播放”时,若你的设备上报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 中我们使用播放器信息同步来同步多端信息,并在某些业务场景中能够正确处理。所以你必须实现好本接口如:

  1. 在手机APP中显示播放的PLAYBACK的信息,和PLAYBACK的播放进度;使用播放信息同步的方式来获取音乐的下一首资源
  2. 云端知晓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.outresponse),发送此类型并告知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 发音人参数,若不填写,使用企业平台的配置。若填写错误,使用默认发音人。