语音合成开发手册(windows)

1. 前提

· 音频参数：采样频率为16KHz，每个采样点2Bytes，单通道；

· 播放器能播放url mp3格式；

· 有物理按键(可选)。

· 预先授权(云端功能概述)

2. 消息格式

dds接口之间通过Message Pack格式交互数据，协议说明详见：http://msgpack.org/;

格式为：message type + payload；其中payload是key，value格式；key是字符串，value可以为：int, double, boolean, string, bin类型，其中bin类型是二进制数据；

2.1 消息接口

struct dds_msg;
 
/* 消息创建与释放 */
struct dds_msg *dds_msg_new();
int dds_msg_delete(struct dds_msg *msg);
 
/* 消息封装接口 *//* 注意，以下接口中char *key, char *value这两个参数不能为NULL */
int dds_msg_set_type(struct dds_msgt *msg, int type);
int dds_msg_set_integer(struct dds_msg *msg, char *key, int value);
int dds_msg_set_double(struct dds_msg *msg, char *key, double value);
int dds_msg_set_boolean(struct dds_msg *msg, char *key, int value);
int dds_msg_set_string(struct dds_msg *msg, char *key, char *value);
int dds_msg_set_bin(struct dds_msg *msg, char *key, char *value, int value_len);int dds_msg_set_bin_p(struct dds_msg *msg, char *key, char *value, int value_len);/*该接口保存二进制数据的指针，不复制具体的数据内容，适用于内存较小的场景*/
 
/* 消息解析接口 */
int dds_msg_get_type(struct dds_msgt *msg, int *type);
int dds_msg_get_integer(struct dds_msg *msg, char *key, int *value);
int dds_msg_get_double(struct dds_msg *msg, char *key, double *value);
int dds_msg_get_boolean(struct dds_msg *msg, char *key, int *value);
int dds_msg_get_string(struct dds_msg *msg, char *key, char **value);
int dds_msg_get_bin(struct dds_msg *msg, char *key, char **value, int *value_len);int dds_msg_get_bin_p(struct dds_msg *msg, char *key, char **value, int *value_len);
 
/* 消息调试接口 */
void dds_msg_print(struct dds_msg *msg);

2.2 语音合成消息类型

DDS_EV_OUT_TTS

说明

语音合成音频url地址，一般为mp3格式

message type

DDS_EV_OUT_TTS

payload

key	value type	说明
speakUrl	string	合成音url地址，如: "http://tts.dui.ai/runtime/v1/cache0f91269784b3bcb9401e6854011e04f4e4f1b3ce"
source	string	产生合成的原因，"dui"：dui对话返回，"external"：触发语音合成的合成音
nlg	string	合成音的文本，可选
stream	binary	实时返回音频，空音频表示结束，与语音合成参数enableRealTimeFeedback配合使用，可选

DDS_EV_OUT_ERROR

说明

dds异常

message type
DDS_EV_OUT_ERROR

payload

key

value type

说明

error

string

异常提示信息

errorId

int

错误码，错误码的定义如下：

宏定义	数值	说明
DDS_ERROR_FATAL	1001	oauth授权错误
DDS_ERROR_TIMEOUT	1002	请求超时
DDS_ERROR_NETWORK	1003	网络错误
DDS_ERROR_SERVER	1004	服务返回结果异常
DDS_ERROR_LOGIC	1005	接口调用逻辑错误
DDS_ERROR_INPUT	1006	输入参数错误

source

string

错误是在哪个连接上产生的，tts表示请求自定义合成报错

subId

int

对DDS_ERROR_NETWORK和DDS_ERROR_TIMEOUT，这两种错误类型的详细描述

数值	说明
1100	websocket连接握手失败
1101	websocket的tcp连接失败
1102	lite tts请求的tcp连接失败
1103	websocket连接异常关闭
1104	lite tts请求的返回异常
1105	lite tts请求超时
1106	websocket请求超时

DDS_EV_OUT_DUI_LOGIN

说明

该事件表示授权完成

message type

DDS_EV_OUT_DUI_LOGIN

