# Producer

Local speech cleanup and mastering for voice recordings. Noise removal uses
ClearVoice or DeepFilterNet3; speech-aware pause silencing uses Silero VAD.
Filtering, dynamics and loudness normalization use FFmpeg. Audio stays local.

`producer.sh` bootstraps its own managed Python environments and downloads
dependencies and models automatically.

## Requirements

- glibc >= 2.28 for AI denoising and speech detection
- `uv` (or Python 3)
- NVidia driver and toolkit (optional)

## Usage

```bash
git clone https://git.historia.vg/git/producer
./producer.sh setup --denoiser clearvoice
./producer.sh recording.wav
```

First run installs the runtime into `lib/runtime/` and may take a few minutes.
The `process` keyword is optional; `./producer.sh process recording.wav` is
equivalent.

The master WAV is always **mono, 32-bit PCM**, at 48 kHz (default) or 44.1
kHz; stereo inputs must be downmixed to mono first. MP3 is encoded as
constant bitrate at 192 kb/s by default. Loudness is normalized to **-19
LUFS with a -1.5 dBTP true-peak ceiling**.

### Examples
```
# Optional MP3 alongside the WAV
./producer.sh recording.wav --mp3

# Other sound profiles
./producer.sh recording.wav --profile narrator
./producer.sh recording.wav --profile radio

# Settings that differ from the built-in profile are named 'custom'
./producer.sh recording.wav --no-denoise   # recording.custom.wav

# Process several files at once
./producer.sh take1.wav take2.wav --mp3

# Write outputs somewhere else
./producer.sh recording.wav --output-dir delivery --mp3

# Skip AI noise removal (FFT fallback or none at all)
./producer.sh recording.wav --denoiser fft
./producer.sh recording.wav --no-denoise

# Compare ClearVoice MossFormer2_SE_48K with DeepFilterNet3
# (larger download; speech preservation depends on the recording)
./producer.sh recording.wav --denoiser clearvoice
./producer.sh setup --denoiser clearvoice --device cpu

# Silence pauses without changing the timing (enabled in config.toml)
./producer.sh recording.wav --pause-silence --no-trim-silence

# Bypass pause silencing for an A/B comparison
./producer.sh recording.wav --no-pause-silence --output-dir comparison

# Optionally shorten long gaps between takes (a separate pacing edit)
./producer.sh recording.wav --trim-silence --max-gap-s 1.5 --gap-pad-s 0.6

# LibriVox-style delivery file: 44.1 kHz, 128 kbps CBR, -19 LUFS, mono
./producer.sh recording.wav \
  --sample-rate 44100 --mp3 --mp3-bitrate 128 \
  --target-lufs -19 --true-peak-db -1.5
```

Edit default settings in `config.toml`

## Optional local browser GUI

```bash
./producer.sh gui
# Optional alternate loopback port:
./producer.sh gui --port 8766
```

Opens a local web page where you pick a WAV, tune settings, render an A/B
comparison, and export. The server binds only to loopback (127.0.0.1); stop
it with Ctrl-C.

## Profiles

| Profile        | Sound                                                     |
| -------------- | --------------------------------------------------------- |
| `natural`      | Mild EQ, 2:1 compression, light de-essing (default)       |
| `narrator`     | Gentler compression, slower attack, wider loudness range  |
| `radio`        | Stronger compression, more warmth/presence, tighter range |
| `cleanup-only` | Denoise + highpass only; no EQ, dynamics or normalization |

## Speech starts and silent pauses

Pause silencing detects speech on the **pre-denoise** audio with pinned Silero
VAD v5.1 ONNX weights (a ~2.3 MB CPU-only download on first use). After
EQ/dynamics, gaps outside protected speech fade to zero before loudness
normalization, leaving the timeline unchanged unless you enable
`--trim-silence`. Defaults protect 120 ms before and after detections, use
10 ms fades, and require an 80 ms silent core; shorter gaps are left alone.
Enable it in `config.toml` (`pause_silence = true`) or with `--pause-silence`.

- `--pause-threshold 0.35`: lower = preserve more possible speech.
- `--pause-pre-ms` / `--pause-post-ms`: padding around detected speech.
- `--pause-min-ms` / `--pause-fade-ms`: silent core and fade lengths.
- `--no-pause-silence`: bypass this stage; combine with `--no-denoise` to
  avoid all AI model/runtime downloads.

The detector can miss whispers, breaths, or unusual speech; if it detects
**no speech**, cleanup fails open with a warning instead of muting the file.
Denoising and pause silencing are different jobs: this stage does not restore
consonants a denoiser has already removed. Audition the result before
committing:

```bash
./producer.sh preview recording.wav --start 10 --duration 30
```

Reports in the `logs/` directory next to `producer.sh` include the attenuated
intervals for inspection.

## Troubleshooting

- **Bootstrap fails:** the first run needs `uv` or Python 3 with venv support
  and network access to PyPI. Install the missing tool and rerun.
- **CUDA unavailable:** run `./producer.sh doctor`, check `nvidia-smi` and the
  driver, then retry `./producer.sh setup --device cuda`. Or use `--device cpu`.
- **Sounds watery or thin:** lower the denoise strength (`--denoise-strength
  0.65`) or compare profiles with `preview`.
- **Word attacks sound soft or ramp up:** AI denoisers can soften consonant
  onsets. Try `--denoiser clearvoice` (larger non-causal model that sees more
  attack context), lower `--denoise-strength`, or compare against
  `--no-denoise` to locate the culprit.

## License

[0BSD](LICENSE).

Upstream components (ClearVoice, DeepFilterNet, Silero VAD, ONNX Runtime,
PyTorch, FFmpeg, uv) carry their own licenses. Silero VAD is MIT-licensed:
https://github.com/snakers4/silero-vad/tree/v5.1