# Producer

Local speech cleanup and mastering for voice recordings, driven by a single
script: `producer.sh`. Noise removal uses DeepFilterNet3; filtering, dynamics
and loudness normalization are FFmpeg. Everything runs on your machine;
`producer.sh` bootstraps its own managed Python environments and downloads
dependencies and models automatically.

## Quick Start

```bash
./producer.sh process recording.wav
```

First run installs the runtime into `lib/runtime/` and may take a few minutes.
After that, runs are fast and work offline.

Requirements: glibc Linux with `bash`. An existing `uv`, or Python 3 with venv
support, plus network access for the first bootstrap. For GPU acceleration
(`--device cuda`) you need a working NVIDIA driver and toolkit; check
`nvidia-smi` first, then run `./producer.sh setup --device cuda`. Use `--device
cpu` for CPU-only processing (the default `auto` picks GPU when available).

## Everyday Use

```bash
# Master with the default (natural) profile; outputs appear next to the input:
#   recording.natural.wav, recording.natural.report.json
./producer.sh process recording.wav

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

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

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

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

# Stereo input requires an explicit channel choice (output is always mono)
./producer.sh process stereo.wav --channel left    # or right, or mix

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

# Measure a recording without processing it
./producer.sh analyze recording.wav > analysis.json
```

Outputs are written beside each input by default: `<stem>.<profile>.wav` plus
`<stem>.<profile>.report.json`, and `<stem>.<profile>.mp3` with `--mp3`.
Existing outputs cause an error unless you pass `--overwrite`.

## Output Format

The master WAV is always **mono, 32-bit PCM**, at 48 kHz (default) or 44.1
kHz:

```bash
./producer.sh process recording.wav --sample-rate 44100
```

MP3 is encoded as constant bitrate at 192 kb/s by default. For example, a
LibriVox-style delivery file (44.1 kHz, 128 kbps CBR, -19 LUFS, mono):

```bash
./producer.sh process recording.wav \
  --sample-rate 44100 --mp3 --mp3-bitrate 128 \
  --target-lufs -19 --true-peak-db -1.5
```

Loudness is normalized to **-19 LUFS with a -1.5 dBTP true-peak ceiling**
(two-pass, then verified on both the WAV and the decoded MP3). All of these
are configurable; run `./producer.sh config` to see every setting and its
default, or `--help` on any command for the flags. A fully commented example
config lives at `lib/project/examples/voice.toml`.

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

Hear the difference on your own audio before committing:

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

Previews are loudness-matched renders of a short clip for each profile.

## Reports

Each run writes a JSON report next to the WAV with measurements, applied
settings and warnings. Check the `warnings` field before publishing: the tool
verifies its own output (loudness target, true peak, format), but misses over
0.5 LU or MP3 true-peak overshoots are reported rather than silently fixed.

## 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`.
- **Model download fails:** check network access and free disk space; never
  bypass the checksum.
- **Sounds watery or thin:** lower the denoise strength (`--denoise-strength
  0.65`) or compare profiles with `preview`.

Add `--rebuild` to any command to rebuild the runtime after editing the source
in `lib/project/`.

## License

[0BSD](LICENSE). Upstream components (DeepFilterNet, PyTorch, FFmpeg, uv)
carry their own licenses; review them before redistributing.