payload

key	value type	说明
deviceName	string	成功
error	string	错误描述

-------------------------------------------------

DDS_EV_IN_EXIT

说明

退出dds

message type

DDS_EV_IN_EXIT

payload

无

DDS_EV_IN_CUSTOM_TTS_TEXT

说明

合成接口，开发者可以自定义需要合成的文本，该接口在0.2.9之后的版本实现

message type

DDS_EV_IN_CUSTOM_TTS_TEXT

payload

key	value type	说明
text	string	需要合成的中文文本
voiceId	string	必选，合成音的音色
speed	double	可选，合成音的速度
volume	int	可选，合成音的音量大小
mode	string	可选， text\|ssml，默认text
enableRealTimeFeedback	bool	可选，0\|1，默认0，返回spealUrl; 取值1，实时返回音频流

DDS_EV_IN_TTS_RESET

说明

退出tts, 仅对 DDS_EV_IN_CUSTOM_TTS_TEXT设置enableRealTimeFeedback 有效

message type

DDS_EV_IN_TTS_RESET
payload

key

value type

说明

voiceCopy

int

可选，0|1，默认0

1 只断开复刻服务

0 只断开TTS服务

3. 软件接口

dds_ev_callback

typedef int (*dds_ev_callback)(void *userdata, struct dds_msg *msg);

事件回调函数，所有的DDS_EV_OUT事件都会通过该接口告诉开发者

struct dds_opt

struct dds_opt {

dds_ev_callback _handler;

void *userdata;

};

结构体成员

· _handler：事件回调函数；

· userdata：用户数据。

dds_start

int dds_start(struct dds_msg *conf, struct dds_opt *opt);

函数功能

启动dds，该接口会一直阻塞，需要在一个单独的线程里面调用执行，通过事件回调函数和系统交互；通过发送事件DDS_EV_IN_EXIT，让其退出。

参数

· conf：dds配置，开发需要配置productId、aliasKey、deviceProfile，这三个值，需要在dui控制台上获取。
配置示例如：

struct dds_msg *msg = dds_msg_new();

dds_msg_set_string(msg, "productId", "100000xxxx");

dds_msg_set_string(msg, "aliasKey", "prod");
dds_msg_set_string(msg, "savedProfile", "xxxx"); //xxx为设备对应的profile文件的路径

其它参数

· opt：可选配置参数，有事件回调函数和用户数据

返回值

0：成功
-1: 失败

dds_send

int dds_send(struct dds_msg *msg);

函数功能

发送数据给dds，一般是DDS_EV_IN_事件，该接口线程安全。

参数

· msg：消息数据，先创建消息，调完dds_send以后，该消息即可释放。

返回值

0：成功
1：失败

4. Example

语音合成用于将用户的语音合成文本转化成音频，输入文本，输出url。

4.1 语音合成文本输入

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_CUSTOM_TTS_TEXT);
dds_msg_set_string(msg, "text", "今天天气非常好");//需要合成的文本
dds_msg_set_string(msg, "voiceId", "zhilingf");//发音人，必选
dds_send(msg);
dds_msg_delete(msg);
msg = NULL;

4.2 语音合成结果输出

static int dds_ev_ccb(void *userdata, struct dds_msg *msg) {
    int type;
    if (!dds_msg_get_type(msg, &type)) {
        switch (type) {
            case DDS_EV_OUT_ERROR: {
                char *value;
                if (!dds_msg_get_string(msg, "error", &value)) {
                    printf("DDS_EV_OUT_ERROR: %s\n", value);
                }
                break;
           }
           case DDS_EV_OUT_TTS: {
               char *value;
               if (!dds_msg_get_string(msg, "speakUrl", &value)) {
                    printf("speakUrl: %s\n", value);//合成的结果以url的形式返回
                    is_get_tts_url = 1;
               }
              if (!dds_msg_get_string(msg, "nlg", &value)) {
                  printf("nlg: %s\n", value);
              }
              break;
          }
          default:
              break;
       }
   }
    return 0;
}