语音输出

摘要

本接口定义语音输出相关的功能，如果设备有扬声器，则应该实现本接口，接入语音输出的能力。接口包括设备端语音播报指令、播报开始和播报结束事件。

版本变更

版本号	变更时间	变更说明
1.0.1	2019-11-07	新增发音人语速变更的相关指令与事件

Speak指令

在服务端需要通过播报来满足用户请求时，服务端会下发Speak指令，附带需要播报的音频内容。设备端收到Speak指令，应该播报返回中所附带的音频内容。

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.voice_output",
        "name": "Speak",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "url": "{{STRING}}",
        "format": "{{STRING}}",
        "token": "{{STRING}}",
    }
}

Payload参数说明

url
- 格式为cid:{{Audio Item CID}}，其中{{Audio Item CID}}对应播报音频的Content-ID
format
- 所附带播报的数据格式
- 取值
  - AUDIO_MPEG: mp3格式
  - AUDIO_L16_RATE_16000_CHANNELS_1: 16bit线性PCM音频，16kHz采样率，单声道，Little endian byte order
token
- 该播报对应的唯一token

附带播报音频

Speak指令是一个multipart message的HTTP返回，该HTTP返回包含两个消息，第一个消息为Speak指令对应的JSON消息，第二个消息为播报的二进制音频数据流，数据流格式由Speak指令JSON消息中的payload.format决定。

Speak指令HTTP返回样例如下：

:status = 200
content-type = multipart/related; boundary=this-is-a-boundary; type="application/json"

--this-is-a-boundary
Content-Type: application/json; charset=UTF-8

{
    {{Speak Directive}}
}

--this-is-a-boundary
Content-Type: application/octet-stream
Content-ID: {{Audio Item CID}}

{{BINARY AUDIO DATA}}
--this-is-a-boundary--

SpeechStarted事件

收到Speak指令后，在开始进行播报之时，上报此事件到服务端。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.voice_output",
        "name": "SpeechStarted",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}",
    }
}

Payload参数说明

token
- 该播报对应的token，对应Speak指令中的token

SpeechFinished事件

设备端收到Speak指令，并且把播报完整播完之时，上报此事件到服务端。注意，如果播报没有完整播完（比如，在播报中间被用户唤醒，播报被打断），则不应该上报此事件。

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.voice_output",
        "name": "SpeechFinished",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "token": "{{STRING}}"
    }
}

Payload参数说明

token
- 该播报对应的token，对应Speak指令中的token

状态上报

正常请求中也需要上报语音输出当前的状态

消息样例

"clientContext": [
    {
        "header": {
            "namespace": "ai.dueros.device_interface.voice_output",
            "name": "SpeechState"
        },
        "payload": {
            "token": "{{STRING}}",
            "offsetInMilliseconds": {{LONG}},
            "voiceId": {{INT}},
            "voiceResourceId":"{{STRING}}",
            "voiceQueryText":"{{STRING}}",
            "playerActivity": "{{STRING}}",
            "speakRate": {{INT}},
            "ttsStyle": {{INT}},
            "ttsComplexity": "{{STRING}}"
        }
    }
]

Payload参数说明

token
- 当前播报（或最近一次播报）对应的token
offsetInMilliseconds
- 播放偏移量
voiceId
- 对应当前设备音色id（用户选中的）
voiceResourceId
- 当前音色资源Id,如果触发音色修改指令包含资源，该字段表示该资源的ID
voiceQueryText
- 当前应答query的具体应答语
playerActivity
- 当前播放状态
- 取值
  - PLAYING: 如果播报正在进行中，则应该处于PLAYING状态
  - FINISHED: 如果播报结束并上报SpeechFinished事件，则应该处于FINISHED状态
(optional) speakRate
- 对应当前设备播报语速
(optional) ttsStyle
- TTS人设风格，不同风格人设对应不同TTS
- 取值
  - 1 （默认default）
  - 2 （文艺风）
  - 3 （幽默风）
  - 4 （极客风）
  - 5 （飒爽风）
  - 6 （温柔风）
  - 7 （调皮风）
