NUI SDK

前提条件

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

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

• 已获取AccessKey ID和AccessKey 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的命令词。

调用步骤

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;
//处理语音事件，事件详情见SDK中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() {
    //其他逻辑
    const char* CUSTOM_API_KEY = "设置第三方API KEY以及DEVICE ID";
    const char* CUSTOM_DEVICE_ID = "设置第三方API KEY以及DEVICE ID";
    const char* CUSTOM_API_KEY = "填写你在阿里云智能语音交互控制台上创建项目时生成的appkey";
    const char* TARGET_ACCESS_ID = "填写阿里云账户AccessKeyId";
    const char* TARGET_ACCESS_SECRET = "填写阿里云账户AccessKeySecret";
    //设置第三方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);
    //根据业务需求是否使能在线语音识别
    const char* TARGET_ENABLE_ASR = "1";
    //TARGET_ENABLE_ASR为string，"0"代表false，其他都是true
    asr_engine_set_params(ASR_PARAM_ENABLE_ASR, 32, TARGET_ENABLE_ASR);
    //设置assets所在路径
    //TARGET_WORKSPACE为assets的绝对/相对路径。
    const char* 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;
}