简介这是一份面向 Android 开发者的离线文字转语音TTS演示工程核心价值在于不依赖手机系统自带 TTS 引擎即使设备未安装任何语音包也能正常发声适合需要为应用集成离线播报能力的初中级开发者参考。压缩包共 25 个文件约 511KB以 14 个 xml 布局与配置、3 个 java 源码、2 个 prefs 偏好设置为主另含 so 动态库、ttsres 语音资源及工程配置文件结构完整可直接导入运行。工程实现了文字转语音的基本流程并支持切换发音人、调节语速等常用参数便于按需改造。目前已有 3094 人学习下载。作者也指出一个待解问题英文单词会被逐字母读出为后续优化留下了明确的排错方向适合作为二次开发与问题排查的起点。1. 离线 TTS 在 Android 上到底能跑多稳一个 demo 包拆开看去年帮一个做工业巡检的团队看设备端语音播报现场没有公网、Wi-Fi 也时断时续他们一开始用在线合成接口结果每次进隧道就哑了。后来换成 Android 系统自带的离线 TTS 引擎问题才算压住。这次拆的android_tts_离线语音demo包文字转语音就是同一类场景的最小可运行工程把文字转语音Text To Speech跑在本地不依赖网络请求适合设备端播报、无障碍朗读、离线导航提示这类需求。它面向的是想快速验证 Android TTS 能不能满足自己业务的人——新手能直接跑起来听效果熟手能顺着代码看到引擎初始化、语言包检测、参数调节这几个关键环节。离线语音包是这套方案的核心装没装、装的是哪个引擎直接决定 demo 能不能出声。2. 离线 TTS 的引擎选型与初始化为什么你的 demo 不出声Android 的 TTS 并不是系统里唯一一个实现它是一套框架底下可以挂不同引擎。很多人第一次跑 TTS demo 发现没声音八成不是代码写错而是设备上压根没有可用的离线引擎或者默认引擎指向了一个需要联网的方案。这一章把选型逻辑和初始化流程讲透后面再动手就不容易翻车。2.1 系统 TTS 框架与第三方引擎的差别Android 从早期版本就提供了android.speech.tts.TextToSpeech这个类它是一层抽象接口真正干活的是安装在设备上的 TTS 引擎应用。常见的离线引擎有厂商预装的比如部分设备自带的语音合成服务也有可以单独安装的第三方引擎。系统框架负责把speak()调用转发给当前选中的引擎引擎再调用本地的声学模型和语言资源完成合成。这里有个容易混淆的点TextToSpeech构造时传入的Context和回调只是告诉框架“我要用 TTS”并不指定用哪个引擎。引擎的选择由系统设置里的默认 TTS 选项决定代码里也可以通过构造函数指定包名来强制使用某个引擎。如果你的 demo 在 A 设备上正常、B 设备上没声先别怀疑代码去对比两台设备的默认引擎和已安装语音包。选型上如果项目要求完全离线且不依赖用户手动装引擎通常的做法是随应用打包一个轻量引擎或者引导用户安装指定引擎后锁定包名。纯依赖系统默认引擎的方案最省事但可控性差适合对播报稳定性要求不极端的场景。2.2 初始化回调与语言可用性检测TTS 初始化是异步的onInit()回调返回SUCCESS之前调用speak()基本都会被丢弃。这是新手最容易踩的坑之一代码顺序看起来没问题但初始化还没完成就触发了播报。正确做法是在onInit里根据状态设置一个标志位或者直接在里面做首次播报。语言可用性检测同样关键。isLanguageAvailable()返回的结果有几种LANG_AVAILABLE、LANG_COUNTRY_AVAILABLE、LANG_COUNTRY_VAR_AVAILABLE、LANG_MISSING_DATA、LANG_NOT_SUPPORTED。只有前三种才代表可以合成LANG_MISSING_DATA说明引擎在但语音数据没装LANG_NOT_SUPPORTED说明引擎根本不支持这门语言。很多“离线包装了还是没声”的情况就是卡在LANG_MISSING_DATA上。下面这段是初始化与检测的典型写法可以直接抄进 demo// 初始化 TTS回调里判断状态并检测中文可用性 private TextToSpeech tts; private boolean ttsReady false; tts new TextToSpeech(getApplicationContext(), new TextToSpeech.OnInitListener() { Override public void onInit(int status) { if (status TextToSpeech.SUCCESS) { // 设置语言为中文 int result tts.setLanguage(Locale.CHINA); if (result TextToSpeech.LANG_MISSING_DATA || result TextToSpeech.LANG_NOT_SUPPORTED) { // 语音数据缺失或语言不支持需要提示用户安装语音包 Log.e(TTS, 中文语音包缺失result result); return; } ttsReady true; // 初始化完成后设置参数 tts.setSpeechRate(1.0f); // 语速1.0 为正常 tts.setPitch(1.0f); // 音调1.0 为正常 } else { Log.e(TTS, TTS 初始化失败status status); } } });逻辑上onInit是唯一可靠的初始化完成信号status SUCCESS只代表引擎连上了不代表语言数据就绪所以还要看setLanguage的返回值。参数说明setSpeechRate取值一般 0.5 到 2.0低于 0.5 会拖沓到听不清高于 2.0 多数引擎会失真setPitch同理0.5 到 1.5 是比较安全的区间。这两个参数在speak()之前设置才生效运行中改也可以但部分引擎对动态修改响应不一致建议初始化时定好。2.3 把文字送进引擎speak 的参数与队列策略speak()的签名里有两个参数值得说queueMode和Bundle。queueMode决定新任务怎么和正在播的任务相处QUEUE_ADD是排队QUEUE_FLUSH是打断当前播报直接播新的。设备端播报场景里如果是连续多条提示用QUEUE_ADD更自然如果是紧急告警要立刻覆盖就得用QUEUE_FLUSH。Bundle里可以塞KEY_PARAM_UTTERANCE_ID配合UtteranceProgressListener就能知道某条播报什么时候开始、结束、出错。没有这个 ID你只能靠猜。下面是一个带队列和进度监听的调用// 播报一条文本带 utteranceId 便于监听进度 String text 设备温度异常请检查; String utteranceId warn_ System.currentTimeMillis(); if (ttsReady) { // QUEUE_FLUSH 表示打断当前播报立即播这条 tts.speak(text, TextToSpeech.QUEUE_FLUSH, null, utteranceId); } // 监听播报状态 tts.setOnUtteranceProgressListener(new UtteranceProgressListener() { Override public void onStart(String utteranceId) { Log.d(TTS, 开始播报: utteranceId); } Override public void onDone(String utteranceId) { Log.d(TTS, 播报完成: utteranceId); } Override public void onError(String utteranceId) { Log.e(TTS, 播报出错: utteranceId); } });参数说明QUEUE_FLUSH适合告警类QUEUE_ADD适合列表播报。utteranceId建议带业务前缀和时间戳方便在日志里定位是哪条出的问题。onError回调里可以进一步查TextToSpeech.getEngines()看引擎状态但多数情况下错误来自语音数据缺失或引擎被系统回收。3. 离线语音包的安装与语言数据检测没声先查这里demo 能跑起来但不出声九成问题出在语音包上。这一章把语音包的安装路径、检测方法和常见缺失场景讲清楚照着排查基本能定位。3.1 语音包到底装在哪、怎么装Android 的 TTS 语音数据由各引擎自己管理没有统一路径。系统预装引擎的数据通常在/system/tts或引擎应用的数据目录下第三方引擎则在自己的私有目录里。用户侧安装语音包一般有两种方式一是通过系统设置里的“文字转语音输出”进入引擎配置下载对应语言的数据二是引擎应用自己提供下载入口。对于 demo 验证最省事的做法是先在系统设置里确认默认引擎再进引擎设置看中文语音包是否已安装。如果设备上没有预装任何离线引擎就需要先装一个支持离线的引擎应用再下载中文数据。注意部分引擎的“中文”数据包分普通话、粤语等选错也会导致LANG_MISSING_DATA。代码层面可以列出设备上所有 TTS 引擎方便判断当前环境// 列出设备上所有 TTS 引擎排查默认引擎是否可用 ListTextToSpeech.EngineInfo engines tts.getEngines(); for (TextToSpeech.EngineInfo info : engines) { Log.d(TTS, 引擎包名: info.name , 标签: info.label); } // 获取当前默认引擎 String defaultEngine tts.getDefaultEngine(); Log.d(TTS, 默认引擎: defaultEngine);逻辑说明getEngines()返回已安装的引擎列表getDefaultEngine()返回系统当前选中的那个。如果列表为空说明设备没有任何 TTS 引擎demo 必然不出声。参数上没什么可调的重点看日志输出里有没有你预期的引擎包名。3.2 用 isLanguageAvailable 做启动自检与其等用户点了播报才发现没声不如在应用启动或进入播报页时做一次自检。自检逻辑就是前面提到的isLanguageAvailable根据返回值给出不同提示。下面是一个自检方法// 启动自检检查中文语音数据是否就绪 private boolean checkChineseTtsReady(TextToSpeech tts) { if (tts null) return false; int result tts.isLanguageAvailable(Locale.CHINA); switch (result) { case TextToSpeech.LANG_AVAILABLE: case TextToSpeech.LANG_COUNTRY_AVAILABLE: case TextToSpeech.LANG_COUNTRY_VAR_AVAILABLE: return true; case TextToSpeech.LANG_MISSING_DATA: Log.w(TTS, 中文语音数据缺失需安装语音包); return false; case TextToSpeech.LANG_NOT_SUPPORTED: Log.w(TTS, 当前引擎不支持中文); return false; default: return false; } }参数说明Locale.CHINA对应简体中文如果业务需要繁体或粤语要换成对应 Locale。返回值里LANG_AVAILABLE表示语言可用但可能没有特定地区变体LANG_COUNTRY_AVAILABLE表示语言加国家可用LANG_COUNTRY_VAR_AVAILABLE最具体。三者都可以正常合成区别只在发音细节。3.3 引擎被系统回收后的重新初始化Android 在内存紧张时会回收后台应用的资源TTS 引擎也可能被断开。表现是应用切回前台后播报没反应但代码没报错。这种情况需要监听引擎变化或在onResume里重新检查ttsReady标志。如果发现引擎不可用重新走一遍初始化流程。常见做法是在onResume里调用一次isLanguageAvailable返回不可用就重新new TextToSpeech。注意旧的tts对象要先shutdown()释放否则可能泄漏。这个坑在长时间运行的设备端应用里很常见demo 阶段不容易遇到但上线前必须处理。4. 避坑与排查离线 TTS 最常见的五类翻车这一章按“现象 → 原因 → 解决”整理五条实际踩过的坑都是 demo 到落地过程中高频出现的。现象一初始化回调一直不返回 SUCCESS。原因通常是设备上没有可用引擎或者引擎应用被禁用。解决用getEngines()确认引擎列表空的话先装引擎非空则检查默认引擎是否被系统禁用去设置里启用。现象二onInit返回 SUCCESS但speak()没声音。原因多是语音数据缺失setLanguage返回了LANG_MISSING_DATA但代码没处理。解决在onInit里判断setLanguage返回值缺失时提示用户安装语音包而不是直接调speak()。现象三播报断断续续或只播第一个字。原因可能是QUEUE_FLUSH被频繁调用前一条还没播完就被打断。解决连续播报场景改用QUEUE_ADD并给每条设置唯一utteranceId便于追踪。现象四切到后台再回来就不出声了。原因是引擎被系统回收tts对象已失效。解决在onResume里重新检测语言可用性不可用则shutdown()后重新初始化。现象五不同设备发音差异大、语速怪。原因是各引擎的声学模型不同setSpeechRate和setPitch的实际效果不一致。解决不要硬编码一套参数按引擎包名做差异化配置或者把语速控制在 0.8 到 1.2 这个多数引擎都正常的区间。提示排查时优先看 Logcat 里 TTS 相关日志引擎自己也会打错误码比只看应用层日志有效。5. 进阶技巧把播报队列和资源释放做扎实demo 跑通只是第一步真正放到设备端长期运行还得处理队列管理和资源释放。这一章给两个具体技巧都是实际项目里验证过的。5.1 用 utteranceId 做播报队列的可观测性前面提过utteranceId它的价值不只是监听单条。把每条播报的 ID 按业务类型加前缀比如warn_、info_、nav_然后在onStart和onDone里打日志就能在日志里还原出完整的播报时序。设备端出问题时这份时序比任何猜测都管用。更进一步可以维护一个待播队列在onDone里触发下一条而不是一次性全丢给speak()。这样能精确控制播报间隔也方便在紧急告警时清空队列。下面是一个简化的队列管理思路// 简化的播报队列onDone 后播下一条 private QueueString speechQueue new LinkedList(); private boolean isSpeaking false; private void enqueueSpeech(String text) { speechQueue.offer(text); if (!isSpeaking) { speakNext(); } } private void speakNext() { String text speechQueue.poll(); if (text null) { isSpeaking false; return; } isSpeaking true; String id queue_ System.currentTimeMillis(); tts.speak(text, TextToSpeech.QUEUE_FLUSH, null, id); } // 在 onDone 里调用 speakNext()逻辑说明用QUEUE_FLUSH配合自己的队列比直接用QUEUE_ADD更可控因为你能决定什么时候播下一条。参数上队列长度建议设上限避免内存里堆积过多待播文本。5.2 释放时机与内存泄漏防范TextToSpeech持有 Context 引用如果在 Activity 里初始化且不释放退出时就会泄漏。标准做法是在onDestroy里调用shutdown()Override protected void onDestroy() { if (tts ! null) { tts.stop(); // 停止当前播报 tts.shutdown(); // 释放引擎资源 tts null; } super.onDestroy(); }参数说明stop()是停止当前播报shutdown()是释放引擎连接两者顺序不能反。如果应用有多个页面共用 TTS建议把 TTS 实例放到 Application 级别或单例里避免反复初始化带来的延迟。我自己的习惯是任何用到 TTS 的页面在onPause里先stop()在onDestroy里再shutdown()这样切页面不会出现声音还在后台飘的情况。从那以后我每次接入离线 TTS 都强制走一遍“引擎检测 → 语言自检 → 队列管理 → 释放”这四步少一步后面都可能返工。希望帮到你。本文还有配套的精品资源点击获取