128 lines
5.8 KiB
Markdown
128 lines
5.8 KiB
Markdown
# 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).
|