密级	公开
版本	10D.2

AICP TTS WebSocket开发手册

1. 概述#

1.1 功能介绍#

语音合成服务 WebSocket 接口，提供了将超长文本（千字或者万字）合成为语音二进制数据的功能，适用于异步调用场景。

注意: 使用标记语言时，依然受限1024字节长度的约束

WebSocket 接口与 HTTP 接口差异在于：

非标记语言格式时，去掉了对500字符待合成文本的长度限制
合成后音频数据返回将分片进行流式发送，更适用于同步发音等场景（人机对话、有声阅读等）
合成过程中支持终止取消合成任务
连接建立后，可重复使用进行合成任务的提交，减少网络连接等消耗，提高效率

1.2 模型特征串#

AICP-10 平台提供的 TTS 能力接口中，模型特征串形式为： {lang}_{voicename}_{domain}。 {lang}表示语言编码，{voicename}表示语音合成的发音人也即对应使用不同的合成资源， {domain}表示领域编码。

模型特征串的概念和语言编码，请参见《AICP 10 开发通用规范》

领域是针对合成任务的一种优化手段。不同领域的模型，可以对这种领域里的常见说话方式等进行针对性优化，就有可能得到更好的语言合成效果。目前仅支持common领域。

目前常见的模型特征串如下，使用端到端算法的 TTS 引擎（称为 E2E 引擎）：

模型特征串(property)	发音人简称	合成风格
cn_zhixingjing_common	知性静	女声知性
cn_chengshuqian_common	成熟谦	女声成熟
cn_liaoliangnan_common	嘹亮楠	女声嘹亮
cn_shuhuankun_common	舒缓昆	女声舒缓
cn_reqingman_common	热情曼	女声热情
cn_yanlirui_common	严历瑞	女声严历
cn_roumeijuan_common	柔美娟	女声柔美
cn_roumeiqian_common	柔美倩	女声柔美
cn_qingchunwei_common	清纯威	女声清纯
cn_roumeiyun_common	柔媚云	台湾女声柔媚
cn_chunzhenhe_common	纯真赫	童声纯真
cn_catongjing_common	卡通婧	童声卡通
cn_daimengxi_common	呆萌西	童声呆萌
cn_youmoxiong_common	幽默兄	男声雕兄
cn_jiangsong_common	激昂松	男声柏松
cn_liluoxu_common	利落旭	男声利落
en_roumeicameal_common	柔美Cameal	英文柔美
en_shenghuobarron_common	生活Barron	英文生活

10D.1 版本起也支持原参数合成算法的 TTS 引擎（称为 H9 引擎），使用不同的 property 区分，常见的模型特征串包括：

模型特征串(property)	发音人简称	合成风格
cn_zhixingjing_common-h9	知性静	女声知性
cn_roumeijuan_common-h9	柔美娟	女声柔美
cn_roumeiqian_common-h9	柔美倩	女声柔美

更多的发音人库可与捷通华声公司联系获得。

1.3 访问认证#

访问接口所需的认证机制，请参见《AICP 10 开发通用规范》

2. 接口交互流程#

通过WebSocket接口的全双工通讯模式，客户端可持续收到当前已经合成完毕的语音片段(二进制帧)，以及识合成程中的进度等反馈信息(文本帧)，同时可在合成过程中随时终止合成任务。连接建立后，可重复使用该链接进行合成任务的提交。

3. 握手阶段#

3.1 握手阶段请求#

3.1.1 请求URI#

ws(s)://ip:port/v10/tts/synth/{property}/stream?appkey={appkey}[&access-token={token}]

参数	类型	必选	说明
property	String	是	模型特征串，服务器端利用此值来调用不同的模型
appkey	String	是	分配给开发者的 appkey
access-token	String	否	通过 get-access-token 获取到的令牌

access-token 是可选的，开发者优先应选用 X-Hci-Access-Token HTTP Header 来传递 access token。当无法设置 X-Hci-Access-Token时，可以使用此 URL 参数来传递 access token。

3.2 请求参数#

3.2.1 HTTP Header#

头域字段	类型	必选	说明
X-Hci-Access-Token	String	是	获取到的访问令牌

X-Hci-Access-Token 是开发者使用分配给开发者的 appkey 和 secret 访问系统服务接口 get-access-token 获取到的令牌，详细见《系统服务 HTTP 开发手册》。

注意： 在 HTML5 中，由于 Javascript 中在创建 WebScoket 对象时，无法设置HTTP 头域，此时可以通过URL中的 access-token 参数来传入获取的令牌。

