# 🎙️ ONNX VC - Standalone Real-Time Voice Changer

🌐 **语言:** [English](../README.md) | [Bahasa Indonesia](README.id.md) | [Español](README.es.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)

基于 **ONNX Runtime** 和 **检索式语音转换 (RVC)** 构建的高性能、低延迟实时 AI 变声系统。配有使用 **Next.js App Router**、**TypeScript** 和 **Tailwind CSS** 构建的高级仪表板，支持完整的国际化。

---

## ✨ 核心功能
* **🚀 WebSocket 音频传输管道:** 使用二进制 WebSocket 连接（原始 PCM float32）进行流式音频传输，确保最低的系统开销。
* **⚡ 多后端 ONNX 加速:** 支持包括 NVIDIA `CUDA`、AMD/Intel `DirectML` 以及备用 `CPU` 在内的多种执行提供程序。
* **🌐 通用本地化:** 支持英文、印尼文、日文、中文和西班牙文的完全可翻译界面。
* **🎨 高级仪表板:** 使用 React 19、Radix UI、Framer Motion 和 Tailwind CSS 构建的完全响应式工作区。
* **🎼 高保真 DSP 处理管道:**
  * **低切滤波器:** 80Hz 处的主动一阶巴特沃斯高通滤波器，用以消除交流蜂鸣声和隆隆声。
  * **噪声门:** 基于阈值的噪声抑制，可在静音期间绕过推理（以节省 CPU/GPU 周期）。
  * **增益控制:** 独立输入/输出数字增益级。
* **🧠 先进的基频提取:** 使用 RMVPE (Retrieval-based Minimum Vocal Pitch Estimation) 模型优化 16kHz 基频预测。
* **🌐 双路由架构:** 支持通过 Web 浏览器（Web Audio API）或直接通过服务器的本地音频硬件（使用 `sounddevice`）进行音频路由。

---

## 🛠️ 系统架构

```mermaid
graph TD
    A[麦克风 / Web 浏览器] -->|Web Audio API| B(WebSocket 连接)
    B -->|原始 Float32 PCM 块| C[server.py 后端]
    C -->|1. 高通滤波器 80Hz| D[DSP 阶段]
    D -->|2. 增益与噪声门| D
    D -->|3. 重采样至 16kHz| E[Hubert/ContentVec ONNX]
    D -->|4. 基频估计 RMVPE| F[基频预测器]
    E --> G[RVC ONNX 模型推理]
    F --> G
    G -->|目标音频块| H(WebSocket 连接)
    H -->|播放音频| I[浏览器扬声器 / 音频设备]
```

---

