You need to enable JavaScript to run this app.
导航
调用流程
最近更新时间: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}");

鉴权

请先到火山控制台申请 AppidToken,申请方法参考控制台使用FAQ1,配置 Token 时需要添加固定前缀 Bearer;

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

网络配置

发起语音识别请求前,需要配置 ADDRESSURI 以及 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);