调用流程

环境依赖

创建流式语音识别 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}");

鉴权

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

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

网络配置

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

//【必须配置】识别服务域名
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_ADDRESS_STRING, "wss://openspeech.bytedance.com");
//【必须配置】识别服务URI
speechEngine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_URI_STRING, "/api/v2/asr");
//【必须配置】识别服务集群
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;