## 📁 仓库结构
* [server.py](file:///M:/Users/ahmad/project/onnx-voice-changer/server.py) — 主要的 WebSocket 后端服务器，用于管理连接循环、音频重采样和模型执行。
* [start.bat](file:///M:/Users/ahmad/project/onnx-voice-changer/start.bat) — Windows 启动批处理文件，可自动解析 Python 虚拟环境并执行服务器。
* [requirements.txt](file:///M:/Users/ahmad/project/onnx-voice-changer/requirements.txt) — Python 依赖列表。
* [frontend/](file:///M:/Users/ahmad/project/onnx-voice-changer/frontend) — 使用 Next.js（TypeScript, Tailwind CSS）构建的前端客户端工作区。
* [frontend-deprecated/](file:///M:/Users/ahmad/project/onnx-voice-changer/frontend-deprecated) — 已弃用的旧前端代码。
* [lib/](file:///M:/Users/ahmad/project/onnx-voice-changer/lib) — 核心包，包含推理模型、ONNX 转换脚本和预测工具。
* [weights/](file:///M:/Users/ahmad/project/onnx-voice-changer/weights) — 角色声音模型权重目录（例如 `weights/HuTao/`）。
* [pretrained/](file:///M:/Users/ahmad/project/onnx-voice-changer/pretrained) — 包含基础预训练模型的目录。

---

## 🚀 安装与设置

### 📋 准备工作
* **Python 3.10+**
* 已安装 **FFmpeg** 并添加到系统 PATH 中（音频处理工具所必需）。
* **Node.js 18+** 和 **npm**（运行 Next.js 前端客户端所必需）。
* （可选）用于 GPU 执行加速的 **NVIDIA CUDA Toolkit** (v11.x/12.x) 和 **cuDNN**。

---

### 📦 1. Python 后端安装
1. 将此仓库克隆到您的本地目录。
2. 初始化并激活虚拟环境：
   ```bash
   python -m venv venv
   # 在 Windows 下:
   .\venv\Scripts\activate
   # 在 Linux/macOS 下:
   source venv/bin/activate
   ```
3. 安装所需依赖：
   ```bash
   pip install -r requirements.txt
   ```

---

### 📥 2. 下载预训练 ContentVec（必需）
该模型需要 ContentVec 基础模型以从声音块生成说话者特征。
1. 从 Hugging Face 下载 `vec-768-layer-12.onnx` 模型：
   👉 **[下载 vec-768-layer-12.onnx](https://huggingface.co/DogManTC/test-rvc-onnx/blob/main/vec-768-layer-12.onnx)**
2. 将下载的文件保存到 `pretrained/` 目录中：
   ```
   pretrained/
   └── vec-768-layer-12.onnx
   ```

---

### 🔄 3. 设置并导出 RVC 模型为 ONNX
要在 ONNX Runtime 上运行角色模型，您必须将标准 PyTorch RVC模型（`.pth`）放入 `weights/` 目录并进行转换。

1. 在 `weights/` 下创建一个以您的角色命名的子文件夹（例如 `HuTao`）：
   ```
   weights/
   └── HuTao/
       └── HuTao.pth
   ```
2. 通过传递模型的文件夹名称来运行 ONNX 转换脚本：
   ```bash
   python lib/export_onnx.py --model_name HuTao
   ```
3. 脚本将自动在 `weights/HuTao/` 中搜索 `.pth` 文件，并在同一目录下导出相应的 `HuTao.onnx` 文件：
   ```
   weights/
   └── HuTao/
       ├── HuTao.pth
       └── HuTao.onnx
   ```

---

### 🖥️ 4. 运行前端客户端
前端客户端可以作为独立的 Next.js 开发服务器或编译后的生产服务器运行。

1. 进入前端目录：
   ```bash
   cd frontend
   ```
2. 安装 npm 依赖项：
   ```bash
   npm install
   ```
3. 启动开发服务器：
   ```bash
   npm run dev
   ```
   打开浏览器并访问 **`http://localhost:3000`**。

或者，构建并运行生产服务器：
```bash
npm run build
npm run start
```

---

## 🏃 运行变声器

### 步骤 1：启动 Python WebSocket 后端
使用终端运行服务器（默认为端口 `8765`）：
```bash
python server.py --host 127.0.0.1 --port 8765 --device cuda
```

#### ⚙️ 命令行参数
| 参数 | 说明 | 默认值 |
|---|---|---|
| `--host` | WebSocket 服务器绑定的地址。 | `127.0.0.1` |
| `--port` | WebSocket 通信端口。 | `8765` |
| `--device` | ONNX Runtime 执行设备（`cpu`、`cuda`、`dml`）。 | `cuda` |
| `--model` | 启动时直接加载的 `weights/` 中的目标文件夹名称。 | `None` |

### 步骤 2：打开前端仪表板
确保您的前端客户端正在运行（通过 `npm run dev` 或在 `http://localhost:3000` 上运行 `npm run start`），在浏览器中打开它，它将自动连接到 WebSocket API 后端。

---

## 音频 DSP 细节
为了在没有输出伪影的情况下实现低延迟，音频处理利用了：
1. **滑动窗口上下文缓冲区:** 保持较短的音频历史缓冲区，以向模型提供所需的上下文帧，同时最小化输出音频延迟。
2. **卷积填充淡出:** 在输入片段中临时追加 120ms 的尾随静音填充，以避免 RVC 卷积步骤中固有的边缘淡入淡出异常。
3. **线性重采样:** 低开销的线性插值，可快速适应采样率。

---

## 🤝 鸣谢与贡献
* **由 [Kanara Technology](https://github.com/kanaratech) 用 ❤️ 制作**
* 基于 [ONNX Runtime](https://onnxruntime.ai/) 和 [Retrieval-based Voice Conversion (RVC)](https://github.com/RVC-Project/Retrieval-based-Voice-Conversion-WebUI)