资讯 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

语音合成 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总体框图

image.png

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 未知错误
上一篇
语音合成 iOS SDK
下一篇
语音识别