音频播放器

摘要

本接口提供了播放音频相关的指令和事件。通过本接口定义的指令可以控制设备端上音频资源的播放，并通过事件可以感知播放进度和缓冲区状态等信息。为了更好的理解这个接口，我们先来看看Audio Player有哪些状态：

PLAYING：设备端正在播放audio item时所处的状态。PLAYING状态时可向服务器发送播放进度和audio item的元数据。以下几种情况会退出PLAYING状态：
- 收到暂停或停止音频流的指令
- 音频流缓冲失败
- 播放失败
STOPPED：以下几种情况会处于STOPPED状态：
- 音频流出现问题导致播放失败
- 服务端下发STOP指令
- 收到ClearQueue指令，其中clearBehavior参数值为CLEAR_ALL
- 收到Play指令，其中playBehavior参数值为REPLACE_ALL
- 处于PAUSED或BUFFER_UNDERRUN状态时，收到clearBehavior参数值为CLEAR_ALL的ClearQueue指令
PAUSED：当优先级更高的Channel进入活跃状态时（例如用户开始语音交互、闹铃响起），应当进入PAUSED状态。
BUFFER_UNDERRUN：当设备端处于PLAYING状态，并且缓冲的数据不足以继续播放，播放器等待缓冲数据时进入BUFFER_UNDERRUN状态，直到缓冲完成才会恢复为PLAYING状态。
FINISHED：在audio item播放完成时将转为FINISHED状态。即使设备端本地播放队列中有多个audio item待播放，在每一个audio item播放结束后也都需要向服务端发送PlaybackFinished事件，并且进入FINISHED状态。另外，设备启动后的初始状态也应当是FINISHED状态。
IDLE: 端上播放器没有被任何音频占用
- 无屏端场景: 端上首次进入音频播放前，状态为IDLE，一旦播放过音频后，在关机断电前一直处于非IDLE状态。
- 有屏端场景：端上前后台都没有显示播放器的情况下，认定为IDLE状态; 区别于STOPPED，STOPPED表明停止播放，但是播放器还在前台或者后台，用户可见的情况
- 无PlaybackState状态上报的情况下，等价于IDLE状态

版本变更

版本号	变更时间	变更描述
1.0.1	2018-12-06	为了辅助定位缓冲导致的播放卡顿问题，PlaybackStutterStarted事件增加_mediaHostInfo字段，设备端可以在该字段中上报正在播放的资源的域名和IP地址
1.1.0	2019-01-08	为PlaybackFinished和PlaybackNearlyFinished事件增加上报clientContext: SettingsState
1.1.1	2019-03-02	PlaybackStopped事件上报情况的进一步明确说明，增加了按键停止、屏幕点击停止、指令执行导致的停止等情况
1.2.0	2019-03-03	为PlaybackFailed事件增加上报clientContext: SettingsState
1.3.0	2019-04-14	为PlaybackState增加IDLE状态
1.4.0	2019-09-06	为Play指令添加过渡音设置
1.4.1	2019-11-07	为Play指令添加副歌相关信息
1.5.0	2020-03-02	为Play指令添加"播放倍速信息" 取值: 0.5,0.75,1,1.25,1.5,2
1.5.1	2020-04-28	为Play指令中 playerName 字段添加 30s 听歌模式 SIMPLIFY_MODE
1.6.0	2020-05-20	为PlaybackState端状态增加version字段，填充audioplayer apk版本号
1.6.1	2021-11-25	Playback事件增加playerName字段表示事件上报来源，确保30s听歌模式下不会修改audio_player的端状态，避免共存情况下端状态更新混乱、30s听歌只上报播放相关事件并通过playerName字段区分

Play指令

Play指令控制设备端的音频播放，指令包含一个所要播放的audio item，以及控制播放行为的playBehavior参数。

控制设备端播放和队列的playBehavior参数，有以下几种类型：

REPLACE_ALL: 立即停止当前播放（如有必要，发送PlaybackStopped事件）并清除播放队列，立即播放指令中的audio item。
ENQUEUE: 将audio item添加到当前队列的尾部。
REPLACE_ENQUEUED: 替换播放队列中的所有audio item，但不影响当前正在播放的audio item。

