接入流程

环境依赖

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

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

创建引擎实例

语音合成 SDK 如下方式获取相关实例。

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

参数配置

引擎类型

// 语音合成引擎
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_ENGINE_NAME_STRING, SpeechEngineDefines.TTS_ENGINE);

日志

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

• 日志级别，开发时设置为 DEBUG, 线上设置 WARN；
• 调试路径，语音合成 SDK 会在该路径下生成文件名前缀为 speech_sdk 的日志文件，开发时设置，线上关闭；

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

线上问题定位

为了方便定位线上问题，需要开发者配置相关参数，包括：

• UID, 用于区分不同的用户，在线合成必需配置；
• DEVICE_ID, 用于区分不同的设备，可选配置；

因为 TTS 服务端的要求，如果不配置 UID 或配置为空字符串会导致无法使用在线合成，因此使用在线合成一定要配置 UID, 离线合成则没有这一要求。UID 配置为任意非空字符串都可以正常使用在线合成，但如果不能保证 UID 对每个用户都是不一样的就会影响问题定位，使我们无法还原问题发生时用户的操作路径。
DEVICE_ID 允许不配置或配置为空字符串，不配置设备 ID 或者无法保证设备 ID 的唯一性同样会影响线上问题定位。
SDK 不会自行采集用户 ID 和设备 ID, 不涉及相关敏感信息的获取。
用户 ID 配置方法：

engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_UID_STRING, "USER ID");

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

engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_DEVICE_ID_STRING, "DEVICE ID");

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

授权

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

在线合成授权

请先到火山控制台申请 Appid 和 Token，申请方法参考这个页面的 Q1，配置 Token 时需要添加固定前缀 Bearer;。

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

离线合成授权

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

无论使用哪一种授权方式，都需要首先配置证书文件的路径。 该路径应由使用 SDK 的 APP 提前创建好且确保具备读写权限。

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

下面分别介绍两种授权方式及各自所需的配置：

• 按包名授权
  • 本地证书，需要配置授权方式和证书路径，同时开发者需要自行将证书文件放置到证书路径，并修改文件名为 speech_license.licbag;
  • 在线证书，语音合成 SDK 也支持在触发鉴权行为时自动下载证书到证书路径，开发者需要配置授权方式，证书名、场景ID和证书路径。

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

• 按装机量授权
  需要配置授权方式、业务标识、密钥、证书服务域名、证书服务 URI和证书路径，按装机量授权同样由 SDK 自动下载证书文件。

// 配置授权方式
engine.setOptionString(engineHandler，SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_TYPE_STRING, SpeechEngineDefines.AUTHENTICATE_TYPE_LATE_BIND);
// 配置 业务标识
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_BUSINESS_KEY_STRING, {BUSINESS KEY});
// 配置密钥
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_SECRET_STRING, {SECRET});
// 配置证书服务域名
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_ADDRESS_STRING, "https://cv-tob.bytedance.com");
// 配置证书服务 URI
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_AUTHENTICATE_URI_STRING, "/v1/api/sdk/tob_license/getlicense");

合成场景

语音合成 SDK 提供了两种合成场景，分别满足不同的需求：

• 单次合成场景 TTS_SCENARIO_TYPE_NORMAL：又称单句场景，引擎每次启动，只合成、播放一段文本的；
• 连续合成场景 TTS_SCENARIO_TYPE_NOVEL：适用于听书业务，每次启动引擎后可以根据需求合成、播放多段文本；

// 合成场景：连续合成场景
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_SCENARIO_STRING, SpeechEngineDefines.TTS_SCENARIO_TYPE_NOVEL);

合成策略

离在线语音合成 SDK，除了可以单独使用的在线合成及离线合成外，还提供了在线合成发生网络错误后自动切换到离线合成的策略，开发者可以通过配置建连超时 PARAMS_KEY_TTS_CONN_TIMEOUT_INT 和接收超时 PARAMS_KEY_TTS_RECV_TIMEOUT_INT 两个参数来控制切换的敏感程度。下面介绍 SDK 支持的几种合成模式：

• 在线合成 TTS_WORK_MODE_ONLINE：只进行在线合成，不需要配置离线合成相关参数；
• 离线合成 TTS_WORK_MODE_OFFLINE：只进行离线合成，不需要配置在线合成相关参数；
• 在线优先 TTS_WORK_MODE_ALTERNATE：优先发起在线合成，失败后（网络错误），启动离线合成引擎开始合成；

