# 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]
[x] Isolate voice (reduce background noise)     strength: 80%
Output MP3: [ .../kage_voicegrab.mp3            ] [Browse…]
──────────────────────────────────────────────────
[ Export MP3 ]
```

## Features
- Works with any container ffmpeg understands: mp4, mkv, mov, webm, avi, flv, m4a…
- **Isolate voice** checkbox: STFT-based noise reduction (runs on CPU, no
  downloads, no GPU). Strength slider + a "stationary noise" mode for
  constant fans/hum.
- 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.
- Also a headless CLI (see below) for scripting/batch work.

## Requirements
- Python 3.10+
- ffmpeg on your PATH (bundled automatically in installer builds)

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

## CLI mode
```bash
voicegrab.py --cli input.mp4 10 35 output.mp3
```

## 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.)

## 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.

## Notes on voice-isolation quality
The built-in reducer is classic DSP (spectral gating / STFT noise
estimation) — great for fan, hum, light room tone. For music or heavy
background speech, a deep-learning model (e.g. Demucs / UVR) gives
better separation but costs ~1–2 GB of downloads and runs far slower
without a GPU. For voice *training* samples, the DSP route is usually
more than enough, and it keeps the installer small and startup instant.