audio item还包含expectedPreviousToken参数，该参数的处理有以下几种情况：

如果expectedPreviousToken不存在，则Play指令正常执行
在playBehavior为ENQUEUE时，expectedPreviousToken应该与当前播放队列末尾audio item中的token一致，如果不一致则不执行本Play指令
在playBehavior为REPLACE_ENQUEUED时，expectedPreviousToken应该与当前正在播放的audio item中的token一致，如果不一致则不执行本Play指令
playBehavior为REPLACE_ALL时，expectedPreviousToken不存在

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "Play",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "playBehavior": "{{STRING}}",
        "playerName": "{{STRING}}",
        "audioItem": {
            "audioItemId": "{{STRING}}",
            "stream": {
                "url": "{{STRING}}",
                "streamFormat" "AUDIO_MPEG",
                "speed": "{{ENUM}}",
                "offsetInMilliseconds": {{LONG}},
                "expiryTime": "{{STRING}}",
                "progressReport": {
                    "progressReportDelayInMilliseconds": {{LONG}},
                    "progressReportIntervalInMilliseconds": {{LONG}}
                },
                "token": "{{STRING}}",
                "expectedPreviousToken": "{{STRING}}",
                "chorus": {
                    "onlyChorus": {{BOOLEAN}},
                    "startInMilliseconds": {{LONG}},
                    "endInMilliseconds": {{LONG}}
                }
            }
        },
        "_transitionSound": {
            "headUrl": "{{STRING}}",
            "tailUrl": "{{STRING}}"
        }
    }
}

Payload参数说明

playBehavior
- 控制客户端播放和队列处理，详见前文说明
(optional) playerName
- 播放器的类型
  - NORMAL 音乐自身渲染的播放器页面
  - SHORTVIDEO 端上判断是否从短视频跳转到音乐播放器页面，点击返回能够回到home页
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器
  - SCENE_RADIO 新增的场景电台（SP >= 58 show版本支持）
audioItem
- 所要播放的音频资源
audioItem.audioItemId
- audio item的id
audioItem.stream
- 音频流的元信息
audioItem.stream.url
- 音频流的资源地址。如果是外部音频资源，则为http/https链接；如果为"cid:"，则本http回复附件中附带音频流
audioItem.stream.streamFormat
- 如果音频流为http回复附件时，表示音频流的格式（目前支持的格式为AUDIO_MPEG）；如果音频流为外部url时此字段不存在
(optional) audioItem.stream.speed
- 播放倍速信息。取值: 0.5,0.75,1,1.25,1.5,2 (不支持倍速可不输出此字段)
audioItem.stream.offsetInMilliseconds
- 从指定的offset开始进行播放
audioItem.stream.expiryTime
- ISO8601格式，表示stream过期时间
audioItem.stream.progressReport.progressReportDelayInMilliseconds
- 如果此字段存在，则设备端在播放该audio item时，播放到所指定时间之后应该上报ProgressReportDelayElapsed事件；如果此字段不存在，则设备端端不需要上报ProgressReportDelayElapsed事件
audioItem.stream.progressReport.progressReportIntervalInMilliseconds
- 如果此字段存在，则设备端在播放该audio item时，每隔指定时间上报ProgressReportIntervalElapsed事件；如果此字段不存在，则设备端不需要上报ProgressReportIntervalElapsed事件
audioItem.stream.token
- 代表本audio item的唯一token
audioItem.stream.expectedPreviousToken
- 如果此字段存在，则应当匹配前一个audio item中的token，如果不匹配则不执行本Play指令；详见前文说明
(optional) audioItem.stream.chorus
- 歌曲的副歌信息，如果有该字段表示本首歌曲有副歌;场景电台付费试听下发字段
(optional) audioItem.stream.chorus.onlyChorus
- 是否只能播放副歌，如果该字段为true，则播放器不能播放副歌以外的部分
(optional) audioItem.stream.chorus.startInMilliseconds
- 副歌的起始时间点;场景电台试听起始时间点
(optional) audioItem.stream.chorus.endInMilliseconds
- 副歌的结束时间点;场景电台试听起始时间点
_transitionSound
- （暂为无屏音箱专属字段）音频过渡音相关字段，不需要时此结构不存在。播放过渡音不上报Play相关事件，audioItem指定的音频资源按照原逻辑上报Play相关事件。
_transitionSound.headUrl
- 过渡音资源地址，需要在audioItem音频之前播放，可由云端配置，不需要时该字段不存在。如果是外部音频资源，则为http/https链接；如果指定某个端上预置过渡音，通过"local:
  "指定资源。"local:
  "取值如下：
  - local:0 端上预置过渡音，音频同http://dueros-short-video.bj.bcebos.com/short-video/stop_1_24k.wav