// 合成策略：在线合成
engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_WORK_MODE_INT, SpeechEngineDefines.TTS_WORK_MODE_ONLINE);
// 建连超时，默认12000ms
engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_CONN_TIMEOUT_INT, 12000);
// 接收超时，默认8000ms
engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_RECV_TIMEOUT_INT, 8000);

在线请求资源配置

发起在线合成请求，需要配置 ADDRESS、URI 以及 CLUSTER 参数。
ADDRESS: websocket接口地址中的 scheme://域名，当前为wss://openspeech.bytedance.com
URI: websocket接口地址中的 ADDRESS 后的部分，当前为/api/v1/tts/ws_binary
CLUSTER: 控制台获取，可参考控制台使用FAQ-Q1

// 在线请求资源配置
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_ADDRESS_STRING, "{ADDRESS}");
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_URI_STRING, "{URI}");
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_CLUSTER_STRING, "{CLUSTER}");

离线请求资源配置

使用离线合成，需要提前下载好离线资源包，现阶段离线合成 SDK 及对应的资源分两个版本：V2和V4. 下载V4资源参考文档：下载V4资源，下载V2资源参考文档：下载V2资源。对于新客户，我们推荐使用效果更好的 V4, V2 版本目前已经停止迭代。
离线资源包下载完成后，需要配置 离线资源所在路径。

// 配置离线资源包路径
// engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_OFFLINE_RESOURCE_PATH_STRING, "{OFFLINE RESOURCE PATH}");

控制合成效果

通过对 发音人、音调、音量 和 语速 等参数的调整，可以获得不同的发声效果，更好满足您业务场景中的播报需求。

发音人

可以使用的发音人列表可以参考文档：发音人参数列表。

// 在线合成使用的“发音人”
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_VOICE_ONLINE_STRING, "{ONLINE VOICE}");
// 在线合成使用的“演绎风格”
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_VOICE_TYPE_ONLINE_STRING, "{ONLINE VOICE TYPE}");
// 离线合成使用的“发音人”
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_VOICE_OFFLINE_STRING, "{OFFLINE VOICE}");
// 离线合成使用的“演绎风格”
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_VOICE_TYPE_OFFLINE_STRING, "{OFFLINE VOICE TYPE}");

音调、音量和语速

在 Android 组件 5.4.3 及后续版本，通过下面的方法设置音调、音量和语速：

// 音色对应音调
engine.setOptionDouble(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_PITCH_RATIO_DOUBLE, 1.0);
// 音色对应音量
engine.setOptionDouble(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_VOLUME_RATIO_DOUBLE, 1.0);
// 音色对应语速
engine.setOptionDouble(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_SPEED_RATIO_DOUBLE, 1.0);

在 Android 组件 5.4.3 之前的版本，通过下面的方法设置音调、音量和语速（与新版本相比，配置项的名字有所不同）：

// 音色对应音调
engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_PITCH_INT, 10);
// 音色对应音量
engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_VOLUME_INT, 10);
// 音色对应语速
engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_SPEED_INT, 10);

合成文本

要合成的 文本，每次触发合成前配置。

// 要合成的文本
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_TEXT_STRING, "{TEXT}");

播放进度

语音合成 SDK 支持返回播放进度，通过回调 MESSAGE_TYPE_TTS_PLAYBACK_PROGRESS 获取进度信息。离线线合成默认开启，在线合成需要配置以下参数：

engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_WITH_FRONTEND_INT, 1);

停止播放时使用淡出效果

向语音合成 SDK 发送STOP_ENGINE指令时，默认情况下会立即停止播放。如果您希望“淡出”地停止播放，可以配置以下参数使用这一效果：

// 根据需要来调整淡出持续的时间，单位为毫秒，且只支持设置成 20 毫秒的非负整数倍。
// 默认为 0，这时表示不使用淡出效果。
engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_AUDIO_FADEOUT_DURATION_INT, {SUITABLE_DURATION});

禁用内建播放器

语音合成 SDK 默认使用内置的播放器播放合成的音频，如果开发者希望使用其他播放器，可以通过以下配置项禁用内置播放器。

engine.setOptionBoolean(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_ENABLE_PLAYER_BOOL, false);

配置内建播放器的音源

语音合成 SDK 默认使用 Media 音源，同时允许开发者通过以下配置项自行调整播放器的音源。

engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_AUDIO_STREAM_TYPE_INT, SpeechEngineDefines.AUDIO_STREAM_TYPE_MEDIA);

