micforge 1.3.0__tar.gz → 1.3.1__tar.gz

{micforge-1.3.0/src/micforge.egg-info → micforge-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: micforge
-Version: 1.3.0
+Version: 1.3.1
 Summary: Real-time microphone clean-up for Discord and voice chat: de-muffle, denoise, level, route.
 Author: Parth Sadaria
 License-Expression: MIT
@@ -44,10 +44,10 @@ Dynamic: license-file
 
 # Micforge
 
-[![Version](https://img.shields.io/badge/version-1.3.0-0284c7.svg)](verison%20notes/v1.3.0.md)
+[![Version](https://img.shields.io/badge/version-1.3.1-0284c7.svg)](verison%20notes/v1.3.1.md)
 [![License: MIT](https://img.shields.io/badge/license-MIT-slate.svg)](LICENSE)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-emerald.svg)](https://www.python.org/)
-[![Tests](https://img.shields.io/badge/tests-128%2F128%20passing-teal.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-139%2F139%20passing-teal.svg)](tests/)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-neutral.svg)]()
 
 > **Real-time, local-first microphone clean-up for Discord, gaming, and streaming.**  
@@ -65,6 +65,10 @@ It pairs an **11-stage modular audio processing rack** with an ultra-lightweight
 
 ### What makes it different?
 - **Ultra-lean footprint:** Consumes only **~70–85 MB of RAM** and **<5–8% CPU** on a single core during gaming. Zero cloud calls, zero telemetry, 100% offline.
+- **Dedicated Process GIL Isolation (v1.3.1):** Moves real-time audio and DSP into an isolated OS process via shared memory and high-priority queues, shielding the audio thread from UI rendering spikes.
+- **Single Shared STFT Rack (v1.3.1):** Unifies AEC, neural denoising, and dereverberation into one frequency-domain pass on a 512-point grid, slashing redundant FFTs and minimizing latency to ~1.1 ms compute time.
+- **Voice-Targeted Naturalness (v1.3.1):** In-domain frequency mixing (`naturalness: 0.08`) modulates dry blend strictly on voiced speech harmonics, banishing underwater phase artifacts while achieving **58.8 dB suppression** on loud stationary hiss and pressure cookers.
+- **Free Neural Mask VAD (v1.3.1):** Derives high-resolution speech probability directly from CoFi-Lite's neural mask ($300-4,000\text{ Hz}$) with hysteresis smoothing to drive gating without chattering.
 - **Continuous Adaptive Noise Profiling (v1.3.0):** Voice-aware background noise learner that adapts to spinning fans and AC drift without ever learning on speech. Includes environment profiles (`quiet_room`, `fan_on`, `mechanical_keyboard`).
 - **Hot-Plug & Auto-Recovery (v1.3.0):** Seamless reconnects with exponential backoff on USB disconnects, with safe bypass fallback so you are never left silently muted.
 - **End-to-End Latency Benchmark (v1.3.0):** Measures actual loopback roundtrip latency and itemizes hardware vs. DSP delays with actionable guidance (`micforge latency`).
@@ -98,6 +102,42 @@ Microphone Input ─┼─▶ High-Pass Filter (Rumble removal, 90 Hz default)
 
 ---
 
+## Real-Time Audio Proof & Side-by-Side Comparison
+
+Don't just take our word for it—listen and visually compare how a real budget microphone recording is transformed in real time through the Micforge DSP rack:
+
+| 🔈 Raw Microphone (Default / Unprocessed) | 🎧 Micforge Enhanced (Live 11-Stage Rack) |
+|:---:|:---:|
+| **[▶️ Click to Listen: Raw Audio (`docs/audio/1_raw.wav`)](docs/audio/1_raw.wav)** | **[▶️ Click to Listen: Processed Audio (`docs/audio/1_processed.wav`)](docs/audio/1_processed.wav)** |
+| [![Raw Spectrogram](docs/images/spectrogram_raw.png)](docs/audio/1_raw.wav) | [![Processed Spectrogram](docs/images/spectrogram_processed.png)](docs/audio/1_processed.wav) |
+| **❌ Loud background noise & hiss**<br>Constant pressure cooker steam & fan drone audible between words ($-35.3\text{ dBFS}$) | **✅ Pure digital black in pauses**<br>Noise floor dropped by **$+38.7\text{ dB}$** ($-74.0\text{ dBFS}$)—zero audible hiss or background hum |
+| **❌ Hollow "empty bathroom" flutter**<br>Untreated hard-wall reflections ring around the speech | **✅ Studio-dry vocal acoustics**<br>Late room reverberation flutter cleanly stripped out |
+| **❌ Thin, tinny, weak headset tone**<br>Sounds like a cheap laptop or budget gaming headset mic | **✅ Warm broadcast radio presence**<br>Rich $120\text{ Hz}$ vocal chest resonance (SM7B/RE20 proximity effect) |
+| **❌ Volume jumps & harsh spikes**<br>Quiet whispers get lost, loud talking clips into distortion | **✅ Consistent, broadcast-leveled volume**<br>Smooth RMS leveling with a hard $-1.5\text{ dBFS}$ peak limiter (zero clipping) |
+
+<br>
+
+<details>
+<summary><b>🔍 Click to view Full Stacked Waveform & High-Resolution Spectrogram Analysis</b></summary>
+<br>
+
+![Full Stacked Comparison](docs/images/spectrogram_comparison.png)
+
+</details>
+
+### 📊 Objective Quality & Latency Benchmark
+| Benchmark Metric | Raw Input (`1_raw.wav`) | Micforge Output (`1_processed.wav`) | Delta / Improvement |
+|:---|:---:|:---:|:---:|
+| **Inter-Word Silence Pause Noise Floor** | -35.29 dBFS | **-73.96 dBFS** | **+38.67 dB quieter** (digital black) |
+| **Broadband Steam / Cooker Hiss** | -30.00 dBFS | **-89.24 dBFS** | **+58.79 dB suppression** |
+| **DNSMOS Overall Quality (OVRL)** | 1.75 | **1.99** | **+0.24 MOS points** |
+| **DNSMOS Speech Quality (SIG)** | 1.00 | **1.45** | **+0.45 MOS points** |
+| **STFT Refactor Null-Test (SI-SDR)**| — | **149.11 dB (CoFi-Lite)** | Bit-exact mathematical null (>40 dB target) |
+| **Per-Block DSP Execution Time** | — | **~1.12 ms** ($N=160$ @ 16 kHz) | Real-time budget headroom > 85% |
+| **Audio-Thread Heap Allocations** | — | **0 allocations** | Zero garbage-collection jitter |
+
+---
+
 ## Realistic Expectations
 
 Let's be engineer-honest:
@@ -264,6 +304,7 @@ micforge/
 ├── src/micforge/
 │   ├── audio/
 │   │   ├── engine.py            # Stream lifecycle, phase centering, cushion re-arming
+│   │   ├── isolated_engine.py   # Dedicated process isolation, shared memory & watchdog
 │   │   ├── loopback.py          # WASAPI loopback speaker capture for AEC
 │   │   ├── cues.py              # Procedural sine-sweep feedback chimes
 │   │   ├── devices.py           # Device discovery & virtual-cable detection
@@ -281,13 +322,15 @@ micforge/
 │   │   ├── doctor.py            # Audio driver diagnostics & zip export
 │   │   └── files.py             # Offline WAV processing
 │   ├── dsp/
+│   │   ├── chain.py             # 11-stage processing rack & per-stage p50/p99 timing
+│   │   ├── spectral_rack.py     # Single unified STFT rack (AEC + Denoise + Deverb)
 │   │   ├── aec.py               # Acoustic Echo Cancellation (PBFDAF + DTD)
 │   │   ├── deverb.py            # Room Dereverberation (Spectral decay envelope)
 │   │   ├── proximity.py         # Voice Proximity (F0 chest resonance & warmth)
-│   │   ├── cofilite.py          # CoFi-Lite neural speech enhancement
+│   │   ├── cofilite.py          # CoFi-Lite neural speech enhancement & mask VAD
 │   │   ├── denoise.py           # Classical Spectral Wiener fallback
 │   │   ├── biquad.py            # Pure NumPy Second-Order Sections (SOS) engine
-│   │   ├── gate.py              # Soft downward expander / noise gate
+│   │   ├── gate.py              # Soft downward expander driven by neural mask VAD
 │   │   ├── compressor.py        # Fast feed-forward compressor & peak limiter
 │   │   ├── deesser.py           # Split-band de-esser
 │   │   └── leveler.py           # Slow RMS speech leveler
@@ -301,17 +344,21 @@ micforge/
 │   ├── presets.py               # Preset CRUD, validation & built-in definitions
 │   └── cli.py                   # Command-line entry point
 ├── docs/
+│   ├── audio/                   # Real-time raw vs. processed WAV samples
+│   ├── images/                  # High-resolution spectrogram and waveform analyses
 │   └── TROUBLESHOOTING.md       # Centralized diagnostic & OS troubleshooting guide
 ├── scripts/
+│   ├── generate_spectrogram_assets.py # Automated waveform & spectrogram generator
 │   ├── compare_two.py           # Dual-file comparison, metrics & A/B listening
 │   └── compare_audio.py         # Automated WAV processing evaluation
-├── tests/                       # 125 automated tests (mocked PortAudio backend)
+├── tests/                       # 139 automated tests (mocked PortAudio backend)
 ├── verison notes/
 │   ├── v1.1.0.md
 │   ├── v1.1.1.md
 │   ├── v1.2.0.md                # AEC, De-Verb, Proximity, Gamer HUD
 │   ├── v1.2.1.md                # RAM reduction (~85 MB) & clock drift fixes
-│   └── v1.3.0.md                # Adaptive profiles, hot-plug recovery, diagnostics & latency
+│   ├── v1.3.0.md                # Adaptive profiles, hot-plug recovery, diagnostics & latency
+│   └── v1.3.1.md                # Shared STFT rack, process GIL isolation, mask VAD, voice naturalness
 ├── pyproject.toml
 └── README.md
 ```