From b84c99c88707aa3b1ff5217da455bc88c306b994 Mon Sep 17 00:00:00 2001
From: akukanara <kanaracathleen@gmail.com>
Date: Sun, 31 May 2026 17:01:52 +0700
Subject: [PATCH] docs: add Spanish, Japanese, and Chinese README translations
 and update language switchers

---
 README.es.md | 165 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.id.md |   2 +-
 README.ja.md | 165 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md    |   2 +-
 README.zh.md | 165 +++++++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 497 insertions(+), 2 deletions(-)
 create mode 100644 README.es.md
 create mode 100644 README.ja.md
 create mode 100644 README.zh.md

diff --git a/README.es.md b/README.es.md
new file mode 100644
index 0000000..024becf
--- /dev/null
+++ b/README.es.md
@@ -0,0 +1,165 @@
+# 🎙️ 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.
diff --git a/README.id.md b/README.id.md
index 82d8dd2..d140d75 100644
--- a/README.id.md
+++ b/README.id.md
@@ -1,6 +1,6 @@
 # 🎙️ ONNX VC - Standalone Real-Time Voice Changer
 
-🌐 **Bahasa:** [English](README.md) | [Bahasa Indonesia](README.id.md)
+🌐 **Bahasa:** [English](README.md) | [Bahasa Indonesia](README.id.md) | [Español](README.es.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)
 
 Sistem konversi suara AI real-time berkinerja tinggi dan latensi rendah yang ditenagai oleh **ONNX Runtime** dan **Retrieval-based Voice Conversion (RVC)**. Dilengkapi dengan dashboard premium yang dibuat menggunakan **Next.js App Router**, **TypeScript**, dan **Tailwind CSS**, serta mendukung internasionalisasi penuh.
 
diff --git a/README.ja.md b/README.ja.md
new file mode 100644
index 0000000..11199ac
--- /dev/null
+++ b/README.ja.md
@@ -0,0 +1,165 @@
+# 🎙️ 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**と**Retrieval-based Voice Conversion (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パイプライン:**
+  * **ローカットフィルター:** ACハム音や低周波ノイズを除去する80Hzのアクティブ1次バターワースハイパスフィルター。
+  * **ノイズゲート:** 無音時のインフェレンスをスキップ（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) — Pythonの仮想環境を自動的に解決し、サーバーを実行するWindowsランチャーバッチファイル。
+* [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. **畳み込みパディングフェードアウト:** RVCの畳み込みステップに固有のエッジフェード異常を回避するために、120msの末尾の無音パディングが入力セグメントに一時的に追加されます。
+3. **線形リサンプリング:** 素早いサンプリングレート適応のための低オーバーヘッドの線形補間。
diff --git a/README.md b/README.md
index 6254213..826701d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # 🎙️ ONNX VC - Standalone Real-Time Voice Changer
 
-🌐 **Languages:** [English](README.md) | [Bahasa Indonesia](README.id.md)
+🌐 **Languages:** [English](README.md) | [Bahasa Indonesia](README.id.md) | [Español](README.es.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)
 
 A high-performance, low-latency, real-time AI voice conversion system powered by **ONNX Runtime** and **Retrieval-based Voice Conversion (RVC)**. Features a premium dashboard built with **Next.js App Router**, **TypeScript**, and **Tailwind CSS**, supporting full internationalization.
 
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..1b9c473
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,165 @@
+# 🎙️ 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. **线性重采样:** 低开销的线性插值，可快速适应采样率。