_transitionSound.tailUrl
- 过渡音资源地址，需要在audioItem音频之后播放，可由云端配置，不需要时该字段不存在。如果是外部音频资源，则为http/https链接；如果指定某个端上预置过渡音，通过"local:
  "指定资源。"local:
  "取值如下：
  - local:0 端上预置过渡音，音频同http://dueros-short-video.bj.bcebos.com/short-video/stop_1_24k.wav

SetPlaybackSpeed指令

用于控制音频播放时的倍速变化

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "SetPlaybackSpeed",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "speed": "{{ENUM}}",
    }

Payload参数说明

speed:
- 倍速数值
- 取值: 0.5,0.75,1,1.25,1.5,2 (端支持速率)

PlaybackStarted事件

audio item开始播放时上报此事件。

注意：对每一个服务端下发的URL（就是Play指令里面下发的URL），设备端应该只上报一次PlaybackStarted事件。如果设备端收到的是一个播放列表的URL，也应该只上报一个PlaybackStarted事件。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackStarted",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "playerName": "{{STRING}}",
        "linkFrom": "{{STRING}}"
    }
}

Payload参数说明

token:
- 要播放的audio item的token
offsetInMilliseconds
- 要开始播放的offset
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器
(optional)linkFrom
- 链接来源

PlaybackFinished事件

audio item播放结束时上报此事件。

以下情况下不上报本事件：

播放停止（Stop指令，或者设备本地停止按钮）
上一首下一首切换时

注意：对每一个服务器下发的URL（就是Play指令里面下发的URL），设备端应该只上报一次PlaybackFinished事件。如果设备端收到的是一个播放列表的URL，也应该只上报一个PlaybackFinished事件。

消息样例

"clientContext": [
    {{ai.dueros.device_interface.settings.SettingsState}}
],
"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackFinished",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "playerName": "{{STRING}}",
        "linkFrom": "{{STRING}}"
    }
}

Client Context说明

需要上报ai.dueros.device_interface.audio_player.SettingsState，是因为云端召回下一首歌时，需要用到SettingsState中，状态以客户端为准的设置，比如qq音乐app的开关等。

Payload参数说明

token
- 播放完成的audio item的token
offsetInMilliseconds
- 播放完成时的offset
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器
(optional)linkFrom
- 链接来源

PlaybackNearlyFinished事件

当当前audio item播放快要结束，准备缓冲/下载播放队列中的下一个audio item时上报此事件。服务端有可能会返回Play指令，添加新的audio item到队列末尾。

消息样例

"clientContext": [
    {{ai.dueros.device_interface.settings.SettingsState}}
],
"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackNearlyFinished",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "playerName": "{{STRING}}",
        "linkFrom": "{{STRING}}"
    }
}

Client Context说明

需要上报ai.dueros.device_interface.settings.SettingsState，是因为云端召回下一首歌时，需要用到SettingsState中，状态以客户端为准的设置，比如qq音乐app的开关等。

Payload参数说明

token
- 本audio item的token
offsetInMilliseconds
- 当前的播放进度
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器
(optional)linkFrom
- 链接来源

PlaybackFailed事件

当设备端播放audio item发生错误时上报此事件。