(optional) ttsComplexity
- TTS的复杂度
- 取值
  - SIMPLE: 简洁
  - COMMON: 普通(default)
  - DETAILED: 详细

SetVoice指令

    设备端执行SetVoice指令，下载resource中的资源，并且将下载的资源设置为设备端的唤醒应答音资源，同时在SpeechState端状态中上报音色id。如果指令不包含resource，那么只需要在SpeechState端状态中上报音色id。

消息样例

"directive": {
    "header": {
        "namespace": "ai.dueros.device_interface.voice_output",
        "name": "SetVoice",
        "messageId": "{{STRING}}",
        "dialogRequestId": "{{STRING}}"
    },
    "payload": {
        "voiceId": {{INT}},
        "voiceName": "{{STRING}}",
        "resource": { 
            "url": "{{STRING}}",
            "md5": "{{STRING}}"
        },
        "updateResources": [{{STRING}}],
        "downloadWithToast": {{BOOLEAN}},
        "adResource": [{ 
            "url": "{{STRING}}",
            "md5": "{{STRING}}",
            "id":"{{STRING}}",
            "adGroupId":"{{STRING}}",
            "type": "{{STRING}}",
            "effectDateTime":[{
                "startInMs": {{INT}},
                "endInMs": {{INT}}
            }],
            "rules"{
                "limitPerDay":{{INT}},
                "firstStation":{{INT}},
                "frequence":{{INT}}
            },
            "monitorUrl":{{STRING}},
            "monitorDownloadUrl" : {{STRING}}
        }],
        "speakRate": {{INT}},
        "token": "{{STRING}}"
    }
}

Payload参数说明

voiceId
- 音色id
(optional) voiceName
- 自定义语音包名称（可选，仅给自定义发音人使用）
(optional) resource
- 音色资源信息，包括：设备唤醒时的应答音资源等，以tar包形式下发。tar包中包含描述文件description.json，详情见后面描述。
- 如果指令不包含resource 则需要使用apk sdk默认唤醒音
resource.url
- 音色资源下载链接,资源文件打tar包格式,tar包含需要切换资源文件列表
- description.json 资源描述文件description.json的格式如下
```
    {
        "resources": [{
            "file" : "{{STRING}}",
            "brief" : "{{STRING}}",
            "weight": {{INT}},
            "type": "{{ENUM}}",
            "isDefault": {{BOOLEAN}}
        }]
    }
```
  - desciption 字段描述：
    - file
      - 资源文件名
    - brief
      - 资源文件对应的应答词内容
    - weight
      - 资源使用概率,如果多个相同类型的资源文件则需要分配使用概率
    - type
      - 资源类型取值如下
        
        WAKEUP:唤醒音资源
    - isDefault
      - 是否固定应答词，当用户未选择"随机应答音"时，端上按固定应答词来应答
      - 固定应答词，也会按对应音色播报
resource.md5
- 资源文件校验md5
updateResources
- 必填项，>=sp57，用于区分SetVoice要更新的是哪种音色（可能两种音色都更新），包括功能音色、广告音色
- 字符串数组，取值枚举：
  - RESOURCE：功能音色
  - ADRESOURCE：广告音色
- 背景：端上sp57以前逻辑，如果没有广告adResource字段为[]或nil，就会删除本地广告资源；sp57及以后，通过该字段区分，如下三个场景：
  - 1 设置-音色列表里切换，这两资源可能都有或只有一个；
  - 2 单独推送功能音色，此时指令中没有adResource字段；
  - 3 单独推送广告音色，此时指令中没有resource字段；
(optional)downloadWithToast
- 下载的时候，是否需要弹toast提示"下载中"，推送音色包更新的场景中，下载不能弹toast
- 取值：
  - false，默认值，在推送音色包更新的场景中，下载不能弹toast
  - true，在用户点击设置音色的场景中，若需要下载音色包，提示"下载中"
