phonepod 0.1.0b1__tar.gz

phonepod-0.1.0b1/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:pypi.org)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:arxiv.org)",
+      "WebFetch(domain:dpdfnet.readthedocs.io)",
+      "WebFetch(domain:www.gradio.app)"
+    ]
+  }
+}

phonepod-0.1.0b1/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+.bench-venv/
+
+# macOS
+.DS_Store
+
+# Model checkpoints
+checkpoints/
+
+# Audio files (generated)
+benchmark_outputs/
+*.wav
+ab_*.wav
+
+# Keep demo audio
+!demo/before.wav
+!demo/after.wav
+
+# Personal test recordings
+recording.m4a
+
+# Generated reports
+audit_report.html
+
+# Test/research artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+research/
+
+# uv
+uv.lock

phonepod-0.1.0b1/.impeccable.md

@@ -0,0 +1,30 @@
+## Design Context
+
+### Users
+Beginner content creators and non-technical people who record audio on their phones and want it to sound professional. They don't know what LUFS, EQ, or compression mean — and they shouldn't have to. They want to drag a file in, press one button, and get a good result. Ved uses it himself, but the audience is anyone who Googles "how to make my phone recording sound better."
+
+### Brand Personality
+**Fun. Competent. Fast.**
+
+phonepod is the friend at the dinner party who's genuinely good at what they do but doesn't take themselves seriously. It jokes, it moves quickly, it gets the job done without making you feel stupid. Think Duolingo's warmth meets Stripe's reliability — personality without sacrificing trust.
+
+### Aesthetic Direction
+- **Not minimalist.** Minimalism reads as boring and personality-less here. The UI needs character.
+- **Not cluttered.** One screen, one flow, zero cognitive load. The complexity lives in the pipeline, not the interface.
+- **Bold + playful utility.** Strong typography, confident color, maybe a wink of humor in microcopy. The kind of tool that makes you smile when you use it.
+- **Dark mode primary.** Fits the audio/creator context. Light mode is not a priority.
+- **References:** Duolingo (fun without being childish), Arc Browser (opinionated design), Raycast (fast + polished dark UI), Poolside FM (personality in a tool)
+- **Anti-references:** Audacity (cluttered, intimidating), Adobe Podcast (corporate intimidation), generic SaaS dashboards (soulless), anything that looks vibe-coded (gradient soup, glassmorphism for no reason), Notion/Linear minimalism (too quiet)
+
+### Color Direction
+- No default Gradio orange — it screams "I didn't customize this"
+- No pastel gradients or neon that suggests vibe-coded
+- Needs a bold, ownable accent color that has energy but isn't generic
+- Consider: electric/warm tones that feel alive — coral, amber, electric green, or a signature hue that becomes "the phonepod color"
+
+### Design Principles
+1. **One screen, one job.** The entire flow (upload, clean, tune, download) lives on a single page. No tabs, no navigation, no settings pages.
+2. **Personality over polish.** A witty loading message beats a perfect spinner. Microcopy should make people smile — "Drop your trash audio here" > "Upload Audio File."
+3. **Confidence through constraint.** Fewer controls = more trust. The user should feel like the tool knows what it's doing. Expert knobs exist but stay out of the way.
+4. **Speed is a feature.** Every interaction should feel instant or show honest, engaging progress. No mystery spinners.
+5. **Never intimidate.** No jargon in the UI. No waveform editors. No dB labels visible by default. If a beginner would hesitate, simplify.

phonepod-0.1.0b1/.uv-cache/.gitignore

@@ -0,0 +1 @@
+*

phonepod-0.1.0b1/.uv-cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

phonepod-0.1.0b1/CLAUDE.md

