# 🎵 音源分離 & L/Rパンニング アプリ セットアップガイド

## 概要

このアプリは音楽/動画ファイルから AI（Demucs）を使って **主旋律（メインボーカル）** と **ハモリ（コーラス）** を分離し、左右のイヤホンで聴き分けられるステレオ WAV を出力します。

```
左チャンネル (L) ───── 主旋律 (メインボーカル)
右チャンネル (R) ───── ハモリ / コーラス
センター (L+R) ──────── 伴奏（音量縮小）
```

---

## ① ffmpeg のインストール（OS別）

ffmpeg はシステムにインストールされている必要があります。

### Windows

```powershell
# winget を使う方法（推奨）
winget install Gyan.FFmpeg

# または Chocolatey を使う方法
choco install ffmpeg

# インストール確認
ffmpeg -version
```

> **手動インストールの場合:**
> 1. https://ffmpeg.org/download.html → Windows → `ffmpeg-release-full.7z` をダウンロード
> 2. 解凍して `C:\ffmpeg\bin` を システムの環境変数 `PATH` に追加

### macOS

```bash
# Homebrew を使う方法（推奨）
brew install ffmpeg

# インストール確認
ffmpeg -version
```

### Linux (Ubuntu / Debian)

```bash
sudo apt update && sudo apt install -y ffmpeg

# インストール確認
ffmpeg -version
```

---

## ② Python 仮想環境のセットアップ

```bash
# プロジェクトディレクトリへ移動
cd c:\musicbot       # Windows
# cd /path/to/musicbot  # macOS / Linux

# 仮想環境を作成 (Python 3.10 以上推奨)
python -m venv venv

# 仮想環境を有効化
# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate
```

---

## ③ 依存ライブラリのインストール

### CPU 環境（GPU なし）の場合

```bash
pip install --upgrade pip

# PyTorch CPU 版を先にインストール（重要: GPU版と混在しないよう）
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu

# その他ライブラリをインストール
pip install -r requirements.txt
```

### GPU 環境（NVIDIA CUDA）の場合（オプション・高速化）

```bash
pip install --upgrade pip

# CUDA 12.1 対応の場合（自分の CUDA バージョンに合わせて変更）
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121

# その他ライブラリをインストール
pip install -r requirements.txt
```

> GPU があると Demucs の処理が **数倍〜10倍** 速くなります。

---

## ④ アプリの実行

### 基本的な使い方

```bash
# 音声ファイル (mp3/wav) を処理
python app.py input.mp3

# 動画ファイル (mp4/mov) を処理（音声が自動抽出されます）
python app.py input.mp4

# 出力ファイル名を指定
python app.py input.mp3 --output my_output.wav

# 伴奏をミュートしたい場合
python app.py input.mp3 --inst-vol 0.0

# 伴奏を少し大きくしたい場合
python app.py input.mp3 --inst-vol 0.3

# モデルを指定する場合（デフォルトは htdemucs_6s）
python app.py input.mp3 --model htdemucs
```

### コマンドライン引数一覧

| 引数 | 説明 | デフォルト |
|---|---|---|
| `input` | 入力ファイルパス（必須） | — |
| `--output` | 出力 WAV ファイル名 | `output_panned.wav` |
| `--inst-vol` | 伴奏音量（0.0〜1.0） | `0.15` |
| `--model` | Demucs モデル名 | `htdemucs_6s` |

### 使用可能なモデル

| モデル名 | ステム数 | 特徴 |
|---|---|---|
| `htdemucs_6s` | 6 (vocals/drums/bass/guitar/piano/other) | **推奨**。vocals と other(コーラス)を独立分離 |
| `htdemucs` | 4 (vocals/drums/bass/other) | 軽量版。ハモリはLR差分で推定 |
| `mdx_extra` | 4 | MDX アーキテクチャ。ボーカル品質重視 |

---

## ⑤ 初回実行について

初回実行時は **Demucs のモデルファイルが自動ダウンロード** されます（数百MB）。
キャッシュは `~/.cache/torch/hub/` に保存されるため、次回以降は高速です。

---

## ⑥ トラブルシューティング

### `ffmpeg not found` エラーが出る

→ ①の手順で ffmpeg をインストールし、`ffmpeg -version` が動くことを確認してください。

### `torch` のインポートエラー

→ 仮想環境が有効化されているか確認 (`venv\Scripts\activate`)。
→ `pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu` を再実行。

### メモリ不足 (OOM) エラー

```bash
# CPU モードを明示的に指定
python app.py input.mp3 --model htdemucs
```
CPU の場合 htdemucs は約 **4〜8GB RAM** を使用します。

### 処理が遅い

Demucs は計算量が多く、CPU 環境では数分かかります。
GPU (CUDA) 環境では大幅に高速化されます。

---

## ⑦ 出力ファイルの確認

処理完了後、`output_panned.wav` が生成されます。
ステレオ対応のヘッドフォン/イヤホンで再生すると：

- **左耳** → 主旋律（メインボーカル）が聴こえる
- **右耳** → ハモリ / コーラスが聴こえる

> 元の音源にハモリ録音がない場合や、モノラル録音の場合は  
> LR の差が小さくなることがあります。