幽冥大陆(七十六) piper.exe 文字朗读TTS——东方仙盟练气期

境准备、核心使用方法、命令行示例、文件调用细节等方面逐步说明，确保你能顺利操作：

一、前期准备（关键前提）

获取 Piper 工具包 ：先下载 Piper 官方工具（包含 piper.exe），推荐从官方仓库下载：
- 官方仓库：https://github.com/rhasspy/piper
- 直接下载 Windows 版本（含 piper.exe）：在仓库的「Releases」页面，下载对应 Windows 系统的压缩包（如 piper_windows_amd64.zip），解压后得到 piper.exe 可执行文件。
获取 zh_CN-huayan-medium 音库 ：
- 音库下载地址：可从 Piper 官方音库仓库下载 zh_CN-huayan-medium 相关文件（核心是 .onnx 模型文件 + .json 配置文件）。
- 音库文件组成：下载后会得到两个核心文件（需放在同一目录）：
  - zh_CN-huayan-medium.onnx（模型文件，语音合成核心）
  - zh_CN-huayan-medium.onnx.json（配置文件，定义音库参数）

文件目录整理（推荐） ：为了方便调用，建议将文件统一放在同一文件夹，目录结构如下：

plaintext

复制代码

piper_voice/
├─ piper.exe          （Piper 可执行文件）
├─ zh_CN-huayan-medium.onnx  （华彦音库模型）
└─ zh_CN-huayan-medium.onnx.json  （华彦音库配置）

二、核心使用方式（两种常用场景）

piper.exe 配合 zh_CN-huayan-medium 的核心是通过命令行指定音库路径，支持「直接输出语音」和「读取文本文件合成语音」两种场景。

场景 1：直接输入文本，合成语音文件（最常用）

操作步骤：

打开 Windows 命令提示符（CMD）：按下 Win+R，输入 cmd 回车。
通过 cd 命令切换到你整理好的 piper_voice 目录（示例路径，需替换为你的实际路径）：

bash

运行
复制代码
```
cd D:\tools\piper_voice
```

执行核心合成命令，格式如下： bash

运行

复制代码

piper.exe --model zh_CN-huayan-medium.onnx --input-text "你要合成的中文文本" --output_file 输出语音文件名.wav

完整示例：

合成文本「大家好，这是 Piper 配合华彦音库的语音合成测试」，输出为 test.wav：

bash

运行

复制代码

piper.exe --model zh_CN-huayan-medium.onnx --input-text "大家好，这是 Piper 配合华彦音库的语音合成测试" --output_file test.wav

执行成功后，在 piper_voice 目录下会生成 test.wav 语音文件，可直接用播放器打开播放。

场景 2：读取文本文件，批量合成语音

如果需要合成大量文本，可先将文本写入 .txt 文件，再通过 piper.exe 读取该文件合成语音。

操作步骤：

在 piper_voice 目录下，新建一个文本文件 input.txt，写入需要合成的中文内容（每行一段文本，支持批量）：

plaintext

复制代码

第一句：Piper 是一款轻量级离线语音合成工具
第二句：zh_CN-huayan-medium 是优质的中文音库
第三句：支持离线使用，无需网络连接

在 CMD 中执行以下命令（读取 input.txt，输出 batch_output.wav）：

bash

运行

复制代码

# 方式1：直接读取文本文件
piper.exe --model zh_CN-huayan-medium.onnx --input input.txt --output_file batch_output.wav

# 方式2：通过管道符（Windows CMD 支持）
type input.txt | piper.exe --model zh_CN-huayan-medium.onnx --output_file batch_output.wav

三、关键参数说明

参数	作用说明	必选 / 可选
`--model`	指定音库模型文件（.onnx 路径）	必选
`--input-text`	直接传入待合成的文本内容（字符串）	可选（二选一）
`--input`	指定待合成的文本文件路径（.txt 等）	可选（二选一）
`--output_file`	指定输出的语音文件路径（支持 .wav 格式）	必选
`--rate`	调整语音语速（默认 22050 Hz，可自定义）	可选
`--volume`	调整语音音量（0~1 之间，默认 1）	可选

四、常见问题排查

报错：找不到模型文件
- 原因：--model 参数指定的路径错误，或 .onnx 与 .onnx.json 文件不在同一目录。
- 解决：确认模型文件路径正确（绝对路径 / 相对路径均可），且两个音库文件放在一起。
合成后无声音 / 声音异常
- 原因：文本编码问题（推荐 UTF-8 编码），或语速 / 音量设置异常。
- 解决：将 .txt 文件保存为 UTF-8 编码，调整 --rate 或 --volume 参数。
CMD 中无法识别 piper.exe
- 原因：未切换到 piper.exe 所在目录，或未配置环境变量。
- 解决：通过 cd 命令切换到对应目录，或直接使用 piper.exe 的绝对路径（如 D:\tools\piper_voice\piper.exe）。

总结

核心前提：piper.exe + zh_CN-huayan-medium 的两个核心文件（.onnx + .onnx.json）需放在可访问目录。
核心命令：通过 --model 指定音库，--input-text/--input 传入文本，--output_file 输出语音。
常用示例：直接文本合成 piper.exe --model 音库.onnx --input-text "文本" --output_file 语音.wav，批量合成可读取 .txt 文件