inital commit

1 files changed, 106 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..057caa8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+# 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.
+
+```bash
+./producer episode.wav
+# -> episode_master.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.
+
+## 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.
+
+`--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. |
+| `--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.
+
+## 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]
+    [--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 `<output>.report.json`
+with before/after RMS, true peak, LUFS, noise floor, and per-stage timings.
+
+Persistent settings go in `config.toml` in the repository root (auto-created on
+first run; CLI flags always win). Example:
+
+```toml
+profile = "audiobook"
+
+[denoise]
+engine = "dfn3"
+strength = 1.0
+
+[audiobook]
+air = 0.4
+deess = 0.8
+```
+
+## 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.
+
+## 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).