@@ -0,0 +1,42 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Agent Identity & Core Directives
+
+You are a Senior Audio Systems Engineer and PyTorch specialist. You are building "Project Resonance," a local, privacy-first audio restoration pipeline.
+
+## Immutable Rules
+
+1. **Hardware Strictness:** The host machine is an Apple Silicon Mac (M-series). Route all PyTorch tensor operations to `mps`. Never default to `cuda`. If `mps` is unavailable, fallback to `cpu` but log a severe warning.
+2. **Context Modularity:** Do not write monolithic scripts. Adhere strictly to the separation of concerns defined in `docs/architecture.md`.
+3. **No UI Hallucinations:** This is a backend engine first. Do not generate frontend code (Gradio/FastAPI) until explicitly instructed in Phase 3.
+4. **Environment:** We strictly use `uv` for Python dependency management. Do not suggest `pip`, `conda`, or `poetry`.
+5. **No External APIs:** This is a 100% local, privacy-first pipeline. Never send audio to an external service.
+
+## Architecture (3-module pipeline)
+
+`engine.py` → `processor.py` → `app.py`
+
+- **engine.py** — Pure tensor-in, tensor-out wrapper around `resemble-enhance`. Takes 16kHz mono `torch.Tensor`, returns enhanced tensor. Zero file I/O. Uses `nfe=64`, `solver="midpoint"`, dual-stage pipeline (UNet Denoiser + CFM).
+- **processor.py** — Overlap-Add chunking manager. Loads `.wav` via `torchaudio`, slices into 10s chunks with 1s overlap, feeds each to `engine.py`, reconstructs with Hanning window crossfade. Handles all file I/O.
+- **app.py** — Gradio UI (Phase 3 only). Drag-and-drop → `processor.py` → A/B comparison player.
+
+The hard boundary: `engine.py` never touches the filesystem. `processor.py` never touches the model. `app.py` never touches tensors.
+
+## Commands
+
+```bash
+# First-time setup (installs all dependencies via uv)
+bash setup.sh
+
+# Run the test script (generates a 30s sine wave and processes it)
+uv run python test_processor.py
+
+# Launch the Gradio UI (localhost:7860)
+uv run python app.py
+```
+
+## Execution Protocol
+
+Before writing any code, you MUST read `docs/architecture.md` to understand the system design, and `docs/tasks.md` to know exactly which phase you are currently executing.

phonepod-0.1.0b1/JOURNEY.md

