PythonAI
Python 文字转语音：使用 pyttsx3 实现文本朗读与避坑指南
介绍如何使用 Python 库 pyttsx3 实现离线文本转语音功能。内容包括环境安装、基础代码示例、音频文件保存方法以及服务器端无扬声器时的解决方案。此外还提供了缓存机制以避免重复合成消耗资源，并列举了不同操作系统下中文语音包的配置问题及排查步骤。
介绍如何使用 Python 库 pyttsx3 实现离线文本转语音功能。内容包括环境安装、基础代码示例、音频文件保存方法以及服务器端无扬声器时的解决方案。此外还提供了缓存机制以避免重复合成消耗资源，并列举了不同操作系统下中文语音包的配置问题及排查步骤。
pyttsx3 是一个跨平台的文字转语音（TTS）库，支持 Windows、macOS、Linux。它直接调用系统自带的语音引擎，不需要网络，也不需要申请 API 密钥，完全离线使用。
特点：
首先确保你的电脑已经安装了 Python（推荐 3.6 及以上版本）。然后用 pip 安装 pyttsx3：
pip install pyttsx3
安装完成后，你就可以开始写代码了。
下面是一个最简示例，朗读一句中英文混合的话。
import pyttsx3
def text_to_speech(text, rate=160, volume=1.0):
# 初始化引擎
engine = pyttsx3.init()
# 设置语速 (默认 200，建议 120-180)
engine.setProperty('rate', rate)
# 设置音量 (0.0~1.0)
engine.setProperty('volume', volume)
# 设置中文语音（需要系统已安装中文语音包）
voices = engine.getProperty('voices')
for voice in voices:
if "chinese" in voice.name.lower():
# 根据系统语音名称匹配
engine.setProperty('voice', voice.id)
break
# 播报文本
engine.say(text)
engine.runAndWait()
# 使用示例
text_to_speech("hello world，欢迎使用 pyttsx3！")
运行这段代码，如果你的电脑有扬声器，就能听到语音了。
pyttsx3.init()：初始化语音引擎。setProperty('rate', ...)：设置语速，数值越大越快，一般 120~180 比较自然。setProperty('volume', ...)：音量，范围 0.0~1.0。getProperty('voices')：获取系统所有可用的语音。我们遍历找到包含'chinese'的语音，设为中文发音。如果找不到，就会用默认语音（通常是英文），读中文会很不自然。engine.say(text)：把文本加入朗读队列。engine.runAndWait()：开始朗读，并等待朗读结束。有时候我们不需要立即播放，而是想把语音存成文件，比如用在视频配音、自动生成音频内容。pyttsx3 可以轻松做到：
import pyttsx3
def text_to_speech_file(text, filename='output.wav', rate=160, volume=1.0):
engine = pyttsx3.init()
engine.setProperty('rate', rate)
engine.setProperty('volume', volume)
# 设置中文语音
voices = engine.getProperty('voices')
for voice in voices:
if "chinese" in voice.name.lower():
engine.setProperty('voice', voice.id)
break
# 保存到文件
engine.save_to_file(text, filename)
engine.runAndWait()
print(f"音频已保存到 {filename}")
# 使用示例
text_to_speech_file("这是一段保存成文件的语音。", "test.wav")
保存后，你就可以用任何播放器播放这个 .wav 文件。
不一定。如果只是保存文件，不需要扬声器。但如果直接调用 engine.say()，程序会试图通过系统的音频设备播放，这时必须确保有可用的音频输出设备（比如耳机、音箱）。如果服务器没有声卡（很多云服务器都没有），播放会失败或无声。
解决方案：在服务器环境，始终使用 save_to_file 保存文件，然后把文件传给前端播放，或者用其他工具播放。
engine.say() 也可能没声音。建议使用 save_to_file 生成文件，然后用浏览器或其它设备播放。espeak 或其他 TTS 后端，并且确保有音频输出（比如 ALSA 配置）。如果只是生成文件，可以不用音频设备，直接用 save_to_file。如果你经常需要朗读相同的文字（比如固定的提示语），每次都重新合成会消耗 CPU 和时间。可以做一个简单的缓存：第一次合成后把音频文件保存下来，下次遇到相同文字直接返回文件。
示例缓存实现：
import os
import hashlib
def text_to_speech_cached(text, cache_dir='tts_cache'):
# 创建缓存目录
os.makedirs(cache_dir, exist_ok=True)
# 根据文本生成文件名（哈希）
hash_value = hashlib.md5(text.encode('utf-8')).hexdigest()
filename = os.path.join(cache_dir, f'{hash_value}.wav')
if os.path.exists(filename):
print("使用缓存的音频文件")
return filename
else:
print("合成新的音频文件")
text_to_speech_file(text, filename)
return filename
# 使用示例
file1 = text_to_speech_cached("你好，欢迎光临")
file2 = text_to_speech_cached("你好，欢迎光临")
# 第二次直接返回缓存文件
这样既节省时间，又避免重复合成。
espeak 提供，但 espeak 的中文发音比较机械。可以安装 espeak-ng 并配置中文，或者使用其他 TTS 引擎（如 Festival、Mimic）。如果你运行代码时没有听到中文，可以打印所有可用语音，看看是否有中文：
engine = pyttsx3.init()
voices = engine.getProperty('voices')
for v in voices:
print(v.name, v.id)
根据打印结果，手动选择一个中文语音的 id 设置。
pyttsx3 是一个简单又强大的离线 TTS 库，非常适合 Python 开发者快速实现语音功能。通过本文，你应该已经掌握了：
如果在服务器上运行，记得用保存文件的方式；如果希望中文更自然，可以安装更高质量的语音包（比如 Windows 上的自然语音）。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online