# cosyvoice

**Repository Path**: code5/cosyvoice

## Basic Information

- **Project Name**: cosyvoice
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-02
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CosyVoice3 本地语音合成（Web 服务 + 音色预设 + JSON API）

基于 [CosyVoice3-0.5B](https://www.modelscope.cn/models/FunAudioLLM/CosyVoice3-0.5B-2512) 的本地化部署方案，提供：

- 🌐 **网页界面**（`http://localhost:8000`）：文本输入、9 个内置音色预设、参考音频上传、语速调节、试听、下载。
- 🔌 **JSON API**（`POST /api/tts_json`）：可直接用代码调用，返回 wav 文件或 base64。
- 🎭 **音色预设**：含官方真人 demo 克隆、风格合成，以及你自己的真人录音（御姐 / 正常姐妹，zero_shot 高保真）。

> 测试环境：Windows 11 + RTX 3070 (8GB) + Miniconda3 (Python 3.10) + CUDA 12.1。已启用 `onnxruntime-gpu`（CUDA 11 / cuDNN 8）解码，实测 RTF≈0.6（快于实时）。

---

## 1. 环境要求

- Python 3.10（推荐用 Miniconda 新建环境）
- NVIDIA GPU + CUDA 12.1 驱动（CPU 也能跑，但很慢）
- 约 10GB 磁盘空间（模型权重约 9GB）

---

## 2. 快速开始

### 2.1 克隆本仓库

```bash
git clone git@gitee.com:code5/cosyvoice.git
cd cosyvoice
```

### 2.2 下载模型权重（本仓库不含权重）

权重需自行下载到 `pretrained_models/Fun-CosyVoice3-0.5B/`。二选一：

**方式 A：ModelScope（国内推荐）**

```bash
pip install modelscope
python -c "from modelscope import snapshot_download; snapshot_download('FunAudioLLM/CosyVoice3-0.5B-2512', local_dir='pretrained_models/Fun-CosyVoice3-0.5B')"
```

**方式 B：HuggingFace 镜像**

```bash
export HF_ENDPOINT=https://hf-mirror.com
pip install huggingface_hub
python -c "from huggingface_hub import snapshot_download; snapshot_download('FunAudioLLM/CosyVoice3-0.5B-2512', local_dir='pretrained_models/Fun-CosyVoice3-0.5B')"
```

下载完后目录结构应类似：

```
pretrained_models/Fun-CosyVoice3-0.5B/
├── llm.pt
├── flow.pt
├── hift.pt
├── campplus.onnx
├── speech_tokenizer_v3.onnx
└── speech_tokenizer_v3.batch.onnx
```

### 2.3 安装依赖

```bash
pip install -r requirements.txt
# 若从官方 requirements 安装时 torch 被装成 CPU 版，强制重装 CUDA 版：
pip install torch==2.3.1+cu121 torchaudio==2.3.1+cu121 --index-url https://download.pytorch.org/whl/cu121
```

> `Matcha-TTS` 已作为普通目录纳入本仓库（`third_party/Matcha-TTS`），clone 后无需再 `git submodule update`。

### 2.4 启动服务

**方式 A：双击脚本（Windows）**

```
run_web.bat
```

**方式 B：命令行**

```bash
python -m uvicorn web_app:app --host 0.0.0.0 --port 8000
```

首次启动会加载模型（约 15~20 秒）。浏览器打开 <http://localhost:8000> 即可使用。

---

## 3. 网页使用

1. 在「合成文本」框输入要生成的中文 / 英文文本。
2. 在「音色预设」区**点选**一个音色（无需上传音频即可用）：
   - 点预设名 → 选中该音色用于下方「生成语音」。
   - 点预设名右侧的 **🔊** → 用固定句子**试听**该音色（不影响主生成区）。
   - 点「＋ 自定义上传」→ 展开参考音频区，上传自己的 3~10 秒清晰人声 + 对应文字，走零样本克隆。
3. 拖动「语速」滑块（0.5 慢 ~ 2.0 快）。
4. 点「▶ 生成语音」→ 在线试听 / 下载 wav。

---

## 4. JSON API（程序调用）

### 接口：`POST /api/tts_json`

请求体（`Content-Type: application/json`）：

| 字段 | 必填 | 说明 |
|---|---|---|
| `text` | ✅ | 要合成的文本 |
| `preset` | | 预设 id，见下表 |
| `prompt_text` | | 参考文本（配合 `sample` 做 zero_shot 高保真） |
| `sample` | | `asset/` 里的参考音频文件名（自定义音色） |
| `speed` | | 语速 0.5~2.0，默认 1.0 |
| `return_base64` | | `true` 时返回 base64 JSON 而非 wav 文件 |

响应：

- 默认：`audio/wav` 二进制文件（24kHz 单声道）
- `return_base64: true`：`{"audio_base64": "...", "sample_rate": 24000, "format": "wav"}`

### 调用示例

**curl（拿到 wav 文件）**

```bash
curl -s -X POST http://localhost:8000/api/tts_json \
  -H "Content-Type: application/json" \
  -d '{"text":"御姐音真的很迷人，你们觉得呢。","preset":"yujie"}' -o out.wav
```

**Python（见 `api_example.py`）**

```python
import requests, base64

r = requests.post("http://localhost:8000/api/tts_json",
                  json={"text": "测试一下", "preset": "sister", "return_base64": True})
d = r.json()
wav = base64.b64decode(d["audio_base64"])   # 24k 单声道 wav 字节
```

### 其它只读接口

| 接口 | 说明 |
|---|---|
| `GET /api/presets` | 列出所有音色预设（id / 名称 / 标签） |
| `GET /api/samples` | 列出 `asset/` 中可用参考音频 |
| `GET /api/health` | 健康检查，返回 `{"model_loaded": true}` |

---

## 5. 内置音色预设

| id | 名称 | 类型 | 说明 |
|---|---|---|---|
| `real_female` | 真人·女声 | 真人克隆 | 官方示例真人女声 |
| `real_male` | 真人·男声 | 真人克隆 | 官方示例真人男声 |
| `gentle` | 温柔甜美 | 风格合成 | 温柔治愈的女生 |
| `cute` | 活泼少女 | 风格合成 | 元气少女音 |
| `male` | 沉稳男中音 | 风格合成 | 成熟稳重男声 |
| `news` | 新闻播音 | 风格合成 | 字正腔圆播报风 |
| `sichuan` | 四川方言 | 风格合成 | 川味方言口音 |
| `yujie` | 御姐 | 真人克隆 | 你的真人录音（zero_shot 高保真） |
| `sister` | 正常姐妹 | 真人克隆 | 你的真人录音（zero_shot 高保真） |

> `御姐` / `正常姐妹` 来自 `asset/御姐.wav` / `asset/正常姐妹.wav`（已转为 16k 单声道），通过 `(音频, 原话)` 配对做 zero_shot 克隆，既保音色又还原录音的语气 / 停顿。

---

## 6. 目录结构

```
cosyvoice/
├── web_app.py            # FastAPI 服务：/api/tts(表单) + /api/tts_json(JSON) + 预设
├── index.html            # 网页操作界面（含预设试听）
├── api_example.py        # JSON API 调用示例
├── run_web.bat           # Windows 一键启动
├── asset/                # 内置参考音频（含御姐.wav / 正常姐妹.wav）
├── outputs/              # 每次合成的 wav 输出
├── cosyvoice/            # CosyVoice3 源码
├── third_party/
│   └── Matcha-TTS/       # flow 解码器（已作普通目录纳入）
└── pretrained_models/    # 模型权重（需自行下载，已 gitignore）
```

---

## 7. 性能与扩展

- **已启用 GPU 推理**：已用 `onnxruntime-gpu` 替换 CPU 版，flow / speech_tokenizer 解码走 CUDA。实测 RTF 从 CPU 版的 ≈1.1 降到 ≈0.6（快于实时）。
  - 关键：onnxruntime-gpu 1.18 的 Windows 构建依赖 **CUDA 11 + cuDNN 8** 运行库。需 `pip install onnxruntime-gpu==1.18.0 nvidia-cuda-runtime-cu11 nvidia-cublas-cu11 nvidia-cufft-cu11 "nvidia-cudnn-cu11==8.9.5.29"`，再把这些包里的 `cudart64_110.dll / cublas64_11.dll / cufft64_10.dll / cudnn64_8.dll` 等复制到 conda 环境**根目录**（`python.exe` 同级，如 `D:\miniconda3\envs\cosyvoice\`），Windows 加载器会优先搜索该目录，从而成功加载 `CUDAExecutionProvider`。装 cu12 版（cudart64_12 / cudnn64_9）会与 onnxruntime 1.18 不匹配，无法启用 GPU。
  - 验证：`python -c "import onnxruntime as ort; print(ort.get_available_providers())"` 出现 `CUDAExecutionProvider` 即成功。
- **长文本自动切句**：网页与 JSON API 输入超长文本时，后端会按句末标点（。！？；等）自动切分、逐句合成并拼接；单句超过约 200 字会按逗号/顿号再切，仍超长则硬切，保证不丢字、韵律自然。`/api/tts_json` 的 base64 响应会额外返回 `segments` 字段（切句段数）。长文本合成耗时大致随字数线性增长。
- 可扩展：批量合成、历史记录。