语音合成 HarmonyOS SDK
1. 文档说明
文档名称 | 语音合成集成文档 |
---|---|
所属平台 | HarmonyOS |
提交日期 | 2024-12-24 |
概述 | 百度语音合成客户端Harmony版SDK(以下简称BDTTSClient)是一种面向HarmonyOS设备的语音合成解决方案,以Har包的形式发布。目前版本已支持SDK内部直接播放合成语音和从SDK获取语音数据,并支持男女声、语速、音调、音量、音频码率设置。 |
短语说明 | 语音合成:将文本合成为语音,即声音文件合成引擎:将文本合成为语音的核心模块TTS:Text To Speech,即“从文本到语音”BDTTSClient:语音合成SDK简称,详见下条语音合成SDK:即本开发包,文中简称为BDTTSClient。BDTTSClient是一个封装了网络收发、音频播放功能的语音合成解决方案。借助BDTTSClient可以快速地在应用程序中集成语音合成功能 |
2. 版本说明
名称 | 版本号 | 说明 |
---|---|---|
语音合成 | 1.0.0 | |
系统支持 | HarmonyOS 5.0.0(APILevel 12)+ | 需要开发者通过compatibleSdkVersion来保证支持系统的检测 |
架构支持 | arm64-v8a |
3. SDK说明
3.1开发包说明
文件名称 | 说明 |
---|---|
doc/Baidu_TTS_SDK_Harmony_Manual.pdf | 本文档 |
har | 语音合成SDK har库 |
BaiduTtsDemo | 开发示例(DevEco Studio project) |
version.readme | 当前产物版本,包括so库及har包 |
3.2总体框图
4.集成指南
4.1添加BDTTSClient到工程
har方式集成:将开发包中的har目录拷贝到工程目录entry/libs/中。在oh-package.json5文件中增加以下依赖
"dependencies": {
"@package/baidu-tts":"file:./libs/xxxx.har"
}
4.2添加语音合成资源文件
BaiduTtsDemo中所有的资源文件以及参数值仅供该demo工程运行体验使用,业务方需要申请自己的资源文件和参数值。可参照demo中的路径以及代码逻辑处理自己的相应文件。
4.3权限声明
BDTTSClient需要一些权限需要在module.json5文件,增加如下权限:
"requestPermissions": [
{
"name":"ohos.permission.INTERNET"
}
]
5.语音合成功能代码
5.1TTS初始化设置
private initialTts(): void {
// 获取tts实例,Context需要保证在tts运行期间不会被释放
let speechSynthesizer = new SpeechSynthesizer(this);
// 设置tts监听器
speechSynthesizer.setSpeechSynthesizerListener(SpeechSynthesizerListener);
// 如果需要离线合成,设置离线资源
this.setOfflineParam(speechSynthesizer);
// 如果需要在线合成,设置在线资源
this.setOnlineParam(speechSynthesizer);
}
private setOfflineParam(speechSynthesizer: SpeechSynthesizer): void {
//设置您的app_id
speechSynthesizer.setParam(SpeechSynthesizer.PARAM_APP_ID, "your appid");
//设置您的鉴权sn
speechSynthesizer.setParam(SpeechSynthesizer.PARAM_AUTH_SN, "your auth sn");
// 离线资源库路径
speechSynthesizer.setParam(SpeechSynthesizer.PARAM_OFFLINE_MODEL, this.setOfflineModel());
// 初始化离线tts服务,服务会读取相应离线资源进行加载,此过程是耗时操作。非必须调用。提前调用,会减少第一次合成或者合成播放接口耗时。
speechSynthesizer.loadOfflineTts().then(
(ttsError: ITtsError) => {
let resultCode = ttsError.getDetailCode();// 返回值为0,初始化离线成功
let resultMessage = ttsError.getDetailMessage();// 返回值为0时,描述信息为空
} );
}
private setOfflineModel():string {
let offlineModel: Record<string, string> = {};
offlineModel[SpeechSynthesizer.TTS_TEXT_MODEL_FILE] = "text音库在设备中的可访问绝对路径";
offlineModel[SpeechSynthesizer.TTS_SPEECH_MODEL_FILE] = "speech音库在设备中的可访问绝对路径";
return JSON.stringify(offlineModel);
}
private setOnlineParam(speechSynthesizer: SpeechSynthesizer) : void {
// 设置在线需要的api_key和secret_key
speechSynthesizer.setParam(SpeechSynthesizer.PARAM_API_KEY, "your api_key");
speechSynthesizer.setParam(SpeechSynthesizer.PARAM_SECRET_KEY, "your secret_key");
// 设置在线发音人
speechSynthesizer.setParam(SpeechSynthesizer.PARAM_ONLINE_SPEAKER,
onlineSpeaker);
// 在线超时时间,MIX模式超时会切换至离线,ONLINE模式会超时
speechSynthesizer.setParam(SpeechSynthesizer.PARAM_ONLINE_TIMEOUT,
“2000”); // 注意参考参数范围
// 初始化在线tts服务,服务会读取相应资源进行加载,此过程是耗时操作。非必须调用。提前调用,会减少第一次合成或者合成播放接口耗时。
speechSynthesizer.loadOnlineTts().then(
(ttsError: ITtsError) => {
let resultCode = ttsError.getDetailCode();// 返回值为0,初始化在线成功
let resultMessage = ttsError.getDetailMessage();// 返回值为0时,描述信息为空
} );
}
5.2参数设置
在初始化tts或者调用tts合成方法之前,可以对参数进行配置(未设置的参数将使用默认值)。设置成功返回值为0。设置后,如果未调用release之前,该值未被新值覆盖前,一直生效。 示例:设置合成音频音量大小
speechSynthesizer.setParam(SpeechSynthesizer.PARAM_VOLUME, "5");
5.2.1在线,离线必设参数如下
参数名 | 默认值 | 备注 |
---|---|---|
PARAM_API_KEY | undefined | 在线请求认证参数,产品key,需要在云上百度配置包名。在线合成必须设置 |
PARAM_SECRET_KEY | undefined | 在线请求认证参数,产品secret,在线合成必须设置 |
PARAM_ONLINE_SPEAKER | "0" | 在线发音人值,在线合成必须设置 |
PARAM_ONLINE_TIMEOUT | "6000" | 在线请求超时时间,在MIX或者ONLINE模式下生效。取值范围200~6000,单位:毫秒 |
PARAM_APP_ID | undefined | 离线请求认证参数,AI开放平台用户填写申请时的app_id,非AI开放平台用户填写产品pid,离线合成必须设置 |
PARAM_TTS_LICENCE_FILE | "/data/storage/el2/base/haps/entry/files/baidu_tts_license" | 离线鉴权文件,用户可以设置可访问的指定文件的保存位置,设置值参考默认值 |
PARAM_OFFLINE_MODEL | undefined | 离线资源文件目录,使用自定义发音人,或者使用text,speech音库这种方案。切换发音人时,修改该值即可,调用loadOfflineTts接口,切换发音人及时生效,否则延迟至下次synthesize,speak等接口调用时生效。 |
5.2.2其它辅助参数如下
参数 | 类型 | 默认值 | 取值范围 | 说明 |
---|---|---|---|---|
PARAM_VOLUME | float | "5" | 范围[0-15] | |
PARAM_SPEED | float | "5" | 范围[0-15] | |
PARAM_PITCH | float | "5" | 范围[0-15] | |
PARAM_AUDIO_ENCODE | AudioEncoderFormat.OPUS | 在线音频压缩方式OPUS、PCM | ||
PARAM_BITRATE | Bitrate.OPUS_64K | 在线音频压缩码率,与PARAM_AUDIO_ENCODE配合使用OPUS_64K,OPUS_128K(OPUS方式)PCM(PCM方式) | ||
PARAM_OPEN_XML | "0" | "0":关闭xml解析"1":打开xml解析 | ||
PARAM_TEXT_CTRL | json | undefined | 前端模型配置参数 | |
PARAM_AUDIO_CTRL | json | undefined | 前端模型配置参数 | |
PARAM_PLAYER_VOLUME | float | "1.0" | 播放器音量[0,1.0] | |
PARAM_PLAYER_USAGE | audio.StreamUsage.STREAM_USAGE_MUSIC | 播放器usage |
5.3合成
speechSynthesizer.synthesize(TtsEntity); 该接口比较耗时,采用排队策略,调用后将自动加入合成队列,并按调用顺序进行合成 TtsEntity参数详解:
参数 | 说明 |
---|---|
text | 此次要合成的文本内容。必设参数。注:该接口传入文本text的长度不能超过1024个GBK字节。 |
TtsMode | 此次合成模式。ONLINE 纯在线模式,OFFLINE纯离线模式,MIX优先使用在线,在线超时后使用离线模式。使用前请确保相应模式的必要参数已经设置。 |
HashMap<string, string> | 此次合成参数,仅本次生效,参数与setParam一致,不会覆盖setParam设置值的默认效果。 |
5.4合成并播报
speechSynthesizer.speak(TtsEntity); 该接口比较耗时,采用排队策略,调用后将自动加入合成队列,并按调用顺序进行合成和播放 TtsEntity参数详解:参照合成接口。
5.5流程控制
服务的生命周期控制方法。
stop():停止当前实例合成或者停止合成播报
release():释放当前实例,当所有实例都被释放时,tts整个服务停止,当前实例的任何API都不能再次调用
pause():暂停当前实例的合成播报内容。如果不需要继续播报,需要先调用stop后,再使用speak
resume():继续播报当前实例的播报内容,与pause()相对应
5.6状态监听
为了更好地实现用于界面,BDTTSClient提供了SpeechSynthesizerListener监听接口用于对合成器的状态进行通知。 完整的开发示例请参见开发包所附示例BaiduTtsDemo。
5.7合成状态监听器回调接口
onSynthesizeResponse(synthesizerResponse: SynthesizerResponse): void;
// 获取业务测设置的合成标识id
let utteranceId = synthesizerResponse.getUtteranceId();
// 获取当前实例id,构建多speechSynthesizer实例时用来区分不同的实例
let instanceId = synthesizerResponse.getInstanceId();
// 当前请求的唯一id,该值会串通后面所有链路
let sn = synthesizerResponse.getSn();
5.7.1合成开始时的回调接口
synthesizerResponse.getSynthesizeType() == SYNTHESIZE_START
5.7.2合成过程中的回调接口
synthesizerResponse.getSynthesizeType() == SYNTHESIZE_DATA_ARRIVED
let progress = synthesizerData.getAudioProgress(); // 获取合成进度
let engineType = synthesizerData.getEngineType();// 获取合成类型。0在线,1离线
let sampleRate = synthesizerData.getAudioSampleRate();// 当前音频采样率
let audioData = synthesizerData.getAudioData();// 当前音频数据
合成数据过程中的回调接口,返回合成数据和进度,分多次回调。参数utteranceId为合成文本的ID;参数progress为合成按字符划分的进度,比如:你好啊进度是0-3;参数audioData为返回的合成音频数据。返回的数据audioData是2字节精度,单声道的pcm数据;参数engineType,0为在线合成引擎合成,1为离线合成引擎合成。
5.7.3合成正常结束时的回调接口
synthesizerResponse.getSynthesizeType() == SYNTHESIZE_FINISH
5.7.4合成出错时的回调接口
synthesizerResponse.getSynthesizeType() == SYNTHESIZE_ERROR
synthesizerResponse.getSynthesizerError() // 获取相关的错误信息
5.7.5合成播报开始时的回调接口
synthesizerResponse.getSynthesizeType() == PLAY_START
参数参照SYNTHESIZE_START。
5.7.6合成播报过程中的回调接口
synthesizerResponse.getSynthesizeType() == PLAY_PROGRESS
参数参照SYNTHESIZE_DATA_ARRIVED。
5.7.7合成播报正常结束时的回调接口
synthesizerResponse.getSynthesizeType() == PLAY_FINISH
参数参照SYNTHESIZE_FINISH。
5.8SynthesizerTool类
5.8.1检验模型文件的有效性
public static verifyModelFile(filePath:string):boolean
filePath:模型文件的绝对路径
5.8.2获取离线引擎基本信息
public static getEngineInfo():string
5.8.3获取libbd_etts.so版本信息
public static getEngineLibVersion():string
5.8.4获取libBDSpeechDecoder_V1.so版本信息
public static getDecoderLibVersion():string
5.8.5获取离线引擎版本信息
public static getEngineVersion():number
5.8.6获取模型文件是否与当前版本匹配
public static matchResEngine(filePath:string) :number
5.8.7获取音库的采样率
public static getSpeechSampleRate(filePath:string):number
5.8.8获取license剩余天数
public static getLicenseLeftValidDays(licenseFilePath:string, id:string, sn:string, cuid:string):number
- @return 剩余天数,小于0为错误。
参数说明
参数名 | 类型 | 说明 |
---|---|---|
licenseFilePath | string | license文件路径需要与{@linkSpeechSynthesizer#PARAM_TTS_LICENCE_FILE}设置的值一致 |
id | string | license_v2 内部产品线传递pid;license_v1 传递appid |
sn | string | license_v2授权参数,没有传递NULL |
6.错误码列表
错误码值 | 错误码描述 |
---|---|
-1 | 在线引擎授权失败 |
-4 | 在线授权中断异常 |
-5 | 在线授权执行时异常 |
-6 | 在线授权时间超时 |
-7 | 在线合成返回错误信息 |
-10 | 在线引擎合成时异常 |
-11 | 当前mode不支持的操作 |
-12 | 在线合成请求解析出错 |
-15 | 在线合成获取合成结果超时 |
-16 | 在线授权被取消 |
-18 | 在线合成无效的主机名 |
-19 | 在线合成读数据失败 |
-20 | 在线合成连接失败 |
-21 | 在线合成socket异常 |
-24 | 在线合成请求主机名为空 |
-25 | 在线合成发送数据失败 |
-29 | 在线合成接收前缀数据长度错误 |
-30 | 在线合成接收数据长度错误 |
-31 | 在线合成合成数据包速度过快 |
-32 | 在线合成网络未知类型错误 |
-39 | 在线服务临时错误 |
-100 | 离线引擎授权失败 |
-102 | 离线授权下载License失败 |
-105 | 离线授权中断异常 |
-106 | 离线授权执行时异常 |
-107 | 离线授权执行时间超时 |
-108 | 离线合成引擎初始化失败 |
-110 | 离线合成时异常 |
-111 | 离线合成返回值非0 |
-118 | 离线授权任务被取消 |
-122 | 离线tts_offline_resource文件异常 |
-123 | 离线发音人参数异常 |
-124 | 下载license失败,sn参数异常 |
-125 | 离线合成文本为空 |
-200 | 混合引擎离线在线都授权失败 |
-204 | 混合引擎初始化tts时,离线初始化失败 |
-206 | 混合引擎初始化tts时,在线初始化失败 |
-300 | 合成文本为空 |
-301 | 合成文本长度过长(不要超过GBK1024个字节) |
-302 | 合成文本无法获取GBK字节 |
-401 | TTS模式无效 |
-402 | TTS合成队列已满 |
-406 | TTS被调用方法参数无效 |
-500 | Context被释放或为空 |
-700 | 播报的短音频文件不存在 |
-701 | 当前接口不支持播报短音频 |
-800 | 当前实例已经被释放,需要重新创建实例 |
-1001 | 模型管理请求出错 |
-1002 | 模型管理服务器端错误 |
-1003 | 模型管理数据库模型信息无效 |
-1004 | 模型管理数据库模型文件信息无效 |
-1005 | 模型数据已经存在(或已下载) |
-1006 | 无法获取到模型信息 |
-1007 | 无法获取到模型文件信息 |
-1008 | 模型检查过程异常 |
-1009 | 模型文件下载时异常 |
-9999 | 未知错误 |