Windows SDK

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_ASR_RESULT

说明

实时识别结果

message type

DDS_EV_OUT_ASR_RESULT

payload

key	value type	说明
var	string	识别中间结果，如：“你好”
text	string	表示识别的最终结果
pinyin	string	合成音的文本，拼音

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

DDS_EV_IN_SPEECH

说明

语音事件输入，包含：语音开始，语音结束，值分别为：“start”，"end"

message type
DDS_EV_IN_SPEECH
payload

key	value type	说明
action	string	语音事件，其值分别为： "start"：语音开始； "end"：语音结束；
asrParams	json string	识别的配置参数，在start的时候传入 { "enableVAD": false, "enableRealTimeFeedback": true, "res": "aihome" }
asrPlusParams	json string	asrPlusParams的为声纹配置参数，在start的时候传入（暂不支持） { "users": [ "userId001", "userId002" ], "enableAsrPlus": true, "organization": "org-001", }

DDS_EV_IN_AUDIO_STREAM

说明

音频流，支持两种送音频方式：

1. 在DDS_EV_OUT_RECORD_AUDIO回调中发送音频，此方式为dds主动索要音频(@Deprecated)

2. 用户主动发送音频，忽略DDS_EV_OUT_RECORD_AUDIO回调，不在dds回调线程，直接使用dds_send接口发送音频

message type

DDS_EV_IN_AUDIO_STREAM

payload

key

value type

说明

audio

binary

音频流的值为二进制数据，消息封装如下：

struct dds_msg *msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_AUDIO_STREAM);

dds_msg_set_bin(msg, "audio", data, length);

dds_send(msg);

dds_msg_delete();

DDS_EV_IN_RESET

说明

断开连接，该接口阻塞实现

message type

DDS_EV_IN_RESET
payload

key

value type

说明

keepConnection

boolean

是否在reset的时候保持连接

1 true

0 false

DDS_EV_IN_PHRASE_HINTS

说明

热词设置，目前仅支持基础技术识别时使用

该配置仅对当前dds实例生效，会被下次DDS_EV_IN_PHRASE_HINTS设置更新

设置热词后，会将语音优先识别为热词中的词

message_type

DDS_EV_IN_PHRASE_HINTS

payload

key

value type

说明

phraseHints

json string

热词配置

格式为： [{"type": "vocab", "name": "词库名", "data":["短语1", "短语2"]}]

其中：type为词库类型，目前只支持vocab

示例："[{"type":"vocab","name":"联系人","data":["张三","李四"]}]"

2.3长语音识别消息类型

DDS_EV_OUT_LASR_RT_RESULT

说明

长语音实时识别结果返回消息

message type

DDS_EV_OUT_LASR_RT_RESULT

payload

key	value	说明
sessionId	string	必选：session标志 87569f3a293a4a7b9f12c1832febbb33
onebest	string	和var二选一 rec最优结果 "做一个幸福的人。" 将所有onebest拼接起来得到转写的完整结果。
var	string	和onebest二选一 var中间结果 "做一个"
eof	int	可选 (和onebest一起) 1 or 0 是否最后一帧
state	int	可选 0,7,8,9 9：服务端结束状态 0：识别结果（某个片段的最终结果） 8：识别实时结果（某个片段的中间结果） 7：服务是否可以开始传音频，必须等待该状态之后才可以开始传音频

DDS_EV_OUT_LASR_RT_RAW

说明

长语音实时识别结果返回消息（服务器数据结构），是DDS_EV_OUT_LASR_RT_RESULT的plus版本，包含服务返回的所有参数

message type

DDS_EV_OUT_LASR_RT_RAW

payload

key

value

说明

data

json string

见服务端接口文档 4.4 节

和onebest二选一，var结果，某个片段的中间结果：

{"errno":8,"error":"","data":{"sessionId":"87569f3a293a4a7b9f12c1832febbb33","var":"做一个","speaker":0,"bg":9120}}

和var二选一，onebest结果，某个片段的最优结果：

{"errno":0,"error":"","data":{"sessionId":"87569f3a293a4a7b9f12c1832febbb33","bg":9120,"ed":10760,"onebest":"做一个幸福的人。","speaker":0}}

