播放控制

版本变更

摘要

如果设备有播放、暂停、上一首、下一首等固定按键（实体物理按键，或者是模拟实体物理按键的虚拟按键），应该实现本接口，在用户按下对应按键之后，上报对应事件到服务端，通知服务端用户的按键行为。

注意，在有屏设备上，在播放音乐的界面中播放、暂停等按键并非为设备固定按键，不属于本端能力范畴。

PlayCommandIssued事件

当用户按了设备端上的播放按钮时，上报PlayCommandIssued事件，并为这次按钮操作创建一个唯一的dialogRequestId。 为了提升物理按键反馈的即时性，建议设备端在按键后立即播放设备缓存的流媒体资源，云端收到PlayCommandIssued事件后会给设备端下发Play指令，设备端对比Play指令中dialogRequestId与当前活跃对话的dialogRequestId是否一致，若dialogRequestId相同，且Play指令中stream url与设备端缓存的流媒体资源地址一致，则不执行Play指令。否则设备遵循端上约定逻辑处理新的Play指令。 说明一下这种设备的参考实现的逻辑： 1.为什么设备端不等收到云端Play指令后再进行播放？ 这种设备端的实现有事件上报和指令下行的延迟，设备播放状态变更不能与按键保持实时的同步，体验较差。 2.为什么不能直接不执行Play指令，只播放设备端本地缓存的流媒体资源？ 原因是设备端缓存的流媒体地址可能会失效，如果缓存地址失效，需要从新下发的Play指令里获取最新的有效的stream url。 3.为什么要判断dialogRequestId一致性的条件？ dialogRequestId是用来判断设备端收到的Play指令与用户按键行为的关联性的。若dialogRequestId一致说明当前设备端收到的Play指令是由用户按了播放按钮触发的，由于此时端上已经处于有效的播放状态，可不执行云端的Play指令，避免端上播放状态的突然抖动。 此方案既考虑了用户使用物理按键后反馈的即时性，又兼容了流媒体地址的有效性，推荐设备端参考实现。

消息样例

"clientContext": [
    {{ai.dueros.device_interface.alerts.AlertsState}},
    {{ai.dueros.device_interface.audio_player.PlaybackState}},
    {{ai.dueros.device_interface.speaker_controller.VolumeState}},
    {{ai.dueros.device_interface.voice_output.SpeechState}}
],
"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.playback_controller",
        "name": "PlayCommandIssued",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
    }
}

Client Context说明

本事件需要设备端上报所有端上状态。

PauseCommandIssued事件

当用户按了设备端上的暂停按钮时，上报PauseCommandIssued事件。 为了提升物理按键反馈的即时性，建议设备端在按键后立即停止音频播放。云端收到PauseCommandIssued事件后会给设备端下发Stop指令，若此时设备端音频播放器已经处在STOPPED状态，则不再执行Stop指令。

消息样例

"clientContext": [
    {{ai.dueros.device_interface.alerts.AlertsState}},
    {{ai.dueros.device_interface.audio_player.PlaybackState}},
    {{ai.dueros.device_interface.speaker_controller.VolumeState}},
    {{ai.dueros.device_interface.voice_output.SpeechState}}
],
"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.playback_controller",
        "name": "PauseCommandIssued",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
    }
}

Client Context说明

本事件需要设备端上报所有端上状态。

NextCommandIssued事件

当用户按了设备端上的下一首按钮时，上报NextCommandIssued事件。

消息样例

"clientContext": [
    {{ai.dueros.device_interface.alerts.AlertsState}},
    {{ai.dueros.device_interface.audio_player.PlaybackState}},
    {{ai.dueros.device_interface.speaker_controller.VolumeState}},
    {{ai.dueros.device_interface.voice_output.SpeechState}}
],
"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.playback_controller",
        "name": "NextCommandIssued",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
    }
}

Client Context说明

本事件需要设备端上报所有端上状态。

PreviousCommandIssued事件

当用户按了设备端上的上一首按钮时，上报PreviousCommandIssued事件。

消息样例

"clientContext": [
    {{ai.dueros.device_interface.alerts.AlertsState}},
    {{ai.dueros.device_interface.audio_player.PlaybackState}},
    {{ai.dueros.device_interface.speaker_controller.VolumeState}},
    {{ai.dueros.device_interface.voice_output.SpeechState}}
],
"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.playback_controller",
        "name": "PreviousCommandIssued",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
    }
}

Client Context说明

本事件需要设备端上报所有端上状态。