本文为您介绍NUI SDK的关键接口、调用步骤及代码示例。
前提条件
下载SDK
在阿里云智能语音交互管控台项目功能配置页面,下载SDK。
关键接口
asr_engine_init
void *asr_engine_init(void);
功能:初始化引擎。
返回值:返回handle供后续api使用。
asr_engine_start
int asr_engine_start(void *handle);
功能:启动引擎,引擎启动后直到用户调用asr_engine_stop将一直工作。
参数handle:asr_engine_init返回的handle。
返回值:ERROR_CODE,0为成功,1为失败,2为参数错误。
asr_engine_feed_data
int asr_engine_feed_data(void handle, char data, int data_size);
功能:向音频引擎提供录音数据。
参数:
handle:asr_engine_init返回的handle。
data:音频数据。
data_size:音频数据长度,单位为字节,可以是任意长度。
返回值:ERROR_CODE,0为成功,1为失败,2为参数错误。
asr_engine_stop
int asr_engine_stop(void *handle)
功能:暂停引擎。
参数handle:asr_engine_init返回的handle。
返回值:ERROR_CODE,0为成功,1为失败,2为参数错误。
asr_engine_finalize
int asr_engine_finalize(void *handle)
功能:释放引擎。
参数handle:asr_engine_init返回的handle。
返回值:ERROR_CODE,0为成功,1为失败,2为参数错误。
asr_engine_get_property
int asr_engine_get_property(ASR_PROPERTY_TYPE property_type, char* value, int length);
功能:获取引擎属性。
参数:
value:属性。
length:value的长度。
property_type:属性类型,下表列出可选属性,参数定义见SDK头文件。
属性
说明
ASRPropertyAEC
是否支持AEC。
ASRPropertyInitOnce
是否只支持初始化一次。
ASRPropertyNeedAuth
是否需要鉴权。
ASRPropertySupportFFVP
是否支持返回前端处理后的音频。
ASRPropertySupportVAD
是否支持返回VAD的音频。
ASRPropertyNeedAuthEveryTime
是否每次都需要联网鉴权。
ASRPropertyMixPcmFormat
参考声道和录音声道的顺序,0为参考在前,1为录音在前。
ASRPropertyDynamicWuws
返回目前设置的所有命令词。
ASRPropertyErrorCode
初始化错误码。
返回值:ERROR_CODE,0为成功,1为失败,2为参数错误。
asr_engine_set_params
ASR_ERROR_CODE asr_engine_set_params(ASR_PARAM_TYPE param_type, unsigned long value_size, void *value);
功能:用以给引擎设置参数。
参数:
value_size:设置数据长度。
value:设置数据。
param_type:参数类型,下表列出可选参数类型,定义见SDK头文件。
参数类型
说明
ASR_PARAM_EVENT_CB
设置引擎事件回调,需要在asr_engine_init之前调用。
ASR_PARAM_ENABLE_AEC
设置引擎使能AEC,默认开启,暂不支持关闭。
ASR_PARAM_MIC_NUM
设置麦克风数量,暂不支持动态修改。
ASR_PARAM_REF_NUM
设置参考声道数量,暂不支持动态修改。
ASR_PARAM_ENABLE_FFVP
设置使能返回前端音频,暂不支持。
ASR_PARAM_ENABLE_VAD
设置使能返回VAD音频,默认返回,暂不支持修改。
ASR_PARAM_ENABLE_DEBUG
设置使能debug模式,设置“1”为开启,“0”为关闭,开启debug模式后会在ASR_PARAM_SET_DEBUG_PATH指定路径生成相关debug文件。
ASR_PARAM_SET_DEBUG_PATH
设置debug文件保存路径。
ASR_PARAM_SET_PRODUCT_ID
设置product_id。
ASR_PARAM_SET_SDK_CODE
设置SDK CODE,暂不用设置。
ASR_PARAM_SET_NUI_APPKEY
设置appkey,需要在asr_engine_init之前调用。
ASR_PARAM_SET_AK_ID
设置access id,需要在asr_engine_init之前调用。
ASR_PARAM_SET_AK_KEY
设置access key,需要在asr_engine_init之前调用。
ASR_PARAM_DIRECT_IP
暂不支持。
ASR_PARAM_SET_WORKSPACE
设置工作路径,需要在asr_engine_init之前调用。
ASR_PARAM_SET_MODE
设置工作模式,0为KWS模式(唤醒),1为VAD模式(不用唤醒直接进行识别),2为命令词模式。
ASR_PARAM_SET_WUWS
设置快捷词,一次调用仅设置一个,如果value是NULL则清空所有快捷词。
ASR_PARAM_ENABLE_WUW_SAVE
设置是否保存唤醒音频数据至云端,暂不支持。
ASR_PARAM_SET_API_KEY
设置第三方APIKEY,初始化必要字段。
ASR_PARAM_SET_DEVICE_ID
设置DEVICE_ID,初始化必要字段。
ASR_PARAM_SET_GAIN
设置软件增益,暂不支持。
ASR_PARAM_ENABLE_ASR
是否开启在线ASR,”1“为开启,”0“为关闭。
ASR_PARAM_ENABLE_DIALOG
是否开启内置对话,暂不支持。
ASR_PARAM_ENABLE_THIRDPARTY_CONTENT_SUPPORT
是否使能云端第三方内容服务支持,暂不支持。
ASR_PARAM_ENABLE_CMD
是否使能命令模式,暂不支持。
返回值:ERROR_CODE,0为成功,1为失败,2为参数错误。
asr_engine_vad_read
int asr_engine_vad_read(void handle, char data, int data_size);
功能:读取vad数据。仅收到vad start事件后有效,调用不会阻塞,需要不停调用来获取所有vad数据,直到vad end发生。
参数:
handle:asr_engine_init返回的handle。
data:放vad数据的buffer。
data_size:放vad数据的buffer长度,单位为字节。
返回值:ERROR_CODE,0为成功,1为失败,2为参数错误。
asr_engine_interactive
int asr_engine_interactive(void *handle);
功能:重置引擎状态并强制切换到INTERACTIVE模式。
参数handle:asr_engine_init返回的handle。
返回值:ERROR_CODE,0为成功,1为失败,2为参数错误。
事件
回调事件方法的原型如下:
void (*asr_event_callback)(ASR_EVENT_TYPE event_type, int cmd, const char *result)
其中ASR_EVENT_TYPE事件类型如下:
事件 | 说明 |
---|---|
ASR_EVENT_AUTH_SUCCESS | 鉴权成功(暂不支持,通过asr_engine_init返回值判断) |
ASR_EVENT_AUTH_FAIL | 鉴权失败(暂不支持,通过asr_engine_init返回值判断) |
ASR_EVENT_AWAKE_SUCCESS | 唤醒事件 |
ASR_EVENT_AWAKE_CMD | 唤醒事件(和ASR_EVENT_AWAKE_SUCCESS一起发生,可以不用处理) |
ASR_EVENT_VAD_START | 人声开始事件 |
ASR_EVENT_VAD_END | 人声结束事件 |
ASR_EVENT_VAD_TIMEOUT | 唤醒后持续10s没有人声开始事件或者设置VAD模式下超过10s没有人声开始事件 |
ASR_EVENT_PARTIAL_ASR_RESULT | ASR中间结果 |
ASR_EVENT_FINAL_ASR_RESULT | ASR最终结果 |
ASR_EVENT_DIALOG | 对话结果 |
ASR_EVENT_ERROR | 错误导致引擎重置为STOP状态 |
其中cmd参数可以配合完成命令词的功能,用于表明唤醒的命令词是哪个,需要和ASR_PARAM_SET_WUWS配合使用。
使用ASR_PARAM_SET_WUWS设置一个命令词时,其value_size
参数将作为一个value保存在一个key-value map中,这个value将作为cmd在asr_event_callback中返回给用户,从而指明是哪个唤醒词被唤醒,如果是主唤醒词,那么这个cmd的value是0,请勿设置value_size为0的命令词。
初始化错误码
错误码 | 说明 |
---|---|
ASR_OK | 无错误 |
ASR_ERROR | 内部引擎错误 |
ASR_ERROR_INVALID_PARAM | 参数错误 |
ASR_ERROR_ALREADY_INIT | 已初始化 |
ASR_ERROR_NO_CALLBACK | 未设置事件回调 |
ASR_ERROR_AUTH_STRING_EMPTY | 鉴权串为空,可能是鉴权关键字段未填入。 |
ASR_ERROR_AUTH_FAILED | 鉴权失败 |
初始化
SDK初始化步骤如下:
确保设备能正常获取MAC地址。
设置设备device_id和第三方APIKEY。
设置必要鉴权信息,包括:
阿里云appkey
阿里云Accesskey ID
阿里云Accesskey Secret
设置模型及资源路径,路径名可以是相对路径。
设置事件回调函数。
调用asr_engine_init完成SDK初始化。
示例代码
#include "asr_api.h"
static pthread_t recording_thread;
//sdk handler
static void *handler;
//处理语音事件,事件详情见API文档。
//尽量不要在回调函数中调用耗时间的函数,请将事件通过非阻塞式队列转移到其他线程中进行处理。
void event_callback(ASR_EVENT_TYPE event_type, int cmd, const char *result) {
}
void *recording_fn(void *param) {
//数据大小可以根据具体软硬件进行调整
int data_size = 512;
char data[512] = {0};
//录音退出时机需要根据具体业务场景来定,这里以简单的死循环模式模拟演示。
while (1) {
//录音部分逻辑根据具体软硬件来决定,这里假设音频全部录到data中,长度为512字节。
//数据提供给SDK
asr_engine_feed_data(handler, data, 512);
//其他逻辑
}
return NULL;
}
int main(int argc, char *argv[]) {
//初始化逻辑
//设置第三方API KEY以及DEVICE ID
//CUSTOM_API_KEY, CUSTOM_DEVICE_ID由您根据自身产品情况来获取。
//32是第三个参数的长度,这里根据实际情况进行设置。
asr_engine_set_params(ASR_PARAM_SET_API_KEY, 32, CUSTOM_API_KEY);
asr_engine_set_params(ASR_PARAM_SET_PRODUCT_KEY, 32, CUSTOM_DEVICE_ID);
//设置SDK APPKEY,ACCESS ID,ACCESS SECRET。
//TARGET_NUI_APPKEY,TARGET_ACCESS_ID,TARGET_ACCESS_SECRET通过阿里云获取。
asr_engine_set_params(ASR_PARAM_SET_NUI_APPKEY, 32, TARGET_NUI_APPKEY);
asr_engine_set_params(ASR_PARAM_SET_AK_ID, 32, TARGET_ACCESS_ID);
asr_engine_set_params(ASR_PARAM_SET_AK_KEY, 32, TARGET_ACCESS_SECRET);
//根据业务需求是否使能在线语音识别
//TARGET_ENABLE_ASR为string,"0"代表false,其他代表true。
asr_engine_set_params(ASR_PARAM_ENABLE_ASR, 32, TARGET_ENABLE_ASR);
//设置assets所在路径
//TARGET_WORKSPACE为assets的绝对/相对路径
asr_engine_set_params(ASR_PARAM_SET_WORKSPACE, 32, TARGET_WORKSPACE);
//设置事件callback
asr_engine_set_params(ASR_PARAM_EVENT_CB, sizeof(event_callback), (void *)event_callback);
//初始化
handler = asr_engine_init();
if (handler == NULL) {
//初始化出错,根据错误码来判断错误原因。
int error = 0;
asr_engine_get_property(ASRPropertyErrorCode, &error, sizeof(error));
//根据错误码来判断错误原因
//...
return -1;
}
//启动引擎
asr_engine_start(handler);
//启动录音线程
pthread_create(&recording_thread, NULL, recording_fn, NULL);
//直到退出
pthread_join(recording_thread, NULL);
//关闭引擎
asr_engine_stop(handler);
//释放引擎
asr_engine_finalize(handler);
return 0;
}
在文档使用中是否遇到以下问题
更多建议
匿名提交