3.3 握手阶段响应#

正常协议升级，HTTP 状态码为 101 Switching Protocols，此时没有其它响应。

如果没有给出令牌或者令牌无效、过期，则会返回 UNAUTHENTICATED 错误（HTTP Response Code 401: Unauthorized）。

其它响应的状态码及错误码，请参见《AICP 10 开发通用规范》

3.4 握手阶段示例#

以HTTP/1.1 协议进行握手和协议升级

客户端发送请求：

GET /v10/tts/synth/cn_xiaokun_common/stream?appkey=xxxxxx HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
X-Hci-Access-Token: xxxxxxxx

服务器响应，完成握手和协议升级：

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

4. 连接阶段#

4.1 连接阶段请求#

4.1.1 开始合成#

客户端发送"开始合成"请求，使用文本类型的数据帧(text message)发送，命令和本次会话的参数以JSON字符串的形式提供。

参数	类型	必选	说明
command	String	是	为 `START`，表示启动合成请求
config	Object	否	语音合成的配置信息
config.pitch	Integer	否	基频，调节音调高低 [-500,500] 缺省:0
config.pitch	Integer	否	基频，调节音调高低 [-500,500] 缺省:0
config.volume	Integer	否	音量，调节音量大小 [0,100] 缺省:50
config.volume	Integer	否	音量，调节音量大小 [0,100] 缺省:50
config.speed	Integer	否	语速，调节语速快慢 [-500,500] 缺省:0
config.speed	Integer	否	语速，调节语速快慢 [-500,500] 缺省:0
config.digitMode	Integer	否	数字处理方式 0: 自动判断规则，优先数目读法(缺省) 1: 自动判断规则，优先电报读法 2: 统一电报读法（如"16"读作"幺六"） 3: 统一数目读法（如"16"读作"十六"）




config.soundEffect	Integer	否	音效控制 0: 不加音效(缺省) 1: 混响 2: 回声 3: 合唱 4: 忽远忽近 5: 机器人
config.puncMode	Boolean	否	是否读出标点符号 {true,false} 缺省:false
config.puncMode	Boolean	否	是否读出标点符号 {true,false} 缺省:false
config.format	String	否	音频编码格式 {"pcm","alaw","ulaw", "jtx_speex", "jtx_opus"} 缺省: pcm
config.format	String	否
config.sampleRate	Integer	否	音频采样率 {8000, 11025, 16000, 22050, 32000, 44100, 48000} 缺省:`16000`
config.sampleRate	Integer	否
config.useS3ML	Boolean	否	传入文本是否是S3ML格式 {true,false} 缺省:false
config.useS3ML	Boolean	否	传入文本是否是S3ML格式 {true,false} 缺省:false
text	String	是	待合成的文本内容，必须使用UTF-8编码

{
  "command":"START",
  "config": {
    "format":"pcm",
    "sampleRate":16000,
    "pitch": 0,
    "volume": 0,
    "speed": 0,
    "digitMode": 0,
    "puncMode": false
  },
  "text": "捷通华声科技股份有限公司，语音合成系统。"
}

4.2 获取音频数据#

会话启动成功后，需要在WebSocket上发送"获取音频"指令，如不发送，服务端仅反馈合成进度，不会主动推送合成的音频数据，具体定义如下：

参数	类型	必选	说明
command	String	是	为 `GET_AUDIO`，表示获取音频数据
config	Object	是	获取音频结构参数
config.timeSlice	Integer	是	预期获取的音频的时长，单位ms ,范围:100~10000

例如：

{
    "command": "GET_AUDIO",
    "config": {
        "timeSlice": 200
    }
}

4.2.1 取消合成#

对于当前正在合成中的会话，需要在Websocket上发送“取消合成”的请求来取消或结束合成。 "取消合成"请求使用文本类型的数据帧 (text message)发送，命令和参数以JSON字符串的形式提供。

参数	类型	必选	说明
command	String	是	为 `CANCEL`，表示中断合成任务

示例:

{
  "command": "CANCEL"
}

4.3 连接阶段响应#

由于WebSocket是全双工的，因此所谓响应就是从服务器端发送给客户端的。

4.3.1 启动合成请求响应#

服务器端收到“启动合成”请求时，会给出如下响应消息，以JSON字符串形式放置在text message中。

