Android离线语音合成实践：基于系统TTS的纯本地文字转语音方案

简介：一款面向 Android 开发者的离线文字转语音演示工程，核心价值在于不依赖手机自带语音合成服务，即使设备未安装任何文字转语音组件，也能独立完成离线朗读，并可自由切换发音人、调节语速，适合需要在无网络或受限环境下提供语音能力的应用作为参考。压缩包共包含 25 个文件，以 Java 源码、XML 布局与配置、prefs 工程配置以及 so 动态库为主，整体体积仅 511KB，轻量易部署；其中 Java 代码负责核心调用逻辑，XML 负责界面布局与资源定义，so 库则封装底层离线合成能力。项目工程目录结构清晰，源码、资源、库文件分区明确，可直接导入集成开发环境运行，便于快速验证离线语音合成效果，并理解语音引擎的调用与集成方式。目前已有 3090 人学习下载，适合需要接入离线语音能力或对现有方案进行二次开发的 Android 工程师。值得留意的是，作者注明英文单词目前会逐字母朗读，这也为后续优化留下了明确的改进方向。 做离线语音合成这个需求，最初是因为一个巡检项目——现场在厂区深处，网络信号约等于没有，但设备必须把告警信息读出来。当时第一反应是找第三方SDK，结果一调研，要么要联网，要么SDK体积大得离谱，要么免费额度根本不够用。后来才把目光放回系统自带的android.speech.tts.TextToSpeech，也就是常说的 Android 原生 TTS，搭配离线语音包，把"文字转语音"这件事彻底做成了纯本地能力。这篇文章就基于我整理的一个 android_tts_离线语音demo包，完整拆解从选型、工程搭建、核心代码到实机踩坑的全过程，给那些同样想把离线 TTS 做进 App、但又不想被第三方 SDK 绑死的同学一条可以照着走的路。

1. 离线TTS选型复盘：为什么这个Demo我只用系统引擎

先说结论：如果你的 App 需要的是"中文播报、无网可用、包体可控、维护成本低"这四个点，Android 系统自带的 TextToSpeech API 就是性价比最高的方案。这个结论不是我拍脑袋得出的，而是对比了一圈之后的结果。

1.1 在线语音合成与离线合成的本质差异

在线 TTS（比如各类云厂商的语音合成接口）有一个绕不开的问题：所有文本都要先上传到服务器，合成完再下载音频。好处是音色多、自然度高，坏处也很明显——依赖网络、有延迟、有并发限制、有费用。在弱网或断网环境下，业务直接瘫掉。对工业巡检、无障碍阅读、导航播报这类场景来说，这种依赖是致命的。

离线 TTS 则完全不同。语音合成在设备本地完成，文本不出设备，响应是毫秒级的。Android 系统从 5.0（API 21）开始，自带的 TextToSpeech 引擎就已经具备比较完整的离线合成能力，只要你把对应语言的语音数据下载到本地。它最大的限制是音色相对单一、自然度不如云端大模型，但这个短板在"告警提示、状态播报、短句朗读"这类场景里完全够用。

1.2 系统引擎与第三方SDK的取舍

我做了个简单的对比表，当时选型时基本就是看这几项：

这里有个容易忽略的细节：系统引擎离线包装好之后，是全局共享的。也就是说，用户在系统设置里下载了"中文（中国）"的离线语音数据，你的 App 直接就能用，不需要再往自己包里塞任何语音资源。这也是我最终选择系统引擎的核心原因——省包体、省流量、省授权费。

1.3 Demo 的核心目标边界

我做的这个 demo 包里没有花哨的功能，只围绕一件事：把"文字转语音"做成一个稳定、可复用的离线播报模块。具体来说包含四块逻辑：

• 初始化 TextToSpeech 引擎并处理异步回调；
• 检查中文语音数据是否可用，缺失时引导用户安装离线语音包；
• 调用 speak 方法完成文字转语音，并监听播报进度；
• 处理 Activity 销毁、引擎启动失败等生命周期和异常问题。

这套东西从"Demo"变成"能上线的模块"，其实就差几个坑没踩平。下面把每一步都摊开讲。

2. 工程搭建与离线语音包准备：动手前先弄清这几件事

2.1 Android Studio 工程的基本配置

我用的是常规的 Android Studio 项目，模块结构没做任何特殊处理。关键的配置集中在build.gradle里：

android { compileSdk 34 defaultConfig { applicationId "com.example.ttsdemo" minSdk 21 targetSdk 34 versionCode 1 versionName "1.0" } }