事件中的token有可能与正在播放中的audio item的token不一致，比如正在播放一个audio item，并要开始缓冲下一个audio item时下一个audio item的缓冲出现错误。

消息样例

"clientContext": [
    {{ai.dueros.device_interface.audio_player.PlaybackState}},
    {{ai.dueros.device_interface.settings.SettingsState}}
],
"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackFailed",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "_mediaHostInfo": {
            "domainName": "{{STRING}}",
            "ipAddress": "{{STRING}}"
        },
        "error": {
            "type": "{{STRING}}",
            "message": "{{STRING}}"
        },
        "playerName": "{{STRING}}"
    }
}

Client Context说明

本事件需要设备端上报端上的ai.dueros.device_interface.audio_player.PlaybackState状态。

Payload参数说明

token
- 发生错误的audio item的token
(optional) _mediaHostInfo
- 正在播放的音频资源的域名、IP地址等信息，用于辅助定位播放失败原因
_mediaHostInfo.domainName
- 正在播放的音频资源的域名
_mediaHostInfo.ipAddress
- 正在播放的音频资源的IP地址，由于每次域名解析的IP地址可能不同，这里的IP地址是指音频资源在此次播放时播放器所解析出的IP地址
error.type
- 错误类型，取值如下
  - "MEDIA_ERROR_UNKNOWN": 未知错误
  - "MEDIA_ERROR_INVALID_REQUEST": stream服务端返回请求无效 (可能的情况有bad request, unauthorized, forbidden, not found等等)
  - "MEDIA_ERROR_SERVICE_UNAVAILABLE": 设备端无法连接stream服务端
  - "MEDIA_ERROR_INTERNAL_SERVER_ERROR": stream服务端接受请求，但未能正确处理
  - "MEDIA_ERROR_INTERNAL_DEVICE_ERROR": 设备端内部错误
error.message：
- 错误描述，仅用于打印日志；如果有HTTP相关的错误，也应该包含在本错误消息中，以便排查问题
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器

ProgressReportDelayElapsed事件

本事件用来统计播放情况。如果Play指令中有progressReportDelayInMilliseconds，则对应audio item播放此时间长后需要上报本事件。

注意一、不是播放offset到此时间，而是播放音频此时间长。例如，progressReportDelayInMilliseconds为10000，Play指令指定的offset为25000，则音频从第25秒处开始播放，当播放了10秒钟之后（播放到offset为35秒处），上报本事件。 注意二、设置倍速播放speed后，上报周期要以物理时间为准，而不是播放进度条为准

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "ProgressReportDelayElapsed",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "playerName": "{{STRING}}"
    }
}

Payload参数说明

token
- 本audio item的token
offsetInMilliseconds
- 当前的播放进度
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器

ProgressReportIntervalElapsed事件

本事件用来统计播放情况。如果Play指令有progressReportIntervalInMilliseconds，则在播放对应audio item时，每隔此时间上报本事件。

注意，上报本事件应根据播放时长，而不是播放offset。例如，progressReportIntervalInMilliseconds为10000，Play指令指定的offset为25000，则音频从第25秒出开始播放，每播放10秒钟（播放到offset为35秒处、45秒处、55秒处等等），上报本事件。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "ProgressReportIntervalElapsed",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "playerName": "{{STRING}}"
    }
}

Payload参数说明

token
- 本audio item的token
offsetInMilliseconds
- 当前的播放进度
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器

PlaybackStutterStarted事件

在PlaybackStarted事件之后，并且设备端播放器已经在开始播放资源过程中，如果资源播放出现卡顿，则立即上报此事件。事件上报后音频播放器应该进入BUFFER_UNDERRUN状态，并保持此状态直到缓冲区满并恢复音频播放。

判断播放卡顿可供参考的方法

播放器缓存中没有音频数据可以继续播放，即可上报该事件
播放器从开始播放到当前的物理时间间隔，大于播放器播放进度时长2s以上，即可上报该事件

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackStutterStarted",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "_mediaHostInfo": {
            "domainName": "{{STRING}}",
            "ipAddress": "{{STRING}}"
        },
        "error": {
            "message": "{{STRING}}"
        },
        "playerName": "{{STRING}}"
    }
}

