From 13e15d78830ad61211d2cadb7d3a4dca8a29ab5c Mon Sep 17 00:00:00 2001 From: historia Date: Sun, 6 Sep 2026 15:51:10 -0400 Subject: readme --- README.md | 104 ++++++++++++-------------------------------------------------- 1 file changed, 19 insertions(+), 85 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 2a4f544..d3c5b6b 100644 --- a/README.md +++ b/README.md @@ -1,111 +1,45 @@ # producer -One-click narration and podcast mastering. Give it a raw recording; it denoises, -enhances, applies a warm "audiobook narrator" voice chain, and delivers a -loudness-normalized master. +One-click audio file mastering. Give it a raw recording; it denoises, enhances, applies a warm voice chain, and delivers a loudness-normalized master. -```bash -./producer episode.wav -# -> episode_processed.wav (44.1 kHz mono, RMS -20 dB, true peak <= -3 dB) -``` - -Everything a user doesn't need to touch lives in `lib/`: the first run -bootstraps its own CPython 3.11 environment (via [uv](https://docs.astral.sh/uv/)) -into `lib/.venv` and installs pinned dependencies. No system packages, no -manual venv, no configuration required. -`./producer doctor` checks the environment at any time. +```bash ./producer .wav ``` ## The sound -The default `audiobook` profile targets the classic close-narration master: -high-pass at 80 Hz, a gentle mud cut, low-shelf warmth, serial compression -(2:1 then 3:1), de-essing, restrained presence/air, breath ducking, then -normalization to RMS -20 dB with a -3 dB true-peak ceiling. +The default `audiobook` profile targets a close-narration master: high-pass at 80 Hz, a gentle mud cut, low-shelf warmth, serial compression (2:1 then 3:1), de-essing, restrained presence/air, breath ducking, then normalization to RMS -20 dB with a -3 dB true-peak ceiling. -`--profile podcast` switches to broadcast loudness: -16 LUFS integrated, --1.5 dBTP ceiling, 48 kHz, slightly brighter EQ. `--profile radio` targets the -deep, warm broadcast voice: +3 dB low shelf at 100 Hz, a tighter mud cut, heavy -serial compression, dynamic resonance control (`soothe`) that ducks boxy -200-450 Hz and harsh 2.5-6 kHz peaks only while they stick out, and asymmetric -tape saturation (`tape`) for the even-harmonic analog sheen. +`--profile podcast` switches to broadcast loudness: -16 LUFS integrated, -1.5 dBTP ceiling, 48 kHz, slightly brighter EQ. `--profile radio` targets the deep, warm broadcast voice: +3 dB low shelf at 100 Hz, a tighter mud cut, heavy serial compression, dynamic resonance control (`soothe`) that ducks boxy 200-450 Hz and harsh 2.5-6 kHz peaks only while they stick out, and asymmetric tape saturation (`tape`) for the even-harmonic analog sheen. ## Engines -Every AI stage is swappable; the trade-offs are explicit: - -| Stage | Choices | Notes | -|---|---|---| -| `--denoise` | `dfn3` (default), `zipenhancer`, `off` | [DeepFilterNet3](https://github.com/Rikorose/DeepFilterNet): 48 kHz full-band, faithful, fast on CPU, CUDA optional. [ZipEnhancer](https://github.com/gyj1201/zipEnhancer) (ICASSP 2025 SOTA, PESQ 3.69): 16 kHz native, bandwidth is restored after, slightly softer highs. | +| Stage | Choices | Notes | +| ----------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--denoise` | `dfn3` (default), `zipenhancer`, `off` | [DeepFilterNet3](https://github.com/Rikorose/DeepFilterNet): 48 kHz full-band, faithful, fast on CPU, CUDA optional. [ZipEnhancer](https://github.com/gyj1201/zipEnhancer) (ICASSP 2025 SOTA, PESQ 3.69): 16 kHz native, bandwidth is restored after, slightly softer highs. | | `--enhance` | `off` (default), `mossformer2`, `resemble` | [MossFormer2_SE_48K](https://github.com/modelscope/ClearerVoice-Studio) (ClearVoice): full-band studio restoration, GPU-strong. [Resemble Enhance](https://github.com/resemble-ai/resemble-enhance): generative restoration for badly damaged audio, runs in an isolated venv; can alter voice timbre, so it is opt-in. | -Engine dependencies (torch ~2.5 GB on CUDA, model weights ~8 MB) are installed -lazily on first use into `lib/` (`lib/models`, `lib/venvs`). Prefer -`--denoise off` for pure-DSP masters with zero heavy downloads. +Engine dependencies (torch ~2.5 GB on CUDA, model weights ~8 MB) are installed lazily on first use into `lib/` (`lib/models`, `lib/venvs`). Prefer `--denoise off` for pure-DSP masters with zero heavy downloads. ## Usage ```bash -./producer in.wav [-o out.wav] [--profile audiobook|podcast|radio] - [--denoise dfn3|zipenhancer|off] [--denoise-strength 0-1] - [--enhance off|mossformer2|resemble] [--enhance-strength 0-1] - [--no-dsp] [--no-levelling] - [--hpf-hz N] [--mud N] [--warmth N] [--soothe N] [--compress N] - [--tape N] [--deess N] - [--presence N] [--air N] [--breath N] # 0-1 strength each - [--target N] [--ceiling N] # loudness target / TP ceiling (dB) - [--format wav|flac|mp3] [--sample-rate N] [--bit-depth 16|24|32] + ./producer in.wav [-o out.wav] [--profile audiobook|podcast|radio] + [--denoise dfn3|zipenhancer|off] [--denoise-strength 0-1] [--enhance off|mossformer2|resemble] + [--enhance-strength 0-1] [--no-dsp] [--no-levelling] [--hpf-hz N] [--mud N] [--warmth N] + [--soothe N] [--compress N] [--tape N] [--deess N] [--presence N] [--air N] [--breath N] + [--target N] [--ceiling N] [--format wav|flac|mp3] [--sample-rateN] [--bit-depth 16|24|32] [--device auto|cuda|cpu] [--batch] [--report] [--dry-run] [-v] -./producer doctor ``` -Batch: `./producer --batch takes/ -o masters/` expands a directory (or glob) -and processes each file. Reports: `--report` writes `.report.json` -with before/after RMS, true peak, LUFS, noise floor, and per-stage timings. - -Without `-o`, outputs are written next to the input as -`_processed.`. If the output path already exists, producer -prompts to overwrite, rename (auto-numbered `..._1`, `..._2`, ...), or cancel; -non-interactive runs (no terminal on stdin) auto-rename and say so. - -Persistent settings go in `config.toml` in the repository root (auto-created on -first run; CLI flags always win). Example: - -```toml -profile = "audiobook" +Batch: `./producer --batch takes/ -o masters/` expands a directory (or glob) and processes each file. Reports: `--report` writes `.report.json` with before/after RMS, true peak, LUFS, noise floor, and per-stage timings. -[denoise] -engine = "dfn3" -strength = 1.0 - -[audiobook] -air = 0.4 -deess = 0.8 -``` +Persistent settings go in `config.toml` ## Requirements -- Linux (glibc: Arch, Debian, Fedora...), macOS, or Windows/WSL -- `curl` (bootstraps uv; removed afterwards is fine) -- `ffmpeg` on PATH for MP3 output and non-soundfile inputs (WAV/FLAC/OGG - work without it) -- NVIDIA GPU optional; everything falls back to CPU - -## Development - -```bash -./producer doctor # environment check -lib/.venv/bin/python -m pytest lib/tests -lib/.venv/bin/python -m pytest lib/tests -m slow # engine integration (needs deps) -lib/.venv/bin/ruff check lib/src lib/tests -``` - -Engine wrappers are exercised against real models by the `slow` tests -(`PRODUCER_TEST_RESEMBLE=1` additionally opts into the isolated generative -venv). Unit tests for meters, DSP, loudness, pipeline, CLI, and I/O run -dependency-free. +- curl +- ffmpeg +- NVidia GPU (optional) ## License -MIT — see [LICENSE.md](LICENSE.md). Model weights keep their upstream licenses -(DeepFilterNet MIT/Apache-2.0, ClearVoice Apache-2.0, Resemble Enhance MIT, -ZipEnhancer MIT). +0BSD -- cgit v1.2.3