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

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

Un sistema de conversión de voz por IA en tiempo real, de alto rendimiento y baja latencia, impulsado por **ONNX Runtime** y **Retrieval-based Voice Conversion (RVC)**. Cuenta con un panel de control premium desarrollado con **Next.js App Router**, **TypeScript** y **Tailwind CSS**, con soporte para internacionalización completa.

---

## ✨ Características Clave
* **🚀 Canal de Audio WebSocket (Audio Pipeline):** Transferencia de audio en tiempo real mediante conexiones WebSocket binarias (PCM float32 sin procesar) para una latencia mínima.
* **⚡ Aceleración ONNX Multi-Backend:** Soporta proveedores de ejecución que incluyen NVIDIA `CUDA`, AMD/Intel `DirectML` y CPU como respaldo.
* **🌐 Localización Universal:** Interfaz completamente traducible que soporta inglés, indonesio, japonés, chino y español.
* **🎨 Panel de Control Premium:** Entorno de trabajo responsivo construido con React 19, Radix UI, Framer Motion y Tailwind CSS.
* **🎼 Canal DSP de Alta Fidelidad:**
  * **Filtro de Corte Bajo (Low-Cut Filter):** Filtro de paso alto Butterworth activo de primer orden a 80 Hz para eliminar el zumbido de CA y los ruidos de fondo.
  * **Puerta de Ruido (Noise Gate):** Supresión de ruido basada en umbral para omitir la inferencia durante el silencio (ahorrando ciclos de CPU/GPU).
  * **Controles de Ganancia:** Control de ganancia digital independiente de entrada y salida.
* **🧠 Extracción Avanzada de Tono:** Predicción de tono optimizada a 16 kHz utilizando el modelo RMVPE (Retrieval-based Minimum Vocal Pitch Estimation).
* **🌐 Arquitectura de Enrutamiento Dual:** Permite enrutar el audio a través del navegador web (Web Audio API) o directamente mediante el hardware de audio local del servidor (utilizando `sounddevice`).

---

## 🛠️ Arquitectura del Sistema

```mermaid
graph TD
    A[Micrófono / Navegador Web] -->|Web Audio API| B(Conexión WebSocket)
    B -->|Fragmento de PCM Float32 sin procesar| C[Backend de server.py]
    C -->|1. Filtro de paso alto 80Hz| D[Tahap DSP]
    D -->|2. Ganancia y puerta de ruido| D
    D -->|3. Remuestreo a 16kHz| E[Hubert/ContentVec ONNX]
    D -->|4. Estimación de tono RMVPE| F[Predictor de tono]
    E --> G[Inferencia del modelo RVC ONNX]
    F --> G
    G -->|Fragmentos de audio de destino| H(Conexión WebSocket)
    H -->|Reproducir audio| I[Altavoces del navegador / Dispositivo de audio]
```

---

