Piper：本地离线神经 TTS 引擎（piper-tts）安装与使用指南

Piper 是由 Open Home Foundation 维护的快速、本地、神经文本转语音（TTS）引擎，它把 espeak-ng 内嵌进来做音素转换，让一段文本在没有网络、没有 GPU 的普通机器上也能立刻合成出接近真人的语音。与云端 TTS 相比，Piper 完全离线、可嵌入 Home Assistant、NVDA 读屏器、LocalAI、Open Voice OS 等项目，是目前开源本地 TTS 里部署最广的方案之一。其语音模型基于 VITS 训练并导出为 onnxruntime 格式，一次加载即可反复合成，避免了每次命令行调用都要重新加载模型的开销。

Piper 的设计取舍很明确：它不追求云端大模型那种"情感丰富、多人声"的效果，而是把"小模型、快、离线、可嵌入"做到极致。espeak-ng 负责把文本转成音素（含标点终止符），VITS 模型负责把音素转成语波，onnxruntime 负责 CPU/GPU 推理。这个三段式让 Piper 可以塞进树莓派、Home Assistant 插件、NVDA 读屏器等资源受限场景，也可以通过 HTTP 服务给业务系统当本地 TTS 网关。官方维护的语音覆盖 40 余种语言，包括简体中文，每个语音都有 .onnx 模型与 .onnx.json 配置两个文件，从 Hugging Face 语音仓库 下载后即用。

Piper 的名字取自风笛，logo 也是风笛造型；它最早由 Rhasspy 项目团队开源，后来移交给 Open Home Foundation 维护。与同类项目相比，Piper 的特点是"薄"：模型只做音素到波形的转换，文本归一化、音素化交给 espeak-ng，调度与服务交给用户自己，这种分层让它既灵活又容易嵌入，也是它能在智能家居、读屏器、离线旁白等场景被广泛采用的根本原因。

一、项目官方信息

二、官方图片

Piper 仓库封面（本站封面）：

三、适用场景

Piper 适合三类场景：一是智能家居与本地自动化，比如 Home Assistant 插件在断网时播报天气、门铃通知；二是辅助技术，比如 NVDA 读屏器给视障用户朗读屏幕文本，要求低延迟、无云依赖；三是离线内容生产，比如给视频、游戏、有声书批量配旁白，用 HTTP 服务常驻模型后批量跑文本。它不适合需要丰富情感演绎、多人对话、克隆特定音色的场景——那些是 OpenVoice、Bark 等模型的方向，Piper 的定位是"稳定、快、离线、多语言"的基础 TTS。与云端 TTS 相比，Piper 没有按字符计费、没有网络延迟、数据不出本机，对隐私敏感的场景尤其合适；与更大的开源 TTS 模型相比，它模型小（中等质量语音几十 MB）、CPU 即可实时合成、启动快，适合嵌进资源受限的设备。

四、环境要求与安装

最简安装只需要一行：

pip install piper-tts

HTTP 服务端需要额外装依赖：

python3 -m pip install piper-tts[http]

• Python：常规 3.x 环境；Piper 用 Python 稳定 ABI（stable ABI）构建，每个平台（Linux、macOS、Windows）只需构建一次 wheel，不必按 Python 版本分别编译。
• GPU 加速：命令行 --cuda 或 Python use_cuda=True 都需要先安装 onnxruntime-gpu；CPU 推理对普通文本已足够快，GPU 主要给高并发 HTTP 网关或长文本合成提速。
• 手动构建：需要系统包 build-essential、cmake、ninja-build，用 scikit-build-core 构建内嵌 espeak-ng 的 Python 扩展。
• 二进制发行版：官方提供 amd64（64 位桌面 Linux）、arm64（树莓派 4）、armv7（32 位树莓派 3/4）三种预编译包，适合不想装 Python 环境的设备。
• 音素化：espeak-ng 已内嵌在 wheel 里，无需单独安装；但想用 espeak-ng --ipa=3 查音素或注入自定义音素时，系统里另装一份 espeak-ng 更方便。

五、部署步骤

1. 下载语音模型

Piper 每个语音由两个文件组成：.onnx 模型文件与 .onnx.json 配置文件。官方提供下载工具：