参数	类型	必选	说明
respType	String	是	为 `START`，表示合成启动响应
traceToken	String	是	服务内部的跟踪令牌，可用于在日志中追溯具体流程。
warning	Array	否	可能的警告信息

warning 是一个数组，每一项的结构如下：

参数	类型	必选	说明
code	Integer	是	警告代码，具体的警告错误码见后
message	String	是	警告的详细信息

warning 字段说明有正常流程之外的情况发生，但可以继续合成下去。其 code 包括：

警告代码	说明
100	不支持的S3ML标签
101	未找到指定的发音人

成功示例：

{
  "respType": "START",
  "traceToken": "token_abcd_12345"
}

成功且带警告示例：

{
  "respType": "START",
  "traceToken": "token_abcd_12345",
  "warning":
  [
    {
      "code": 100,
      "message": "s3ml tag xxx not supported ignore it"
    },
    {
      "code": 101,
      "message": "voice xxx not found fallback default"
    }
  ]
}

4.3.2 合成音频数据响应#

启动合成任务后，为节省流量，音频以二进制数据帧形式（binary message）的方式发送给客户端。
音频数据将分片发送，也即在服务合成一定量音频数据后就会发送一个binary message。

4.3.3 合成结束时的响应#

参数	类型请求	必选	说明
respType	String	是	为 `END`，表示结束合成响应
traceToken	String	是	服务内部的令牌，可用于在日志中追溯具体流程。
reason	String	是	结束原因，参见下表

reason 的可能取值：

结束原因	说明
NORMAL	正常结束
CANCEL	由客户端发送“取消合成”指令后的响应
ERROR	合成过程中出现错误

示例：

{
  "respType": "END",
  "traceToken": "token_abcd_12345",
  "reason":"NORMAL"
}

{
  "respType": "END",
  "traceToken": "token_abcd_12345",
  "reason":"CANCEL"
}

4.3.4 错误响应#

参数	类型	必选	说明
respType	String	是	为 `ERROR`，表示错误响应
traceToken	String	否	服务内部的跟踪令牌，可用于在日志中追溯具体流程。
errCode	Integer	是	错误码，请参见《AICP 10 开发通用规范》
errMessage	String	是	处理结果的详细描述，主要是错误状态

这里的错误响应，通常是指不影响流程，但当前会话无法再进行下去的错误，包括如下情况：

配置串错误，包括存在不识别的配置串，或者配置串值的范围不合法
时序不正确，比如没有发“开始合成”指令，就发送了“结束合成”指令
合成过程中发生错误

出现错误响应时，如果已经在一个会话中了，会再发送一个“合成结束”的响应，表示合成任务结束。如果任务还没有开始，那么发送此错误响应后不做其它操作，直到收到下一个“开始合成”请求。

返回错误响应后，连接不会关闭，只是会关闭当前会话。客户端仍然可以在同一连接上启动新的会话。但如果在一定时间内出现错误响应的次数超过一定阈值时，服务器端也会发送“严重错误”响应，然后主动关闭连接。

错误响应示例

{
  "respType": "ERROR",
  "traceToken":"token_abce_12345",
  "errCode": 3,
  "errMessage": "parse task config failed"
}

4.3.5 严重错误响应#

参数	类型	必选	说明
respType	String	是	为 `FATAL_ERROR`，表示严重错误响应
traceToken	String	否	服务内部的跟踪令牌，可用于在日志中追溯具体流程。
errCode	Integer	是	错误码，请参见《AICP 10 开发通用规范》
errMessage	String	是	处理结果的详细描述，主要是错误状态

严重错误，通常指流程无法继续的情况。比如当出现以下情况：

连接空闲时间（也即连接上没有任何有效会话）超过一定阈值，目前连接空闲超时时间缺省为2min
在一段时间内连续出现错误情况超过一定次数

出现严重错误响应时，流程不再继续，服务器端会主动断连。

严重错误响应示例

{
  "errCode": 10,
  "respType": "FATAL_ERROR",
  "errMessage": "too many errors",
}

5. 版本记录#

接口版本	平台支持版本	组件及支持版本	修改内容
10.1.0	10D.1	aicp_tts 10.2.0 aicp_tts_h9 10.1.0	1. `extraInfo` 参数位置调整，和其它能力接口一致
10.1.0	10D.1	aicp_tts 10.2.0 aicp_tts_h9 10.1.0	1. `extraInfo` 参数位置调整，和其它能力接口一致
10.0.0	10C.0	aicp_tts 10.0.0	初始版本