@@ -0,0 +1,237 @@
+# Project Resonance — Build Journey
+
+> Local, privacy-first audio restoration pipeline. Phone recording in → podcast-quality audio out.
+
+## The Goal
+
+Record a voice memo on your phone, run one command, get podcast-quality output. No cloud. No subscriptions. No Adobe. Everything runs locally on Apple Silicon.
+
+## Phase 1: The Architecture (2026-03-30)
+
+Started with a clean 3-module architecture based on `resemble-enhance`, an open-source model from Resemble AI:
+
+```
+engine.py (AI model wrapper) → processor.py (OLA chunking) → cli.py (user interface)
+```
+
+**Key design decisions:**
+- `engine.py` handles zero file I/O — pure tensor-in, tensor-out
+- `processor.py` implements Overlap-Add with Hanning window crossfade to prevent audio clicking at chunk boundaries
+- Strict MPS-first device routing for Apple Silicon, CPU fallback with warning
+- `uv` for dependency management (not pip/conda)
+- Signal handlers + `atexit` for clean shutdown — model unloading, MPS cache flush, temp file cleanup
+
+**Expert review caught 4 issues before first run:**
+1. Wrong import path (`resemble_enhance.enhancer` vs `resemble_enhance.enhancer.inference`) — would have crashed on import
+2. MPS detection needed both `is_available()` AND `is_built()` — wrong PyTorch build would silently fall back to CPU
+3. torch version floor needed (`>=2.1.0`) to guarantee MPS support
+4. `lambd=0.9` was too aggressive — reviewer correctly identified it would degrade speech quality
+
+## Phase 2: First Run — The NumPy Wall (2026-03-30)
+
+**Problem:** `resemble-enhance` was written against NumPy 1.x. NumPy 2.0+ broke implicit scalar conversion.
+
+```
+Error: only 0-dimensional arrays can be converted to Python scalars
+```
+
+**Fix:** Pinned `numpy<2.0` (installed 1.26.4). Root cause: `resemble-enhance` hasn't been updated for NumPy 2.x breaking changes.
+
+## Phase 3: The MPS Disaster (2026-03-30)
+
+Ran the full pipeline. Output: **pure noise.**
+
+Built a diagnostic script (`diagnose.py`) to isolate the problem layer by layer:
+
+| Test | Result | Verdict |
+|---|---|---|
+| Denoise only (MPS) | Recognizable but degraded | Denoiser works on MPS |
+| Full enhance (CPU) | Louder but robotic | CFM enhancement adds artifacts even on CPU |
+| Full enhance (MPS) | Pure noise | **MPS completely breaks the CFM ODE solver** |
+
+**Root cause:** The Continuous Flow Matching stage runs 64 sequential ODE solver steps. MPS has float32 precision issues with iterative numerical solvers — errors compound across steps until the output is pure noise. This is a known class of issue with Apple's MPS backend.
+
+## Phase 4: The Parameter Sweep (2026-03-30)
+
+Refused to give up on `resemble-enhance`. Ran a 7-configuration parameter sweep on CPU, varying `nfe` (solver steps), `lambd` (denoise strength), and `tau` (temperature):
+
+| Config | nfe | lambd | tau | Time | Result |
+|---|---|---|---|---|---|
+| light_clean | 32 | 0.1 | 0.1 | 57s | Lightest touch |
+| medium_clean | 32 | 0.5 | 0.1 | 85s | Moderate |
+| heavy_denoise_low_temp | 32 | 0.9 | 0.1 | 87s | Heavy denoise |
+| original_settings | 64 | 0.5 | 0.5 | 98s | Previous default |
+| original_low_temp | 64 | 0.5 | 0.1 | 132s | Low randomness |
+| heavy_denoise_more_steps | 64 | 0.9 | 0.1 | 189s | Max denoise |
+| max_steps_low_temp | 128 | 0.5 | 0.1 | 277s | Maximum quality attempt |
+
+**Result:** All 7 configurations had a "tearing" effect at louder passages. Noise was reduced but the output was not podcast quality. The CFM generative model was over-processing the audio — it was **re-synthesizing** the voice rather than cleaning it up.
+
+## Phase 5: The Research Pivot (2026-03-30)
+
+Researched how **professional podcast audio engineers** actually process audio. Key finding:
+
+> Adobe Podcast "Enhance Speech" is ALSO a generative re-synthesizer. When it fails, it outputs English-sounding babble — proving it generates speech tokens, not just filters them.
+
+**The professional processing chain (in order):**
+1. Noise Gate/Reduction
+2. High-Pass Filter (80Hz — removes rumble)
+3. Subtractive EQ (cut mud at 200-400Hz)
+4. Compressor (3:1 ratio, serial compression preferred)
+5. De-Esser (tame sibilance at 4-10kHz)
+6. Additive EQ (presence at 2-4kHz, air at 8-12kHz)
+7. Loudness Normalization (-16 LUFS)
+8. Brick-Wall Limiter (-1.5dB ceiling)
+
+**Key insight:** We needed a **discriminative denoiser** (removes what shouldn't be there) followed by a **traditional DSP mastering chain** (shapes what's left). Not a generative model trying to re-imagine the audio.
+
+## Phase 6: The Hybrid Pipeline (2026-03-30)
+
+Rebuilt the engine with:
+- **DeepFilterNet3** (1M params, real-time on CPU) for noise suppression
+- **Spotify's Pedalboard** for the professional DSP mastering chain
+- **pyloudnorm** for LUFS loudness normalization
+
+First attempt used `resemble-enhance` denoiser + pedalboard. Result: still too noisy. The resemble-enhance denoiser wasn't aggressive enough.
+
+Swapped to DeepFilterNet3. Required monkey-patching `torchaudio.backend` (removed in torchaudio 2.9+, but DeepFilterNet still imports it).
+
+**Final pipeline:**
+```
+Input (.m4a/.wav/any format)
+  → ffmpeg convert to 48kHz mono WAV
+  → DeepFilterNet3 noise suppression (full file, real-time)
+  → High-Pass Filter (80Hz)
+  → Subtractive EQ (-3dB at 300Hz)
+  → Dual Compressor (2:1 then 3:1, serial)
+  → De-Esser (-4dB at 6kHz)
+  → Presence Boost (+2.5dB at 3kHz)
+  → Air Boost (+2dB at 10kHz)
+  → LUFS Normalization to -16 LUFS
+  → Brick-Wall Limiter (-1.5dB)
+Output (.wav)
+```
+
+**Result:** 75-80% there. Voice is clean, noise is gone, compression and EQ are working. Slightly too loud — needs LUFS target tuning.
+
+## Remaining Work
+
+- [ ] Tune LUFS target (try -18 or -19 instead of -16)
+- [ ] Integrate DeepFilterNet into `engine.py` properly (replace resemble-enhance denoiser)
+- [ ] Remove the torchaudio monkey-patch (create a proper compatibility layer)
+- [ ] Update `processor.py` — DeepFilterNet processes full files in real-time, OLA chunking may not be needed
+- [ ] Update `app.py` Gradio UI for the new pipeline
+- [ ] A/B test against Adobe Podcast Enhance on the same recording
+
+## Tech Stack (Final)
+
+| Component | Library | Purpose |
+|---|---|---|
+| Noise Suppression | DeepFilterNet3 | ML-based noise removal (1M params, real-time) |
+| DSP Mastering | Spotify Pedalboard | HPF, EQ, compression, de-essing, limiting |
+| Loudness | pyloudnorm | LUFS measurement and normalization |
+| Audio I/O | torchaudio + ffmpeg | Format conversion and file handling |
+| Package Manager | uv | Python dependency management |
+
+## What We Learned
+
+1. **Generative ≠ better.** For decent input audio, a discriminative denoiser + traditional DSP chain beats a generative re-synthesizer. The generative approach (resemble-enhance CFM) hallucinates artifacts on clean-ish audio.
+
+2. **MPS is not CUDA.** Apple's MPS backend has precision issues with iterative numerical solvers (ODE/SDE). Single forward-pass models work fine; 64-step flow matching does not.
+
+3. **The professional podcast chain is 8 specific steps in a specific order.** Order matters because audio processing is non-commutative. Compress-then-EQ ≠ EQ-then-compress.
+
+4. **DeepFilterNet3 (1M params) outperformed resemble-enhance denoiser (10M params)** for this use case. Purpose-built tools beat general-purpose tools.
+
+5. **The "tearing at loudness" was caused by the absence of a limiter and compressor** — the raw model output had no dynamic range control. Adding the professional mastering chain fixed it.
+
+## Phase 7: ClearVoice MossFormer2 (2026-03-31)
+
+**Problem:** v2 (DeepFilterNet + Pedalboard) had noise gone but lacked richness. v3 (DeepFilterNet + FlashSR + Pedalboard) introduced popping sounds from chunk boundary artifacts in FlashSR.
+
+**Discovery:** ClearerVoice-Studio (Alibaba, 4k stars) bundles MossFormer2_SE_48K — a discriminative speech enhancement model that processes at 48kHz natively. It handles enhancement + quality improvement in one pass, no chunking needed.
+
+**Dependency hell:** AudioSR pinned numpy==1.23.5 (won't build on Python 3.13). ClearVoice pinned librosa==0.10.2 and soundfile==0.12.1. Had to carefully resolve conflicts by removing competing pins.
+
+**v4 test (MossFormer2 only):** Quality improved but noise came back — MossFormer2 enhances but doesn't aggressively denoise. Needed both models.
+
+**v5 final pipeline (the breakthrough):**
+```
+DeepFilterNet3 (noise kill) → MossFormer2 (enhance) → Pedalboard (master) → LUFS (-18) → Limiter
+```
+
+**Result:** ~85% podcast quality. Noise eliminated, loudness correct, no artifacts, no popping. Entire 2-minute recording processes in ~15 seconds total (DeepFilterNet ~3s + MossFormer2 ~7s + DSP instant).
+
+**Remaining gap:** Studio mic character — proximity effect warmth (80-250Hz), harmonic saturation/richness, voice-specific EQ tuning. This is the "last mile" problem — the difference between clean audio and audio that sounds like it was recorded on a $500 condenser mic.
+
+## Phase 8: The Last Mile — Integration & Studio Character Experiments (2026-04-01)
+
+### Code Integration (v6)
+
+Integrated the v5 pipeline (previously a standalone test script) into the proper codebase:
+- **engine.py** — replaced FlashSR with MossFormer2_SE_48K via ClearVoice. LUFS target adjusted from -16 to -18. Uses ClearVoice file I/O mode (not tensor-to-tensor) because t2t mode OOMs on MPS for >60s audio — file I/O mode handles internal 4s sliding-window segmentation.
+- **processor.py** — removed OLA chunking entirely (115 → 55 lines). Both DeepFilterNet and MossFormer2 handle their own segmentation, so external chunking was redundant and caused artifacts.
+- **cli.py** — ffmpeg conversion target changed from 16kHz to 48kHz to match the pipeline's native sample rate.
+
+### FINALLY Research (Dead End)
+
+Investigated Samsung's FINALLY (NeurIPS 2024) via the inverse-ai/FINALLY-Speech-Enhancement repo:
+- **No pretrained weights available.** Training from scratch requires multi-GPU, LibriTTS-R + DAPS-clean datasets, and a 3-stage pipeline with known NaN stability issues.
+- **Voice identity risk.** Generative GAN approach can shift accents and change speaker voice in low-SNR regions. Dealbreaker for podcast use.
+- **MOS > ground truth (4.63 vs 4.56)** — model adds aesthetic coloration, not faithful restoration. Same fundamental problem as resemble-enhance CFM.
+- **One interesting idea:** learnable 16→48kHz upsampling (Upsample WaveUNet). Could be explored as a standalone module later.
+
+### Studio Mic Character Experiments (Ruled Out)
+
+Tested two DSP approaches to close the "studio mic character" gap:
+
+**A) Proximity effect + soft-clip saturation (tanh):** Symmetric waveshaping, odd harmonics only. Result: voice sounds "sleepy/meditative" — rounds off transients, removes speech energy. Good for ambient content, wrong for podcasts.
+
+**B) Proximity effect + tube simulation (asymmetric waveshaping):** Even + odd harmonics, models vacuum tube nonlinearity. Result: adds warmth/body at subtle settings, but even conservative parameters (drive=1.5, bias=0.15) sounded like added coloration rather than natural quality improvement. At higher settings, sounds like a cheap old wired mic.
+
+**Key finding: MossFormer2 already does its own spectral enhancement.** Layering proximity + saturation on top of an already-enhanced signal adds coloration to coloration. The clean v6 pipeline (no studio character) consistently sounded best in A/B testing. The "last 15%" gap may be smaller than estimated, or it requires a fundamentally different approach (learned upsampling, voice-specific fine-tuning) rather than DSP post-processing.
+
+**v6 is the final pipeline:**
+```
+Input (.m4a/.wav/any) → ffmpeg 48kHz mono → DeepFilterNet3 (denoise) → MossFormer2 (enhance) → Pedalboard DSP (HPF/EQ/compress/de-ess/presence/air) → LUFS -18 → Limiter -1.5dB → Output
+```
+
+Processing time: ~14s for 2 minutes of audio on Apple M4.
+
+## Version History
+
+| Version | Pipeline | Result |
+|---------|----------|--------|
+| v1 | resemble-enhance (full CFM, MPS) | Pure noise |
+| v1b | resemble-enhance (full CFM, CPU) | Robotic, artifacts |
+| sweep | 7 parameter configs on CPU | All had tearing |
+| v2 | resemble-enhance denoise + Pedalboard | 75-80%, noise still present |
+| v3 | DeepFilterNet + FlashSR + Pedalboard | Popping at chunk boundaries |
+| v4 | MossFormer2 + Pedalboard | Good but noise returned |
+| v5 | DeepFilterNet + MossFormer2 + Pedalboard | ~85%, noise gone, standalone script |
+| v6 | v5 integrated into engine.py + processor.py | Production-ready, ~85-90% |
+| v6+sat | v6 + proximity + saturation (softclip/tube) | Ruled out — coloration, not improvement |
+
+## What We Learned (Updated)
+
+1. **Generative ≠ better.** For decent input audio, discriminative models beat generative re-synthesizers.
+
+2. **MPS is not CUDA.** Iterative ODE solvers produce noise on Apple MPS. Single-pass models (DeepFilterNet, MossFormer2) work fine.
+
+3. **Order matters.** The professional podcast chain is 8 steps in a specific order. Signal chain is non-commutative: saturation→compression ≠ compression→saturation.
+
+4. **Purpose-built > general-purpose.** DeepFilterNet (1M params) outperformed resemble-enhance denoiser (10M params).
+
+5. **No limiter = tearing.** Raw model output needs dynamic range control.
+
+6. **Chunking creates artifacts.** Processing full files in one pass is better than OLA chunking when the model supports it.
+
+7. **Two specialized models > one generalist.** DeepFilterNet (noise only) + MossFormer2 (enhance only) outperformed either alone.
+
+8. **Dependency pinning is the real enemy.** More time fighting dependency conflicts than writing code.
+
+9. **Don't layer enhancement on enhancement.** MossFormer2 already does spectral shaping. Adding DSP saturation/proximity on top of it adds coloration, not quality. The clean pipeline is the best pipeline.
+
+10. **Generative models are a voice identity risk.** FINALLY (Samsung, NeurIPS 2024) achieves MOS scores above ground truth but can shift accents and change speaker voice. For content where voice identity matters, discriminative models are safer.
+
+11. **ClearVoice tensor-to-tensor mode OOMs on long audio.** File I/O mode handles internal segmentation (4s sliding windows). Always use file I/O for production; t2t only for short clips.