python3 -m piper.download_voices

选择一个语音（先在 试听页 听样例），例如下载英文 lessac 中等质量语音：

python3 -m piper.download_voices en_US-lessac-medium

默认下载到当前目录，可用 --data-dir <DIR> 指定。语音模型托管在 Hugging Face 的 rhasspy/piper-voices 仓库，覆盖阿拉伯语、加泰罗尼亚语、捷克语、威尔士语、丹麦语、德语、希腊语、英语（英/美）、西班牙语（阿根廷/西班牙/墨西哥）、波斯语、芬兰语、法语、匈牙利语、冰岛语、印尼语、意大利语、格鲁吉亚语、哈萨克语、卢森堡语、拉脱维亚语、马拉雅拉姆语、印地语、尼泊尔语、荷兰语（比利时/荷兰）、挪威语、波兰语、葡萄牙语（巴西/葡萄牙）、罗马尼亚语、俄语、斯洛伐克语、斯洛文尼亚语、塞尔维亚语、瑞典语、斯瓦希里语、泰卢固语、土耳其语、乌克兰语、越南语、简体中文等 40 余种语言。每个语音还有质量档位（如 medium）与说话人数量之分，多说话人语音可在合成时用 speaker 或 speaker_id 切换。

2. 命令行合成

下载好 en_US-lessac-medium 后：

python3 -m piper -m en_US-lessac-medium -f test.wav -- 'This is a test.'

这会把句子写到 test.wav。如果装了 ffplay，省略 -f 即可直接在扬声器播放：

python3 -m piper -m en_US-lessac-medium -- 'This will play on your speakers.'

常用命令行参数：

• --cuda：启用 GPU 加速（需 onnxruntime-gpu）；
• --input-file：从一个或多个文件读入文本；
• --sentence-silence：在除最后一句外的每句之间插入指定秒数静音；
• --volume：音量倍数（默认 1.0）；
• --no-normalize：关闭自动音量归一化；
• --data-dir <DIR>：指定语音模型目录。

命令行方式每次都要重新加载模型，适合偶尔试用；反复合成建议用 HTTP 服务。如果想用原始 PCM 流而不是写 wav 文件，可用 --output-raw 参数配合管道直接喂给音频播放器或上游服务。

3. HTTP 服务端

python3 -m piper.download_voices en_US-lessac-medium
python3 -m piper.http_server -m en_US-lessac-medium

服务默认监听 5000 端口（用 --host、--port 改），浏览器打开 http://localhost:5000 即可看到网页界面：输入文本点 Speak 试听，页面还会显示语音信息（名称、语言、说话人数）以及最近一次合成的耗时、音素与音频对齐；在 Settings 里可调 length（语速）、noise（说话变异度）、noise_w（音素宽度变异）三个参数，多说话人语音还能选说话人，"Reset to voice defaults" 恢复语音默认值。

接口调用：

# 查看语音信息（JSON）
curl localhost:5000/info

# 合成 WAV
curl -X POST -H 'Content-Type: application/json' \
  -d '{ "text": "This is a test." }' -o test.wav localhost:5000/synthesize

# 列出可用语音
curl localhost:5000/voices

/synthesize 的 JSON 字段：text（必填）、voice（可选，默认 -m 指定的语音）、speaker 与 speaker_id（多说话人语音选择说话人）、length_scale（语速，默认 1）、noise_scale（说话变异度）、noise_w_scale（音素宽度变异）；留空的字段依次回退到命令行参数、再到语音配置。/info 除了语音名、语言、说话人数，还会列出每个说话人的 id 与 name，以及合成请求未指定参数时使用的 defaults，方便业务侧对齐默认值。

4. Python API

import wave
from piper import PiperVoice

voice = PiperVoice.load("/path/to/en_US-lessac-medium.onnx")
with wave.open("test.wav", "wb") as wav_file:
    voice.synthesize_wav("Welcome to the world of speech synthesis!", wav_file)

调节合成参数：

from piper import SynthesisConfig
syn_config = SynthesisConfig(
    volume=0.5,          # 半音量
    length_scale=2.0,    # 两倍慢
    noise_scale=1.0,     # 更多音频变异
    noise_w_scale=1.0,   # 更多说话变异
    normalize_audio=False,  # 使用语音原始音频
)
voice.synthesize_wav(..., syn_config=syn_config)

