说明:
当前页面为 v2.x.x 版本 SDK 开发文档。
离线 SDK 包含在线 SDK 功能,在线部分请参考 v2.x.x 版本在线 SDK 开发文档。
开发相关
开发准备
支持 Android 4.1 以上版本 API LEVEL 16,支持手机与平板。
按设备授权方式需要手机能够连接网络(3/4/5G 或 Wi-Fi 网络等)。
建议使用 Android Studio 进行开发。
下载安装 SDK
请参考开通授权,根据指引开通并下载 SDK 文件
解压后即是示例代码工程,目录 sdk 下的 aar 文件即 SDK 包。
用 Android Studio 打开工程查看语音合成示例代码。
环境配置
添加实时语音合成 SDK aar 包放在 libs 目录下,在 App 的 build.gradle 文件中添加以下代码。
implementation(name: 'qcloudtts-release', ext: 'aar')
<uses-permission android:name="android.permission.INTERNET"/><uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
接口说明
获得 TTS 合成器实例
//获得实例TtsController mTtsController = TtsController.getInstance();//销毁实例TtsController.release();
初始化引擎
mTtsController.init(Context context,TtsMode mode,TtsResultListener listener)
TTS合成器工作模式参数
如果您下载的压缩包为"xxx_offline.zip",则支持以下三种模式,如果为"xxx_online.zip",则仅支持在线模式。
参数 | 说明 |
TtsMode.OFFLINE | 离线 |
TtsMode.ONLINE | 在线 |
TtsMode.MIX | 混合 |
在线模式参数配置(不使用则不需要配置)
TtsController 配置参数方法
接口 | 说明 |
setAppId(long l) | 配置腾讯云 AppId |
setSecretId(String s) | 配置腾讯云 SecretId |
setSecretKey(String s) | 配置腾讯云 SecretKey |
setToken(String s) | STS 临时证书鉴权时需要设置 Token |
setOnlineVoiceSpeed(float f) | 设置在线所合成音频的语速,范围:[-2,2],分别对应不同语速: -2代表0.6倍,-1代表0.8倍,0代表1.0倍(默认),1代表1.2倍,2代表1.5倍
如果需要更细化的语速,可以保留小数点后 2 位,例如0.5/1.25/2.81等 |
setOnlineVoiceVolume(float f) | 设置在线所合成音频的音量 |
setOnlineVoiceType(int i) | |
setOnlineVoiceLanguage(int i) | 主语言类型:1-中文(默认),2-英文 |
setOnlineCodec(String s) | 在线模式编码格式,非业务必要不建议更改:默认mp3,目前支持"mp3"\\"wav"\\"pcm",如更改为 pcm 不支持播放 |
setConnectTimeout(int i) | 连接超时,默认15000ms(15s) ,范围[500,30000] 单位ms , Mix 模式下建议调小此值,以获得更好的体验 |
setReadTimeout(int i) | 读取超时,默认30000ms(30s) ,范围[2200,60000] 单位ms, Mix 模式下建议调小此值,以获得更好的体验 |
示例:
mTtsController.setAppId(0L);mTtsController.setSecretId("************************************");mTtsController.setSecretKey("***************************");mttsController.setToken(null);mTtsController.setOnlineVoiceSpeed(mVoiceSpeed);mTtsController.setOnlineVoiceVolume(1.0);mTtsController.setOnlineVoiceType(1001);mTtsController.setOnlineVoiceLanguage(1);mTtsController.setOnlineCodec("mp3");mTtsController.setConnectTimeout(15 *1000);mTtsController.setReadTimeout(30 *1000);
离线模式参数配置(不使用则不需要配置)
TtsController 配置参数方法
按设备授权
接口 | 说明 |
refreshAuth | 是否强制联网刷新授权(false:仅第一次联网激活下载授权文件,true:联网刷新授权文件,无网络下将激活失败) |
secret_id | 腾讯云 SecretId(可能与在线模式不是同一个账号,需要输入购买离线 SDK 对应的账号的 SecretId ) |
secret_key | 腾讯云 SecretKey (可能与在线模式不是同一个账号,需要输入购买离线 SDK 对应的账号的 SecretKey ) |
lic_key | 密钥对应的 licKey,请在腾讯云官网页面获取,或者由腾讯云商务线下下发 |
lic_pk | 密钥对应的 licPk,请在腾讯云官网页面获取,或者由腾讯云商务线下下发 |
示例:
String secret_id = "AKID********************9SXO";String secret_key ="f5********************05xa";String lic_key = "AI8********************064";String lic_pk = "hg9********************2BO";mTtsController.setOfflineAuthParamDoOnline(true, secret_id,secret_key,lic_key,lic_pk);
按应用授权
接口 | 说明 |
lic | 授权密钥 ,请在腾讯云官网页面获取,或者由腾讯云商务线下下发 |
lic_sign | 该密钥对应的 licPk,请在腾讯云官网页面获取,或者由腾讯云商务线下下发 |
lic_pk | 该密钥对应的 licSign,请在腾讯云官网页面获取,或者由腾讯云商务线下下发 |
示例:
String lic = "PLK********************YEoeO1EEUoTDH/R/mk=";String lic_sign = "PoTpR********************g0ucFkOQOU=";String lic_pk = "hg9********************2BO";mTtsController.setOfflineAuthParamDoOffline(lic,lic_sign,lic_pk);
TtsController 配置参数方法
接口 | 说明 |
setOfflineVoiceVolume(float voiceVolume) | 离线音量 > 0 |
setOfflineVoiceSpeed(float voiceSpeed) | 离线语速[0.5,2.0] |
setOfflineVoiceType(String s) | 离线音色名称,名称配置位于音色资源目录\\voices\\config.json 中,可自行删除或增加音色,音色需要授权,对应音色如未授权合成时会报错,可联系腾讯云商务购买。 默认如下(离线音色名称 - 音色名称) M206 - 智皓
db1 - 智聆
db3 - 智萌
db7 - 智甜
f0 - 智莉
f2 - 智芸
femozhifou - 智蓉
fn - 智瑜
kefu - 智美
kefu2 - 智娜
kefu3 - 智琪
m0 - 智云
m25 - 智华
memozhifou - 智靖
newsman - 智宁
pb - 智逍遥
xiaowei - 智言 |
setOfflineResourceDir(String resourceDir) | 设置离线模型资源所在路径 |
示例
mTtsController.setOfflineResourceDir("/sdcard/res");mTtsController.setOfflineVoiceSpeed(1.0f);mTtsController.setOfflineVoiceVolume(1.0f);mTtsController.setOfflineVoiceType("pb");
混合模式参数配置(不使用则不需要配置)
混合模式提供一种策略会在离线合成和在线合成之间进行切换。
在线模式下根据网络情况会切换自动离线模式(SDK判断网络较差时会切换),离线模式下每隔一段时间会尝试切回在线模式。
TtsController 授权配置
混合模式需要在线和离线均有授权,授权配置参照在线模式与离线模式的方法(两个都需要配置)。
TtsController 配置参数方法
在线模式配置和离线模式配置会影响混合模式下处于相应状态时合成行为。
以下为混合模式特有配置会影响策略的选择:
接口 | 说明 |
setCheckNetworkIntervalTime(int i) | Mix 模式下,已经连接网络,但出现网络错误或者后台错误后的检测间隔时间,用于从离线模式自动切换回在线模式,默认值5分钟,单位为秒 |
示例:
mTtsController.setCheckNetworkIntervalTime(5 * 60);
合成文本入参接口
接口 | 说明 |
synthesize(String text,) | text 为需要合成的文本 |
synthesize( String utteranceId) | utteranceId 为标记该文本的 ID,将随合成结果返回宿主层 |
示例:
//内部有维护队列,可持续添加语句,SDK内将依次合成TtsError error = null;error = mTtsController.synthesize("今天天气不错","第1句");error = mTtsController.synthesize("腾讯云语音合成","第2句");error = mTtsController.synthesize("腾讯云AI","第3句");error = mTtsController.synthesize("腾讯云AI","第4句");//取消未合成的任务并清空内部队列mTtsController.cancel();
合成监听器,用于获取合成结果
实例化TtsResultListener时,默认需要重写onSynthesizeData()和onError()方法。
onSynthesizeData()方法签名说明
参数 | 说明 |
byte[] bytes | 语音数据 |
String utteranceId | 语句 ID |
String text | 文本 |
int engineType | 引擎类型;0:在线,1:离线 |
onError()方法签名说明
参数 | 说明 |
TtsError error | 错误信息,无错误返回 null |
String utteranceId | 语句 ID(如果有则返回) |
String text | 文本(如果有则返回) |
onOfflineAuthInfo()方法签名说明
参数 | 说明 |
offlineAuthInfo.getExpireTime() | 授权到期时间 |
offlineAuthInfo.getError().getCode() | 0为授权成功,其他为失败 |
offlineAuthInfo.getResponse() | 使用在线拉取授权文件的方式鉴权时,服务器返回的 Response 数据(仅授权失败时需要关注) |
示例
TtsResultListener listener = new TtsResultListener() {@Overridepublic void onSynthesizeData(byte[] bytes, String utteranceId, String text, int engineType) {// 您可以在这里将音频保存或者送入播放接口播放,可调用播放器入参接口入参}@Overridepublic void onError(TtsError error, String utteranceId, String text) {// 您可以在这里添加错误后处理//注:实际业务上判断一下,如果是混合模式下返回在线合成的后端错误码,应当忽略,可不做处理,SDK内会调用离线合成继续工作}@Overridepublic void onOfflineAuthInfo(QCloudOfflineAuthInfo offlineAuthInfo) {//offlineAuthInfo 返回离线sdk授权信息,包含错误码、到期时间、当前设备ID//注意,如果使用离线模式,需要收到此回调后再调用合成接口,否则可能会因授权失败导致合成失败!!!}@Overridepublic void onChunk(ByteBuffer chunk) {// 离线合成返回的流式数据,格式为16k 单通道pcm}}
初始化播放器
如果 SDK 的内置播放器无法满足您的需求,您也可以使用自己实现的播放器替换。demo 中也额外提供了一份播放器源码,您可以修改播放器逻辑,源代码位于 MediaPlayerDemo.java,与 SDK 内置播放器一致。
//使用SDK中提供的播放器QCloudMediaPlayer mediaPlayer = new QCloudMediaPlayer(new QCloudPlayerCallback() {@Overridepublic void onTTSPlayStart() {Log.d(TAG, "开始播放");}@Overridepublic void onTTSPlayWait() {Log.d(TAG, "播放完成,等待音频数据");}@Overridepublic void onTTSPlayResume() {Log.d(TAG, "恢复播放");}@Overridepublic void onTTSPlayPause() {Log.d(TAG, "暂停播放");}@Overridepublic void onTTSPlayNext(String text, String utteranceId) {Log.d(TAG, "开始播放: " + utteranceId + "|" + text);}@Overridepublic void onTTSPlayStop() {Log.d(TAG, "播放停止,内部队列已清空");}@Overridepublic void onTTSPlayError(QPlayerError error) {Log.d(TAG, "播放器发生异常:"+error.getmCode() + ":" + error.getmMessage());}/*** @param currentWord 当前播放的字符(此为预估值)* @param currentIndex 当前播放的字符在所在的句子中的下标(此为预估值)*/@Overridepublic void onTTSPlayProgress(String currentWord, int currentIndex) {Log.d(TAG, "onTTSPlayProgress: " + currentWord + "|" + currentIndex);}});
播放器入参
enqueue()方法签名说明
接口 | 说明 |
byte[] bytes | 返回音频流,通过传入字节数组播放 |
File audio | 返回音频文件,通过传入文件播放 |
String text | 音频对应的文本 |
String utteranceId | 文本 ID |
示例
//通过音频数据入参QPlayerError err = mediaPlayer.enqueue(byte[] bytes,String text,String utteranceId);//通过音频文件入参QPlayerError err = mediaPlayer.enqueue(File audio,String text,String utteranceId);