akukanara
177 lines
7.3 KiB
Markdown
177 lines
7.3 KiB
Markdown
# 🎙️ 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/kanaratechnologyindonesia)** (镜像: [git.kanara.tech](https://git.kanara.tech/kanara)) **用 ❤️ 制作**
|
||
* 基于 [ONNX Runtime](https://onnxruntime.ai/) 和 [Retrieval-based Voice Conversion (RVC)](https://github.com/RVC-Project/Retrieval-based-Voice-Conversion-WebUI)
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
本项目采用 Apache 2.0 许可证进行授权。详情请参阅 [LICENSE](file:///M:/Users/ahmad/project/onnx-voice-changer/LICENSE) 文件。
|