# AIkit通用XTTS合成 Windows SDK 文档
# 1. 通用XTTS合成能力简介
离线合成能力能将文字信息转化为声音信息,让应用具备离线语音合成的能力。即让机器像人一样开口说话,给开发者的应用配上“嘴巴“。广泛应用于出行导航服务、阅读听书、智能音箱等行业领域。
支持多实例并发:否
协议类型:异步流式
# 2. 授权说明
# 授权方式支持【设备授权】
设备授权: 按照设备数和有效期授权,激活设备数达到授权量上限后,新设备将无法继续激活使用。SDK采集多个设备标识按照权重算法生成设备指纹精准标识设备,计量准确。支持所有平台。
在能力首次使用时,需要先激活后方可使用。激活时会获取授权license缓存到设备内部存储中。
在线激活: 在首次使用时,需要将设备联网,SDK初始化时获取授权license激活。设备激活后,即可在无网环境下使用。如果有恢复出厂设置或清空应用缓存等操作,将license清除后,能力将无法正常使用,将设备联网重启应用即可恢复。适用于设备可联网场景,激活过程简单。
# 3. 兼容性说明
类别 | 兼容范围 |
---|---|
接口 | C++ 接口 |
网络 | 对网络无要求,设备具备联网条件,可使用在线激活方式,首次使用需要连接网络。若设备不能联网,需要使用离线激活方式 |
开发环境 | 建议使用 Visual Studio 进行开发 |
# 4. SDK包组成
DEMO 中已经集成了SDK, 您可以参考DEMO,集成SDK。集成前,请先测通DEMO,了解调用原理。如果您自己代码过于复杂,可以使用一个helloworld项目了解集成过程。
将SDK zip包解压缩,得到如下文件:
- Demo //能力SDK Demo、SDK使用说明readme.txt,示例能力调用
- SDK //能力SDK,导入SDK库时使用
- resource //能力对应模型资源,多能力组合时,resource文件夹中包含多个子文件夹
- 测试报告 //SDK 测试报告
- ReleaseNotes.txt //SDK版本日志
# 5. 接口调用流程
# 6. 快速集成指南
# 6.1 导入SDK库
将SDK/libs文件夹(包含libAIKit.so、各能力引擎库)、头文件文件夹include存放到项目中,并在环境变量里添加库路径;
#include "aikit_biz_api.h"
#include "aikit_constant.h"
#include "aikit_biz_config.h"
# 6.2 配置权限
SDK工作路径需要读写权限用于存储日志及授权license,缺少读写权限,能力将无法正常使用。
# 6.3 资源导入
复制resource文件夹中文资源到应用的工作目录,即为SDK初始化中的workDir。该路径需要赋可读、可写的权限。
# 6.4 SDK初始化
在使用能力前,需要首先初始化SDK,使用SDK提供的单能力或组合能力时,SDK均只需要初始化一次。SDK V2.2.13+版本SDK初始化示例代码如下:
AIKIT_Configurator::builder()
.app()
.appID("")
.apiKey("")
.apiSecret("")
.workDir("./") //设置SDK工作路径,示例为当前路径
.auth()
.ability("e2e44feff")
.log()
.logLevel(LOG_LVL_INFO)
.logPath("./");
int ret = AIKIT_Init();
if(ret != 0){
printf("AIKIT_Init failed:%d\n",ret);
goto exit;
}
SDK初始化参数中appID、apiKey、apiSecret 和workDir为必填项。
初始化配置选项分为三个部分,分别是应用、授权、日志相关配置,可通过链式的调用方式去配置相关参数。
模块 | 配置选项 | 类型 | 必填 | 说明 |
---|---|---|---|---|
app | appID | string | 是 | 应用ID |
app | apiKey | string | 是 | 离线引擎托管平台创建应用后,生成的唯一应用标识 |
app | apiSecret | string | 是 | 离线引擎托管平台创建应用后,生成的唯一应用秘钥 |
app | workDir | string | 是 | SDK工作目录,默认授权缓存、读取能力资源、写SDK日志在此路径下 |
app | resDir | string | 否 | 指定资源读取路径,不设置默认从workDir读取 |
auth | authType | string | 否 | 离线授权类型(0或1),0-->(默认)设备级授权(DEVICE)和 1-->应用级授权(APP) |
auth | channelID | string | 否 | 渠道ID,存在多个能力集可指定使用的能力集 |
auth | UDID | string | 否 | 用户自定义设备标识,需要服务端配置开启支持后才支持使用,建议设置长度低于256 |
auth | ability | string | 是 | 竞争授权注册的能力id组合,格式如"xxxxx1;xxxxx2",多个能力通过英文分号隔开,如果进行设置,则按照注册的能力进行授权,如果设置为空或者没有设置,则按照旧版sdkid的方式进行授权 |
log | logLevel | int | 否 | 日志的输出等级:LOG_LVL_VERBOSE: verbose日志,日志最全LOG_LVL_DEBUG: debug级别LOG_LVL_WARN:警告级别信息LOG_LVL_INFO: 重要信息LOG_LVL_ERROR:错误级别日志LOG_LVL_FATAL:错误级别日志LOG_LVL_OFF:错误级别日志 |
log | logMode | int | 否 | 模式: LOG_STDOUT:linux 控制台 LOG_FILE:文件形式 |
log | logPath | string | 否 | 输出模式为文件时的文件名称(带有文件名称的路径) |
# 6.5 注册回调监听
SDK 初始化状态及能力结果可通过AIKIT_RegisterAbilityCallback注册能力回调,为每个能力指定一个结果回调监听,示例代码如下:
void OnOutput(AIKIT_HANDLE* handle, const AIKIT_OutputData* output){
printf("OnOutput abilityID :%s\n",handle->abilityID);
printf("OnOutput key:%s\n",output->node->key);
if((output->node->value) && (fin != nullptr))
{
//output->node->value 即为能力计算结果
}
}
void OnEvent(AIKIT_HANDLE* handle, AIKIT_EVENT eventType, const AIKIT_OutputEvent* eventValue){
printf("OnEvent:%d\n",eventType);
if(eventType == AIKIT_Event_End){
//计算结束
}
}
void OnError(AIKIT_HANDLE* handle, int32_t err, const char* desc){
printf("OnError:%d\n",err);
}
AIKIT_Callbacks cbs = {OnOutput,OnEvent,OnError};
AIKIT_RegisterAbilityCallback("e2e44feff",cbs);
AIKIT_Callbacks结构体的成员变量说明
OnOutput
参数 | 类型 | 说明 |
---|---|---|
handle | AIKIT_HANDLE* | 会话handle |
output | AIKIT_OutputData* | 输出数据 |
OnEvent
参数 | 类型 | 说明 |
---|---|---|
handle | AIKIT_HANDLE* | 会话handle |
eventType | AIKIT_EVENT | 事件类型 |
eventValue | AIKIT_OutputEvent* | 事件数据 |
OnError
参数 | 类型 | 说明 |
---|---|---|
handle | AIKIT_HANDLE* | 会话handle |
err | int32_t | 错误码 |
desc | char* | 错误码描述 |
# 6.6 能力调用
# 6.6.1 创建能力会话
通过 start 方法开启会话,传入当前能力所需要指定的参数。示例代码如下:
AIKIT_ParamBuilder* paramBuilder = nullptr;
paramBuilder = AIKIT_ParamBuilder::create();
paramBuilder->param("vcn", "$paramValue",strlen("$paramValue"));
paramBuilder->param("language", "$paramValue");
//paramBuilder->param("pitch", 50);
//paramBuilder->param("volume", 50);
//paramBuilder->param("speed", 50);
//paramBuilder->param("reg", 0);
//paramBuilder->param("rdn", 0);
paramBuilder->param("textEncoding", "$paramValue",strlen("$paramValue"));
ret = AIKIT_Start("$abilityId",AIKIT_Builder::build(paramBuilder),nullptr,&handle);
if(ret != 0) {
printf("AIKIT_Start failed:%d\n", ret);
goto exit;
}
功能参数说明:
功能标识 | 功能描述 | 数据类型 | 取值范围 | 必填 | 默认值 |
---|---|---|---|---|---|
vcn | 发音人模型 | string | xiaoyan:xiaoyan(Female, Chinese), xiaofeng:xiaofeng(Male, Chinese), catherine:catherine(Female, US English)), chongchong:chongchong(Female, Chinese), john:john(Male, US English), christiance:德语, mariane:法语, anna:意大利语, xiaolin:日语, zhongcun:日语, kim:韩语, keshu:俄语, felisa:西班牙语, xiaofang:中文童声, xiaomei:粤语, xiaoyuan:中文普通话, abha:印地语, suparut:泰语, qianqian:中文qianqian, xiaoguan:中文xiaoguan, nannan:中文男童楠楠, ningning:中文男童宁宁, xiaoai:中文诺诺, xiaohou:中文逍遥子, xiaoshi:中文小师, xiaoxi:中文水哥, xiaoxue:中文小雪, yifei:中文一菲, yifeng:中文一峰, yiping:中文一萍, xiaoqian:中文东北话女xiaoqian, yezi:中文四川yezi , kavita:英语印度女kavita, xiaodong:中文山东xiaodong, xiaodu:中文成都xiaodu, xiaokun:中文河南xiaokun, xiaoqiang:中文湖南xiaoqiang, xiaorong:中文四川xiaorong, xiaowang:中文湖北xiaowang, xiaofei:中文合肥xiaofei | 是 | |
language | 合成语种 | int | 1:中文, 2:英文, 3:法语, 5:日语, 6:俄语, 9:德语, 15:意大利语, 16:韩语, 23:西班牙语, 12:粤语, 8:印地语, 27:泰语 | 是 | |
pitch | 合成语调 | int | 最小值:0, 最大值:100 | 否 | 50 |
volume | 合成音量 | int | 最小值:0, 最大值:100 | 否 | 50 |
speed | 合成语速 | int | 最小值:0, 最大值:100 | 否 | 50 |
reg | 英文发音方式 | int | 0:引擎自动判断, 1:按字母发音, 2:按单词发音 | 否 | 0 |
rdn | 数字发音方式 | int | 0:引擎自动判断, 1:按数字发音, 2:按字符串发音 | 否 | 0 |
textEncoding | 文本编码 | string | GBK:GBK编码, UTF-8:UTF-8编码, Unicode:Unicode编码 | 是 |
AIKIT_Start 方法说明:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
ability | char* | 是 | 能力标识ID |
param | AIKIT_BizParam* | 是 | 能力的配置和输入,可使用AIKIT_Builder快捷构建 |
usrContext | void* | 否 | 用户上下文指针,保存在outHandle中,用以回调中使用 |
outHandle | AIKIT_HANDLE**(指针的指针) | 是 | 生成的会话句柄 |
返回:AiHandle
AiHandle对象内部提供isSucess方法,用于判断会话是否启动成功,0=成功,非0失败。
0=成功,其他=错误
# 6.6.2 送入数据
通过调用 AIKIT_Write 方法送入能力输入数据。
AIKIT_Write 方法说明:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
handle | AIKIT_HANDLE* | 是 | AIKIT_Start生成的会话handle |
input | AIKIT_InputData* | 是 | 输入数据 |
送入数据实现代码如下:
AIKIT_DataBuilder* dataBuilder = AIKIT_DataBuilder::create();
//输入文本数据
AiText* textData = AiText::get("text")->data(text.c_str(),text.length())->valid();
dataBuilder->payload(textData);
int ret = AIKIT_Write(handle,AIKIT_Builder::build(dataBuilder));
if (ret != 0) {
printf("AIKIT_Write:%d\n",ret);
goto exit;
}
能力输入数据
数据段名称:text 数据类型:文本
以下是文本输入参数含义说明:
字段 | 含义 | 数据类型 | 取值范围 | 默认值 | 说明 | 必填 |
---|---|---|---|---|---|---|
encoding | 文本编码 | string | utf8, gb2312 | utf8 | 取值范围可枚举 | 否 |
compress | 文本压缩格式 | string | raw, gzip | raw | 取值范围可枚举 | 否 |
format | 文本格式 | string | plain, json, xml | json | 取值范围可枚举 | 否 |
data | 文本数据 | string | 文本大小:0-1M | 否 |
# 6.6.3 获取能力输出结果
获取能力结果
结果将通过 AIKIT_RegisterAbilityCallback 回调返回,AIKIT_RegisterAbilityCallback 接口实现可参考 6.5节;
能力结果数据格式及含义如下:
数据段名称:audio 数据类型:音频
以下是音频输出参数含义说明:
字段 | 含义 | 数据类型 | 取值范围 | 默认值 | 说明 |
---|---|---|---|---|---|
encoding | 音频编码 | string | pcm | pcm | 取值范围可枚举 |
sample_rate | 采样率 | int | 16000 | 16000 | 音频采样率,可枚举 |
channels | 声道数 | int | 1 | 1 | 声道数,可枚举 |
bit_depth | 位深 | int | 16 | 16 | 单位bit,可枚举 |
data | 音频数据 | string | 音频大小:0-10M | ||
frame_size | 帧大小 | int | 最小值:0, 最大值:1024 | 0 | 帧大小,默认0 |
# 6.6.4 结束会话
数据处理完毕,调用AIKIT_End方法结束会话,示例代码如下:
int ret = AIKIT_End(handle);
if (ret != 0) {
printf("AIKIT_End failed : %d\n", ret);
}
AIKIT_End方法说明:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
handle | AIKIT_HANDLE* | 是 | AIKIT_Start生成的会话handle |
# 6.7 SDK逆初始化
当不再使用能力时,需调用逆初始化方法释放资源,示例代码如下:
/**
* SDK逆初始化函数用以释放SDK所占资源 *
@return 结果错误码,0=成功 */
AIKITAPI int32_t AIKIT_UnInit();
# 7. 高级功能
# 7.1 日志配置
可根据需要设置日志输入级别、方式等
/**
* 设置日志级别,模式,以及保存路径
* @param level 日志级别
* @param mode 日志输出模式
* @param path 输出模式为文件时的文件名称
* @return 错误码 0=成功,其他表示失败
*/
AIKITAPI int32_t AIKIT_SetLogInfo(int32_t level, int32_t mode, const char* path);
日志配置参数说明:
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
level | int32_t | 否 | 日志的输出等级: LOG_LVL_VERBOSE:最全日志信息 LOG_LVL_DEBUG: debug级别, LOG_LVL_WARN:警告级别信息 LOG_LVL_INFO: 重要信息 LOG_LVL_ERROR:错误级别日志 LOG_LVL_FATAL:错误级别日志 LOG_LVL_OFF:错误级别日志 |
mode | int32_t | 否 | 模式: LOG_STDOUT:linux 控制台 LOG_FILE:文件形式 |
path | const char* | 否 | 输出模式为文件时的文件名称(带有文件名称的路径) |
# 7.2 获取设备ID
通过传入字符类型的指针地址,来获取设备ID。
/**
* 获取设备ID
* @param deviceID 设备指纹输出字符串
* @return 结果错误码,0=成功
*/
AIKITAPI int32_t AIKIT_GetDeviceID(const char** deviceID);
# 7.3 设置授权时间间隔
设置在线授权校验间隔时长,默认为300s,可自定义设置,最短为60s,最长为24小时,单位秒,示例代码如下:
/**
* 设置授权更新间隔,单位为秒,默认为300秒
* AIKIT_Init前设置
* @param interval 间隔秒数
* @return 结果错误码,0=成功
*/
AIKITAPI int32_t AIKIT_SetAuthCheckInterval(uint32_t interval);
# 7.4 获取SDK版本号
/**
* 获取SDK版本号
* @return SDK版本号
*/
AIKITAPI const char* AIKIT_GetVersion();