# piper_tts练习

**Repository Path**: futurelei/pipertts-practice

## Basic Information

- **Project Name**: piper_tts练习
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Piper 中文语音合成工具 (Windows/Embedded)

一个基于 Piper TTS 的中文语音合成工具，支持 Windows 开发和嵌入式部署，使用 uv 进行 Python 环境管理。

## 📁 项目结构

```
win-dev/
├── models/                          # 模型文件目录
│   ├── zh_CN-huayan-medium.onnx
│   └── zh_CN-huayan-medium.onnx.json
├── main_piper.py                    # 主程序
├── pyproject.toml                   # uv 项目配置
├── uv.lock                          # uv 锁文件
└── README.md                        # 本文件
```

## 🚀 快速开始

### 1. 安装 uv（如果未安装）

```bash
# 一键安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. 下载中文语音模型

模型文件已放在 `models/` 目录，包含：
- `zh_CN-huayan-medium.onnx` (约 63MB) - 中文语音模型
- `zh_CN-huayan-medium.onnx.json` - 模型配置文件

如果 models 目录为空，从以下地址下载：

```bash
# 使用国内镜像,魔搭社区的
curl -L -o models/zh_CN-huayan-medium.onnx \
  https://www.modelscope.cn/models/Trelis/piper-zh-cn-huayan-medium/resolve/master/model.onnx

curl -L -o models/zh_CN-huayan-medium.onnx.json \
  https://www.modelscope.cn/models/Trelis/piper-zh-cn-huayan-medium/resolve/master/model.onnx.json
```

### 3. 安装依赖

```bash
# 创建虚拟环境并安装依赖
uv sync

# 或手动安装核心依赖
uv add piper-tts soundfile

# 可选：实时播放功能
uv add sounddevice
uv add pyaudio
```

### 4. 运行测试

```bash
# 基本合成
uv run python main_piper.py --text "你好，系统已启动"

# 合成并播放
uv run python main_piper.py --text "所有传感器运行正常" --play

# 交互模式
uv run python main_piper.py --interactive
```

## 📋 功能特性

| 功能 | 命令示例 | 说明 |
|------|----------|------|
| 文本转语音 | `--text "你好"` | 基础文本转语音 |
| 文件输出 | `--output speech.wav` | 保存为 WAV 文件 |
| 实时播放 | `--play` | 合成后立即播放 |
| 交互模式 | `--interactive` | 交互式输入文本 |
| 批量处理 | `--input-file texts.txt` | 从文件批量处理 |
| 速度调节 | `--speed 1.2` | 调节播放速度 (0.5-2.0) |
| 流式输出 | 代码调用 | 支持流式音频输出 |

## 🎯 使用示例

### 基础使用

```bash
# 1. 单句合成
uv run python main_piper.py --text "温度传感器读数正常" --output temp.wav

# 2. 合成并播放
uv run python main_piper.py --text "系统启动完成" --play

# 3. 调节语速
uv run python main_piper.py --text "警告：温度过高" --play --speed 1.5
```

### 批量处理

创建 `sentences.txt` 文件：
```txt
系统启动完成
温度传感器正常
湿度传感器正常
所有设备在线
```

运行批量合成：
```bash
uv run python main_piper.py --input-file sentences.txt
```

### Python API 调用

```python
from main_piper import PiperTTS

# 初始化
tts = PiperTTS("models/zh_CN-huayan-medium.onnx")

# 1. 保存到文件
tts.synthesize_to_file("系统启动完成", "startup.wav")

# 2. 实时播放
tts.play_stream("传感器数据已更新", block=True)

# 3. 流式输出
for audio_chunk in tts.synthesize_to_stream("正在处理数据"):
    # 处理音频块
    process_audio(audio_chunk)
```

## 🔧 嵌入式部署

### 树莓派/RK3588 配置

```bash
# 1. 安装系统依赖
sudo apt update
sudo apt install -y python3-pip python3-venv

# 2. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

# 3. 复制项目文件
scp -r win-dev/kokoro/ user@raspberrypi:~/

# 4. 在板子上运行
ssh user@raspberrypi
cd kokoro
uv sync
uv run python main_piper.py --text "树莓派启动完成" --play
```

### 开机自启服务

创建 `/etc/systemd/system/tts-service.service`：

```ini
[Unit]
Description=Piper TTS Service
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/kokoro
Environment="PATH=/home/pi/.local/bin:/usr/bin"
ExecStart=/home/pi/.cargo/bin/uv run python main_piper.py --text "系统启动完成" --play
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

启用服务：
```bash
sudo systemctl enable tts-service
sudo systemctl start tts-service
```

## 📊 性能对比

| 模型 | 文件大小 | 内存占用 | CPU占用 (RPi 4) | 音质 | 支持平台 |
|------|----------|----------|-----------------|------|----------|
| Piper 中文 | 63MB | ~150MB | 中等 | 良好 | Windows/Linux/ARM |
| Kokoro int8 | 40MB | ~200MB | 较高 | 一般 | Windows/Linux/ARM |
| KittenTTS | 25MB | ~100MB | 低 | 一般 | 全平台 |

## 🐛 常见问题

### 1. 模型下载失败
```bash
# 使用国内镜像
export HF_ENDPOINT=https://hf-mirror.com
```

### 2. 播放无声音
- Windows: 确保音频输出设备正常
- Linux: 安装 ALSA/PulseAudio
```bash
# Ubuntu/Debian
sudo apt install alsa-utils pulseaudio

# 测试音频
aplay /usr/share/sounds/alsa/Front_Center.wav
```

### 3. 内存不足
- 使用 `zh_CN-huayan-x_low` 低质量模型
- 减少并发处理
- 增加交换空间

### 4. 发音不准确
Piper 中文模型基于 VITS 架构，对某些专有名词可能发音不准。建议：
- 使用常用词汇
- 适当调整文本
- 考虑专业 TTS 服务

## 🔄 升级维护

### 更新依赖
```bash
# 更新所有依赖
uv update

# 更新特定包
uv update piper-tts
```

### 添加新依赖
```bash
# 添加新包
uv add package-name

# 添加开发依赖
uv add --dev pytest
```

## 📄 许可证

本项目基于 Piper TTS (Apache 2.0) 和 uv (MIT)，中文语音模型遵循相应许可证。

## 🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支
3. 提交更改
4. 推送分支
5. 创建 Pull Request

## 📞 技术支持

- 问题反馈: GitHub Issues
- 模型下载: https://huggingface.co/rhasspy/piper-voices
- 文档: https://github.com/rhasspy/piper

---

**备注**：本项目已配置为使用 uv 管理，确保在运行任何 Python 命令前使用 `uv run` 前缀。