phonepod-0.1.0b1/MANIFEST.md

@@ -0,0 +1,69 @@
+# Manifest
+
+## Package (phonepod/)
+- `phonepod/__init__.py` — Public API: enhance(), Engine, process_audio, shutdown_engine
+- `phonepod/_compat.py` — Torchaudio backend compatibility shim
+- `phonepod/engine.py` — 5-stage pipeline: DeepFilterNet → MossFormer2 → Pedalboard → LUFS → Limiter. Subtractive EQ philosophy (cuts only, no boosts). _apply_ceiling fix for peak clipping.
+- `phonepod/processor.py` — Audio loader, mono conversion, engine passthrough, file save
+- `phonepod/cli.py` — CLI interface with ffmpeg format conversion
+- `phonepod/app.py` — Gradio web UI with A/B comparison player
+
+## Legacy (flat files, superseded by phonepod/)
+- `engine.py` — Old engine (now in phonepod/engine.py)
+- `processor.py` — Old processor (now in phonepod/processor.py)
+- `cli.py` — Old CLI (now in phonepod/cli.py)
+- `app.py` — Old app (now in phonepod/app.py)
+- `JOURNEY.md` — Full build log from idea to working pipeline (Phases 1-8)
+- `CLAUDE.md` — Agent identity, architecture rules, execution protocol
+- `docs/architecture.md` — System architecture and module definitions
+- `docs/tasks.md` — Execution roadmap and phase status
+- `docs/references.md` — 30+ models/repos/papers evaluated
+- `docs/knowledge-base.md` — Model evaluations, API reference, parameter guide
+- `setup.sh` — First-time setup script (uv dependencies)
+- `recording.m4a` — Test input (voice memo)
+- `podcast_v6_final.wav` — Current best output
+
+## Test Scripts
+- `test_full_pipeline.py` — Original v2 pipeline test (DeepFilterNet + Pedalboard, no MossFormer2)
+- `test_deepfilter.py` — DeepFilterNet isolation test
+- `test_studio_character.py` — A/B/C test: none vs softclip vs tube saturation
+- `test_tube_sweep.py` — Parameter sweep for tube saturation (6 configs)
+- `test_processor.py` — Original processor test (sine wave)
+- `diagnose.py` — Layer-by-layer diagnostic (MPS vs CPU, denoise vs enhance)
+- `sweep.py` — resemble-enhance 7-config parameter sweep
+- `test_broadcast_ab.py` — A/B test: subtractive EQ (hybrid) vs additive EQ chain comparison
+
+## Benchmark Scripts
+- `benchmark_denoisers.py` — DPDFNet vs DeepFilterNet3 isolated comparison
+- `benchmark_clearvoice_numpy.py` — ClearVoice file I/O vs numpy mode comparison
+- `benchmark_pipeline.py` — Full pipeline A/B: DeepFilterNet3 vs DPDFNet-2 48kHz
+
+## Tuner UI
+- `tuner_minimal.py` — Voice tuner Gradio app with custom PhonepodTheme, semantic sliders, preset save/load
+- `.impeccable.md` — Design context: users, brand personality, aesthetic direction, design principles
+- `phonepod/profile.py` — MasteringParams dataclass, Profile save/load, params_from_semantic(). Subtractive EQ: mud/box/nasal cuts replace presence/air boosts.
+
+## Planning & Documentation
+- `TODOS.md` — Full task list: Sprints 1-5, dependency graph, research findings
+- `docs/system-architecture.html` — Visual system architecture (open in browser)
+- `docs/benchmarks.md` — Benchmark results and decision record (Sprint 1)
+
+## New Files (2026-04-04)
+- `phonepod/audit.py` - Pipeline audit tool: generates HTML report with per-stage spectrograms, metrics, pass/fail
+- `diagnose_muffled.py` - Diagnostic script: isolates each pipeline stage into separate WAV files
+
+## Recent Changes
+- 2026-04-04: RESOLVED muffled audio blocker - root cause was mastering chain crushing dynamics (LUFS overshooting -18 by 3.6dB, crest halved). Fixed with iterative LUFS normalization, gentler compression defaults
+- 2026-04-04: Added noise gate (Pedalboard NoiseGate, -50dB threshold) - silences artifacts between speech
+- 2026-04-04: Added studio room reverb (Pedalboard Reverb, 3% wet default) - subtle early reflections
+- 2026-04-04: Added Room slider to tuner UI + signal health metrics display
+- 2026-04-04: Fixed LUFS convergence bug in enhance() found by Codex audit - was comparing against mutable target instead of original
+- 2026-04-04: Softened noise gate from -40dB to -50dB, longer release (200ms) to preserve speech tails
+- 2026-04-04: Added input clamping to lerp() in params_from_semantic()
+- 2026-04-04: KEY FINDING - mastering DSP has minimal audible impact; ML models determine 95% of output character. Pipeline cleans well but cannot manufacture condenser mic qualities from phone recordings.
+- 2026-04-04: Switched to subtractive EQ philosophy (cuts only, no boosts). Fixed peak clipping bug (_apply_ceiling). Hybrid chain validated via A/B test.
+- 2026-04-03: Reskinned tuner UI - custom coral theme, Space Grotesk, fun microcopy, accordion layout, WCAG fixes
+- 2026-04-03: Created `.impeccable.md` - design context for all future UI work
+- 2026-04-01: Sprint 2 - restructured into `phonepod/` package, public API, pyproject.toml, 19 tests passing
+- 2026-04-01: Sprint 1 complete - benchmarked DPDFNet (rejected), switched ClearVoice to numpy mode (3.2x faster)
+- 2026-04-01: Product named `phonepod` - PyPI available, no trademark conflicts