GPU 加速：voice = PiperVoice.load(..., use_cuda=True)，需装 onnxruntime-gpu。流式合成用 voice.synthesize(...) 逐 chunk 产出，每个 chunk 带 sample_rate、sample_width、sample_channels 与 audio_int16_bytes，可边合成边播放。

Python API 的设计是"加载一次、反复合成"：PiperVoice.load 只在进程启动时调用一次，之后 synthesize_wav 或 synthesize 可对任意文本复用同一份模型与 espeak-ng 上下文，延迟远低于命令行反复拉起。SynthesisConfig 的四个参数里，volume 是音量倍数、length_scale 是语速（值越大越慢）、noise_scale 控制说话变异度、noise_w_scale 控制音素宽度变异，三者都是模型训练时学到的随机参数，调整会让音色更稳定或更有变化。

5. 手动从源码构建

git clone https://github.com/OHF-voice/piper1-gpl.git
cd piper1-gpl
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .[dev]
python3 setup.py build_ext --inplace
python3 -m piper --help

打包 wheel 用 python3 -m build。设计上 espeak-ng 通过 espeakbridge.c 的 Python limited API 桥接，使用稳定 ABI，所以每个平台只需构建一次；内置的 espeak-ng 提供 espeak_TextToPhonemesWithTerminator 函数，把标点（逗号、句号、问号、感叹号）作为"终止音素"传给语音模型，让模型学会不同句末标点用不同语气读句子。这一点对自然度影响很大——没有终止音素时，所有句子都会平铺直叙，逗号、问号也不会产生停顿与语调变化。

六、使用方法要点

• 原始音素注入：可以在文本里用 [[ <phonemes> ]] 块直接插入 espeak-ng 音素，例如 I am the [[ bˈætmæn ]] not [[bɹˈuːs wˈe‍ɪn]]；用 espeak-ng -v <VOICE> --ipa=3 -q <TEXT> 查询文本对应的音素。
• 语音文件成对：每个语音必须同时有 .onnx 与 .onnx.json，缺一会报错；从 Hugging Face 下载时两个文件要放在同一目录。
• 模型许可：Piper 面向个人使用与 TTS 研究，不附加额外限制，但各语音模型的 MODEL_CARD 可能有各自许可，商用前务必逐个核对。
• 维护状态：Open Home Foundation 正在为 Piper 招募维护者，有意者联系 voice@openhomefoundation.org。
• 生态集成：Piper 已被 Home Assistant 用作官方 TTS 插件、被 NVDA 读屏器采用、被 Open Voice OS 与 LocalAI 集成本地语音合成，社区还有 Java JNI 绑定、Vim 插件、mintPiper 等周边项目，适合在智能家居、辅助阅读、游戏旁白等场景落地。

七、训练新语音

Piper 自带训练代码（src/piper/train），基于 PyTorch Lightning 与 LightningCLI，可运行 python3 -m piper.train fit。训练环境需先装系统包 build-essential、cmake、ninja-build，再 pip install -e '.[train]' 并执行 ./build_monotonic_align.sh 构建 cython 扩展。

训练数据是一个以 | 分隔的 CSV：第一列是音频文件名（librosa 支持的任意格式，放在 --data.audio_dir 指定目录），第二列是文本，默认会交给 espeak-ng 做音素化。多说话人数据集时第二列换成说话人名字，Piper 启动时自动统计唯一说话人并映射成 id，写进 config.json。关键训练参数：data.voice_name（语音名）、data.csv_path、data.audio_dir、model.sample_rate（通常 22050）、data.espeak_voice（如 en-us）、data.cache_dir（缓存音素与裁剪后音频）、data.config_path（输出 JSON 配置）、data.batch_size，以及强烈建议传入的 ckpt_path（已有 Piper checkpoint，能大幅加速，即使来自不同语言也可，且只支持 medium 质量）。

