NUI 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)

初始化

SDK初始化步骤如下：

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;
}