phonepod-0.1.0b1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: phonepod
+Version: 0.1.0b1
+Summary: Local AI audio restoration. Phone recording → podcast quality.
+Project-URL: Homepage, https://github.com/vedantggwp/phonepod
+Project-URL: Issues, https://github.com/vedantggwp/phonepod/issues
+Author-email: Ved <vedant.g26@gmail.com>
+License-Expression: MIT
+Keywords: audio,denoising,podcast,restoration,speech-enhancement
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Requires-Dist: clearvoice>=0.1.2
+Requires-Dist: deepfilternet>=0.5.6
+Requires-Dist: numpy<2.0
+Requires-Dist: pedalboard>=0.9.22
+Requires-Dist: pyloudnorm>=0.2.0
+Requires-Dist: torch>=2.1.0
+Requires-Dist: torchaudio>=2.1.0
+Requires-Dist: torchcodec>=0.11.0
+Provides-Extra: ui
+Requires-Dist: gradio>=6.10.0; extra == 'ui'

phonepod-0.1.0b1/README.md

@@ -0,0 +1,111 @@
+# phonepod
+
+Local AI audio restoration. Phone recording → podcast quality.
+
+**Zero cloud. Zero uploads. Everything runs on your machine.**
+
+phonepod transforms noisy voice memos into broadcast-ready audio. It combines neural noise suppression (DeepFilterNet3 + MossFormer2) with a subtractive DSP mastering chain - all running locally on CPU. No cloud, no uploads, no subscription.
+
+> Status: `0.1.0-beta.1` - works well, API may change. Feedback welcome.
+
+## Before / After
+
+> Audio demos coming soon — record on your phone, run `phonepod`, hear the difference.
+
+<!-- TODO: Add audio player embeds once demo files are hosted -->
+
+## Install
+
+```bash
+pip install phonepod
+```
+
+Requires Python 3.11+ and ffmpeg (`brew install ffmpeg` on macOS).
+
+## Usage
+
+### CLI (simplest)
+
+```bash
+phonepod recording.m4a podcast.wav
+```
+
+### Python API
+
+```python
+import phonepod
+
+# One-liner: file in, file out
+phonepod.enhance("recording.m4a", "podcast.wav")
+
+# Advanced: tensor-level control
+engine = phonepod.Engine()
+enhanced_tensor, sample_rate = engine.enhance(audio_tensor, input_sr)
+```
+
+### Web UI
+
+```bash
+pip install phonepod[ui]
+python -m phonepod.app
+# Opens at http://localhost:7860
+```
+
+## What it does
+
+| Stage | Model / Tool | What it does |
+|-------|-------------|-------------|
+| 1 | DeepFilterNet3 | Neural noise suppression - removes background noise |
+| 2 | MossFormer2 (48kHz) | Speech enhancement - fills frequencies phones can't capture |
+| 3 | Pedalboard DSP | Subtractive mastering - gate, HPF, EQ cuts (mud/box/nasal), 2x compression, de-ess |
+| 4 | Pedalboard Reverb | Optional studio room ambience |
+| 5 | pyloudnorm | Loudness normalization to -18 LUFS (podcast standard) |
+| 6 | Limiter + ceiling | Prevents clipping at -1.5 dB ceiling |
+
+**Subtractive philosophy**: all EQ moves are cuts, not boosts. Remove mud (200Hz), boxiness (500Hz), nasal honk (1500Hz), and harshness (6500Hz). The ML models already shaped the frequency balance - cuts work with them, boosts fight them.
+
+Processing a 2-minute recording takes ~7 seconds on Apple Silicon.
+
+## How it started
+
+phonepod began as a personal problem: voice memos recorded on a phone sound terrible in a podcast. The AI models that exist are research demos, not products. Professional mastering chains exist but don't denoise. Nothing combines both into a single, local pipeline.
+
+So I built it. The full build story — from first prototype to production pipeline, every dead end and breakthrough — is in [JOURNEY.md](JOURNEY.md).
+
+## Architecture
+
+```
+Input (any format)
+  -> ffmpeg -> 48kHz mono WAV
+  -> Stage 1: DeepFilterNet3 (noise suppression)
+  -> Stage 2: MossFormer2_SE_48K (speech enhancement)
+  -> Stage 3: Pedalboard mastering (gate -> HPF -> mud/box/nasal cuts -> 2x compression -> de-ess)
+  -> Stage 4: Reverb (subtle room ambience, optional)
+  -> Stage 5: LUFS normalization (-18 LUFS)
+  -> Stage 6: Limiter + hard ceiling (-1.5 dB)
+Output: podcast-quality 48kHz WAV
+```
+
+Hard boundaries: the engine never touches the filesystem. The processor never touches the model. The CLI never touches tensors.
+
+## Development
+
+```bash
+# Clone and setup
+git clone https://github.com/vedantggwp/phonepod.git
+cd phonepod
+uv sync
+
+# Run tests (fast unit tests only)
+uv run pytest -m "not slow"
+
+# Run full test suite (loads ML models, ~30s)
+uv run pytest
+
+# Run on a file
+uv run phonepod recording.m4a output.wav
+```
+
+## License
+
+MIT