训练完成后导出 ONNX：python3 -m piper.train.export_onnx --checkpoint /path/to/checkpoint.ckpt --output-file /path/to/model.onnx，再按 <language>-<name>-medium.onnx 命名，与训练时写出的 .onnx.json 配对即可作为 Piper 语音使用。硬件方面，多数官方语音在 Threadripper 1900X + 128GB 内存 + A6000（48GB）或 3090（24GB）上训练/微调，但用户反馈 8GB 显存甚至 RX 7600 也能跑起来。学习率默认每轮按 --trainer.max_epochs 退火，终值为初始的 --model.lr_final_ratio（默认 0.05）；从零训练还可用 --model.vocoder_warmstart_ckpt 热启动声码器，允许音素数量不同。除默认 espeak-ng 音素化外，还支持 --data.phoneme_type text（直接喂 UTF-8 音素）与 --data.data_type phoneme_ids（完全自定义音素 id）两种高级模式，并提供 script/libritts_r_to_csv 一键把 LibriTTS-R 数据集转成多说话人训练 CSV。训练完成的语音导出后，把 .onnx 与 .onnx.json 同名放在一起，即可像官方语音一样被命令行、Python API 与 HTTP 服务加载使用。

八、常见问题 FAQ

Q：为什么命令行每次合成都很慢？ A：命令行每次调用都要重新加载语音模型；高频使用请启动 HTTP 服务（模型只加载一次），或用 Python API 长驻进程。

Q：中文语音怎么选？ A：在 rhasspy/piper-voices 仓库找 zh_CN 目录，用 python3 -m piper.download_voices zh_CN-xxx 下载，再按相同方式 -m zh_CN-xxx 使用。

Q：能跑在树莓派上吗？ A：可以，官方提供 arm64（树莓派 4）与 armv7（32 位树莓派 3/4）预编译包，也可以用 pip install piper-tts 后在系统 Python 里直接跑。

Q：GPU 加速怎么开？ A：先 pip install onnxruntime-gpu，命令行加 --cuda 或 Python 里 PiperVoice.load(..., use_cuda=True)。

Q：语速、语调怎么调？ A：HTTP 服务的 Settings 或 /synthesize 的 length_scale（语速，越小越快）、noise_scale（变异度）、noise_w_scale（音素宽度）三个参数；Python 用 SynthesisConfig 同样可调。

Q：标点会影响合成吗？ A：会。Piper 把标点作为终止音素传给模型，问号、感叹号、句号会读出不同语气；逗号、分号用于自然停顿。

Q：如何注入自己的音素？ A：在文本里用 [[ <phonemes> ]] 块插入 espeak-ng 音素；用 espeak-ng -v <VOICE> --ipa=3 -q <TEXT> 查询文本对应音素。这对专有名词、缩写的定制发音很有用。

Q：Piper 与 Piper 1 的关系？ A：当前仓库 OHF-Voice/piper1-gpl 是 Open Home Foundation 维护的 Piper 1 分支，GPL 许可；历史上 rhasspy/piper 是原仓库。命令行、Python API、HTTP 接口用法一致，语音模型也通用。

Q：流式合成怎么用？ A：Python 里用 voice.synthesize("...") 逐 chunk 迭代，每个 chunk 带采样率、位宽、声道与 int16 音频字节，可边合成边写入音频播放器，实现"边读边出音"的低延迟体验。

Q：多说话人语音怎么选声音？ A：HTTP 合成时传 speaker（名字）或 speaker_id（数字 id），Python 里在 SynthesisConfig 或 synthesize 调用时指定；/info 接口会列出当前语音所有说话人的 id 与名字。

Q：导出的 ONNX 能在其他框架用吗？ A：理论上可以，只要遵循 onnxruntime 格式；但 Piper 官方的语音配置（.onnx.json）包含 espeak-ng 音素表与归一化参数，脱离 Piper 运行时需要自行复刻这部分逻辑。

九、跳转链接

• GitHub 仓库：OHF-Voice/piper1-gpl
• 语音模型：rhasspy/piper-voices
• 语音试听：piper-samples
• HTTP API 文档：API_HTTP.md
• Python API 文档：API_PYTHON.md
• 命令行文档：CLI.md
• 训练新语音：TRAINING.md
• 手动构建：BUILDING.md
• espeak-ng：espeak-ng/espeak-ng