## 📁 Estructura del Repositorio
* [server.py](file:///M:/Users/ahmad/project/onnx-voice-changer/server.py) — El servidor backend WebSocket principal que gestiona los bucles de conexión, el remuestreo de audio y la ejecución del modelo.
* [start.bat](file:///M:/Users/ahmad/project/onnx-voice-changer/start.bat) — Archivo por lotes ejecutable para Windows que inicializa automáticamente el entorno virtual de Python y ejecuta el servidor.
* [requirements.txt](file:///M:/Users/ahmad/project/onnx-voice-changer/requirements.txt) — Lista de dependencias de Python.
* [frontend/](file:///M:/Users/ahmad/project/onnx-voice-changer/frontend) — El espacio de trabajo del cliente frontend construido con Next.js (TypeScript, Tailwind CSS).
* [frontend-deprecated/](file:///M:/Users/ahmad/project/onnx-voice-changer/frontend-deprecated) — Código frontend antiguo ya en desuso.
* [lib/](file:///M:/Users/ahmad/project/onnx-voice-changer/lib) — Paquete central que contiene los modelos de inferencia, scripts de conversión a ONNX y herramientas de predicción.
* [weights/](file:///M:/Users/ahmad/project/onnx-voice-changer/weights) — Directorio para los archivos de peso de los modelos de voz de personajes (ej. `weights/HuTao/`).
* [pretrained/](file:///M:/Users/ahmad/project/onnx-voice-changer/pretrained) — Directorio que contiene los modelos base preentrenados.

---

## 🚀 Instalación y Configuración

### 📋 Requisitos Previos
* **Python 3.10+**
* **FFmpeg** instalado y agregado al PATH del sistema (necesario para las utilidades de procesamiento de audio).
* **Node.js 18+** y **npm** (necesario para ejecutar el cliente frontend Next.js).
* (Opcional) **NVIDIA CUDA Toolkit** (v11.x/12.x) y **cuDNN** para aceleración de ejecución en GPU.

---

### 📦 1. Instalación del Backend de Python
1. Clone este repositorio en su directorio local.
2. Inicialice y active un entorno virtual:
   ```bash
   python -m venv venv
   # En Windows:
   .\venv\Scripts\activate
   # En Linux/macOS:
   source venv/bin/activate
   ```
3. Instale las dependencias requeridas:
   ```bash
   pip install -r requirements.txt
   ```

---

### 📥 2. Descargar ContentVec Preentrenado (Requerido)
El modelo requiere un modelo base ContentVec para generar las características del hablante a partir de los fragmentos de voz.
1. Descargue el modelo `vec-768-layer-12.onnx` desde Hugging Face:
   👉 **[Descargar vec-768-layer-12.onnx](https://huggingface.co/DogManTC/test-rvc-onnx/blob/main/vec-768-layer-12.onnx)**
2. Guarde el archivo descargado dentro del directorio `pretrained/`:
   ```
   pretrained/
   └── vec-768-layer-12.onnx
   ```

---

### 🔄 3. Configuración y Exportación de Modelos RVC a ONNX
Para ejecutar modelos de personajes en ONNX Runtime, debe colocar sus modelos RVC estándar de PyTorch (`.pth`) bajo el directorio `weights/` y convertirlos.

1. Cree una subcarpeta bajo `weights/` con el nombre de su personaje (ej. `HuTao`):
   ```
   weights/
   └── HuTao/
       └── HuTao.pth
   ```
2. Ejecute el script de conversión a ONNX pasando el nombre de la carpeta del modelo:
   ```bash
   python lib/export_onnx.py --model_name HuTao
   ```
3. El script buscará automáticamente el archivo `.pth` dentro de `weights/HuTao/` y exportará el archivo `HuTao.onnx` correspondiente en el mismo directorio:
   ```
   weights/
   └── HuTao/
       ├── HuTao.pth
       └── HuTao.onnx
   ```

---

### 🖥️ 4. Ejecución del Cliente Frontend
El cliente frontend se ejecuta como un servidor de desarrollo independiente de Next.js o como un servidor de producción compilado.

1. Navegue al directorio frontend:
   ```bash
   cd frontend
   ```
2. Instale las dependencias de npm:
   ```bash
   npm install
   ```
3. Inicie el servidor de desarrollo:
   ```bash
   npm run dev
   ```
   Abra su navegador y acceda a **`http://localhost:3000`**.

Alternativamente, para compilar y ejecutar el servidor de producción:
```bash
npm run build
npm run start
```

---

## 🏃 Funcionamiento del Cambiador de Voz

### Paso 1: Iniciar el Backend WebSocket de Python
Ejecute el servidor desde su terminal (puerto predeterminado `8765`):
```bash
python server.py --host 127.0.0.1 --port 8765 --device cuda
```

#### ⚙️ Argumentos de Línea de Comandos
| Argumento | Descripción | Predeterminado |
|---|---|---|
| `--host` | La dirección a la que se enlaza el servidor WebSocket. | `127.0.0.1` |
| `--port` | Puerto de comunicación WebSocket. | `8765` |
| `--device` | El dispositivo de ejecución de ONNX Runtime (`cpu`, `cuda`, `dml`). | `cuda` |
| `--model` | Nombre de la carpeta de destino en `weights/` para cargar directamente al inicio. | `None` |

### Paso 2: Abrir el Panel de Control Frontend
Asegúrese de que su cliente frontend esté ejecutándose (a través de `npm run dev` o `npm run start` en `http://localhost:3000`), ábralo en su navegador y este se conectará automáticamente al backend de la API WebSocket.

---

## 🔊 Detalles de DSP de Audio
Para lograr una latencia baja sin artefactos de salida, el procesamiento de audio utiliza:
1. **Búfer de Contexto de Ventana Deslizante:** Mantiene un búfer histórico corto de audio para alimentar al modelo con los fragmentos de contexto necesarios, minimizando el retraso de la salida de audio.
2. **Desvanecimiento por Relleno de Convolución:** Se añade temporalmente un relleno silencioso de 120 ms al final de los segmentos de entrada para evitar anomalías de desvanecimiento en los bordes, inherentes a los pasos de convolución RVC.
3. **Remuestreo Lineal:** Interpolación lineal de bajo costo computacional para una rápida adaptación de la frecuencia de muestreo.