文档中心

调用流程

最近更新时间：2023.11.03 21:08:28

首次发布时间：2022.12.19 17:56:01

初始化

环境依赖

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

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

创建引擎实例

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

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

参数配置

引擎类型

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

日志

为便于您集成调试，有如下建议：

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

engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_LOG_LEVEL_STRING, SpeechEngineDefines.LOG_LEVEL_WARN);
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_DEBUG_PATH_STRING, "{DEBUG PATH}");

鉴权

使用离在线语音识别能力时，需要完成相关授权验证。

在线鉴权

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

// 在线鉴权
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_ID_STRING, "{APPID}");
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_TOKEN_STRING, "Bearer;{TOKEN}");

离线鉴权

离线鉴权包括两种授权方式，按包名授权和按装机量授权，均需联系商务获取。按包名授权是指开通了权限的 APP 可以不限次数的使用离线识别功能；按装机量授权不限制 APP 的包名，但是限制使用离线识别的设备数量。

对于这两种授权方式，需要配置的参数如下：

按包名授权
- 本地证书，需要配置鉴权方式， 证书路径，证书文件名必须为 speech_license.licbag。
- 在线证书，语音识别 SDK 也支持离线鉴权证书自动下载，开发者需要配置鉴权方式， 证书名、证书路径 和 场景ID。

// 配置鉴权方式
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_TYPE_STRING, SpeechEngineDefines.AUTHENTICATE_TYPE_PRE_BIND);
// 配置证书名
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_LICENSE_NAME_STRING, {LICENSE_NAME});
// 配置场景ID
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_LICENSE_BUSI_ID_STRING, {BUSI_ID});

无论使用在线证书还是本地证书，都需要配置证书文件的路径。

// 配置证书文件路径
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_LICENSE_DIRECTORY_STRING, "{LICENSE DIRECTORY}");

配置证书路径后，如果使用在线证书，证书文件会被下载到该路径；如果使用离线证书，开发者需要自行将证书文件放置到该路径。

按装机量授权

需要配置鉴权方式，业务标识，密钥，证书服务域名和证书服务 URI。

// 配置鉴权方式
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_TYPE_STRING, SpeechEngineDefines.AUTHENTICATE_TYPE_LATE_BIND);
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_BUSINESS_KEY_STRING, ${BUSINESS KEY});
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_SECRET_STRING, ${SECRET});
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_ADDRESS_STRING, "https://cv-tob.bytedance.com");
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_URI_STRING, "/v1/api/sdk/tob_license/getlicense");

在线请求资源配置

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

// 设置为在线模式
engine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_ASR_WORK_MODE_INT, SpeechEngineDefines.ASR_WORK_MODE_ONLINE);
// 配置在线资源
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_ADDRESS_STRING, "wss://openspeech.bytedance.com");
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_URI_STRING, "/api/v2/asr");
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_CLUSTER_STRING, "{CLUSTER}");
// 支持调整建连、接收超时。如无特殊需要，建议使用默认值
engine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_ASR_CONN_TIMEOUT_INT, 12000);
engine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_ASR_RECV_TIMEOUT_INT, 8000);

离线请求资源配置

发起离线识别请求，需要配置 离线资源所在路径。模型资源前往模型资源下载最新版即可。

// 设置为离线模式
engine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_ASR_WORK_MODE_INT, SpeechEngineDefines.ASR_WORK_MODE_OFFLINE);
// 配置离线资源包路径
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ASR_OFF_RESOURCE_PATH_STRING, "{OFFLINE RESOURCE PATH}");

音频来源

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

SpeechEngineDefines.RECORDER_TYPE_RECORDER，系统内置录音机；
SpeechEngineDefines.RECORDER_TYPE_STREAM，原始音频流；
SpeechEngineDefines.RECORDER_TYPE_FILE，原始音频文件。

// 使用系统内置录音机
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_RECORDER_TYPE_STRING, SpeechEngineDefines.RECORDER_TYPE_RECORDER);

当使用系统内置录音机时，SDK 支持返回归一化的录音音量。

// 是否需要返回录音音量
engine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_ENABLE_GET_VOLUME_BOOL, mEnableGetVolume);

控制识别效果

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

// 是否开启自动判停
engine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_ASR_AUTO_STOP_BOOL, true);
// 是否显示分句详细信息
engine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_ASR_SHOW_UTTER_BOOL, true);

初始化引擎实例

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

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

发送指令

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

建议不要在 SDK 的回调线程中调用该接口，推荐将所有的指令调用都放到一个单独的线程中。但不推荐放到 UI 线程，因为这可能造成 UI 卡顿。
sendDirective 接口所支持的指令中， START_ENGINE, STOP_ENGINE 是异步指令，在相应的回调到达后才真正完成了操作。

启动引擎 `DIRECTIVE_START_ENGINE`

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

音频输入完成 `DIRECTIVE_FINISH_TALKING`

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

关闭引擎 `DIRECTIVE_STOP_ENGINE`

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

回调接收返回数据

引擎启动成功 `MESSAGE_TYPE_ENGINE_START`

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

引擎关闭 `MESSAGE_TYPE_ENGINE_STOP`

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

错误信息 `MESSAGE_TYPE_ENGINE_ERROR`

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

req_id：请求 ID；
err_msg：错误描述信息；
err_code：错误码，可参考语音识别 SDK 错误码说明。

中间识别结果 `MESSAGE_TYPE_PARTIAL_RESULT`

表示已处理的部分音频的识别结果JSON，JSON格式参考：识别结果
其中离线模式的字段是在线模式字段的子集，部分细节字段离线模式可能不支持，但在线模式均能支持。

最终识别结果 `MESSAGE_TYPE_FINAL_RESULT`

表示整段音频的识别结果JSON，JSON格式参考：识别结果
其中离线模式的字段是在线模式字段的子集，部分细节字段离线模式可能不支持，但在线模式均能支持。

整段音频是指：

不开启自动判停时，指截止到发送 DIRECTIVE_FINISH_TALKING 的所有音频；
开启自动判停时，表示服务端给出的停止点前的所有音频。

销毁引擎实例

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

engine.destroyEngine();
engine = null;

语音技术