# py-tts

**Repository Path**: chenfei6095/py-tts

## Basic Information

- **Project Name**: py-tts
- **Description**: TTS语音合成，python实现，集成MQTT解耦
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-27
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# py-tts

基于 Python 的离线文本转语音（TTS）服务，集成 MQTT 协议与 Web 管理界面，支持流式合成秒播。

## 特性

- **离线运行** — 基于 sherpa-onnx，无需联网即可合成语音
- **流式秒播** — 回调机制边生成边播放，首字延迟极低
- **多模型支持** — VITS、Matcha-TTS、Kokoro 等主流模型
- **MQTT 集成** — 订阅文本主题，发布合成结果，适配物联网场景
- **Web 控制台** — Waveform Studio 深色主题管理界面，实时监控与任务管理
- **任务队列** — 最大队列限制、超时清理、历史持久化、排队取消
- **自动清理** — 可配置保留天数，定时清理过期音频文件
- **配置热更新** — TTS 配置即时生效，无需重启，自动持久化
- **运行日志** — 实时查看系统运行日志，自动滚动，按级别高亮
- **Docker 部署** — 一键容器化部署

## 项目结构

```
py-tts/
├── app.py                  # Flask Web 应用（API + 页面路由）
├── main.py                 # 主入口，初始化并启动所有组件
├── config/
│   ├── config.yaml         # 业务配置（TTS/MQTT/客户端）
│   └── logging_config.yaml # 日志配置
├── src/
│   ├── tts/
│   │   ├── tts_generator.py   # TTS 语音生成器
│   │   ├── tts_player.py      # 音频流式播放器
│   │   ├── mqtt_listener.py   # MQTT 消息监听与任务调度
│   │   └── task_manager.py    # 任务队列管理器
│   ├── utils/
│   │   ├── config_loader.py   # YAML 配置加载器
│   │   ├── mqtt_client.py     # MQTT 客户端封装
│   │   ├── file_cleaner.py    # 过期文件清理器
│   │   ├── logger_util.py     # 按业务分目录的日志工具
│   │   └── path_util.py       # 路径工具
│   └── others/
│       ├── offline-tts.py     # 离线 TTS 命令行工具
│       └── offline-tts-play.py # 离线 TTS 播放工具
├── static/                  # 前端静态资源
├── templates/
│   ├── dashboard.html       # 管理控制台页面
│   └── play.html            # 音频播放页面
├── Dockerfile
├── docker-compose.yml
└── requirements.txt
```

## 快速开始

### 1. 下载模型

选择一个模型下载并解压到 `models/` 目录：

| 模型 | 语言 | 链接 |
|------|------|------|
| sherpa-onnx-vits-zh-ll | 中文 | [下载](https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/sherpa-onnx-vits-zh-ll.tar.bz2) |
| matcha-icefall-zh-baker | 中文 | [下载](https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/matcha-icefall-zh-baker.tar.bz2) |
| matcha-icefall-en_US-ljspeech | 英文 | [下载](https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/matcha-icefall-en_US-ljspeech.tar.bz2) |
| kokoro-en-v0_19 | 英文 | [下载](https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/kokoro-en-v0_19.tar.bz2) |

### 2. 安装依赖

```bash
python -m venv py_tts_env
# Windows
.\py_tts_env\Scripts\activate
# Linux/macOS
source py_tts_env/bin/activate

pip install -r requirements.txt
```

### 3. 配置

编辑 `config/config.yaml`：

```yaml
tts:
  auto_play: False          # 是否自动播放合成语音
  retention_days: 1         # 音频文件保留天数
  save_path: "data/tts_output"  # 输出目录
  default_sid: 4            # 默认说话人 ID
  default_speed: 0.8        # 默认语速
  max_queue_size: 10        # 最大任务队列
  queue_timeout_seconds: 30 # 任务超时时间

mqtt:
  broker: "localhost"
  port: 1883
  username: ""
  password: ""
  topics:
    tts_request: "/voice/tts/generator"
    tts_result: "/voice/tts/response"
```

### 4. 启动服务

```bash
python main.py
```

启动后访问 http://localhost:5000 进入 Waveform Studio 管理界面。

## API 接口

### 创建合成任务

```
POST /api/tts
Content-Type: application/json

{
    "content": "要合成的文本",
    "sid": 4,
    "speed": 0.8
}
```

响应：

```json
{
    "task_id": "uuid",
    "reqId": "uuid",
    "message": "任务已创建",
    "status": "queued"
}
```

### 查询所有任务

```
GET /api/tasks
```

### 查询任务详情

```
GET /api/tasks/{task_id}
```

### 取消任务

```
POST /api/tasks/{task_id}/cancel
```

### 系统状态

```
GET /api/system/status
```

### 获取配置

```
GET /api/config
```

### 更新配置（热更新，无需重启）

```
PUT /api/config
Content-Type: application/json

{
    "tts": {
        "auto_play": true,
        "file_split_switch": false,
        "default_sid": 4,
        "default_speed": 0.8,
        "retention_days": 3
    }
}
```

支持热更新的字段（修改后即时生效，并自动持久化到配置文件，重启后仍然有效）：
- `tts.auto_play` — 自动播放开关（开/关时自动创建/清空播放器）
- `tts.file_split_switch` — 文件分割开关
- `tts.default_sid` — 默认说话人 ID
- `tts.default_speed` — 默认语速
- `tts.retention_days` — 文件保留天数
- `tts.save_path` — 音频文件存储路径

### 取消任务

```
POST /api/tasks/{task_id}/cancel
```

仅可取消状态为"排队中"或"处理中"的任务，取消后状态变为"已丢弃"，并记录取消原因"用户取消"。排队中的任务提供醒目的"取消排队"按钮。

### 删除任务

```
DELETE /api/tasks/{task_id}
```

删除已完成/失败/已取消的任务，同时清理关联的音频文件和元数据文件。

### 流式播放音频

```
GET /stream/{filename}
```

以流式方式返回音频文件（不触发下载），适用于在线播放。

### 获取运行日志

```
GET /api/logs?lines=200
```

返回最新的系统运行日志，默认返回最后 200 行，最多 500 行。日志按级别高亮显示（ERROR 红色、WARNING 黄色、DEBUG 灰色）。

响应：

```json
{
    "logs": ["日志行1", "日志行2", ...],
    "log_file": "web_app/20260416.log",
    "total_lines": 1234
}
```

### 下载音频

```
GET /download/{filename}
```

## MQTT 协议

### 请求格式

发送到配置的 `tts_request` 主题：

```json
[
    {
        "content": "要合成的文本内容",
        "sid": 4,
        "speed": 0.8
    }
]
```

仅 `content` 字段必填，`sid` 和 `speed` 可选，其他字段会原样返回。

### 响应格式

发布到配置的 `tts_result` 主题：

```json
{
    "reqId": "请求唯一ID",
    "status": "success",
    "content": "请求的文本内容",
    "fileName": "tts_xxxxx.wav",
    "filePath": "/path/to/tts_xxxxx.wav"
}
```

## Docker 部署

```bash
docker-compose up -d
```

默认映射端口 5000，可通过 `docker-compose.yml` 修改。

## 技术栈

- **TTS 引擎**: sherpa-onnx
- **Web 框架**: Flask
- **消息协议**: MQTT (paho-mqtt)
- **前端**: Vue 2 + Element UI
- **音频处理**: soundfile + sounddevice
- **容器化**: Docker

## 参与贡献

欢迎提交 Issue 或 Pull Request。

## License

MIT