AIUI语音SDK集成文档

1 SDK简介

能力	说明
语音识别	将语音转换成文字，支持中文离线和在线识别。
语义理解	将文本进行语义理解，转换成指令下发。
语音合成	将文字转换成语音，支持英文离线合成，中文在线合成。
语音唤醒 *	检测语音中的关键词，在检测到关键词时通知外部。用于开发一些由语音触发的功能。支持离线。
声纹验证 *	识别说话人的声纹特征，用于判断说话人的身份。支持离线。
性别年龄 *	识别说话人的音色，用于判断说话人的性别年龄，可用于个性化问答

备注

带*星号的能力需要vtn配合使用，后面会有详细说明

警告

若非特别说明，SDK所有接口默认接收16k采样率，16bit编码，小端序的PCM音频数据输入。

SDK对各平台的支持情况：

平台	支持的架构	开发语言	SDK包形式
Android	armeabi-v7a, arm64-v8a, x86, x86_64	Java	.jar包 + so库
Linux	arm, aarch64, x86, x86_64, mips, loongArch	C/C++	.h头文件 + .so库
Windows	x86, amd64	C/C++	.h头文件 + .lib库 + .dll库

备注

支持所有 gnu-gcc 编译的平台，客户可以提供编译链来交叉编译

2 Linux & Windows 平台

Linux和Windows两个平台上调用的都是C++ SDK，接口完全一样，这里放在一起进行介绍。

2.1 准备工作

2.1.1 引入SDK包

将头文件（位于SDK包的include目录）和SDK库（Linux上为 libaiui.so，Windows上为 aiui.lib 和 aiui.dll）放到目标工程中。

如果要用到 语音唤醒，还要添加 vtn 库（Linux上为 lib_vtn_mic1.so，Windows上为 vtn_mic1.dll)。

备注

vtn_mic1 指的是单麦降噪唤醒，如需其他多麦降噪唤醒，请在 AIUI开放平台 联系商务。

2.1.2 准备资源

将要用到的资源文件（在SDK包AIUI目录下）复制到具有访问权限的文件夹即可。

2.1.3 认识配置文件

AIUI集成了众多能力，一般不可能全部都用得上，可以通过配置文件内参数的方式，选择需要的能力，示例如下：

• 交互参数 interact

字段名	类型	参考值	必选	说明
interact_timeout	string	“10000”	否	-1 为永不超时，大于0的数为超时毫秒数
result_timeout	string	“5000”	否	结果超时时间，默认 5000ms

• 全局参数设置 global

字段名	类型	参考值	必选	说明
scene	string	main_box	是	aiui中台配置的场景名

• 语音云登录参数 login

字段名	类型	参考值	必选	说明
appid	string	xxxxxxxxx	是	平台申请的应用 appid
key	string	xxxxxxxxx	否	平台申请的应用 key, 默认打包在动态库中

• 音频端点检测参数 vad

字段名	类型	参考值	必选	说明
vad_enable	bool	true	否	是否启用端上VAD能力
engine_type	string	meta	是	启用的VAD类型，目前可选 meta、 fix_front。待增加 2 evad， avvad。
vad_output_enable	bool	false	否	在 EVENT_VAD 事件中是否需要带出音频
res_type	string	path	否	assets 仅android使用，资源放在apk包中， path 为系统资源路径
res_path	string	AIUI/assets/evad.jet	否	指定引擎所需要的资源路径
vad_bos	string	“5000”	否	前端点超时时间，默认为5000ms
vad_eos	string	“1000”	否	后端点超时时间，默认为1000ms
cloud_vad_info	string	“end”	否	固定值，适配云端语义VAD 2

• 云端识别段配置 iat

字段名	类型	参考值	必选	说明
sample_rate	string	“16000”	否	仅能设置为 16000，默认可不填

• 唤醒段配置 ivw

字段名	类型	参考值	必选	说明
mic_type	string	mic1	是	设置要加载的唤醒引擎版本
res_type	string	path	否	assets 仅android使用，资源放在apk包中， path 为系统资源路径
res_path	string	vtn.ini;hlw.cfg	是	设置引入的唤醒配置路径，其中 hlw.cfg 为免唤醒配置，可不配置
vtn_path 1	string	vtn_mic1.dll	否	手动设置唤醒库的位置，默认在aiui库同级的目录搜索
zeroshot_enable *	bool	false	否	免唤醒入口开关 要使用这个能力，请联系我们技术支持

警告

zeroshot_enable 免唤醒开关不要轻易开启，需在我司支持人员指导下进行开发，可能因操作不当导致sdk无法正常工作。

• 离线合成段配置 tts

