# Producer

Local speech cleanup and mastering for voice recordings. Noise removal uses `DeepFilterNet3`. Filtering, dynamics and loudness normalization are `FFmpeg`.

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

## Requirements

- glibc
- `uv` (or Python 3)
- NVidia driver and toolkit (optional)

## Usage

```bash
git clone https://git.historia.vg/git/producer
./producer.sh setup
./producer.sh process recording.wav
```

First run installs the runtime into `lib/runtime/` and may take a few minutes.

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**. A diagnostic report for each run
is written to a `logs/` directory next to the outputs, not beside the audio.

### Examples

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

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

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

All of these settings are configurable; run `./producer.sh config` to see every
setting and its default, or `--help` on any command for the flags. A fully
documented 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 |

Test the difference on your own audio before committing:

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

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

## License

[0BSD](LICENSE).

Upstream components (DeepFilterNet, PyTorch, FFmpeg, uv)
carry their own licenses