失败：

原因会通过 DDS_EV_OUT_ERROR 抛出

DDS_EV_OUT_LASR_RAW

说明

长语音识别文件转写返回消息

message type

DDS_EV_OUT_LASR_RAW

payload

key

value

说明

data

json string

见服务端接口文档

五选一，文件上传开始结果，返回音频ID：

{"audio_id":"5f51b27c19465a2dd802b292","slices":0,"total":0,"url":""}

五选一，文件分片上传结果：

{"audio_id":"5f51b27c19465a2dd802b292","slices":1,"total":6,"url":""}

五选一，转写任务创建成功，生成taskID：

{"task_id":"5f51b2883f4126470dfda611"}

五选一，查询转写结果：

{"progress":6}

五选一，获取转写结果（因长度问题部分结果被删掉）：

{
    "_id":"5f51b2883f4126470dfda611",
    "res":"aitransoff_gpu_v14_ygys",
    "res_version":"6.3.32.1_avx.2020.8.10.18:15:02",
    "request":{
        "app_id":"278583711",
        "audio_file_path":"http://lasr-task-audio.oss-cn-hangzhou-internal.aliyuncs.com/beta/20200904/95c83df6e0f043e0bf0ff80992606ce3.wav",
        "audio_id":"5f51b27c19465a2dd802b292",
        "audio_length":5864884,
        "duration":183276,
        "lang":"cn",
        "sample_rates":16000,
        "channel":1,
        "sample_bytes":2,
        "use_txt_smooth":1,
        "use_segment":1
    },
    "segment":[
        {
            "bg":47630,
            "ed":47770,
            "speaker":0,
            "wp":"n",
            "onebest":"我"
        },
        {
            "bg":177910,
            "ed":179310,
            "onebest":"春暖花开。 ",
            "auxinfo":{
                "emotion":"sad",
                "age":"adult",
                "gender":"male"
            }
        }
    ]
}

失败：

原因会通过 DDS_EV_OUT_ERROR 抛出

state

int

必选：文件操作状态：

DDS_LASR_UPLOAD_BEGIN 0 服务端生成audio_id，客户端可以开始文件上传

DDS_LASR_UPLOAD_SLICE 1 客户端分片上传文件的中间结果

DDS_LASR_UPLOAD_END 2 客户端分片上传文件结束

DDS_LASR_TASK_BEGIN 3 请求生成task_id，开始转写流程

DDS_LASR_TASK_PROGRESS 4 返回识别进度

DDS_LASR_TASK_END 5 返回识别结果

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

DDS_EV_IN_LASR_RT_START

说明

实时长语音开始接口

message type

DDS_EV_IN_LASR_RT_START

payload

key

value type

说明

audioParams

json string

必选：音频参数

全部参数见服务端开发文档 4.2 节

{

"audioType":"wav",

"sampleRate":16000,

"sampleBytes":2,

"channel":1

}

lasrParams

json string

可选：识别环境变量

全部参数见服务端开发文档 4.2 节

{

"use_txt_smooth": 1,

"use_tprocess": 1,

"use_sensitive_wds_norm": 1

}

参考代码

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_LASR_RT_START);
dds_msg_set_string(msg, "audioParams", "{\"audioType\": \"wav\", \"sampleRate\": 16000, \"sampleBytes\": 2, \"channel\": 1}");
dds_msg_set_string(msg, "lasrParams", "{\"use_txt_smooth\": 1, \"use_tprocess\": 1, \"use_sensitive_wds_norm\": 1}");
dds_send(msg);
dds_msg_delete(msg);

DDS_EV_IN_AUDIO_LASR

说明

用户主动发送音频，不在dds回调线程，直接使用dds_send接口发送音频

message type

DDS_EV_IN_AUDIO_LASR

payload

key

value type

说明

audio

binary

音频流的值为二进制数据，消息封装如下：

struct dds_msg *msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_AUDIO_LASR);

dds_msg_set_bin(msg, "audio", data, length);

dds_send(msg);

dds_msg_delete();

DDS_EV_IN_LASR_RT_STOP