SDK 支持的音源类型有

public static final int AUDIO_STREAM_TYPE_VOICE = 0;
public static final int AUDIO_STREAM_TYPE_SYSTEM = 1;
public static final int AUDIO_STREAM_TYPE_RING = 2;
public static final int AUDIO_STREAM_TYPE_MEDIA = 3;
public static final int AUDIO_STREAM_TYPE_ALARM = 4;
public static final int AUDIO_STREAM_TYPE_NOTIFICATION = 5;

每次启动引擎都创建新的播放器对象

语音合成 SDK 默认在初始化阶段创建播放器对象，后续每次启动、关闭引擎都复用了同一个播放器对象。如果想每次启动引擎都创建新的播放器对象，并在停止引擎时销毁这个对象，可以使用以下配置项。

engine.setOptionBoolean(engineHandler, SpeechEngineDefines.PARAMS_KEY_PLAYER_DISABLE_REUSE_BOOL, true);

利用每次启动引擎都创建新的播放器对象的特点，开发者可以将配置音源的时机放在启动引擎之前，以实现每次启动引擎时应用不同的音源类型。

返回音频数据

语音合成 SDK 支持返回合成出来的音频数据，可以通过监听回调MESSAGE_TYPE_TTS_AUDIO_DATA来拿到PCM格式的音频流。默认关闭，需要配置以下参数开启

engine.setOptionInt(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_DATA_CALLBACK_MODE_INT, 2);

在离线切换断点续播

语音合成 SDK 在 Work Mode 为 TTS_WORK_MODE_ALTERNATE 时，可以在断网或弱网情况下自动从在线合成切换到离线合成，这种自动切换支持断点续播，也即离线合成从在线合成断开的地方继续合成、播放，而不是从头开始。开启断点续播除了要将 Work Mode 配置为 TTS_WORK_MODE_ALTERNATE 外，还依赖在线合成返回的 TTS 前端信息，需要添加以下配置

engine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_TTS_WITH_FRONTEND_INT, 1);

为了让在离线切换足够平滑、无感，SDK 会淡出地播放完在线合成音频，然后淡入地开始播放离线合成音频。开发者可以通过下面两个配置项分别控制淡出与淡入效果持续的长度

/**
 * Tts fadeout duration
 * The duration of the online tts audio fade-out when resuming from breakpoint.
 * Optional for online TTS, default is 30ms, config it before init engine.
 */
public static final String PARAMS_KEY_TTS_FADEOUT_DURATION_INT = "tts_fadeout_duration";

/**
 * Tts fadein duration
 * The duration of offline tts fade-in audio when resuming from a breakpoint.
 * Optional for online TTS, default is 30ms, config it before init engine.
 */
public static final String PARAMS_KEY_TTS_FADEIN_DURATION_INT = "tts_fadein_duration";

限制离线合成的 CPU 占用

为了尽可能快速的合成完音频，默认情况下离线合成会倾向于使用更多的 CPU 资源。如果您 profiling 后认为离线合成的 CPU 占用太高了，或者要避免系统主动杀死 CPU 持续占用过高的进程，可以通过下面的配置来降低离线合成的 CPU 占用。
注意：开启以下选项会使离线合成的实时率(RTF)变大。

engine.setOptionBoolean(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_LIMIT_CPU_USAGE_BOOL, true);

使用复刻音色

语音合成 SDK 支持使用复刻的音色进行合成，目前仅在线合成模式可以使用，且与预制的音色相比配置会有一些变化，需要配置一些额外参数。包括：

• 集群，与其他音色相比，使用复刻音色合成时的集群配置可能有变化；
• 后端集群，使用复刻音色合成时，需要额外加一项后端集群配置。
• 发音人，复刻音色的发音人配置会在复刻流程中返回，将得到的voice type值设入即可。
• 开启复刻音色，在配置中选择开启复刻音色，进入复刻音色合成流程。
• 设置复刻风格，在复刻流程-查询用户训练任务状态的返回结果中，会说明复刻音色所支持的风格参数，如通用中文，通用美式英文等，配置所需的风格值即可。

