# VoiceGrab

Cut a time range out of any video file and export a clean, loudness-normalized
**MP3 voice sample** — ready to use for AI voice training / cloning.

```
Voice / audio file: [ kage.mp4                    ] [Open…]
Start: 0:10.00   Stop: 0:35.00   [Load preview] [▶ Play range]
Voice processing (choose one):
  (•) Fast noise reduction (CPU) — fan / hum / room tone; no downloads
  ( ) AI voice separation (Demucs) — music & second speakers; GPU if available
  ( ) No processing — just loudness-normalize
  strength: 80%   [x] stationary noise
Output MP3: [ .../kage_voicegrab.mp3            ] [Browse…]
──────────────────────────────────────────────────
[ Cancel ] [ Export MP3 ]
```

## Features
- Works with any container ffmpeg understands: mp4, mkv, mov, webm, avi, flv, m4a…
- **Voice processing — pick one mode** (toggle, mutually exclusive):
  - **Fast noise reduction (CPU, default)** — STFT spectral gating via
    `noisereduce`. Great for fan, hum, room tone. No downloads, no GPU;
    strength slider + a "stationary noise" mode for constant fans/hum.
  - **AI voice separation (Demucs)** — deep-learning 4-stem separation
    (we keep the *vocals* stem). Handles background music and a second
    speaker, which spectral gating cannot. Optional install; uses an
    NVIDIA GPU (CUDA) or Apple GPU if present, otherwise CPU (slower).
  - **No processing** — just loudness-normalize.
- Export is **320 kbps MP3**, loudness-normalized to −16 LUFS (broadcast
  reference — good levels for voice-training datasets).
- "▶ Play range" lets you audition the exact segment before saving.
- AI runs report chunk progress in the status bar and can be **cancelled**
  between chunks.
- Also a headless CLI (see below) for scripting/batch work.

## Requirements
- Python 3.10+
- ffmpeg on your PATH (bundled automatically in installer builds)
- Optional, only for AI voice separation: `pip install -r requirements-ai.txt`
  (pulls `torch` + `demucs`, ~1.5–2.5 GB with CUDA wheels)

## Run from source
```bash
cd voicegrab2
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python voicegrab.py
```

## AI voice separation (optional — GPU recommended)
```bash
.venv/bin/pip install -r requirements-ai.txt
```
- Pick **AI voice separation (Demucs)** in the GUI. The mode is disabled
  (with an explanation) until `torch` + `demucs` are installed — the core
  app never requires them.
- **First use downloads the `htdemucs_ft` model (~90 MB)** to the app data
  dir (`<appdata>/VoiceGrab/models/`) and caches it — later runs are
  instant. GPU (NVIDIA CUDA / Apple) is used automatically when present,
  otherwise CPU.
- Performance expectations (5 s → 60 s clip):
  - GPU (≥ 6 GB VRAM): ~1–3 s → ~15–40 s
  - CPU (8 cores): ~10–25 s → a few minutes
- **Cancel** stops an AI run at the next chunk boundary. Fast DSP runs
  finish in seconds and are not cancellable (by design).
- Quality note: aggressive separation can thin sibilance/breath — for voice
  *training* samples the fast DSP mode is usually enough; reach for AI mode
  when there's music or a competing speaker.
- Licensing: Demucs code is MIT and the `htdemucs_ft` weights are MIT
  (see `THIRD_PARTY.md`).

## CLI mode
```bash
voicegrab.py --cli input.mp4 10 35 output.mp3              # default: fast DSP
voicegrab.py --cli input.mp4 10 35 output.mp3 --mode dsp   # fast noise reduction
voicegrab.py --cli input.mp4 10 35 output.mp3 --mode ai    # Demucs (requirements-ai.txt)
voicegrab.py --cli input.mp4 10 35 output.mp3 --mode none  # just loudness-normalize
```

## Tests
```bash
.venv/bin/python tests/test_separators.py   # or: .venv/bin/pytest tests/
```
Covers: DSP shape/dtype/NaN invariants, AI graceful degradation without
torch, device selection, AI unit separation (44.1 kHz output), and the full
CLI pipeline in all three modes (valid 320 kbps MP3, duration 5.0 s ± 0.15 s).

## Windows installer (single .exe + installer)
1. `pip install pyinstaller`
2. `python voicegrab.py.spec` is not needed — run:
   ```bat
   pyinstaller --onefile --windowed --name VoiceGrab ^
       --add-binary "C:\ffmpeg\bin\ffmpeg.exe;." ^
       --add-binary "C:\ffmpeg\bin\ffprobe.exe;." ^
       --icon assets/icon.ico voicegrab.py
   ```
3. Build the installer with Inno Setup:
   ```bat
   "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" installer\VoiceGrab.iss
   ```
   (Copy `dist\VoiceGrab.exe` to `installer\` first — the script assumes
   `dist\VoiceGrab.exe` relative to the project root.)

   To ship the AI mode inside the frozen exe (bigger, ~2 GB), install
   `requirements-ai.txt` into the venv first and add
   `--collect-all demucs --collect-all torch` to the PyInstaller command.

## Linux
- **AppImage**: `installer/build_linux.sh` (needs PyInstaller +
  `linuxdeploy` or `appimagetool` + your ffmpeg in PATH).
- **Debian/Ubuntu**: just run the PyInstaller binary, or install ffmpeg via
  apt and run from source. A `.desktop` entry template is in `installer/`.
- **Flatpak** is also a fine route if you want it in your store.
- AI mode: `WITH_AI=1 ./installer/build_linux.sh` bundles `demucs`/`torch`
  into the binary (bigger build).

## Notes on voice-isolation quality
- **Fast mode** is classic DSP (spectral gating / STFT noise estimation) —
  great for fan, hum, light room tone; it can't remove music or a second
  speaker.
- **AI mode** (Demucs `htdemucs_ft`) is a source separator — the right tool
  for speech-over-music or competing voices. It's a product feature behind a
  radio button, never a hard dependency: the core app stays small and starts
  in < 2 s without `torch`/`demucs` installed.
- The AI path *replaces* the DSP path — one or the other, never stacked
  (double-processing adds artifacts).