You need to enable JavaScript to run this app.
导航
调用流程
最近更新时间:2024.05.07 14:35:40首次发布时间:2022.05.18 16:10:08
前置操作

环境依赖

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

鉴权

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

//【必须配置】鉴权相关:AppID
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_APP_ID_STRING, "{APPID}");
//【必须配置】鉴权相关:Token
engine.setOptionString(engineHandler, 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
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");
//【必须配置】识别服务CLUSTER
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 结构,内部包含三个字段:

中间识别结果 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();
    }
});
  1. 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;