// 集群，需要重新初始化引擎实例才会使修改后的配置生效
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_TTS_CLUSTER_STRING, "{YOUR CLUSTER}");
// 后端集群
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_TTS_BACKEND_CLUSTER_STRING, "{YOUR BACKEND CLUSTER}");
// 发音人，在复刻场景下，VOICE值固定为other，而VOICE_TYPE为复刻流程所提供的值
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_TTS_VOICE_ONLINE_STRING, "other");
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_TTS_VOICE_TYPE_ONLINE_STRING, "{VOICE TYPE}");
// 开启复刻音色，启动复刻音色合成流程
engine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_TTS_USE_VOICECLONE_BOOL, true);
// 设置复刻风格
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_TTS_VOICECLONE_STYLE_STRING, "");

初始化引擎实例

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

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

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

1. 该接口不要在回调线程中调用，我们推荐将所有的指令调用都放到一个单独的线程中。但不推荐放到 UI 线程，因为这可能造成 UI 卡顿；
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_STOP_ENGINE

取消请求，关闭引擎。单次合成场景下正常结束不需要调用，引擎内部会自动结束；连续合成场景下当不再使用合成功能时应主动调用。

engine.sendDirective(engineHandler, SpeechEngineDefines.DIRECTIVE_STOP_ENGINE, "")

建立连接 DIRECTIVE_CREATE_CONNECTION

建连指令用于在发送合成请求之前建立网络连接，可以在语音交互场景下减少在线合成的端到端延时。该指令需要在启动引擎之前调用。

engine.sendDirective(engineHandler, SpeechEngineDefines.DIRECTIVE_CREATE_CONNECTION, "")

合成语音 DIRECTIVE_SYNTHESIS

连续合成场景下，使用该指令触发一次合成，可以多次调用。推荐的调用策略如下：

• 第一句文本，直接调用；
• 非首句文本，在收到 合成结束回调 后发送；
• 使用 SDK 内置播放器时，如果返回值为 ERR_SYNTHESIS_PLAYER_IS_BUSY，表明内部缓存已经耗尽，应该在收到下一个 播放结回调时 再次调用；

// “合成”指令必须要在收到 MESSAGE_TYPE_ENGINE_START 后发送
engine.sendDirective(engineHandler, SpeechEngineDefines.DIRECTIVE_SYNTHESIS, "");

暂停/继续播放 DIRECTIVE_PAUSE_PLAYER/DIRECTIVE_RESUME_PLAYER

语音合成 SDK 支持播放器的暂停和恢复操作，该操作只影响播放，不影响合成，即播放被暂停但是合成还在继续。

// 暂停播放
engine.sendDirective(engineHandler, SpeechEngineDefines.DIRECTIVE_PAUSE_PLAYER, "");
// 继续播放
engine.sendDirective(engineHandler, SpeechEngineDefines.DIRECTIVE_RESUME_PLAYER, "");

当不再需要语音合成后，应该对引擎实例进行销毁，释放内存资源。

eEngine.destroyEngine(engineHandler);
engineHandler = -1;
engine = null;

引擎启动成功 MESSAGE_TYPE_ENGINE_START

引擎启动成功，收到该回调后，在单次合成场景下收到该回调时语音合成已经开始，同时数据字段为该次请求的请求 ID; 连续合成场景下还需要再发送合成指令，才真正的开始合成。

引擎关闭 MESSAGE_TYPE_ENGINE_STOP

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

错误信息 MESSAGE_TYPE_ENGINE_ERROR

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

• reqid: 请求 ID；
• err_msg: 错误描述信息；
• err_code: 错误码，不同错误码的处理方式参考文档：错误码说明。

发生合成方式切换 MESSAGE_TYPE_TTS_SYNTHESIS_MODE_TOGGLE

在线优先策略下，在线合成失败切换离线合成时返回该事件；

合成开始 MESSAGE_TYPE_TTS_SYNTHESIS_BEGIN

合成开始回调。数据字段为当次合成的请求 ID。

合成结束 MESSAGE_TYPE_TTS_SYNTHESIS_END

当次合成完成。

播放开始 MESSAGE_TYPE_TTS_START_PLAYING

播放开始回调。数据字段为当次播放的请求 ID，开发者可以据此完成文本高亮等操作。

播放结束 MESSAGE_TYPE_TTS_FINISH_PLAYING

播放结束回调。

播放进度 MESSAGE_TYPE_TTS_PLAYBACK_PROGRESS

播放进度回调，数据部分是一个序列化的 JSON 字符串，包含正在播放的请求的播放进度（单位：百分比），格式如下：

{
    "progress": 0.3,
    "reqid": "bb081d44-0671-4789-8df5-0050edae517b",
}

音频数据 MESSAGE_TYPE_TTS_AUDIO_DATA

合成出来的 PCM 格式音频数据。