Spaces:
Sleeping
Sleeping
| # 🎵 音源分離 & 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 の差が小さくなることがあります。 | |