You need to enable JavaScript to run this app.
导航
语音技术
  • 文档首页
    • /语音技术/开发参考/SDK接入文档/流式语音识别 SDK(含一句话)/Linux C++/调用流程
调用流程
最近更新时间：2024.05.07 14:35:41首次发布时间：2022.07.14 15:23:12
我的收藏
初始化

环境依赖

创建流式语音识别 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，申请方法参考控制台使用FAQ1，配置 Token 时需要添加固定前缀 Bearer;。

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

网络配置

发起语音识别请求前，需要配置 ADDRESS、URI 以及 CLUSTER 参数。
ADDRESS: websocket接口地址中的 scheme://域名，当前为wss://openspeech.bytedance.com
URI: websocket接口地址中的 ADDRESS 后的部分，当前为/api/v2/asr
CLUSTER: 控制台获取，可参考控制台使用FAQ-Q1

//【必须配置】识别服务ADDRESS
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_ASR_ADDRESS_STRING,
                        "wss://openspeech.bytedance.com");
//【必须配置】识别服务URI
SpeechSDK_SetOptionString(handle, OPTIONS_KEY_ASR_URI_STRING, "/api/v2/asr");
//【必须配置】识别服务CLUSTER
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);