Payload参数说明

token
- 本audio item的token
offsetInMilliseconds
- 当前的播放进度
(optional) _mediaHostInfo
- 正在播放的音频资源的域名、IP地址等信息，用于辅助定位缓冲导致的播放卡顿原因
_mediaHostInfo.domainName
- 正在播放的音频资源的域名
_mediaHostInfo.ipAddress
- 正在播放的音频资源的IP地址，由于每次域名解析的IP地址可能不同，这里的IP地址是指音频资源在此次播放时播放器所解析出的IP地址
error.message：
- 错误描述，仅用于打印日志；如果有HTTP相关的错误，也应该包含在本错误消息中，以便排查问题
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器

PlaybackStutterFinished事件

PlaybackStutterStarted事件之后，缓冲恢复到正常状态，可重新开始播放时（播放资源卡顿恢复）上报本事件；重新开始播放时，不需要再额外上报PlaybackStarted事件。

注意：本事件可能不会同PlaybackStutterStarted事件配对出现。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackStutterFinished",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "stutterDurationInMilliseconds": {{LONG}},
        "playerName": "{{STRING}}"
    }
}

Payload参数说明

token
- 本audio item的token
offsetInMilliseconds
- 当前的播放进度
stutterDurationInMilliseconds
- 从PlaybackStutterStarted到PlaybackStutterFinished时间间隔
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器

Stop指令

停止音频播放。用户的语音指令，用户按下设备端物理按钮，或者通过软件界面点击等情况都有可能使得服务端下发Stop指令。

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "Stop",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
    }
}

PlaybackStopped事件

停止音频播放时上报，有以下几种可能：

收到Stop指令，停止了播放
收到了Play指令，playBehavior为REPLACE_ALL，停止了当前音频流的播放
收到ClearQueue指令，clearBehavior为CLEAR_ALL，停止了当前音频流的播放
对于有停止播放按键（包括暂停播放按键）的设备，用户点击停止播放按键，停止了当前音频流的播放
对于有屏设备，用户点击屏幕上的停止播放按钮（包括暂停按钮），停止了当前音频流的播放
其他一些指令的执行或用户操作导致停止了当前音频流的播放，并且在指令执行完或者用户操作完毕后不再恢复当前音频流播放的情况，比如执行extensions.screen_navigation端能下的Exit指令时，退出audio_player并停止了当前音频流的播放，或者用户点击退出按钮退出了播放器等情况。补充说明一下，指令执行完恢复当前音频流播放的典型情况是音乐播放被语音播报打断的情况，这时应该上报PlaybackPaused/PlaybackResumed，具体可以参见PlaybackPaused/PlaybackResumed事件的描述。

注意：本事件的上报，是在上述情况下停止了当前音频流的播放时发生。如果音频播放完毕正常结束，应该上报PlaybackFinished事件，不上报本事件。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackStopped",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "playerName": "{{STRING}}"
    }
}

Payload参数说明

token
- 本audio item的token
offsetInMilliseconds
- 当前的播放进度
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器

PlaybackPaused事件

在音频播放时，如果发生对话/闹钟等更高优先级的Channel行为，则音频播放应该暂停，等更高优先级的Channel行为结束之后再重新继续播放。此时，应该上报PlaybackPaused事件和PlaybackResumed事件。

注意：如果发生语音输入，应该先上报ListenStarted事件，之后再上报PlaybackPaused事件，以减少语音交互延迟。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackPaused",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": "{{STRING}}",
        "playerName": "{{STRING}}"
    }
}

Payload参数说明

token
- 本audio item的token
offsetInMilliseconds
- 当前的播放进度
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器

PlaybackResumed事件

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackResumed",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": "{{STRING}}",
        "playerName": "{{STRING}}"
    }
}

Payload参数说明