minSdk 21对应 Android 5.0，这是系统 TTS 离线能力比较完整的起点。如果你的业务设备系统版本更低，也不是不能用，但离线语音包的管理逻辑会弱一些，我不建议在太老的系统上折腾离线 TTS。

权限方面有个反直觉的点：离线 TTS 完全不需要网络权限。我在 demo 的AndroidManifest.xml里特意不声明INTERNET权限，这既是为了确认"离线"是真的离线，也能防止审核时被质疑多余权限。如果你只是做纯本地播报，千万别手滑加网络权限。

<manifest xmlns:android="http://schemas.android.com/apk/res/android"> <application android:label="@string/app_name" android:theme="@style/Theme.AppCompat"> <activity android:name=".MainActivity" android:exported="true"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> </application> </manifest>

2.2 离线语音包从哪来

这是最容易被误解的地方。很多人以为离线语音包是 SDK 的一部分，要自己下载然后塞进 assets。其实在系统 TTS 的体系里，语音数据由 TTS 引擎自己管理。常见的引擎包括 Google 的 Speech Services、部分国产 ROM 自带的语音引擎（比如小爱语音引擎、讯飞语音引擎），它们都遵循 Android 的 TTS 框架接口。

所以流程是这样的：

• App 通过接口询问引擎："中文（普通话）能不能合成？"
• 引擎返回LANG_MISSING_DATA（缺数据）或LANG_AVAILABLE（可用）；
• 如果缺数据，App 发送一个系统 Action，跳转到语音数据安装页面；
• 用户在页面里点下载，等下载完成，语音数据就躺在系统里了；
• 之后任何 App 再调用同一个引擎做中文合成，都是离线完成。

话虽简单，这里藏着一个巨大的坑：不同厂商 ROM 自带的引擎不一样，跳转安装页的代码在部分机型上会直接找不到页面。这个问题我在后面"踩坑记录"里详细说，先记住结论——不能假设 ACTION_INSTALL_TTS_DATA 在所有设备上都能跳转成功。

2.3 检查语言可用性的标准写法

初始化 TTS 时，最核心的一件事是检查语言状态。标准的onInit回调里，我们拿到TextToSpeech实例后立刻设置语言，并用返回值判断：

