创建语音合成 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
;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}");
为了方便定位线上问题,需要开发者配置相关参数,包括:
因为 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");
说明
在 4.4.0 版本前,开发者需要配置 PARAMS_KEY_DEBUG_PATH_STRING 来保证信息上传成功。
engine.setOptionString(engineHandler, SpeechEngineDefines.PARAMS_KEY_DEBUG_PATH_STRING, "{DEBUG PATH}");
从 4.4.0 版本开始不再需要配置该项,转而需保证调用setContext
接口配置 Android Application Context.
使用离在线语音合成能力时,需要完成相关授权验证。
请先到火山控制台申请 Appid
和 Token
,申请方法参考控制台使用FAQ1,配置 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
;证书路径
,开发者需要配置授权方式
,证书名
、场景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);
注意
在 5.4.3 之前的版本,音高、音量和语速的配置值与直觉不符,例如配置为 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 资源。如果您 profiling 后认为离线合成的 CPU 占用太高了,或者要避免系统主动杀死 CPU 持续占用过高的进程,可以通过下面的配置来降低离线合成的 CPU 占用。
注意:开启以下选项会使离线合成的实时率(RTF)变大。
engine.setOptionBoolean(engineHandler, SpeechEngineDefines.PARAMS_KEY_TTS_LIMIT_CPU_USAGE_BOOL, true);
语音合成 SDK 支持使用复刻的音色进行合成,目前仅在线合成模式可以使用,且与预制的音色相比配置会有一些变化,需要配置一些额外参数。包括:
// 集群,需要重新初始化引擎实例才会使修改后的配置生效 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
触发各种操作,需要注意以下两点:
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
连续合成场景下,使用该指令触发一次合成,可以多次调用。推荐的调用策略如下:
合成结束回调
后发送;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 结构,内部包含三个字段:
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 格式音频数据。