ASR录音机

以下描述了如何使用灵云ASR录音机功能。

1. ASR录音机简介

ASR录音机封装了系统的录音接口及灵云sdk的ASR接口，其目标是将输入的语音信号转换为相应的文本或命令。

2. ASR能力

ASR录音机封装了灵云SDK的ASR能力，其许多概念仍然是基于ASR基础API的。建议在使用灵云ASR录音机之前， 先熟悉 ASR能力 的相关内容。

在使用灵云ASR录音机之前，需要选择合适的ASR模块和能力以及音频编解码库， 具体请参见 选择模块和能力 和 音频编解码库。

3. 初始化

在使用录音机之前，仍然需要先初始化系统模块，请参见 系统模块的初始化/终止。

3.1 创建录音机对象

在初始化系统模块之后，就可以使用 hci_asr_recorder_init() 创建录音机对象，同时需要设置初始化参数和回调函数参数。

3.2 设置初始化参数

初始化参数主要是设置本地资源库的路径等：

//设置回调函数及用户数据
RECORDER_CALLBACK_PARAM recorderCallbackParam;

recorderCallbackParam.pfnEventChange = RecorderEventChangeCallback;
recorderCallbackParam.pfnRecogFinish = RecorderRecogFinishCallback;
recorderCallbackParam.pfnSdkErr = RecorderErrorCallback;
recorderCallbackParam.pfnRecording = RecorderRecordingCallback;
recorderCallbackParam.pvRecogFinishUsrParam = NULL;
recorderCallbackParam.pvEventChangeUsrParam = NULL;
recorderCallbackParam.pvSdkErrorUsrParam = NULL;
recorderCallbackParam.pvRecordingUsrParam = NULL;

// 设置初始化参数
// initCapKeys: 如果使用本地能力，需要设置希望使用的能力，SDK利用此信息初始化模型库
// dataPath: 如果使用本地能力，需要设置ASR语言模型文件的路径
const char* pszConfig = "initCapKeys=asr.local.grammar.v4,dataPath=/mount/myapp/Document";

// 用指定的初始化参数对录音机对象进行初始化
RECORDER_ERR_CODE errorCode = hci_asr_recorder_init(pszConfig, &recorderCallbackParam);

如果是只使用云端能力，可以直接指定初始化配置串为空或者NULL。

注解

使用ASR录音机模块，并不需要调用ASR基础API的初始化操作，也即无需调用 HciCloudAsr.hciAsrInit()。

3.3 设置回调函数

为了能接收录音机内部信息，如状态信息、识别情况及错误信息等，应用层需要实现录音机的回调函数接口。 回调函数通过 PLAYER_CALLBACK_PARAM 参数传递给 hci_asr_recorder_init() 函数。 下面的代码示例实现了回调函数接口的写法：

// 事件回调，通知外部录音机状态的变化，如开始录音、开始识别等
void RecorderEventChangeCallback( RECORDER_EVENT eRecorderEvent, void * pUsrParam )
{
        switch (eRecorderEvent) {
                //处理录音机的各种事件
        }
}


// 识别结果回调
void RecorderRecogFinishCallback(RECORDER_EVENT eRecorderEvent, ASR_RECOG_RESULT *pRecogResult, void * pUsrParam )
{
        //得到识别结果
}

// 出错回调，通知外部出现的错误
void RecorderErrorCallback(eRecorderEvent, HCI_ERR_CODE eErrorCode, void * pUsrParam )
{
        switch (eErrorCode) {
                //错误处理
        }
}


// 录音回调，通知外部当前的录音数据和音量大小
void RecorderRecordingCallback(void *pVoiceData, unsigned int uiVoiceLen, int nVolume, void * pUsrParam )
{
        //可以在这里对音频数据进行处理, 或根据音量大小显示波形
}

4. 启动录音机