说明

实时长语音结束接口

message type

DDS_EV_IN_LASR_RT_STOP

payload

none

参考代码

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_LASR_RT_STOP);
dds_send(msg);
dds_msg_delete(msg);

DDS_EV_IN_LASR_FILE_UPLOAD

说明

长语音文件转写服务，上传文件接口

message type

DDS_EV_IN_LASR_FILE_UPLOAD

payload

key	value type	说明
audioParams	json string	必选，音频参数见服务端开发文档 4.2 节 { "audio_type":"wav", "sample_rate":16000, "sample_bytes":2, "channel":1 }
localPath	string	必选，待上传文件路径 ./lasr-file-api.wav
index	int	选填，用于当某个分片文件上传失败的时候，通过需要重传文件 1-N N为分片大小

参考代码

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_LASR_FILE_UPLOAD);
dds_msg_set_string(msg, "localPath", "./lasr-file-api.wav");
dds_msg_set_string(msg, "audioParams", "{\"audio_type\": \"wav\", \"sample_rate\": 16000, \"channel\": 1, \"sample_byte\": 2}");
dds_send(msg);
dds_msg_delete(msg);

DDS_EV_IN_LASR_TASK_CREATE

说明

长语音文件转写服务，创建转写任务接口

message type

DDS_EV_IN_LASR_TASK_CREATE

payload

key	value type	说明
audioParams	json string	必选，音频参数见服务端开发文档 4.4 节 { "audio_type":"wav", "sample_rate":16000, "sample_bytes":2, "channel":1 }
lasrParams	json string	可选：识别环境变量见服务端开发文档 4.4 节 { "use_txt_smooth": 1, "use_inverse_txt": 1, "use_segment": 0 }
audio_id	string	必选，待识别的音频ID 示例：5f51b27c19465a2dd802b292

参考代码

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_LASR_TASKC_CREATE);
dds_msg_set_string(msg, "audioParams", "{\"audio_type\": \"wav\", \"sample_rate\": 16000, \"channel\": 1, \"sample_byte\": 2}");
dds_msg_set_string(msg, "lasrParams", "{\"use_txt_smooth\": 1,\"use_inverse_txt\": 1,\"use_segment\": 0}");
dds_msg_set_string(msg, "audio_id", "5f51b27c19465a2dd802b292");
dds_send(msg);
dds_msg_delete(msg);

DDS_EV_IN_LASR_TASK_QUERY

说明

长语音文件转写服务，查询结果（进度或者结果）接口

message type

DDS_EV_IN_LASR_TASK_QUERY

payload

key

value type

说明

task_id

string

必选，识别的任务ID

示例：5f51b2883f4126470dfda611

参考代码

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_LASR_TASK_QUERY);
dds_msg_set_string(msg, "task_id", "5f51b2883f4126470dfda611");
dds_send(msg);
dds_msg_delete(msg);

2.4语音合成消息类型

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_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服务

2.5声纹消息类型(不支持)

DDS_EV_OUT_VPR_REGISTER

说明

声纹注册服务器返回结果

message type

DDS_EV_OUT_VPR_REGISTER

payload

key

value

说明

raw

json string

声纹注册结果：

成功：

{
    "state":0,
    "data":{
        "option":"register_stop",
        "res_version":"td_vprint-online-0822-nihaoxiaochi",
        "model_types":2,
        "content":"",
        "speech_lack_count":0,
        "thresh":15
    },
    "requestId":"request-id-in-uuid",

"userId":"f4d3bc76e34e41dabed0aaf60b93338f"
}

失败：

原因会通过 DDS_EV_OUT_ERROR 抛出

DDS_EV_OUT_VPR_VERIFY

说明

声纹验证服务器返回结果

message type

DDS_EV_OUT_VPR_VERIFY

payload

key

value

说明

raw

json string

声纹验证结果：

成功：

