全部产品

NUI SDK

更新时间:2020-10-14 10:12:07

本文为您介绍NUI SDK的关键接口、调用步骤及代码示例。

前提条件

  • 在使用SDK之前,请先阅读接口说明,详情请参见接口说明

  • 已在智能语音管控台创建设备端解决方案项目,详情请参见创建项目

  • 已获取AccessKey IDAccessKey Secret,详情请参见开通服务

下载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地址。

  1. 设置设备device_id和第三方APIKEY。

  2. 设置必要鉴权信息,包括:

    1. 阿里云appkey

    2. 阿里云Accesskey ID

    3. 阿里云Accesskey Secret

  3. 设置模型及资源路径,路径名可以是相对路径。

  4. 设置事件回调函数。

  5. 调用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;
}