You need to enable JavaScript to run this app.
导航
调用流程
最近更新时间:2024.05.07 14:35:41首次发布时间:2022.07.14 15:23:21
初始化

环境依赖

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

int ret = SpeechEngineGenerator.prepareEnvironment();
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    System.out.println("Prepare Environment Failed: " + ret);
    return;
}

创建引擎实例

流式语音识别 SDK 通过如下方式获取相关实例。每个实例在某一时刻只能处理一次识别任务,如需同时处理多个任务可以开启多个实例。

SpeechEngine speechEngine = SpeechEngineGenerator.getInstance();
speechEngine.createEngine();

参数配置

引擎类型

// 语音识别引擎
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ENGINE_NAME_STRING, SpeechEngineDefines.ASR_ENGINE);

日志

为便于您集成调试,有如下建议:

  • 日志级别,开发时设置为 TRACE(最高级别),线上设置 WARN

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

//【可选配置】设置日志级别
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_LOG_LEVEL_STRING, SpeechEngineDefines.LOG_LEVEL_WARN);
//【可选配置】设置调试路径,该路径必须在设备中存在,否则请提前创建
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_DEBUG_PATH_STRING, "{DEBUG PATH}");

线上问题定位

为了方便定位线上问题,需要您配置相关参数,包括:

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

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

speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_UID_STRING, "{UID}");

鉴权

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

//【必须配置】鉴权相关:AppID
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_ID_STRING, "{APPID}");
//【必须配置】鉴权相关:Token
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_TOKEN_STRING, "Bearer;{TOKEN}");

网络配置

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

//【必须配置】识别服务ADDRESS
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_ADDRESS_STRING, "wss://openspeech.bytedance.com");
//【必须配置】识别服务URI
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_URI_STRING, "/api/v2/asr");
//【必须配置】识别服务CLUSTER
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_CLUSTER_STRING, "{CLUSTER}");

SDK 还支持调整建连、接收超时和重连。(单位:毫秒)

//【可选配置】建连超时时间,建议使用默认值
speechEngine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_ASR_CONN_TIMEOUT_INT, 12000);
//【可选配置】数据接收超时时间,建议使用默认值
speechEngine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_ASR_RECV_TIMEOUT_INT, 8000);
//【可选配置】请求断连后是否尝试重连,默认0不重连
speechEngine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_ASR_MAX_RETRY_TIMES_INT, 0);

音频来源

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

  • SpeechEngineDefines.RECORDER_TYPE_FILE,原始音频文件,需要设置音频文件路径;
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_RECORDER_TYPE_STRING, SpeechEngineDefines.RECORDER_TYPE_FILE);
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_RECORDER_FILE_STRING, "./asr_rec_file.pcm");
  • SpeechEngineDefines.RECORDER_TYPE_STREAM,原始音频流,需要在执行过程中 输入音频数据,并在所有音频数据均输入完成后,发送 音频输入完成 指令;
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_RECORDER_TYPE_STRING, SpeechEngineDefines.RECORDER_TYPE_STREAM);

设置最大录音时长,当达到设置的时间后,会发送音频结束包并等待asr结果

//【可选配置】最大录音时长,默认60000ms,如果使用场景超过60s请修改该值,-1为不限制录音时长
speechEngine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_VAD_MAX_SPEECH_DURATION_INT, 60000);

控制识别效果

通过选择是否返回标点符号等功能,可以更加细致地控制识别结果的形式,满足您不同层次的识别需求。

//【可选配置】是否开启自动判停,默认false,不开启
speechEngine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_ASR_AUTO_STOP_BOOL, true);
//【可选配置】是否返回标点符号,默认false,不返回
speechEngine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_ASR_SHOW_NLU_PUNC_BOOL, true);
//【可选配置】是否隐藏句尾标点,默认false,默认不隐藏
speechEngine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_ASR_DISABLE_END_PUNC_BOOL, true);
//【可选配置】是否返回分句信息,默认false,不返回
speechEngine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_ASR_SHOW_UTTER_BOOL, true);
//【可选配置】设置纠错词表,识别结果中会把匹配到纠错词表key值对应的文字置换为纠错词表value值对应的文字
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_CORRECT_WORDS_STRING, "{\"星球崛起\":\"猩球崛起\"}");

控制识别效果

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

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

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

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

初始化引擎实例

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

int ret = speechEngine.initEngine();
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    System.out.println("Init Engine Failed: " + ret);
    speechEngine.destroyEngine();
    return;
}
speechEngine.setListener(this);
发送指令

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

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

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

启动引擎 DIRECTIVE_START_ENGINE

//注意这里先调用同步停止,避免SDK内部异步线程带来的问题
speechEngine.sendDirective(SpeechEngineDefines.DIRECTIVE_SYNC_STOP_ENGINE, "")
speechEngine.sendDirective(SpeechEngineDefines.DIRECTIVE_START_ENGINE, "")

音频输入完成 DIRECTIVE_FINISH_TALKING

//音频输入完成,等待最终识别结果
speechEngine.sendDirective(SpeechEngineDefines.DIRECTIVE_FINISH_TALKING, "")

关闭引擎 DIRECTIVE_STOP_ENGINE

//取消本次请求,在业务超时时,可以调用该指令,正常结束不需要调用,引擎内部会自动结束
speechEngine.sendDirective(SpeechEngineDefines.DIRECTIVE_STOP_ENGINE, "")

设置热词 DIRECTIVE_UPDATE_ASR_HOTWORDS

// 设置热词词表,支持在任意时刻设置
speechEngine.sendDirective(SpeechEngineDefines.DIRECTIVE_UPDATE_ASR_HOTWORDS, "")
输入音频数据

输入音频文件

  1. 即音频来源为SpeechEngineDefines.RECORDER_TYPE_FILE时:

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

speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_RECORDER_TYPE_STRING, SpeechEngineDefines.RECORDER_TYPE_FILE);
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_RECORDER_FILE_STRING, "./asr_rec_file.pcm");

输入音频流

即音频来源为SpeechEngineDefines.RECORDER_TYPE_STREAM时:
需要主动通过feedAudio接口输入音频数据,并在结束后发送音频输入完成 DIRECTIVE_FINISH_TALKING指令。

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

try {
    InputStream in = new FileInputStream("./asr_rec_file.pcm");
    byte[] bytes = new byte[2048];
    while (true) {
        int n = in.read(bytes);
        if (n == -1) {
            break;
        }
        // 输入音频数据
        speechEngine.feedAudio(bytes, n);
    }
    in.close();
    // 音频输入完成
    speechEngine.sendDirective(SpeechEngineDefines.DIRECTIVE_FINISH_TALKING, "");
} catch (IOException e) {
    e.printStackTrace();
    System.out.println("Read Audio Failed");
    speechEngine.destroyEngine();
    return;
}
回调接收返回数据

引擎启动成功 MESSAGE_TYPE_ENGINE_START

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

引擎关闭 MESSAGE_TYPE_ENGINE_STOP

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

错误信息 MESSAGE_TYPE_ENGINE_ERROR

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

  • req_id:请求 ID;

  • err_msg:错误描述信息;

  • err_code:错误码,可参考:错误码

中间识别结果 MESSAGE_TYPE_PARTIAL_RESULT

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

最终识别结果 MESSAGE_TYPE_FINAL_RESULT

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

  1. 不开启自动判停时,指截止到发送 DIRECTIVE_FINISH_TALKING 的所有音频;

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

销毁引擎实例

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

speechEngine.destroyEngine();
speechEngine = null;