(optional)adResource
- 包含广告的音色资源信息，包括：设备唤醒时的应答音资源等，以tar包形式下发。tar包中包含描述文件description.json，详情见后面描述。 resource字段仅服务于车联网，adResource是小度sp50为增加广告唤醒音增加的字段。资源超出有效范围后，设备需删除该资源防止存储无意义占用。
(optional) adResource[].url
- 有屏音箱：音色资源下载链接,资源文件打tar包格式,tar包含需要切换资源文件列表 / 无屏音箱：json字符串，具体内容如有屏音箱解压tar包中资源描述文件description.json的内容
(optional) adResource[].md5
- 有屏音箱：tar包资源文件校验md5 / 无屏音箱：adResource[].url字符串对应的md5
(optional) adResource[].id
- 当前资源唯一ID
(optional) adResource[].adGroupId
- 广告资源组ID，与屏保广告、上屏皮肤广告联动使用
(optional) adResource[].type
- 广告唤醒应答音类型，取值：
  - screenSaverWakeup，屏保互动唤醒广告音，在屏保广告物料adGroupId匹配的场景下触发
  - standardWakeup，普通互动唤醒广告音，在满足频控规则后或屏保广告下没有匹配到adGroupId对应物料后触发
(optional) adResource[].effectDateTime
- 生效区间，支持多个区间
(optional) adResource[].effectDateTime[].startInMs
- 生效开始时间戳单位毫秒
(optional) adResource[].effectDateTime[].endInMs
- 生效结束时间戳单位毫秒，所有时间段最后一个时间之后需要上报VoiceChanged事件
(optional) adResource[].rules[].limitPerDay
- 每日广告应答音播报上限
(optional)adResource[].rules[].firstStation
- 每日首次播报广告应答的位置 eg:当firstStation=3,则在每日前两次播报标准应答，第三次播报广告应答音
(optional)adResource[].rules[].frequence
- 广告应答音播报频次。eg：当frequence=3,表示在生效时间内，每三次播报一次广告应答音
(optional)adResource[].monitorUrl
- 广告曝光埋点统计链接，便于广告进行统计以及第三方秒针统计
(optional)adResource[].monitorDownloadUrl
- 广告物料下载成功事件统计链接，便于广告统计物料下载的成功率
(optional) speakRate
- （车联网用）tts语速信息，指定调整的语速值，取值范围为0-15，1为最慢语速，15为最快语速，规则参考AI开放平台-语音合成接口。如果下发该字段，设备需要更改播报语速调整到对应值。
(optional) token
- （车联网用）切换音色指令对应的token

VoiceChanged事件

SetVoice指令执行完毕，及其他方式(如设置端上的切换音色按钮)带来的音色变化, 或者短时生效的特定唤醒音超时恢复时都上报此事件

消息样例

"event": {
    "header": {
        "namespace": "ai.dueros.device_interface.voice_output",
        "name": "VoiceChanged",
        "messageId": "{{STRING}}"
    },
    "payload": {
        "voiceId": {{INT}},
        "speakRate": {{INT}},
        "token": "{{STRING}}"
    }
}

Payload参数说明

voiceId
- 当前设备音色id
(optional) speakRate
- （车联网用）当前设备tts播报音速
(optional) token
- （车联网用）SetVoice指令中的token或触控切换音色音速时端上自行生成的token

语音输出

摘要

版本变更

Speak指令

消息样例

Payload参数说明

附带播报音频

SpeechStarted事件

消息样例

Payload参数说明

SpeechFinished事件

消息样例

Payload参数说明

状态上报

消息样例

Payload参数说明

SetVoice指令

消息样例

Payload参数说明

VoiceChanged事件

消息样例

Payload参数说明

智能家居平台

技能平台

周边支持

友情链接

联系我们