TextToSpeech tts = new TextToSpeech(context, status -> { if (status == TextToSpeech.SUCCESS) { int result = tts.setLanguage(Locale.CHINESE); if (result == TextToSpeech.LANG_MISSING_DATA || result == TextToSpeech.LANG_NOT_SUPPORTED) { // 语言数据缺失或引擎不支持 Intent installIntent = new Intent(TextToSpeech.Engine.ACTION_INSTALL_TTS_DATA); installIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); startActivity(installIntent); } else { // 中文离线语音可用，可以正常 speak } } });

setLanguage的返回值非常关键，很多人栽在这。返回LANG_MISSING_DATA不等于引擎不行，只是语音包没装；返回LANG_NOT_SUPPORTED才是引擎压根不支持中文。这两者的处理策略完全不同：

• LANG_MISSING_DATA：引导用户去下载语音包，这是可修复的状态；
• LANG_NOT_SUPPORTED：建议用户更换 TTS 引擎（比如装一个支持中文的引擎并在系统设置里切换）。

3. 核心代码链路：初始化、语言检查、语音合成与进度回调

这一节直接把我 demo 里最核心的封装代码摊开讲。我不会贴完整的一百行类，而是把每个职责拆分出来，你照着拼就能用。

3.1 初始化：引擎启动是异步的，状态机必须设计好

TextToSpeech的构造函数是异步初始化，onInit回调触发时引擎才真正可用。这个"异步"坑了好多人——很多人直接在new TextToSpeech()之后立刻调用speak，结果压根没声音，就是因为引擎还没就绪。

我的处理方式是给 TTS 模块维护一个简单的状态：

public class TtsManager { private TextToSpeech tts; private boolean initialized = false; private final Queue<String> pendingQueue = new ArrayDeque<>(); public void init(Context context) { if (tts == null) { tts = new TextToSpeech(context, status -> { if (status == TextToSpeech.SUCCESS) { int langResult = tts.setLanguage(Locale.CHINESE); if (langResult == TextToSpeech.LANG_AVAILABLE) { initialized = true; // 把初始化期间积压的文本一次性播报 while (!pendingQueue.isEmpty()) { speakInternal(pendingQueue.poll()); } } } }); } } public void speak(String text) { if (!initialized) { pendingQueue.offer(text); return; } speakInternal(text); } private void speakInternal(String text) { tts.speak(text, TextToSpeech.QUEUE_ADD, null, "utterance_" + System.currentTimeMillis()); } }

看起来简单，但这里面有两个细节值得说：

• 积压队列：初始化完成前，调用方可能已经发来了好几条播报请求（比如 Activity onCreate 里连续调用）。如果不缓冲，这些播报会全部丢弃。这个队列是在真机上被"吞播报"之后才加上的。
• utteranceId 唯一：speak 的第四个参数是 utteranceId，它用来关联进度回调，我故意用时间戳保证唯一，否则回调里可能出现混乱。

3.2 speak 队列模式：QUEUE_FLUSH 和 QUEUE_ADD 到底怎么选

这是 TTS 使用中最让人纠结的一个点。简单说：

• QUEUE_FLUSH：清空当前正在播和排队的语音，立刻播这一条；
• QUEUE_ADD：把这条语音追加到当前队列尾部，播完前面的才轮到它。

业务里通常的规则是：紧急打断型播报用 FLUSH，普通通知型播报用 ADD。比如巡检设备报"温度过高"，这种必须立刻打断当前播报，用 FLUSH；如果是"北京时间十二点整"，排队讲就行，用 ADD。

我把这个选择直接暴露成接口参数：

public void speak(String text, boolean interrupt) { int queueMode = interrupt ? TextToSpeech.QUEUE_FLUSH : TextToSpeech.QUEUE_ADD; tts.speak(text, queueMode, null, "utterance_preview"); }

这里有个性能隐患：如果连续多条 ADD 且每段文本很长，TTS 引擎会逐句合成并排队，内存和 CPU 都会有压力。所以我在 demo 里对长文本做了简单分段限制，超过某个长度就拆成多条按 ADD 送入，避免一条超长文本让引擎卡顿。

3.3 进度回调：播报完成后的"钩子"

光有 speak 还不够，很多时候业务需要知道"这段话什么时候读完"。比如播报完一条告警后，要紧接着执行下一步操作。这个钩子由UtteranceProgressListener提供：

tts.setOnUtteranceProgressListener(new UtteranceProgressListener() { @Override public void onStart(String utteranceId) { // 开始播报 } @Override public void onDone(String utteranceId) { // 播报完成 } @Override public void onError(String utteranceId) { // 播报失败 } });

注意onDone是在引擎的 Binder 线程回调的，不能直接更新 UI，需要 post 到主线程。还有个小坑：旧版本的OnUtteranceCompletedListener已经废弃，但很多老教程还在用，新项目请直接走UtteranceProgressListener。

3.4 语音参数调节：语速、音调与音量

离线 TTS 的可调参数不算多，但够用：

// 语速，1.0 为正常速度，0.5 慢一倍，2.0 快一倍 tts.setSpeechRate(1.0f); // 音调，同样以 1.0 为基准 tts.setPitch(1.0f);

这两个参数直接影响听感。我的实测经验是：告警类文本建议语速 1.2 左右，音调 1.0，太快容易听不清关键信息，太慢又拖沓；朗读类内容可以语速 0.9，音调 1.0，听起来更从容。音量则直接用系统的媒体音量控制，也可以在合成前用AudioManager临时调整，但注意别忘了恢复。

3.5 生命周期管理：Activity 销毁时及时释放

如果不释放 TTS 实例，会一直占用引擎资源，严重时导致后续初始化变慢甚至失败。标准做法是在Activity.onDestroy()里 shutdown：

@Override protected void onDestroy() { if (ttsManager != null) { ttsManager.shutdown(); } super.onDestroy(); }

这里有个真实场景：如果 App 里多个页面都会播报，建议把 TTS 模块做成单例，由 Application 统一持有，而不是每个 Activity 都创建新实例。否则每次进页面都要等待异步初始化，体验很差，而且频繁创建/释放容易触发引擎的 Binder 连接问题。

4. 真机运行中的实测踩坑记录

Demo 跑起来容易，跑稳很难。这一节是我在实机上踩过的坑，每一个都花过不少时间排查。

4.1 坑一：部分机型跳转语音包安装页直接报 ActivityNotFoundException

这是个经典问题。ACTION_INSTALL_TTS_DATA并不是所有 ROM 都实现了。某些国产 ROM 的引擎包名不同，对应的安装页面 Activity 也不在默认路径下，直接 startActivity 就会抛异常。

排查链路是这样的：

• 先用adb shell dumpsys package查看当前默认 TTS 引擎是什么；
• 再用PackageManager.queryIntentActivities检查 ACTION_INSTALL_TTS_DATA 是否有可响应的 Activity；
• 如果确实没有，就得退而求其次：跳转到系统"文字转语音"设置页（Settings.ACTION_TEXT_TO_SPEECH_SETTINGS），让用户手动去设置里安装语言数据。

示例代码：

private void openTtsSettings(Context context) { try { Intent intent = new Intent(TextToSpeech.Engine.ACTION_INSTALL_TTS_DATA); intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); context.startActivity(intent); } catch (ActivityNotFoundException e) { // 降级：打开系统 TTS 设置页 Intent settings = new Intent(Settings.ACTION_TEXT_TO_SPEECH_SETTINGS); settings.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); context.startActivity(settings); } }

降级方案虽然多了用户手动操作，但至少不会崩溃。在特殊硬件设备（比如工业平板）上，这个降级路径几乎是必走的。

4.2 坑二：明明设置了语言，为什么还是 LANG_NOT_SUPPORTED

这个问题绝大多数出现在"模拟器优先开发"的人身上。电脑模拟器里的 TTS 引擎经常没有中文语音数据，甚至根本没有可用的离线引擎。你在模拟器上测试，setLanguage返回 LANG_NOT_SUPPORTED 是正常的，不代表真机上不行。

解决办法只有一个：尽早用真机测试。如果手边只有模拟器，可以先在系统设置里看"文字转语音输出"是否有可用的引擎和语言数据。这个排查顺序很重要，别一上来就怀疑代码写错了。

4.3 坑三：QUEUE_ADD 模式下播报文本堆积

这个坑比较隐蔽。业务里如果有一条超长文本被切成几十段连续 ADD，或者短时间内收到大量播报请求，TTS 队列会越积越长，用户听到的就是没完没了的朗读，而且想打断都难。

我的处理策略是给队列加一个"水位线"。当 pending 的播报超过 N 条时，直接丢弃中间部分，只保留最新一条。对于告警类场景，丢旧保新是完全合理的——用户只需要知道当前最紧急的状态。

public void speak(String text, boolean interrupt) { if (interrupt) { tts.speak(text, TextToSpeech.QUEUE_FLUSH, null, "utterance_" + System.currentTimeMillis()); } else { if (pendingCount >= MAX_QUEUE_SIZE) { tts.stop(); // 清空已有队列 } tts.speak(text, TextToSpeech.QUEUE_ADD, null, "utterance_" + System.currentTimeMillis()); } }

当然，stop()之后立即 ADD 偶尔会丢首句，所以稳妥一点的做法是先短暂延迟再 ADD，或者在 onDone 回调里再发下一条。这些细节需要在具体场景里调。

4.4 坑四：初始化完成后立刻 speak 偶发无声

这也是异步初始化带来的连锁问题。onInit回调里setLanguage成功后立刻调用speak，听感上有时会丢前半句。原因是引擎虽然报告初始化完成，但语音数据可能还在加载（尤其是刚下载完离线包，引擎还没有重新扫描数据）。

我的解决方法是：在 onInit 成功但不立刻 speak，而是在极短延迟（比如 100ms）后再发，或者等待第一次 onStart 回调后再发后续内容。这个"极短延迟"听起来不够优雅，但在实际项目中确实能有效解决偶发丢字。

4.5 坑五：多个 TTS 实例互相干扰

如果你在 App 里同时创建了两个 TextToSpeech 实例，操作同一个引擎，有时会出现其中一个实例的设置（语速、音调）影响另一个实例，甚至出现"一个正常播报，另一个没声音"的情况。

排查这个问题的思路是先全局搜索new TextToSpeech，确认只有一个实例。我的 demo 直接把 TTS 模块做成了 Application 级别的单例，从根上避免这种问题。这也是为什么我建议不要在页面级频繁创建销毁 TTS 的原因之一。

5. 从Demo到可落地的模块：性能、体验与后续优化方向

Demo 跑通只是一个起点。真正让它变成可用模块，还需要做一些性能与体验层面的打磨。

5.1 预初始化：让第一句播报更快

如果等到用户点击播报按钮时才去创建 TTS 实例，第一次播报的延迟会非常明显（引擎初始化加语音数据加载，冷启动可能几百毫秒到一秒多）。更好的做法是在 Application 启动时异步初始化 TTS，甚至在 Activity 启动后空闲时预热。

我的做法是：

• Application.onCreate 里启动一个低优先级线程，初始化 TTS；
• 初始化完成后仅设置好语言和参数，不立即播报；
• 用户真正触发播报时，实例已经 ready，首句几乎零延迟。

这样做的代价是进程启动时多占了几 MB 内存，但换来的体验提升非常明显。

5.2 音频焦点：别让播报和音乐打架

离线 TTS 默认走的是媒体的音频流（STREAM_MUSIC)。如果用户正在听音乐，播报会直接盖过去，音乐停了之后还得手动恢复，体验很差。

建议在 speak 前请求音频焦点，播报完再释放。Android 的AudioManager提供了requestAudioFocus和abandonAudioFocus，配合setAudioAttributes使用更专业：

AudioAttributes audioAttributes = new AudioAttributes.Builder() .setUsage(AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY) .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH) .build(); tts.setAudioAttributes(audioAttributes);

这个细节在文档里不难找，但很多人根本不知道 TTS 还能设置 AudioAttributes。对于做无障碍阅读或者导航播报的场景，这一项几乎是必做的。

5.3 长文本分段策略：别让引擎吃撑

系统 TTS 对超长文本的处理并不理想。我实测过一篇几千字的文章一次性丢给 TTS 合成，不仅合成的等待时间很长，而且播报过程中如果用户打断了，恢复的粒度和灵活性都很差。

比较实用的做法是：将长文本按中文标点（句号、问号、感叹号、分号）拆分成短句，逐条调用 speak，用QUEUE_ADD串起来。这样打断和恢复的单位都变小，用户操作更跟手。

public void speakLongText(String text, boolean interrupt) { String[] sentences = text.split("(?<=[。！？；])"); int mode = interrupt ? TextToSpeech.QUEUE_FLUSH : TextToSpeech.QUEUE_ADD; for (String sentence : sentences) { String trimmed = sentence.trim(); if (!trimmed.isEmpty()) { tts.speak(trimmed, mode, null, "utterance_" + System.currentTimeMillis()); mode = TextToSpeech.QUEUE_ADD; // 后续全部排队 } } }

这个策略是我在实际项目中踩过"长文本播报吞字、卡顿"之后总结出来的，虽然是笨办法，但稳定可靠。

5.4 神经网络TTS与传统TTS的取舍

现在的系统引擎如果比较新（比如 Android 11 以上的 Google 引擎），部分语言已经支持基于神经网络的高质量合成，自然度比传统拼接合成好很多。但要注意两点：

• 神经网络语音包体积通常更大，下载耗时更久；
• 部分低端设备上，神经网络 TTS 的首字延迟可能反而更高，因为推理需要更多 CPU 时间。

所以在硬件配置不高的设备上，我倾向于使用传统语音包，或者给用户提供"高质量/低延迟"的选择开关。

5.5 一个容易被忽略的收尾：引擎监听与切换

如果用户在系统设置里切换了 TTS 引擎（比如从 A 引擎换成 B 引擎），你的 App 里已经创建的 TextToSpeech 实例并不会自动跟随切换。需要在onResume里检测默认引擎是否变化，如果有变化就重建实例。

我是在实际设备上碰到过一次"切换引擎后 App 播报没声"的问题，排查半天才知道是这个原因。检测方法很简单：

String currentEngine = tts.getDefaultEngine(); // 在 onResume 里与上次记录的引擎比较，不同则 recreate

这个场景不算高频，但做稳定的产品必须覆盖。

最后分享一点个人体会：系统 TTS 这套方案，看着简单，真正用起来还是有不少细节需要打磨。尤其是离线语音包的引导安装、不同厂商 ROM 的兼容性、初始化异步的时序问题，这三件事几乎每个项目都会遇到。我见过不少人因为前两次碰到坑就放弃系统 TTS，转头去接第三方离线 SDK，结果包体涨了、授权费用来了、限制也更多了。其实只要把状态管理做扎实，系统引擎的离线 TTS 完全能撑起大部分中文播报场景。后续如果你想在这套 demo 基础上继续扩展，可以考虑的方向有两个：一是把 TTS 模块封装成 AIDL 跨进程服务，供多个应用共享；二是把播报内容与业务事件解耦，做成订阅式的播报中心。这两块的思路以后有机会再单独写一篇。

本文还有配套的精品资源，点击获取