调用流程

环境依赖

创建流式语音识别 SDK 引擎实例前调用，完成网络环境等相关依赖配置。本方法每个进程生命周期内仅需调用一次。

int ret = SpeechSDK_PrepareEnvironment();
if (ret) {
    std::cout << "Fail to prepare engine environment!" << std::endl;
    return -1;
}

创建引擎实例

流式语音识别 SDK 通过如下方式获取相关实例。每个实例在某一时刻只能处理一次识别任务，如需同时处理多个任务可以开启多个实例。
其中第三个void*参数会在回调接口中作为参数提供，如无需要可以设为nullptr。

SpeechSDK_Handle handle;
ret = SpeechSDK_CreateHandle(&handle, OnMessage, nullptr);
if (ret) {
    std::cout << "Fail to create engine!" << std::endl;
    SpeechSDK_DestroyHandle(handle);
    return -1;
}

参数配置

引擎类型

// 语音识别引擎
  SpeechSDK_SetOptionString(handle, OPTIONS_KEY_ENGINE_NAME_STRING,
                            ASR_ENGINE_NAME);

日志

为便于您集成调试，有如下建议：

• 日志级别，开发时设置为 TRACE（最高级别），线上设置 WARN；

• 调试路径，流式语音识别 SDK 会在该路径下生成名为 speech_sdk.log 的日志文件，开发时设置，线上关闭。

SpeechSDK_SetOptionString(handle, OPTIONS_KEY_LOG_LEVEL_STRING,
                        LOG_LEVEL_TRACE);
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_DEBUG_PATH_STRING, "./");

线上问题定位

为了方便定位线上问题，需要开发者配置相关参数，包括：

• UID，用于区分不同的用户

开发者需要保证参数是可靠的，如果出现多个用户使用同一个 UID ，会导致技术人员无法还原问题发生时的现场状况，从而难以定位、解决问题。 配置方法如下：

SpeechSDK_SetOptionString(handle, OPTIONS_KEY_UID_STRING, "{YOUR UID}");

鉴权

需要申请 Appid 和 Token，配置时 Token 需要添加固定前缀 Bearer;。

SpeechSDK_SetOptionString(handle, OPTIONS_KEY_APP_ID_STRING,
                        "{YOUR APPID}");
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_APP_TOKEN_STRING,
                        "Bearer;{YOUR TOKEN}");

网络配置

发起语音识别请求前，需要配置 域名、URI 以及 集群 参数。

//【必须配置】识别服务域名
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_ASR_ADDRESS_STRING,
                        "wss://openspeech.bytedance.com");
//【必须配置】识别服务URI
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_ASR_URI_STRING, "/api/v2/asr");
//【必须配置】识别服务集群
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_ASR_CLUSTER_STRING,
                        "{YOUR CLUSTER}");

SDK 还支持调整建连、接收超时和重连（单位：毫秒）

//【可选配置】建连超时时间，建议使用默认值
SpeechSDK_SetOptionInt(handle, OPTIONS_KEY_ASR_CONN_TIMEOUT_INT, 12000);
//【可选配置】数据接收超时时间，建议使用默认值
SpeechSDK_SetOptionInt(handle, OPTIONS_KEY_ASR_RECV_TIMEOUT_INT, 8000);
//【可选配置】请求断连后是否尝试重连，默认0不重连
SpeechSDK_SetOptionInt(handle, OPTIONS_KEY_ASR_MAX_RETRY_TIMES_INT, 0);

音频来源

对于 Linux 平台，语音识别 SDK 支持以原始音频流或音频文件作为输入，配置值分别为

• RECORDER_TYPE_FILE，原始音频文件，需要设置音频文件路径；

SpeechSDK_SetOptionString(handle, OPTIONS_KEY_RECORDER_TYPE_STRING,
                        RECORDER_TYPE_FILE);
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_RECORDER_FILE_STRING,
                            "../data/asr_rec_file.pcm");

• RECORDER_TYPE_STREAM，原始音频流，需要在执行过程中 输入音频数据，并在所有音频数据均输入完成后，发送 音频输入完成 指令；

SpeechSDK_SetOptionString(handle, OPTIONS_KEY_RECORDER_TYPE_STRING,
                        RECORDER_TYPE_STREAM);

控制识别效果

通过选择是否开启自动判停等功能，可以更加细致地控制识别结果的形式，满足您不同层次的识别需求。

//【可选配置】是否开启自动判停，默认false，不开启
SpeechSDK_SetOptionBoolean(handle, OPTIONS_KEY_ASR_AUTO_STOP_BOOL, true);
//【可选配置】是否返回标点符号，默认false，不返回
SpeechSDK_SetOptionBoolean(handle, OPTIONS_KEY_ASR_SHOW_NLU_PUNC_BOOL, true);
//【可选配置】是否隐藏句尾标点，默认false，不隐藏
SpeechSDK_SetOptionBoolean(handle, OPTIONS_KEY_ASR_DISABLE_END_PUNC_BOOL, true);
//【可选配置】是否返回分句信息，默认false，不返回
SpeechSDK_SetOptionBoolean(handle, OPTIONS_KEY_ASR_SHOW_UTTER_BOOL, true);
//【可选配置】设置纠错词表，识别结果中会把匹配到纠错词表key值对应的文字置换为纠错词表value值对应的文字
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_ASR_CORRECT_WORDS_STRING, "{\"星球崛起\":\"猩球崛起\"}");

