# MoYoYo.tts 使用手册

## 目录

- [简介](#简介)
- [快速开始](#快速开始)
- [系统要求](#系统要求)
- [安装指南](#安装指南)
  - [安装 uv 包管理器](#31-安装-uv-包管理器)
  - [Python 环境设置](#32-python-环境设置)
  - [下载必需的数据文件](#33-下载必需的数据文件)
  - [前端设置](#34-前端设置)
- [配置](#配置)
  - [后端 API 配置](#41-后端-api-配置)
  - [前端配置](#42-前端配置)
- [运行应用](#运行应用)
  - [启动后端 API 服务器](#51-启动后端-api-服务器)
  - [启动前端 Electron 应用](#52-启动前端-electron-应用)
- [首次设置](#首次设置)
- [功能概览](#功能概览)
- [故障排除](#故障排除)

---

## 简介

MoYoYo.tts 是一个综合性的声音克隆和文本转语音系统，结合了：

- **后端 API**：基于 FastAPI 的 REST API，用于声音训练和推理
- **前端应用**：Electron + Vue 桌面应用，具有直观的用户界面

该系统基于 GPT-SoVITS 技术构建，能够使用最少的训练数据（最短 5 秒音频）实现高质量的声音克隆。

**目标用户**：
- 想要创建自定义文本转语音声音的最终用户
- 将语音合成集成到应用程序中的开发人员
- 从事声音克隆技术研究的研究人员

**主要功能**：
- 快速模式：为初学者提供一键式声音克隆
- 高级模式：对训练管道进行精细控制
- 通过服务器发送事件（SSE）进行实时进度跟踪
- 多语言支持（中文、英文、日文）
- 支持 GPU 加速的 CUDA

---

## 快速开始

通过以下基本步骤，在 5 分钟内启动并运行：

**1. 安装 uv**（Python 包管理器）：
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

**2. 设置 Python 环境**：
```bash
cd GPT-SoVITS
uv sync  # 创建 .venv 并安装所有依赖项
source .venv/bin/activate  # macOS/Linux
# 或: .venv\Scripts\activate  # Windows
```

**3. 下载必需的模型**（详见 3.3 节）：
```bash
# 下载并解压 NLTK 数据、预训练模型等
# 或使用前端应用自动下载
```

**4. 启动后端 API**：
```bash
cd api_server
python app/main.py
# API 运行在 http://localhost:8000
```

**5. 启动前端应用**（在新终端中）：
```bash
cd tts-voice-app
npm install
npm run dev
```

大功告成！Electron 应用将引导您完成模型设置和声音克隆。

有关详细的安装说明、平台特定注意事项和配置选项，请继续阅读以下内容。

---

## 系统要求

### 软件要求

| 组件 | 版本 | 说明 |
|-----------|---------|-------|
| **Python** | 3.10 - 3.12 | 推荐 Python 3.11 |
| **Node.js** | >= 18.x | 用于前端开发 |
| **uv** | 最新版 | Python 包管理器 |
| **CUDA** | 12.6 或 12.8 | 可选，用于 GPU 加速 |

### 硬件要求

| 组件 | 最低配置 | 推荐配置 |
|-----------|---------|-------------|
| **CPU** | 双核 | 四核或更好 |
| **RAM** | 16 GB | 32 GB（用于训练） |
| **GPU** | 无（CPU 模式） | 配备 6GB+ 显存的 NVIDIA GPU |
| **存储** | 20 GB 可用空间 | 50 GB+（用于多个声音） |

**GPU 说明**：
- GPU 是可选的，但可显著加快训练速度（5-10 倍）
- 推荐使用支持 CUDA 12.6 或 12.8 的 NVIDIA GPU
- 目前不支持 AMD GPU 和 Apple Silicon 进行训练

---

## 安装指南

### 3.1 安装 uv 包管理器

uv 是一个快速的 Python 包安装器和解析器，可以替代 pip。

**macOS / Linux**：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows**（PowerShell）：
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

验证安装：
```bash
uv --version
```

### 3.2 Python 环境设置

该项目使用 `uv` 进行依赖管理，配置文件为 `pyproject.toml`。设置过程简化为一个命令。

**步骤 1：进入项目目录**
```bash
cd GPT-SoVITS
```

**步骤 2：同步所有依赖项**
```bash
# 这个命令将：
# - 创建虚拟环境（.venv）
# - 安装 Python 3.11（或您指定的版本）
# - 从 pyproject.toml 安装所有依赖项
# - 为您的平台安装正确的 PyTorch 版本
uv sync
```

**步骤 3：激活环境**

macOS / Linux：
```bash
source .venv/bin/activate
```

Windows：
```cmd
.venv\Scripts\activate
```

您应该在终端提示符中看到 `(.venv)` 前缀。

**平台特定的 PyTorch 安装工作原理**：

`pyproject.toml` 会自动选择适当的 PyTorch 版本：
- **macOS**：安装仅 CPU 的 PyTorch（Apple Silicon 使用 CPU 模式）
- **Linux**：默认安装 CUDA 12.6 PyTorch
- **Windows**：需要手动选择 CUDA 版本（见下文）

**Windows 用户 - 选择 CUDA 版本**：

对于 Windows，您需要明确指定 PyTorch 索引：

**CUDA 12.6**（默认）：
```bash
uv sync
```

**CUDA 12.8**：
```bash
uv sync --index pytorch-cu128
```

**仅 CPU**（无 GPU）：
```bash
uv sync --index pytorch-cpu
```

**验证安装**：
```bash
# 检查 Python 版本
python --version  # 应显示 Python 3.11.x

# 检查 PyTorch 安装
python -c "import torch; print(f'PyTorch: {torch.__version__}')"

# 检查 CUDA 可用性（如果您有 GPU）
python -c "import torch; print(f'CUDA 可用: {torch.cuda.is_available()}')"
```

### 3.3 下载必需的数据文件

以下数据文件是文本处理和声音训练所必需的。

#### NLTK 数据（文本处理必需）

NLTK（自然语言工具包）数据用于文本分词和处理。

```bash
# 从 ModelScope 下载
wget https://www.modelscope.cn/models/XXXXRT/GPT-SoVITS-Pretrained/resolve/master/nltk_data.zip

# 解压到 Python 环境
unzip -q -o nltk_data.zip -d .venv/

# 清理
rm nltk_data.zip
```

**大小**：约 10 MB
**时间**：< 1 分钟

#### Open JTalk 词典（日语必需）

Open JTalk 是日语文本转语音处理所必需的。

```bash
# 获取 pyopenjtalk 安装路径
PYOPENJTALK_PATH=$(python -c "import os, pyopenjtalk; print(os.path.dirname(pyopenjtalk.__file__))")

# 从 ModelScope 下载
wget https://www.modelscope.cn/models/XXXXRT/GPT-SoVITS-Pretrained/resolve/master/open_jtalk_dic_utf_8-1.11.tar.gz

# 解压到 pyopenjtalk 目录
tar -xzf open_jtalk_dic_utf_8-1.11.tar.gz -C "$PYOPENJTALK_PATH"

# 清理
rm open_jtalk_dic_utf_8-1.11.tar.gz
```

**大小**：约 50 MB
**时间**：< 2 分钟


### 3.4 前端设置

前端是使用 Vue.js 构建的 Electron 应用程序。

```bash
# 进入前端目录
cd tts-voice-app

# 安装 Node.js 依赖项
npm install
```

**时间**：2-5 分钟
**说明**：这会安装所有必需的 Node.js 包，包括 Electron、Vue 和 UI 组件。

---

## 配置

### 4.1 后端 API 配置

后端使用环境变量进行配置。在项目根目录创建 `.env` 文件以进行自定义设置。

**创建 `.env` 文件**（可选，默认值适用于本地开发）：

```bash
# 部署模式
# 选项：local, server
DEPLOYMENT_MODE=local

# API 服务器设置
API_HOST=0.0.0.0
API_PORT=8000

# 数据存储路径
DATA_DIR=~/.moyoyo-tts/data
SQLITE_PATH=~/.moyoyo-tts/data/tasks.db

# 训练设置
LOCAL_MAX_WORKERS=1  # 并发训练任务数
```

**配置选项**：

| 变量 | 默认值 | 说明 |
|----------|---------|-------------|
| `DEPLOYMENT_MODE` | `local` | 部署环境（local/server） |
| `API_HOST` | `0.0.0.0` | API 服务器绑定地址 |
| `API_PORT` | `8000` | API 服务器端口 |
| `DATA_DIR` | `~/.moyoyo-tts/data` | 数据存储目录 |
| `SQLITE_PATH` | `~/.moyoyo-tts/data/tasks.db` | SQLite 数据库路径 |
| `LOCAL_MAX_WORKERS` | `1` | 最大并发训练任务数 |

**说明**：
- `API_HOST=0.0.0.0` 允许来自任何网络接口的连接
- `LOCAL_MAX_WORKERS=1` 防止内存有限的系统出现内存问题
- 在高端系统上增加 `LOCAL_MAX_WORKERS` 以同时训练多个声音

### 4.2 前端配置

前端在本地开发时只需要最少的配置。

**默认设置**：
- **API 端点**：`http://localhost:8000`
- **声音存储**：`~/.moyoyo-tts/voices/`
- **模型存储**：`GPT_SoVITS/pretrained_models/`

**自动配置**：
Electron 应用将：
1. 自动检测并连接到本地 API 服务器
2. 首次启动时创建所需的目录
3. 通过模型设置页面下载缺失的模型

标准使用无需手动配置。

---

## 运行应用

### 5.1 启动后端 API 服务器

**步骤 1：激活 Python 环境**

```bash
# 进入项目目录
cd GPT-SoVITS

# 激活虚拟环境
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows
```

**步骤 2：启动 API 服务器**

方法 1 - 使用主脚本：
```bash
cd api_server
python app/main.py
```

方法 2 - 直接使用 uvicorn：
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

**预期输出**：
```
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```

**API 文档**：
服务器运行后，访问交互式 API 文档：

- **Swagger UI**：http://localhost:8000/docs
- **ReDoc**：http://localhost:8000/redoc
- **OpenAPI JSON**：http://localhost:8000/openapi.json

**健康检查**：
```bash
curl http://localhost:8000/health
# 预期输出：{"status": "healthy"}
```

### 5.2 启动前端 Electron 应用

**步骤 1：打开新终端**

保持后端服务器运行，打开一个新的终端窗口。

**步骤 2：进入前端目录**

```bash
cd tts-voice-app
```

**步骤 3：启动开发模式**

```bash
npm run dev
```

**预期输出**：
```
> tts-voice-app@1.0.0 dev
> electron-vite dev

  VITE v4.x.x  ready in xxx ms
  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Electron app starting...
```

Electron 应用将自动启动，开发模式下启用热重载。

**开发模式功能**：
- 热模块替换（HMR）实现即时 UI 更新
- Vue DevTools 集成
- 用于调试的控制台日志记录
- 主进程更改时自动重启

---

## 首次设置

首次启动 Electron 应用时，您需要下载必需的模型。

**设置流程**：

1. **启动 Electron 应用**
   ```bash
   cd tts-voice-app
   npm run dev
   ```

2. **模型设置页面**
   - 应用自动检测缺失的模型
   - 您将被重定向到模型设置页面

3. **下载模型**
   - 点击"下载所有模型"按钮
   - 要下载的模型：
     - **预训练模型**：4.56 GB
     - **G2PW 模型**：588.86 MB
     - **FunASR**：1.09 GB
     - **Faster Whisper**：2.85 GB
   - 总下载大小：约 9 GB

4. **监控进度**
   - 实时进度条显示下载状态
   - 预计时间：10-30 分钟（取决于连接速度）
   - 下载可以暂停和恢复

5. **设置完成**
   - 所有模型下载完成后，点击"继续"
   - 您将被重定向到主 TTS 页面
   - 应用现在可以使用了

**故障排除**：
- 如果下载失败，请检查您的互联网连接
- 确认您有约 10 GB 的可用磁盘空间
- 如需手动安装，请参见 3.3 节

---

## 功能概览

MoYoYo.tts 通过直观的界面提供强大的声音克隆和文本转语音功能：

**快速模式**为初学者提供简化的一键式工作流程。只需上传 5-30 秒的音频样本，选择您的质量预设（fast/standard/high），然后开始训练。系统自动处理所有管道阶段，包括音频处理、语音识别、特征提取和模型训练。在 10-40 分钟内，您将获得一个可用于文本转语音生成的自定义声音。

**高级模式**为经验丰富的用户提供对训练管道各个阶段的精细控制。您可以微调音频切片参数，在 ASR 模型之间选择（用于中文的 DamoASR，用于多语言的 Faster Whisper），调整训练轮数和批次大小，并监控每个阶段的详细进度。此模式非常适合优化质量或处理特定的音频特性。

**文本转语音生成**允许您立即使用任何训练好的声音将文本转换为自然发音的语音。调整说话速度（0.5x-2.0x），如果支持则选择情感语气，并在几秒钟内生成高质量的音频输出。系统支持多种语言，并提供实时音频播放和下载功能。

**声音库管理**将所有训练好的声音集中在一个地方。按语言或质量浏览、搜索和筛选声音。使用样本音频预览任何声音，导出模型进行备份或共享，并有效管理您的声音收藏。

有关详细的 API 文档和高级使用，请在后端服务器运行时访问交互式 Swagger UI：**http://localhost:8000/docs**。

---

## 故障排除

### 后端问题

#### 端口已被占用

**症状**：启动服务器时出现 `Address already in use` 错误消息。

**解决方案 1** - 在 `.env` 中更改端口：
```bash
echo "API_PORT=8001" >> .env
python app/main.py
```

**解决方案 2** - 查找并终止使用端口的进程：
```bash
# macOS/Linux
lsof -ti:8000 | xargs kill -9

# Windows
netstat -ano | findstr :8000
taskkill /PID <pid> /F
```

#### 数据库错误

**症状**：`sqlite3.OperationalError` 或数据库损坏消息。

**解决方案** - 重置数据库：
```bash
# 备份现有数据库（可选）
cp ~/.moyoyo-tts/data/tasks.db ~/.moyoyo-tts/data/tasks.db.backup

# 删除损坏的数据库
rm ~/.moyoyo-tts/data/tasks.db

# 重启 API 服务器（数据库将被重新创建）
python app/main.py
```

#### Python 环境问题

**症状**：`ModuleNotFoundError` 或导入错误。

**解决方案**：
```bash
# 验证环境已激活
which python  # 应显示 .venv 中的路径

# 重新安装所有依赖项
uv sync --reinstall

# 或从头强制重新安装
rm -rf .venv
uv sync

# 检查缺失的包
uv pip list
```

### 前端问题

#### 无法连接到 API

**症状**：前端显示"无法连接到服务器"错误。

**诊断**：
```bash
# 检查后端是否正在运行
curl http://localhost:8000/health

# 检查网络连接
ping localhost
```

**解决方案**：
1. **后端未运行**：启动后端服务器（参见 5.1 节）
2. **错误的端口**：检查后端是否在端口 8000 上
3. **防火墙**：允许连接到 localhost:8000
4. **CORS 错误**：检查后端 `.env` 中的 CORS 设置

#### 模型未下载

**症状**：模型下载失败或无限期挂起。

**解决方案**：
1. **检查互联网连接**：
   ```bash
   curl -I https://www.modelscope.cn
   ```

2. **检查磁盘空间**：
   ```bash
   df -h  # 需要约 10GB 可用空间
   ```

3. **手动下载**：参见 3.3 节进行手动安装

4. **代理问题**：配置代理设置：
   ```bash
   export http_proxy=http://proxy.example.com:8080
   export https_proxy=http://proxy.example.com:8080
   ```

#### Electron 应用无法启动

**症状**：应用启动时崩溃或显示空白屏幕。

**解决方案 1** - 清除缓存并重建：
```bash
# 进入前端目录
cd tts-voice-app

# 清除缓存
rm -rf node_modules package-lock.json dist .vite

# 重新安装依赖项
npm install

# 重建
npm run dev
```

**解决方案 2** - 检查 Node.js 版本：
```bash
node --version  # 应该是 >= 18.x

# 如需更新 Node.js
nvm install 18
nvm use 18
```

**解决方案 3** - 检查 Electron 日志：
```bash
# macOS
~/Library/Logs/tts-voice-app/

# Linux
~/.config/tts-voice-app/logs/

# Windows
%APPDATA%\tts-voice-app\logs\
```

---

**最后更新**：2026-01-23
**版本**：1.0.0
**维护者**：MoYoYo.tts 开发团队