token
- 本audio item的token
offsetInMilliseconds
- 当前的播放进度
(optional)playerName
- 播放器的类型，可选字段，如果不上报此字段，则默认当前事件上报来自音频播放器
  - SIMPLIFY_MODE 新增的 30s 听歌模式专用播放器

ClearQueue指令

用于清除播放队列。ClearQueue指令有两种行为（clearBehavior参数），CLEAR_ENQUEUED用于清除队列但保留当前正在播放的audio item，CLEAR_ALL用于清除播放队列并停止当前播放的audio item。

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "ClearQueue",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "clearBehavior": "{{STRING}}"
    }
}

Payload参数说明

clearBehavior
- 清除行为，取值：CLEAR_ENQUEUED, CLEAR_ALL

PlaybackQueueCleared事件

设备端处理完ClearQueue指令后上报此事件。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "PlaybackQueueCleared",
        "messageId": "{{STRING}}"
    },
    "payload": {
    }
}

StreamMetadataExtracted事件

设备端播放音频资源时，如果音频资源附带元信息，把元信息作为key/value对作为JSON对象进行上报本事件。元信息中的字符串和数字作为JSON string，元信息中的boolean作为JSON boolean，如果元信息中包含二进制数据（如图片、附件、应用程序数据），则不上传二进制部分的key/value。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "StreamMetadataExtracted",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
        "metadata": {
            "{{STRING}}": "{{STRING}}",
            "{{STRING}}": {{BOOLEAN}}
            "{{STRING}}": "{{STRING NUMBER}}"
            ...
        }
    }
}

Payload参数说明

token
- 本audio item的token
metadata
- 元信息key/value对

状态上报

消息样例

"clientContext": [
    {
        "header": {
            "namespace": "ai.dueros.device_interface.audio_player",
            "name": "PlaybackState"
        },
        "payload": {
            "token": "{{STRING}}",
            "offsetInMilliseconds": {{LONG}},
            "playerActivity": "{{STRING}}",
            "version" : "{{STRING}}",
            "playerName": "{{STRING}}"
        }
    }
]

Payload参数说明

(optional) token
- 正在播放中的audio item的token，当播放器没有播放资源时，可以不上报token字段
(optional) offsetInMilliseconds
- 当前的播放进度，当播放器没有播放资源时，可以不上报offsetInMilliseconds字段
playerActivity
- 音频播放器当前状态，详见音频播放器摘要描述
- 取值：PLAYING, STOPPED, PAUSED, BUFFER_UNDERRUN, FINISHED, IDLE
(optional) version
- 如果此字段存在，由audioplayer apk填充当前apk版本号
(optional) playerName
- 云端决策依赖端状态上报播放器的类型，字段缺失默认音乐播放器，场景电台播放器：SCENE_RADIO

Continue指令

取消暂停/播放/继续

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.audio_player",
        "name": "Continue",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

token
- 下发指令时携带的token

音频播放器

摘要

版本变更

Play指令

消息样例

Payload参数说明

SetPlaybackSpeed指令

消息样例

Payload参数说明

PlaybackStarted事件

消息样例

Payload参数说明

PlaybackFinished事件

消息样例

Client Context说明

Payload参数说明

PlaybackNearlyFinished事件

消息样例

Client Context说明

Payload参数说明

PlaybackFailed事件

消息样例

Client Context说明

Payload参数说明

ProgressReportDelayElapsed事件

消息样例

Payload参数说明

ProgressReportIntervalElapsed事件

消息样例

Payload参数说明

PlaybackStutterStarted事件

消息样例

Payload参数说明

PlaybackStutterFinished事件

消息样例

Payload参数说明

Stop指令

消息样例

PlaybackStopped事件

消息样例

Payload参数说明

PlaybackPaused事件

消息样例

Payload参数说明

PlaybackResumed事件

消息样例

Payload参数说明

ClearQueue指令

消息样例

Payload参数说明

PlaybackQueueCleared事件

消息样例

StreamMetadataExtracted事件

消息样例

Payload参数说明

状态上报

消息样例

Payload参数说明

Continue指令

消息样例

Payload参数说明

智能家居平台

技能平台

周边支持

友情链接

联系我们