onnx-voice-changer/docs/README.ja.md

# 🎙️ 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. **線形リサンプリング:** 素早いサンプリングレート適応のための低オーバーヘッドの線形補間。

---

## 🤝 クレジットと謝辞
* **[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 License 2.0 の下でライセンスされています。詳細は [LICENSE](file:///M:/Users/ahmad/project/onnx-voice-changer/LICENSE) ファイルを参照してください。