# DeepFilterNet3 WAV ノイズ抑制ツール

WAV 音声に [DeepFilterNet3](https://github.com/Rikorose/DeepFilterNet) を適用し、背景ノイズを抑制するコマンドラインツールです。

入力音声は DeepFilterNet3 の処理サンプリング周波数（通常 48 kHz）へ自動変換されます。処理後は、既定では入力と同じサンプリング周波数の PCM16 WAV として保存されます。

## 開発環境の構築

### 必要なもの

- NVIDIA GPU
- CUDA 12.8 に対応する NVIDIA ドライバー
- Python 3.11（64-bit）
- `pip`
- SoundFile（WAV の読み書きに使用）
- モデルと Python パッケージを取得するためのインターネット接続

このスクリプトは DeepFilterNet 0.5.6、PyTorch 2.11.0、TorchAudio 2.11.0、CUDA 12.8 の組み合わせを基準にしています。DeepFilterNet は利用可能な CUDA デバイスを自動的に選択します。

### Windows環境（PowerShell）

NVIDIA ドライバーをインストールし、PowerShellでGPUが認識されていることを確認します。

```powershell
nvidia-smi
```

Python 3.11をインストールしてから、プロジェクト用の仮想環境を作成します。

```powershell
cd D:\usr\prog\deepfilternet3_enhance
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
```

PowerShell の実行ポリシーにより仮想環境を有効化できない場合は、その PowerShell セッションに限って次を実行してから、もう一度有効化してください。

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
```

CUDA 12.8対応のPyTorchと、アプリケーションの依存パッケージをインストールします。

```powershell
python -m pip install torch==2.11.0 torchaudio==2.11.0 --index-url https://download.pytorch.org/whl/cu128
python -m pip install deepfilternet==0.5.6 soundfile
```

### Linux環境

NVIDIA ドライバーをインストールし、GPUが認識されていることを確認します。

```bash
nvidia-smi
```

Python 3.11と仮想環境機能を導入します。Ubuntu／Debian系では、次のようにインストールできます。

```bash
sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip
```

使用しているディストリビューションにPython 3.11のパッケージがない場合は、そのディストリビューションの手順に従ってPython 3.11を導入してください。

プロジェクト用の仮想環境を作成します。

```bash
cd /path/to/deepfilternet3_enhance
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

CUDA 12.8対応のPyTorchと、アプリケーションの依存パッケージをインストールします。

```bash
python -m pip install torch==2.11.0 torchaudio==2.11.0 --index-url https://download.pytorch.org/whl/cu128
python -m pip install deepfilternet==0.5.6 soundfile
```

### CUDAの動作確認

Windows、Linuxともに、仮想環境を有効にした状態で次を実行します。

```powershell
python -c "import torch; print('PyTorch:', torch.__version__); print('CUDA runtime:', torch.version.cuda); print('CUDA available:', torch.cuda.is_available()); print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'not available')"
```

正常に認識されている場合は、`CUDA available: True` と GPU 名が表示されます。DeepFilterNet 0.5.6 は利用可能な CUDA デバイスを自動的に選択するため、このツールに GPU 用オプションを指定する必要はありません。実行ログにも `Running on device cuda` と表示されます。

## 実行方法

基本構文は次のとおりです。

```text
python deepfilternet3_enhance.py INPUT_WAV OUTPUT_WAV [オプション]
```

例：

```powershell
python deepfilternet3_enhance.py sample1a305s.wav enhanced.wav
```

出力先の親ディレクトリが存在しない場合は自動的に作成されます。利用可能な引数は `--help` でも確認できます。

```powershell
python deepfilternet3_enhance.py --help
```

### コマンドオプション

| 引数 | 必須 | 説明 |
| --- | --- | --- |
| `INPUT_WAV` | はい | 入力 WAV ファイル。拡張子は `.wav` である必要があります。 |
| `OUTPUT_WAV` | はい | 出力 WAV ファイル。拡張子は `.wav` である必要があります。 |
| `--post-filter` | いいえ | ポストフィルタを有効にし、ノイズ抑制をやや強くします。 |
| `--atten-lim-db DB` | いいえ | 最大抑制量を dB で制限します。`0` より大きい値を指定してください。未指定時は制限しません。 |
| `--mono` | いいえ | ステレオなどの多チャンネル入力を、チャンネル平均によりモノラル化してから処理します。 |
| `--model-rate-output` | いいえ | 入力の周波数へ戻さず、モデルのサンプリング周波数（通常 48 kHz）で出力します。 |
| `-h`, `--help` | いいえ | ヘルプを表示して終了します。 |

### 実行例

ポストフィルタを有効にして、抑制を強める場合：

```powershell
python deepfilternet3_enhance.py input.wav output_pf.wav --post-filter
```

最大抑制量を 12 dB に制限し、音声の変質を抑えたい場合：

```powershell
python deepfilternet3_enhance.py input.wav output_lim12.wav --atten-lim-db 12
```

ステレオ入力をモノラル化する場合：

```powershell
python deepfilternet3_enhance.py input.wav output_mono.wav --mono
```

モデルのサンプリング周波数で保存する場合：

```powershell
python deepfilternet3_enhance.py input.wav output_48k.wav --model-rate-output
```

オプションは組み合わせて指定できます。

```powershell
python deepfilternet3_enhance.py input.wav output.wav --post-filter --atten-lim-db 18 --mono
```

## 実行結果の表示

実行中は、入力チャンネル数、サンプリング周波数、音声の長さ、処理時間などが表示されます。

- `Real-time factor` は「処理時間 ÷ 音声時間」です。`1` 未満なら、音声の再生時間より短い時間で処理できたことを示します。
- `処理後ピーク値` が `1.0` を超えた場合は、PCM16 の範囲に収めるためにクリッピングされ、警告が標準エラー出力へ表示されます。
- 正常終了時の終了コードは `0`、エラー発生時は `1` です。

## 使用上の注意

- 初回実行時は DeepFilterNet3 の学習済みモデルが取得されることがあり、インターネット接続と保存領域が必要です。2 回目以降は通常、キャッシュされたモデルが使用されます。
- 対応する入出力形式は WAV のみです。MP3、M4A、FLAC などは、事前に WAV へ変換してください。
- 既定の出力形式は PCM16 です。入力が 24-bit PCM や浮動小数点 WAV でも、そのビット深度は維持されません。
- WAV の読み書きには SoundFile を使用します。DeepFilterNet 0.5.6 が内部で参照する旧 TorchAudio 音声 I/O API は使用しません。
- 既定では、処理後の音声を入力 WAV のサンプリング周波数へ戻します。余分な再変換を避けたい場合は `--model-rate-output` を指定してください。
- `--post-filter` はノイズを強く抑えられる一方、声の質感や残響も変化しやすくなります。結果を試聴して利用を判断してください。
- `--atten-lim-db` の値を小さくすると抑制が控えめになり、原音の変質を抑えやすくなります。ただし、背景ノイズは多く残ります。
- `--mono` を指定しない場合、入力のチャンネル数は維持されます。モノラル化するとステレオ定位の情報は失われます。
- 長い音声や多チャンネル音声は、処理時間とメモリ使用量が増えます。元ファイルを残し、まず短い区間で設定を確認することを推奨します。
- 出力先に既存ファイルを指定すると上書きされる可能性があるため、重要なファイルとは別のパスを指定してください。
- ノイズの種類や録音状態によっては、声の欠落、金属的な音、残留ノイズなどが発生します。本番利用前に必ず出力を試聴してください。

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

### `ModuleNotFoundError: No module named 'df'`

仮想環境を有効にし、DeepFilterNet をインストールしてください。

```powershell
.\.venv\Scripts\Activate.ps1
python -m pip install deepfilternet==0.5.6 soundfile
```

### `ModuleNotFoundError: No module named 'torchaudio.backend'`

DeepFilterNet 0.5.6 と新しい TorchAudio の組み合わせで発生する互換性エラーです。このスクリプトは旧 API の import に対する互換処理を内蔵し、実際の WAV 入出力には SoundFile を使用します。最新版のスクリプトを使用し、SoundFile が未導入の場合はインストールしてください。

```powershell
python -m pip install soundfile
```

### 入力ファイルが見つからない

現在のディレクトリとファイル名を確認するか、引用符付きの絶対パスを指定してください。

```powershell
python deepfilternet3_enhance.py "D:\audio files\input.wav" "D:\audio files\output.wav"
```

### 処理が遅い、またはメモリ不足になる

まず短い WAV で動作を確認してください。必要に応じて音声を複数ファイルへ分割して処理します。分割する場合は、つなぎ目で音が不自然にならないよう、前後に余裕を持たせてください。

### `CUDA available: False` と表示される

次の点を順番に確認してください。

- `nvidia-smi` で NVIDIA GPU とドライバーが認識されているか
- CUDA 対応版の PyTorch をインストールした仮想環境が有効になっているか
- `python -m pip show torch` が、意図した仮想環境のパッケージを示しているか
- `torch.version.cuda` が `None` になっていないか。`None` の場合はCUDA対応ビルドがインストールされていません。
- NVIDIA ドライバーが、選択した PyTorch CUDA ビルドに対応しているか

CUDA対応ビルドが入っていない場合は、前述のWindowsまたはLinuxのセットアップ手順に従って `torch` と `torchaudio` を入れ直してください。