# AIKit语音唤醒 Windows SDK 文档
# 1. 语音唤醒简介（能力id：e867a88f2）
该能力可满足无网络环境下在连续语音流中实时检测出关键词片段。SDK轻巧方便，无需网络流量，实时响应，可运行于Android、Linux、Windows等平台Android或嵌入式设备。可用于智能终端、智能家居、家电、车机系统等服务场景。
支持多实例并发：否
协议类型：异步流式
# 2. 授权说明
授权方式支持【设备授权】
设备授权： 按照设备数和有效期授权，激活设备数达到授权量上限后，新设备将无法继续激活使用。SDK采集多个设备标识按照权重算法生成设备指纹精准标识设备，计量准确。支持所有平台。
在能力首次使用时，需要先激活后方可使用。激活时会获取授权license缓存到设备内部存储中。
在线激活: 在首次使用时，需要将设备联网，SDK初始化时获取授权license激活。设备激活后，即可在无网环境下使用。如果有恢复出厂设置或清空应用缓存等操作，将license清除后，能力将无法正常使用，将设备联网重启应用即可恢复。适用于设备可联网场景，激活过程简单。
# 3. 兼容性说明
| 类别 | 兼容范围 |
|---|---|
| 接口 | C++ 接口 |
| 网络 | 设备具备联网条件，可使用在线激活方式，首次使用需要连接网络。 |
| 开发环境 | 建议使用 Virsual 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初始化示例代码如下（2.2.12及之前版本SDK初始化参考下文）：
AIKIT_Configurator::builder()
.app()
.appID("")
.apiKey("")
.apiSecret("")
.workDir("./") //示例为当前路径
.auth()
.ability("e867a88f2")
.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("e867a88f2",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 配置自定义唤醒词
唤醒词由用户自定义在配置文件keyword.txt中。keyword.txt文件要求utf-8的格式，且每个唤醒词占一行，结尾以";"(英文的;)结束。示例如下：
你好小迪;
小白小白;
小T小T;
通过AIKIT_LoadData方法加载配置文件，可加载多个配置文件。通过AIKIT_SpecifyDataSet方法设置要生效的唤醒词文件。
每次会话时，均需要调用AIKIT_SpecifyDataSet设置要生效的唤醒词，AIKIT_LoadData方法初始化之后调用一次即可。
SDK 配置自定义唤醒词示例代码如下：
AIKIT_CustomBuilder *customData = AIKIT_CustomBuilder::create();
customData->text("key_word", "./keyword.txt",strlen("./keyword.txt"),0);//传入唤醒词名称
int ret = AIKIT_LoadData("e867a88f2",AIKIT_Builder::build(customData));
int indexs[]={0};
AIKIT_SpecifyDataSet("e867a88f2","key_word",indexs,1);
个性化数据参数说明
数据段名称：key_word 数据类型：文本
AIKIT_LoadData 方法参数说明：设置唤醒词
设置唤醒词配置文件，可设置多个，初始化前调用一次即可。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| abilityId | char* | 是 | 能力标识ID |
| data | AIKIT_CustomData* | 是 | 个性化数据构造器 |
AIKIT_SpecifyDataSet 方法参数说明：
指定要使用的唤醒词文件数据集合，每次会话开启前需要调用。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| abilityId | char* | 是 | 能力标识ID |
| key | char* | 是 | 个性化资源key |
| indexs | int[] | 是 | 个性化资源索引数组 |
| count | int | 是 | 个性化数据索引数组成员个数 |
AIKIT_PreProcess 方法参数说明：
非必须方法，为避免个性化数据重复加载耗时，可调用该预处理方法，对原始个性化资源进行预处理，再次调用能力时，则引擎会自动加载预处理后的资源。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| abilityId | char* | 是 | 能力标识ID |
| srcData | AIKIT_CustomData* | 是 | 原始数据输入 |
| data | AIKIT_CustomData** | 是 | 结果数据输出 |
# 6.7 能力调用
# 6.7.1 创建能力会话
通过 start 方法开启会话，传入当前能力所需要指定的参数。示例代码如下：
AIKIT_ParamBuilder* paramBuilder = nullptr;
paramBuilder = AIKIT_ParamBuilder::create();
//paramBuilder->param("wdec_param_nCmThreshold", "$paramValue",strlen("$paramValue"));
//paramBuilder->param("gramLoad", false);
ret = AIKIT_Start("e867a88f2",AIKIT_Builder::build(paramBuilder),nullptr,&handle);
if(ret != 0) {
printf("AIKIT_Start failed:%d\n", ret);
goto exit;
}
功能参数说明：
| 功能标识 | 功能描述 | 数据类型 | 取值范围 | 必填 | 默认值 |
|---|---|---|---|---|---|
| wdec_param_nCmThreshold | 门限值 格式 0 0:1500 门限值解释说明：表示第一个自定义唤醒词文本里面第一个词的门限，即可以对不同唤醒词文件里的不同的唤醒词单独设置门限值 | string | 最小长度:0, 最大长度:1024 | 否 | |
| gramLoad | 更新自定义唤醒词 | bool | true:true, false:false | 否 | false |
AIKIT_Start 方法说明：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| ability | char* | 是 | 能力标识ID |
| param | AIKIT_BizParam* | 是 | 能力的配置和输入，可使用AIKIT_Builder快捷构建 |
| usrContext | void* | 否 | 用户上下文指针，保存在outHandle中，用以回调中使用 |
| outHandle | AIKIT_HANDLE**（指针的指针） | 是 | 生成的会话句柄 |
返回：AiHandle
AiHandle对象内部提供isSucess方法，用于判断会话是否启动成功，0=成功，非0失败
0=成功，其他=错误
# 6.7.2 送入数据
通过调用 AIKIT_Write 方法送入能力输入数据。
AIKIT_Write 方法说明：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| handle | AIKIT_HANDLE* | 是 | AIKIT_Start生成的会话handle |
| input | AIKIT_InputData* | 是 | 输入数据 |
送入数据实现代码如下：
AIKIT_DataBuilder* dataBuilder = AIKIT_DataBuilder::create();
//输入音频数据
AiAudio* wavData = AiAudio::get("wav")->data(buffer,bufferLen)->valid();
dataBuilder->payload(wavData);
int ret = AIKIT_Write(handle,AIKIT_DataBuilder::build(dataBuilder));
if (ret != 0) {
printf("AIKIT_Write:%d\n",ret);
goto exit;
}
能力输入数据
数据段名称：wav 数据类型：音频
以下是音频输入参数含义说明：
| 字段 | 含义 | 数据类型 | 取值范围 | 默认值 | 说明 | 必填 |
|---|---|---|---|---|---|---|
| encoding | 音频编码 | string | lame, speex, opus, speex-wb | speex-wb | 取值范围可枚举 | 否 |
| sample_rate | 采样率 | int | 16000, 8000 | 16000 | 音频采样率，可枚举 | 否 |
| channels | 声道数 | int | 1, 2 | 1 | 声道数，可枚举 | 否 |
| bit_depth | 位深 | int | 16, 8 | 16 | 单位bit，可枚举 | 否 |
| data | 音频数据 | string | 音频大小：0-10M | 否 | ||
| frame_size | 帧大小 | int | 最小值:0, 最大值:1024 | 0 | 帧大小，默认0 | 否 |
# 6.7.3 获取能力输出结果
获取能力结果
结果将通过 AIKIT_RegisterAbilityCallback 回调返回，AIKIT_RegisterAbilityCallback 接口实现可参考 6.5节；
能力结果数据格式及含义如下：
数据段名称：rlt 数据类型：文本
以下是文本输出参数含义说明：
字段 含义 数据类型 取值范围 默认值 说明 必填 encoding 文本编码 string utf8, gb2312 utf8 取值范围可枚举 否 compress 文本压缩格式 string raw, gzip raw 取值范围可枚举 否 format 文本格式 string plain, json, xml json 取值范围可枚举 否 data 文本数据 string 文本大小：0-1M 否
输出结果示例：
func_wake_up:{"rlt":[{"sid":"undefine","istart":4,"iresid":1,"iresIndex":0,"iduration":96,"nfillerscore":83645,"nkeywordscore":196206,"ncm_keyword":1993,"ncm_filler":0,"ncm":1993,"ncmThresh":1120,"decConfidence":0.000000,"keyword":"你好小迪","nDelayFrame":0,"wakeUpType":0}]}
- func_wake_up：唤醒结果
| 结果json参数 | 字段含义 |
|---|---|
| sid | 本次会话唤醒的任务id |
| istart | 唤醒词开始时间（单位是10ms） |
| iresid | 唤醒词序号 |
| iresIndex | 无需关注 |
| iduration | 唤醒词持续时间（单位是10ms，例如78表示时间长度是 780ms） |
| nfillerscore | - |
| nkeywordscore | - |
| ncm_keyword | 唤醒词keyword得分 |
| ncm_filler | filler得分 |
| ncm | 唤醒词得分 |
| ncmThresh | 唤醒词门限 |
| decConfidence | - |
| keyword | 识别到的唤醒词 |
| nDelayFrame | - |
| wakeUpType | 唤醒类型 |
pl: “ - ” 意味着该参数不重要，无需关注。
# 6.7.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.8 SDK逆初始化
当不再使用能力时，需调用逆初始化方法释放资源，示例代码如下：
/**
* SDK逆初始化函数用以释放SDK所占资源 *
@return 结果错误码，0=成功 */
AIKITAPI int32_t AIKIT_UnInit();
/**
* 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 个性化数据卸载
已加载的个性化数据，如果不在使用或者需要替换，需要卸载已加载的个性化资源，示例代码如下：
/**
* 个性化数据加载
* @param ability 能力唯一标识
* @param key 个性化数据唯一标识
* @param index 个性化数据索引
* @return 错误码 0=成功，其他表示失败
*/
AIKITAPI int32_t AIKIT_UnLoadData("e867a88f2", "key_word", int index);
可配置参数
| 参数 | 类型 | 说明 |
|---|---|---|
| ability | String | 能力id |
| key_word | String | 个性化数据唯一标识 |
| index | String | 个性化数据索引 |
# 7.4 设置授权时间间隔
设置在线授权校验间隔时长，默认为300s，可自定义设置，最短为60s，最长为24小时，单位秒，示例代码如下：
/**
* 设置授权更新间隔，单位为秒，默认为300秒
* AIKIT_Init前设置
* @param interval 间隔秒数
* @return 结果错误码，0=成功
*/
AIKITAPI int32_t AIKIT_SetAuthCheckInterval(uint32_t interval);
# 7.5 获取SDK版本号
/**
* 获取SDK版本号
* @return SDK版本号
*/
AIKITAPI const char* AIKIT_GetVersion();