字段名	类型	参考值	必选	说明
ent 2 *	string	xtts	否	设置离线TTS引擎，默认为 msc
local_engine	string	cloud	是	切换离在线， local 为离线， cloud 为在线
res_type	string	path	否	assets 仅android使用，资源放在apk包中， path 为系统资源路径
res_path	string	common.jet;xiaoxue.jet	是	设置离线引擎所需要的资源路径，多个资源以 ; 分割
voice_name	string	xiaoxue	是	设置合成发言人
volume	string	“100”	否	设置合成音量

小技巧

线上版本不支持离线合成，如需请联系我司商务开通相关权限

• 离线识别配置 2 esr

字段名	类型	参考值	必选	说明
engine_type	string	wfst_fsa	是	wfst_fsa 离线听写+离线命令词匹配模式， wfst 离线听写模式， fsa 离线命令词匹配模式
pgs_enable	string	“0”	否	控控制离线听写模式开启时是否有流式听写结果返回
res_type	string	path	否	assets 仅android使用，资源放在apk包中， path 为系统资源路径
res_path	string	AIUI/esr/esr.jet	是	设置离线引擎所需要的资源路径，可为AIUI工作路径的相对路径
preloads	json	[{ “id”: 2, “res_type”: “path”, “res_path”: “AIUI/esr/music.fsa” }]	否	配置初始化时默认编译加载的离线语法资源，可以配置多条预加载的资源， 在每一条配置中需要声明编译加载语法的ID和语法文件路径。
threshold	string	“5000”	否	置信度，和结果中的 score 对比，需要多次测试得出

小技巧

线上版本不支持离线识别，如需请联系我司商务开通相关权限

• 业务相关参数 speech

字段名	类型	参考值	必选	说明
wakeup_mode 2	string	off	否	设置唤醒引擎， serialport 为降噪板 ivw 为开放平台单麦70唤醒 hlw 为 hlw 兼容唤醒 vtn 为最新支持的71唤醒 默认为 off
interact_mode	string	continuous	否	设置交互默认， continuous 为一次唤醒持续交互， oneshot 为唤醒一次交互一次
intent_engine_type	string	cloud	是	设置语义理解工作模式， cloud 为纯在线交互， local 为纯离线模式， mixed 为混合模式， pipe 串行模式 2
audio_captor	string	off	否	内部录音的驱动， system 为系统单通道录音， portaudio 为独立声卡使用，可录制多通道音频

小技巧

pipe 模式需要开通权限，如需请联系我司商务开通

• 录音参数 2 recorder

字段名	类型	参考值	必选	说明
channel_count	int	8	是	录音板录制的最大声道数
channel_filter	string	“”	否	音频通道规整，-1 代表生成一个0填充的声道数据
sound_card_name	string	“”	否	指定录音声卡名
sample_size	int	2	否	指定录音采样值， 2 为16bit， 4 为32bit数据

• 日志设置 log

字段名	类型	参考值	必选	说明
debug_log	bool	“0”	否	输出大量日志， 1 或 0
save_datalog	bool	“0”	否	保存交互音频及交互日志
datalog_path	string	“”	否	保存音频的存储位置，默认指向AIUI工作目录
datalog_size	int	1024	否	保存的音频总大小，单位为 MB
raw_audio_path	string	“”	否	内部录音时保存原始音频的存储位置，默认指向AIUI工作目录

• 云端透传参数 2 attachparams

字段名	类型	参考值	必选	说明
iat_params	string		否	暂无
nlp_params	string		否	暂无
tts_params	string	tts_res_type=url_v2,vcn=xiaoyan	否	指定云端合成所需要的参数， = 表示键值对， , 为分割符 tts_res_type 设置合成下发方式，默认是 pcm 数据流， url_v2 为mp3链接 vcn 为指定合成发言人 2 ，默认为 xiaoyan 详见语音合成

• 语音透传参数 audioparams

字段名	类型	参考值	必选	说明
msc.lng	string	“117.16334474130745”	否	经度
msc.lat	string	“31.821021912318592”	否	维度
pers_param	string	“{"appid":"","uid":""}”	否	个性化参数 appid 表明为appid级别个性化 uid 表明为用户级个性化

1

将在新版本 5.6.1071.0000 中实现。

2(1,2,3,4,5,6,7,8,9)

定制参数，使用前请咨询我司技术支持

简单示例：

{
   "global": {
      "scene": "main_box"
   },

   "login": {
      "appid": "xxxxxxxx"
   },

   "vad": {
      "engine_type": "meta"
   },

   "ivw": {
      "mic_type": "mic1",
      "res_path": "AIUI/assets/vtn/vtn.ini"
   },

   "speech": {
      "wakeup_mode": "vtn",
      "interact_mode": "continuous",
      "intent_engine_type": "cloud",
      "audio_captor": "system"
   },

   "recorder": {
      "channel_count": 1,
      "channel_filter": "0,-1"
   },

   "attachparams": {
      "tts_params":"tts_res_type=url_v2"
   }
}

2.1.4 初始化SDK前准备

备注

无其他特殊声明， C 示例需要包含 AIUI_C.h 头文件。 C++ 示例需包含 aiui_v2.h 头文件， aiui.h 因兼容性问题，已被废弃

