调用流程

环境依赖

创建语音识别 SDK 引擎实例前调用，完成网络环境等相关依赖配置。

SpeechEngineGenerator.PrepareEnvironment(getApplicationContext(), getApplication());

创建引擎实例

语音识别 SDK ，通过如下方式获取相关实例。

SpeechEngine engine = SpeechEngineGenerator.getInstance();
long engineHandler = engine.createEngine();

参数配置

引擎类型

engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_ENGINE_NAME_STRING, SpeechEngineDefines.ASR_ENGINE);

用户id（必填）和设备id（选填）

用户id和设备id都是用于线上排查问题而设置的，可由SDK开发者传递任意字符串，不涉及敏感信息。遇到问题时如果采集不到reqid，则可提供相应的用户id或设备id辅助火山引擎服务端人员定位问题。
用户id配置方法：

engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_UID_STRING, "用任意非空字符串替换");

设备id配置方法，不配置该项则不采集该配置项：

engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_DEVICE_ID_STRING, "用任意非空字符串替换");

日志

为便于开发者集成调试，有如下建议：

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

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

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

鉴权

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

网络配置

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

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

SDK 还支持调整建连、接收超时和重连。

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

音频来源

语音识别 SDK 支持以内置录音机、外部 PCM 音频流或音频文件作为输入，配置值分别为：

• SpeechEngineDefines.RECORDER_TYPE_RECORDER，内置录音机；

• SpeechEngineDefines.RECORDER_TYPE_STREAM，外部 PCM 音频流；

• SpeechEngineDefines.RECORDER_TYPE_FILE，PCM 格式的音频文件。

//【必须配置】默认使用系统内置录音机
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_RECORDER_TYPE_STRING, SpeechEngineDefines.RECORDER_TYPE_RECORDER);

当使用内置录音机时，SDK 支持返回归一化的录音音量，如果 APP 需要显示音频波形可以使用这里返回的音量值。

//【可选配置】是否需要返回录音音量
engine.setOptionBoolean(engineHandler, SpeechEngineDefines.PARAMS_KEY_ENABLE_GET_VOLUME_BOOL, mEnableGetVolume);

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

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

控制识别效果

通过选择是否打开标点、顺滑等功能，可以更加细致地控制识别结果的形式，满足您不同层次的识别需求。

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

控制识别结果的形式

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

//【可选配置】设置结果返回形式，建议设置为增量返回
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_ASR_RESULT_TYPE_STRING, SpeechEngineDefines.ASR_RESULT_TYPE_SINGLE);

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

//【可选配置】设置结果返回形式，建议设置为全量返回
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_ASR_RESULT_TYPE_STRING, SpeechEngineDefines.ASR_RESULT_TYPE_FULL);

初始化引擎实例

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

engine.setContext(getApplicationContext());
int ret = engine.initEngine(engineHandler);
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    String errMessage = "Init Engine Faile: " + ret;
    Log.e(SpeechDefines.TAG, errMessage);
}
engine.setListener(this);

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

1. 不建议在 SDK 的回调线程中调用该接口；

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

启动引擎 DIRECTIVE_START_ENGINE

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

音频输入完成 DIRECTIVE_FINISH_TALKING

//音频输入完成，引擎内部会关闭录音机，等待最终识别结果
engine.sendDirective(engineHandler, SpeechEngineDefines.DIRECTIVE_FINISH_TALKING, "")

关闭引擎 DIRECTIVE_STOP_ENGINE

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

设置热词 DIRECTIVE_UPDATE_ASR_HOTWORDS

// 设置热词词表，支持在任意时刻设置
engine.sendDirective(engineHandler, SpeechEngineDefines.DIRECTIVE_UPDATE_ASR_HOTWORDS, "{\"hotwords\":[{\"word\":\"过秦论\",\"scale\":2.0}]}")

引擎启动成功 MESSAGE_TYPE_ENGINE_START

收到该回调后表示识别已经开始。

引擎关闭 MESSAGE_TYPE_ENGINE_STOP

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

错误信息 MESSAGE_TYPE_ENGINE_ERROR

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

• req_id：请求 ID；

• err_msg：错误描述信息；

• err_code：错误码，可参考语音识别 SDK 错误码说明。

中间识别结果 MESSAGE_TYPE_PARTIAL_RESULT

表示当前 session 已处理的部分音频的识别结果。对于流式 ASR 而言，处理最终识别结果和中间识别结果的方法相同。数据字段为 json 格式，json 数据的详细信息参考这里。

PARAMS_KEY_ASR_RESULT_TYPE_STRING不同场景结果处理示例

1. full或single模式，结果直接上屏，处理示例：

String stdData = new String(data);
this.runOnUiThread(() -> {
    try {
        // 从回调的 json 数据中解析 ASR 结果
        JSONObject reader = new JSONObject(stdData);
        if (!reader.has("result")) {
            return;
        }
        String text = reader.getJSONArray("result").getJSONObject(0).getString("text");
        if (text.isEmpty()) {
            // 过滤掉结果为空的情况
            return;
        }
        // 设置文字上屏
        // setResultText(text);
    } catch (JSONException e) {
        e.printStackTrace();
    }
});

2. single模式，模拟结果追加形式上屏，处理示例：

private String lastSentence = ""; // 上一句的结果
private String totalText = ""; // 全量结果

String stdData = new String(data);
this.runOnUiThread(() -> {
    try {
        // 从回调的 json 数据中解析 ASR 结果
        JSONObject reader = new JSONObject(stdData);
        if (!reader.has("result")) {
            return;
        }
        String text = reader.getJSONArray("result").getJSONObject(0).getString("text");
        if (text.isEmpty() && !lastSentence.isEmpty()) {
            totalText += lastSentence;
        }
        lastSentence = text;
        // 设置文字上屏
        // setResultText(totalText);
    } catch (JSONException e) {
        e.printStackTrace();
    }
});

最终识别结果 MESSAGE_TYPE_FINAL_RESULT

表示当前 session 的整段音频的识别结果。处理方法参考前述“中间识别结果”的处理方法。

当前音量 MESSAGE_TYPE_VOLUME_LEVEL

使用内置录音机时，才会返回的一个回调。其值为[0-1]之间的归一化值，正常音量在0.2附近。

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

engine.destroyEngine(engineHandler);
engine = null;