# 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();
在线
咨询
建议
反馈
体验
中心