UniOS文档中心

# 音频播放器

# 协议类型

消息类型 名称 必须实现
directive audio_out 是
event progress_sync 是

# context

"unios_context": {
  ....
  "audio_player": {
    "version": "1.0",
    "state": "PLAYING",
    "resource_id": "xxx",
    "offset": 60000
  },
  ...
}
1
2
3
4
5
6
7
8
9
10
参数 类型 说明 必填
version String 模块版本，现在是1.0 是
state String 内容播放器的状态，取值：
- PLAYING: 播放中
- IDLE: 空闲中 。刚开机时或设备没有播放列表时上报这个状态
- PAUSED: 已暂停。设备有播放列表，但没有在播放时，上报这个状态		 是
resource_id String 当前播放器中播放/可播放的音频的唯一标识。state取值为IDLE时该项可不出现 否
offset Long 当前播放器中的资源的播放进度，以毫秒为单位；state取值为IDLE时该项可不出现。如果设备不支持，可不上传（有可能影响设备的体验） 否

# directive

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

回复示例

{
    "unios_directives": [
        {
            "header": {
                "name": "tts_player.voice_out"
            },
            "payload": {
                "url": "http://music.unios.cn/tts/sadf.mp3?token=xxxxxxxx",
                "behavior": "UPCOMING",
                "metadata": {
                    "text": "为您播放刘德华的忘情水"
                }
            }
        },
        {
            "header": {
                "name": "audio_player.audio_out"
            },
            "payload": {
                "url": "http://music.unios.cn/tts/sadf.mp3?token=xxxxxxxx",
                "control": "PLAY",
                "behavior": "UPCOMING",
                "resource_id": "e52e7xxxxxxxxxxxe52e7",
                "offset": 3000,
                "duration": 28379000
            }
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
参数 类型 说明 必填
control String 播放器控制，取值：
- PLAY: 播放
- PAUSE: 暂停
- RESUME: 继续播放		 否
behavior String 资源播放方式。
- IMMEDIATELY: 马上播放，收到资源资源之后必须马上播放
- UPCOMING: 即将播放，收到资源后必须在当前设备播放队列播放完毕之后播放，可以先行预加载。当设备已有预加载内容的情况下，再次收到UPCOMING的内容时，需要把设备已预加载的内容清除，再预加载。		 否
url String 内容播放地址，当control为RESUME时不会出现 否
resource_id String 内容ID，当control为RESUME时不会出现 否
offset Long 播放位置，常见于快进快退，和某些暂停播放，单位：毫秒，当control为PLAY才会出现 否
duration Long 音频长度，单位为毫秒。当control为PLAY才会出现，但不是所有音频都能够获取到长度 否
provider.name String 内容提供商名称 否

举例
1.当用户请求播放音频资源时，收到的unios_directive如下：

{
  "unios_directives": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "url": "https://music.unios.cn/tts/sadf.mp3?token=xxxxxxxx",
        "control": "PLAY",
        "behavior": "UPCOMING",
        "resource_id": "e52e7xxxxxxxxxxxe52e7",
        "offset": 3000
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

2.当用户说“继续播放”时：若设备没有上报offset，收到的unios_directive如下：

{
  "unios_directives": [
    ...,
    {
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "control": "RESUME"
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13

3.当用户说“继续播放”时，若设备有上报offset，收到的unios_directive如下：

{
  "unios_directives": [
    ...,
    {//表示从`offset`指定的位置开始播放音频
      "header": {
        "name": "audio_player.audio_out"
      },
      "payload": {
        "url": "https://music.unios.cn/tts/sadf.mp3?token=xxxxxxxx",//音频播放链接
        "control": "PLAY",
        "behavior": "IMMEDIATELY",
        "resource_id": "e52e7xxxxxxxxxxxe52e7",//音频内容ID
        "offset": 3000//设备上报的当前音频的播放进度
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# event

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

  1. 在手机APP中显示当前播放的内容和播放进度
  2. 使用播放信息同步的方式来获取音乐的下一首资源

请求示例

{
  "unios_header": {...},
  "unios_context": {...},
  "unios_event": {
    "header": {
      "name": "audio_player.progress_sync",
      "message_id": "xxxxxxxx"
    },
    "payload": {
      "type": "STARTED",
      "resource_id": "xxxxx",
      "offset": 60000,
      "failure_code": 1001
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
参数 类型 说明 必填
unios_header Object 构建的通用 unios_header 是
unios_context Object 构建的通用 unios_context 是
type String 状态类型，详细信息见下表 是
resource_id String 该请求对应的内容ID。若为播放失败，则此处为失败的内容ID 是
offset Long 内容的播放进度，若有的设备无法获取该字段，可不传。 否
failure_code Long 错误代码，type为 FAILED 时，必填。取值1001~1005，代码含义见下表 否

type 取值说明

type类型 说明 是否有回复
必须发送
LOADING 加载中，上报的时机由终端决定，比如加载了3秒后还没开始播放 是，得到一个正在加载的TTS 否
STARTED 开始播放的时候，发送此类型并告知 resource_id，手机端可获得播放内容信息 否 是
FAILED 播放失败的时候，发送此类型并告知播放失败的 resource_id，云端会下发其他内容 可能得到一个新的内容 是
NEARLY_FINISHED 音频播放即将结束，一般取内容的1/3的时间长度，如果在小内存系统中，可以选择结束前10秒或者播放开始后30秒 可能回复下一首的资源 否
PAUSED 正在播放的内容被暂停时（被用户按键暂停，或收到了云端下发的PAUSE类型audio_player.audio.out的directive），发送此类型并告知resource_id 否 是
FINISHED 播放结束时候发送此类型，发送此类型并告知 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 设备端内部错误

← 系统相关 →