控制识别效果

如果识别时长较长建议设置识别结果形式为增量返回，只返回当前分句，否则内存会有增长。

//【可选配置】设置结果返回形式，建议设置为增量返回 <"single">
speechEngine.setOptionString(SpeechEngineDefines.OPTIONS_KEY_ASR_RESULT_TYPE_STRING, SpeechEngineDefines.ASR_RESULT_TYPE_SINGLE);

一句话场景下可以选用全量返回模式：

//【可选配置】设置结果返回形式，建议设置为增量返回 <"full">
speechEngine.setOptionString(SpeechEngineDefines.OPTIONS_KEY_ASR_RESULT_TYPE_STRING, SpeechEngineDefines.ASR_RESULT_TYPE_FULL);

初始化引擎实例

参数配置完成后，调用 初始化接口，完成引擎实例的初始化，初始化后配置 回调监听器。

ret = SpeechSDK_InitEngine(handle);
if (ret) {
    std::cout << "Fail to initialize engine!" << std::endl;
    SpeechSDK_DestroyHandle(handle);
    return -1;
}

语音识别 SDK 通过发送指令接口 SpeechSDK_SendDirectiveToEngine 触发各种操作，需要注意以下两点：

1. 该接口不要在回调线程中调用；

2. 该接口所支持的指令中， kStartEngine, kStopEngine 是异步指令，在相应的回调到达后才真正完成了操作。

启动引擎 kStartEngine

//注意这里先调用同步停止，避免SDK内部异步线程带来的问题
SpeechSDK_SendDirectiveToEngine(handle, DirectiveType::kSyncStopEngine, "");
SpeechSDK_SendDirectiveToEngine(handle, DirectiveType::kStartEngine, "");

音频输入完成 kFinishTalking

//音频输入完成，等待最终识别结果
SpeechSDK_SendDirectiveToEngine(handle, DirectiveType::kFinishTalking, "");

关闭引擎 kStopEngine

//取消本次请求，在业务超时时，可以调用该指令，正常结束不需要调用，引擎内部会自动结束
SpeechSDK_SendDirectiveToEngine(handle, DirectiveType::kStopEngine, "");

更新热词 kUpdateAsrHotWords

//设置热词词表，支持在任意时刻设置
SpeechSDK_SendDirectiveToEngine(handle, DirectiveType::kUpdateAsrHotWords, "");

输入音频文件

1. 即音频来源为 RECORDER_TYPE_FILE 时：

无需主动输入音频数据，SDK 会自行读取配置路径下的音频文件。

SpeechSDK_SetOptionString(handle, OPTIONS_KEY_RECORDER_TYPE_STRING,
                        RECORDER_TYPE_FILE);
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_RECORDER_FILE_STRING,
                            "../data/asr_rec_file.pcm");

输入音频流

即音频来源为 RECORDER_TYPE_STREAM 时：
需要主动通过SpeechSDK_FeedAudioToEngine接口输入音频数据，并在结束后发送音频输入完成 kFinishTalking指令。

以下示例是输入并读取音频文件。但实际上可以通过这种方式，输入从任何地方获得的音频数据，比如客户端网络上传或者通过其他RPC方式获得的数据：

FILE* fp = fopen("../data/asr_rec_file.pcm", "rb");
char data[2048];
while (!feof(fp)) {
    auto n = fread(data, 1, 2048, fp);
    
    // Feed audio.
    ret = SpeechSDK_FeedAudioToEngine(
        handle, reinterpret_cast<const int16_t*>(data), n / 2);
    if (ret) {
        std::cout << "Fail to feed audio!" << std::endl;
        SpeechSDK_DestroyHandle(handle);
        return -1;
    }
}
fclose(fp);
SpeechSDK_SendDirectiveToEngine(handle, DirectiveType::kFinishTalking, "");

引擎启动成功 kEngineStart

收到该回调后表示识别已经开始。数据字段为该次请求的请求 ID.

引擎关闭 kEngineStop

收到该回调后，引擎进入空闲状态。

错误信息 kEngineError

引擎发生错误。数据部分为 JSON 结构，内部包含三个字段：

• req_id：请求 ID；

• err_msg：错误描述信息；

• err_code：错误码，可参考：错误码 。

中间识别结果 kAsrPartialResult

表示已处理的部分音频的识别结果JSON，JSON格式参考：识别结果 说明。

最终识别结果 kAsrFinalResult

表示整段音频的识别结果JSON，JSON格式参考：识别结果 说明。整段音频是指：

1. 不开启自动判停时，指截止到发送 kFinishTalking 的所有音频；

2. 开启自动判停时，指服务端给出的停止点前的所有音频。

当不再需要语音识别后，建议对引擎实例进行销毁，释放内存资源。

SpeechSDK_DestroyHandle(handle);