使用 hci_asr_recorder_start() 来启动录音机，启动后录音机就自动开始了录音、端点检测、识别的过程。 以进行自由说识别为例：

// 使用自由说识别
const char * pszConfig = "capKey=asr.cloud.freetalk,audioformat=pcm16k16bit");
// 自由说时无需指定语法文件
const char * pszGrammarData = NULL;

// 开始识别
RECORDER_ERR_CODE  eRet = hci_asr_recorder_start(pszConfig, pszGrammarData);

具体识别过程的概念、参数设置和注意事项请参见和 语法识别 和 自由说识别。

这里的配置项pszConfig包括了初始化会话的配置项（capKey和realtime）、识别选项、端点检测选项以及录音设备ID（deviceId）选项。

• capKey选项请参见 ASR能力描述 。
• deviceId选项用于指定录音设备的ID，不指定则为系统自动匹配（WAVE_MAPPER） 。

当使用本地语法识别，可以把语法数据通过 pszGrammarData 直接传入 hci_asr_recorder_start() 中，并指明grammarType的配置项为wordlist或者jsgf。 但这种方式每次识别的时候都会重新加载语法，识别完后卸载语法，因此效率低下，不推荐使用。 本地语法识别时建议先使用 hci_asr_recorder_load_grammar() 方式加载语法，获得语法ID， 在 hci_asr_recorder_start() 的时候指明grammarType为id来进行识别。示例如下：

// 以加载一个词表为例:
// 词表必须是utf-8编码, 有些平台下可能需要转码
char * pszWordList = "播放\r\n暂停\r\n停止\r\n\打开\r\n下一首\r\n上一首\r\n";

// 加载词表语法，获得语法id
int nGrammarId = 0;
errCode = hci_asr_recorder_load_grammar("grammarType=wordlist", pszWordList, &nGrammarId);

// 识别
char szRecogConfig[1000] = {0};
sprintf(szRecogConfig, "capKey=asr.local.grammar.v4,audioFormat=pcm16k16bit,encode=none,grammarType=id,grammarId=%d", nGrammarId);

// 无需指定语法数据
char * pszGrammarData = NULL;

errCode = hci_asr_recorder_start(szRecogConfig,pszGrammarData);

// 可以使用此id进行多次识别

// 不再使用此id时，进行卸载
hci_asr_recroder_unload_gammar(nGrammarId);

5. 端点检测

端点检测功能可以在传入的音频中检测到开始说话和停止说话的位置。录音机内部实现了端点检测能力， 无须开发者调用，但可以在调用 hci_asr_recorder_start() 时的配置项中设置相关参数，相关参数请参见ASR基础API 。

6. 结束录音

1. 调用 hci_asr_recorder_start() 后录音机会自动进行端点检测，检测到末端后会自动启动识别。通过回调函数 pfnRecogFinish 返回结果后，自动停止。
2. 通过 hci_asr_recorder_stop_and_recog(), 也可以不等端点检测检测到末端，直接结束录音，启动识别。通过回调函数 pfnRecogFinish 返回结果后，自动停止。
3. 在录音过程中可以随时使用 hci_asr_recorder_cancel() 来结束录音或取消识别。

录音结束后，可以再使用 hci_asr_recorder_start() 函数进行下一轮的录音识别工作。

7. 获取录音机状态

可以使用 hci_asr_recorder_get_state() 来获取录音机的当前状态：

RECORDER_STATE recorderState = hci_asr_recorder_get_state();
switch(recorderState)
{
        // 不同状态的处理
        ...
}

8. 反初始化

当不再使用ASR录音机的时候，需要反初始化ASR录音机，示例如下：

// 反初始化
RECORDER_ERR_CODE recorderError = hci_asr_recorder_release();

当不再使用其它灵云能力时，需要反初始化系统模块，请参见 系统模块的初始化/终止。

9. 实时识别

录音机支持 实时识别 功能，只需在初始化时将realtime配置项设为yes即可。