在创建AIUI的 agent 之前，需要设置一些全局参数

• 设置AIUI-SDK的工作目录，默认使用当前目录下的 AIUI 目录

  • C++示例:

    AIUISetting::setAIUIDir("D:\\Works\\AIUI");
    

  • C 示例:

    aiui_set_aiui_dir("D:\\Works\\AIUI");
    

• 设置SDK内部输出的日志等级， _debug 为记录详细会话日志， _none 完全关闭日志

  • C++示例:

    AIUISetting::setNetLogLevel(aiui::_debug);
    

  • C 示例:

    aiui_set_net_log_level(aiui_debug);
    

• 设置设备唯一ID， 这个很重要

  • C++示例:

    AIUISetting::setSystemInfo(AIUI_KEY_SERIAL_NUM, "unique-id-created-by-yourself");
    

  • C 示例:

    aiui_set_system_info(AIUI_KEY_SERIAL_NUM, "unique-id-created-by-yourself");
    

  备注

  sn 属于必传参数，否则sdk初始化的时候无法成功， 可以由本机的MAC地址实现，需保证每台设备唯一， 否则导致装机量不准。具体可以参考线上SDK包内的示例。

  警告

  通过 setSystemInfo 设置 sn 是必填选项，否则在 MyListener::onEvent() 中接收到 EVENT_ERROR。显示 must provide serial num, set by AIUISetting.setSystemInfo(KEY_SERIAL_NUM, xxx)。

2.1.5 初始化SDK

SDK只有在初始化成功之后才能使用，否则一创建接口对象即会抛出异常。使用IAIUIAgent和IAIUIListener进行初始化。

class MyListener : public IAIUIListener
{
public:
   void onEvent(const IAIUIEvent& event) override
   {
      //todo: do someting...
   }
}

MyListener listener;

// 设置aiui工作路径
AIUISetting::setAIUIDir("AIUI");
// 设置aiui的日志输出等级
AIUISetting::setNetLogLevel(aiui_debug);
// 设置设备唯一识别ID，由自己生成，可采用mac地址
AIUISetting::setSystemInfo(AIUI_KEY_SERIAL_NUM, "the-content-you-should-created-by-yourself");

string params = reade_from_file("AIUI/cfg/aiui.cfg");

IAIUIAgent* agent = IAIUIAgent::createAgent(params.c_str(), &listener);

IAIUIAgent *IAIUIAgent::createAgent(const char *params, IAIUIListener *listener, const char *sn);

初始化 aiui agent，并设置 sn ， sn 作为必填参数

在 5.6.1071.0000 版本加入.

2.1.6 SDK状态说明

此时若无其他错误，sdk将进入 STATE_IDLE 待工作状态

状态名称	说明
STATE_IDLE	服务未开启 此时只能进行start（开启服务）操作。
STATE_READY	待唤醒状态 此时可以通过语音（唤醒词）或者直接向服务发送CMD_WAKEUP消息唤醒服务。 调用AIUIAgent.createAgent创建对象之后，服务即为就绪状态
STATE_WORKING	工作状态 此时可以输入语音、文本与AIUI后台进行交互。

具体的转换关系如下图所示：

操作名称	说明
start	启动后默认状态或者向SDK发送 CMD_START 消息。
stop	向SDK发送 CMD_STOP 消息。
wakeup	说出定制唤醒词（默认为“小飞小飞”），或者向SDK发送 CMD_WAKEUP 消息。
reset_wakeup	向SDK发送 CMD_SLEEP 消息。
sleep	休眠，当一段时间内无有效交互（语义）发生。
re_wakeup	在STATE_WORKING状态下，再次说出唤醒词，或者向SDK发送 CMD_WAKEUP 消息。

2.2 命令发送

以手动唤醒为例，说明消息发送的流程，前期初始化SDK成功，会生成一个AIUI agent 句柄，发送消息需要用到。

IAIUIMessage* wakeupMsg = IAIUIMessage::create(AIUIConstant::CMD_WAKEUP);
agent->sendMessage(wakeupMsg);
wakeupMsg->destroy();

• 使用重载的 IAIUIMessage::create 函数，指定消息类型，创建一个消息。

• 用SDK初始化得来的 agent 将消息发送到AIUI内部，此步骤是异步的，会马上返回。

• 调用消息体的 destroy 方法，销毁占用的资源。

• 一个最简单的消息就发送完成了， 待AIUI内部处理好之后，在事件回调 MyListener::onEvent 就可以收到AIUI状态变化

2.3 消息接收

class MyListener : public IAIUIListener
{
public:
   void onEvent(const IAIUIEvent& event) override
   {
      switch(event.getType()) {
         case AIUIConstant::EVENT_RESULT:
         .....
         break;
   }
}

备注

命令类型 & 消息类型 可翻阅头文件。