{
    "state":4,
    "data":{
        "option":"verify_stop",
        "res_version":"sti_vprint-online-0806",
        "model_types":2,
        "content":"",
        "speech_lack_count":0,
        "verify_result":{
            {
            "models":[ // 用户模型得分列表
                {
                    "id":9527110,    // 注册时id
                    "score":20.777687       // 分值
                },
                {
                    "id":9527111,
                    "score":20.777687
                }
            ],
            "n_users":2, // 用户总数
            "result_id":9527110   // 内核选中的用户id
        }
        }
    },
    "thresh":15,
    "requestId":"request-id-in-uuid",

"userId":"f4d3bc76e34e41dabed0aaf60b93338f"
}

失败：

原因会通过 DDS_EV_OUT_ERROR 抛出

DDS_EV_OUT_VPR_UNREGISTER

说明

声纹取消注册服务器返回结果

message type

DDS_EV_OUT_VPR_UNREGISTER

payload

key

value

说明

raw

json string

声纹取消注册结果：

成功：

{
    "state":0,
    "requestId":"request-id-in-uuid",
    "data":{"count":1}
}

失败：

原因会通过 DDS_EV_OUT_ERROR 抛出

DDS_EV_OUT_ASR_VPR_RESULT

说明

ASR识别声纹返回结果

message type

DDS_EV_OUT_ASR_VPR_RESULT

payload

key

value

说明

raw

json string

声纹识别结果：

{
    "speakerLabels":[
        {
            "rec":"识别结果",
            "bg":350,
            "speakerId":"zhangsan",
            "ed":10150
        }
    ]
}

失败：

原因会通过 DDS_EV_OUT_ERROR 抛出

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

DDS_EV_IN_VPR_REGISTER

说明

云端声纹注册接口

message type

DDS_EV_IN_VPR_REGISTER

payload

key	value type	说明
path	string	必选，用于注册声纹的原始音频文件路径；为了保证注册效果，有效音频长度不低于15秒 "/tmp/vpr_register.pcm"
params	json string	必选，音频文件描述 { "organization": "org-001", "userId":"userId001", "audio": { "audioType": "wav", "sampleRate": 16000, "channel": 1, "sampleBytes": 2 } }

参考代码

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_VPR_REGISTER);
dds_msg_set_string(msg, "path", "/tmp/vpr_register.pcm");
dds_msg_set_string(msg, "params", "{\"userId\": \"userId001\",\"organization\": \"org-001\"}");
dds_send(msg);
dds_msg_delete(msg);

DDS_EV_IN_VPR_VERIFY

说明

云端声纹验证接口

message type

DDS_EV_IN_VPR_VERIFY

payload

key

value type

说明

path

string

必选，用于声纹验证的原始音频文件路径；为了保证识别效果，有效音频长度不低于10秒

"/tmp/vpr_verify.pcm"

params

json string

必选，需要验证的usrId列表，音频文件描述

{

"users": ["userId001", "userId002"],

"organization": "org-001",

"audio": {

"audioType": "wav",

"sampleRate": 16000,

"channel": 1,

"sampleBytes": 2

}

参考代码

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_VPR_VERIFY);
dds_msg_set_string(msg, "path", "/tmp/vpr_register.pcm");
dds_msg_set_string(msg, "params", "{\"users\": [\"userId001\",\"userId002\"],\"organization\": \"org-001\"}");
dds_send(msg);
dds_msg_delete(msg);

DDS_EV_IN_VPR_UNREGISTER

说明

云端声纹取消注册接口

message type

DDS_EV_IN_VPR_UNREGISTER

payload

key

value type

说明

params

json string

必选，需要取消注册的userId标识

{

"userId": "userId001",

"organization": "org-001"

}

参考代码

msg = dds_msg_new();
dds_msg_set_type(msg, DDS_EV_IN_VPR_UNREGISTER);
dds_msg_set_string(msg, "params", "{\"userId\": \"userId001\",\"organization\": \"org-001\"}");
dds_send(msg);
dds_msg_delete(msg);

2.6通用消息类型

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_OUT_WEB_CONNECT

说明

和DUI平台tcp连接状态

message type

DDS_EV_OUT_WEB_CONNECT

payload

key	value	说明
result	string	connected/disconnected

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

DDS_EV_IN_EXIT

说明

退出dds

message type

DDS_EV_IN_EXIT

payload

无

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

详见sdk开发包