micforge 1.3.0__tar.gz

micforge-1.3.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Parth Sadaria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

micforge-1.3.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: micforge
+Version: 1.3.0
+Summary: Real-time microphone clean-up for Discord and voice chat: de-muffle, denoise, level, route.
+Author: Parth Sadaria
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Parthsadaria/MicForge
+Project-URL: Documentation, https://github.com/Parthsadaria/MicForge#readme
+Project-URL: Repository, https://github.com/Parthsadaria/MicForge.git
+Project-URL: Issues, https://github.com/Parthsadaria/MicForge/issues
+Project-URL: Changelog, https://github.com/Parthsadaria/MicForge/tree/main/verison%20notes
+Keywords: audio,microphone,dsp,noise-suppression,speech-enhancement,discord,cofilite,streaming
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: sounddevice>=0.4.6
+Requires-Dist: rich>=13.0
+Requires-Dist: onnxruntime>=1.16
+Requires-Dist: pystray>=0.19
+Requires-Dist: pillow>=9.0
+Requires-Dist: pynput>=1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: onnx>=1.14; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# Micforge
+
+[![Version](https://img.shields.io/badge/version-1.3.0-0284c7.svg)](verison%20notes/v1.3.0.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/)
+[![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.**  
+> Built and maintained by **[Parth Sadaria](https://github.com/Parthsadaria)**.
+
+---
+
+## What is Micforge?
+
+Most budget desk mics and gaming headsets sound thin, pick up room reflections (that hollow "talking in an empty bathroom" ring), bleed keyboard clatter, and capture speaker audio. 
+
+**Micforge** is an open-source, local real-time DSP engine designed to run silently on your machine and make your microphone sound clean, warm, and broadcast-ready before it reaches Discord, OBS, Zoom, or your game.
+
+It pairs an **11-stage modular audio processing rack** with an ultra-lightweight neural speech model based on **[CoFi-Lite](https://arxiv.org/abs/2607.10142)** (~83k parameters). 
+
+### 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.
+- **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`).
+- **Simple vs. Advanced Tuning UX (v1.3.0):** 4 intuitive macro knobs (Clarity, Warmth, Noise Removal, Room Cleanup) for casual streamers, plus deep parametric controls for engineers.
+- **Redacted Diagnostics (.zip):** One-click diagnostic bundle export with zero telemetry and automatic secret/path redaction (`micforge doctor --export`).
+- **Zero audio-thread heap allocations:** Critical DSP loops operate with pre-allocated scratch buffers to ensure zero clicks, pops, or garbage collection spikes.
+- **Acoustic Echo Cancellation (AEC):** Ingests game/speaker audio directly via native Windows WASAPI loopback without needing third-party cables, eliminating Discord voice echo.
+- **Room Dereverberation:** Strips out late room flutter and untreated wall reflections.
+- **Voice Proximity Effect:** Adds warm chest resonance (80–180 Hz) and even-order harmonics, giving cheap mics the presence of a broadcast dynamic mic.
+- **Esports Gamer HUD (`Tab`):** A minimalist terminal overlay designed for second monitors, featuring a Voice Activity Detector badge, mini-presence wave, and bold mute alert banner.
+
+```
+                  ┌────────────────────── 11-Stage Modular DSP Rack ─────────────────────┐
+                  │                                                                      │
+Microphone Input ─┼─▶ High-Pass Filter (Rumble removal, 90 Hz default)                   │
+                  │   └─▶ Acoustic Echo Cancellation (WASAPI speaker loopback reference) │
+                  │       └─▶ CoFi-Lite AI Denoiser (or classical Spectral Wiener)       │
+                  │           └─▶ Room Dereverberation (Late reflection tail decay)      │
+                  │               └─▶ Soft Noise Gate / Downward Expander                │
+                  │                   └─▶ Voice Proximity (Chest resonance & warmth)    │
+                  │                       └─▶ Parametric EQ (De-mud / Presence / Air)    │
+                  │                           └─▶ Split-Band De-Esser (Sibilance tame)   │
+                  │                               └─▶ Slow RMS Auto-Leveler              │
+                  │                                   └─▶ Fast Feed-Forward Compressor   │
+                  │                                       └─▶ Peak Limiter (-1.5 dBFS)   │
+                  └───────────────────────────────────┬──────────────────────────────────┘
+                                                      │
+                                                      ├──▶ Virtual Cable Output ──▶ Discord / OBS / Games
+                                                      └──▶ Headphone Monitor (with isolated audio cues)
+```
+
+---
+
+## Realistic Expectations
+
+Let's be engineer-honest:
+- **Micforge cleans up noise, room flutter, and tone balance.** It can remove fan drone, quiet loud keystrokes, cancel speaker bleed, and add chest warmth.
+- **It cannot fix bad physics.** If your microphone is 3 feet away near a mechanical keyboard, software can only do so much before your voice sounds watery. Keeping your mic 4–6 inches from your mouth will always do more than any plugin on earth.
+
+---
+
+## Quick Start
+
+### 1. Prerequisites
+- **Python 3.10** or higher
+- A virtual audio cable to route processed sound into Discord/games:
+  - **Windows:** [VB-CABLE Driver](https://vb-audio.com/Cable/) *(free, recommended)*
+  - **macOS:** [BlackHole 2ch](https://github.com/ExistentialAudio/BlackHole) (`brew install blackhole-2ch`)
+  - **Linux:** PulseAudio/PipeWire null sink (`pactl load-module module-null-sink sink_name=micforge`)
+
+### 2. Installation
+```bash
+git clone https://github.com/Parthsadaria/MicForge.git
+cd MicForge
+pip install -e .
+```
+*(Debian/Ubuntu: `sudo apt install libportaudio2` · macOS: `brew install portaudio`)*
+
+### 3. Setup & First Run
+```bash
+micforge doctor      # check audio drivers and environment
+micforge setup       # pick your real mic, virtual cable, and headphones
+micforge calibrate   # sample room silence for 3s to set gate threshold
+micforge run         # start the live interactive dashboard
+```
+
+> **Windows Tip:** In `micforge setup`, always select the **WASAPI** entries for your mic and `CABLE Input`. The legacy MME entries add 40+ ms of driver latency and drift.
+
+### 4. Application Configuration
+In Discord, OBS Studio, Steam, or Zoom:
+1. Set **Input Device** to `CABLE Output (VB-Audio Virtual Cable)`.
+2. Disable downstream **Noise Suppression** (e.g. Discord Krisp) and **Automatic Gain Control** to avoid double-processing artifacts.
+3. Keep Discord's **Echo Cancellation** disabled if you use headphones; leave it enabled if you play on open speakers.
+
+To run Micforge silently in the background:
+```bash
+micforge --tray
+```
+
+---
+
+## Live Monitoring & Gamer HUD
+
+Micforge includes two live view modes in the terminal (`micforge run`):
+
+### 1. Studio Inspector Mode (Full View)
+A comprehensive broadcast monitor displaying live input/output levels, sweet-spot meter, real-time reduction telemetry, dual FFT spectrum, and hardware diagnostics:
+
+```
+┌────────────────────────────── micforge v1.3.0 ──────────────────────────────┐
+│  MIC ENHANCER    ● PROCESSED   preset [gaming]                              │
+│ mic Microphone (Realtek Audio)  →  CABLE Input (VB-Audio)                   │
+│ Rack: HPF● AEC● AI● VERB● GATE· BODY● EQ● DEESS● LVL● COMP● LIM●            │
+│                                                                             │
+│ IN   ██████████████████████████················   -24.2 dB                  │
+│ OUT  ████████████████████████████████··········   -16.1 dB   [SWEET SPOT]   │
+│ REF  ··········································   silent (Clean/Headphones) │
+│                                                                             │
+│ ┌─ processing & dsp reductions ───────────────────────────────────────────┐ │
+│ │ noise   █████████████████████████  -24.5 dB                             │ │
+│ │ de-verb █████                       -3.2 dB                             │ │
+│ │ body    ████                        +2.5 dB                             │ │
+│ │ gate    OPEN                         0.0 dB                             │ │
+│ └─────────────────────────────────────────────────────────────────────────┘ │
+│                                                                             │
+│ latency   ~ 68 ms        noise floor  -64.2 dBFS   uptime   01h 14m         │
+│ dsp load  ███·····  18%  input gain   +0.0 dB      memory   85.4 MB         │
+│ glitches  0 (SYNCED)     clock fixes  0            profile  Active          │
+│                                                                             │
+│  Tab  HUD │  1-6  Preset │  x  Mute │  b  Bypass │  s  GUI │  ?  Help │  q    │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 2. Esports Gamer HUD (`Tab` Key)
+Press `Tab` to switch to an ultra-compact overlay designed for minimal distraction on a second monitor:
+- **Voice Activity Badge:** Instant state feedback (`[🎙️ VOICED SPEECH]`, `[👂 LISTENING]`, `[💤 IDLE NAP]`).
+- **Mini Vocal Waveform:** Live ASCII vocal presence and body resonance monitor.
+- **Double-Border Muted Warning:** A bold red alert panel appears when muted so you never accidentally talk on mute during matches.
+
+### In-Console Live Hotkeys
+| Key | Action | Key | Action |
+|:---:|:---|:---:|:---|
+| `Tab` | Toggle Studio Inspector ⟷ Gamer HUD | `1`–`6` | Direct preset jump (`discord`, `gaming`, `broadcast`, `studio`, `noisy_room`, `de_muffle`) |
+| `b` | A/B Bypass (hear raw mic vs processed) | `e` | Toggle Acoustic Echo Cancellation (AEC) |
+| `x` | Mute / unmute microphone | `w` | Cycle Voice Proximity warmth (Off → 35% → 55% → 75%) |
+| `s` | Open Native Multi-Tab Control Center GUI | `v` | Cycle Room De-Verb (Off → 30% → 50% → 70%) |
+| `+` / `-` | Denoise strength (±10%) | `c` | Recalibrate room noise (3s silence) |
+| `[` / `]` | Input gain (±1 dB) | `?` / `h` | Toggle hotkey cheatsheet overlay |
+| `q` | Clean quit | | |
+
+---
+
+## Native Multi-Tab Control Center (`micforge settings` or `s` key)
+
+For visual tuning without editing configuration files, Micforge features a sleek, dark native Control Center (`560x680`):
+
+1. **Tab 1: 🎛️ Presets & DSP Rack**
+   - Built-in vs Custom preset management (`[➕ New]`, `[💾 Save]`, `[🗑 Delete]`, `[📤 Export]`, `[📥 Import]`).
+   - Grouped into 3 clean logical cards:
+     - **Voice Character & Room:** Proximity intensity, warmth saturation, chest fundamental pitch (F0), anti-mud notch, and room decay (RT60).
+     - **Noise & Echo:** CoFi-Lite AI strength and AEC power.
+     - **Dynamics:** Gate threshold/range and Compressor ratio/makeup gain.
+2. **Tab 2: ⚡ Global Hotkeys & Audio Cues**
+   - Bind OS-wide hotkeys (Mute, Push-to-Talk, Push-to-Mute, Bypass) with one-click key recording.
+   - Adjust volume and test headphone feedback chimes.
+3. **Tab 3: 🎙️ Audio Hardware & Windows System**
+   - Select physical mic, virtual cable, and monitor headphones from dropdowns.
+   - Toggle Windows Boot Autostart and Minimize to System Tray.
+
+---
+
+## Custom Preset Engine (`micforge preset ...`)
+
+Save, duplicate, share, and backup custom vocal chains from the command line:
+
+```bash
+micforge preset list                         # view built-in & custom presets
+micforge preset save my_stream --from gaming # clone and customize
+micforge preset export my_stream preset.json # export to share with friends
+micforge preset import preset.json           # import community preset
+micforge preset show my_stream               # inspect all 11 stages
+micforge preset delete my_stream             # delete custom preset (built-ins protected)
+```
+
+---
+
+## Under the Hood: Engineering Highlights
+
+### 1. ~50% RAM Optimization (v1.2.1)
+Standard Python scientific audio tools easily pull in 150–200 MB of RAM because `scipy` imports massive compiled BLAS/LAPACK runtimes and optimization suites. 
+
+In v1.2.1:
+- Replaced `scipy.signal.sosfilt` with a vectorized pure NumPy Direct Form II Transposed biquad engine ($< 10^{-8}$ difference, 0 memory allocations).
+- Replaced SciPy FIR decimation/interpolation with NumPy sinc windowing and valid-mode convolution.
+- Disabled ONNX Runtime CPU memory arena (`enable_cpu_mem_arena = False`), preventing ONNX from hoarding 30–50 MB of idle heap caches.
+- **Result:** Live streaming process RAM dropped from **165.4 MB down to ~85 MB** with zero degradation in audio quality.
+
+### 2. Clock Drift Phase Centering & Anti-Glitch Architecture
+When Windows initializes two independent audio devices (USB microphone and virtual cable), they start asynchronously with an initial ~15–30 ms phase difference. 
+
+Earlier drift detectors misidentified this harmless startup offset as physical crystal clock drift, firing hundreds of false 1-sample corrections and pulling the ring buffer into starvation.
+- **Dynamic Phase Centering:** After the stream establishes a 60-block (~600 ms) steady state, Micforge calibrates its center point to the real hardware offset. Clock fixes stay at **0** during normal sessions.
+- **Guaranteed Cushion Re-Arming:** If a heavy background game causes an underrun, the buffer instantly re-arms with 30 ms of cushion and a 500 ms quiet window, completely preventing cascading frame drops (`glitches: 0 (SYNCED)`).
+
+### 3. Isolated Procedural Cues
+When you mute or unmute, Micforge synthesizes a clean, logarithmic sine sweep with half-Hann envelopes (*blip* on mute, *chirp* on unmute). The audio cue is mixed exclusively into your headphone monitor—it is never sent down the virtual cable to Discord or your stream.
+
+### 4. Smart Idle Nap Mode
+During silent pauses or when the mic is muted, CoFi-Lite's neural inference engine automatically enters a low-power nap mode, dropping inference CPU usage to 0% and instantly waking up on the very first speech syllable.
+
+---
+
+## Repository Structure
+
+```
+micforge/
+├── src/micforge/
+│   ├── audio/
+│   │   ├── engine.py            # Stream lifecycle, phase centering, cushion re-arming
+│   │   ├── loopback.py          # WASAPI loopback speaker capture for AEC
+│   │   ├── cues.py              # Procedural sine-sweep feedback chimes
+│   │   ├── devices.py           # Device discovery & virtual-cable detection
+│   │   ├── device_watch.py      # Hot-plug watcher daemon & auto-recovery
+│   │   ├── noise_profile.py     # Voice-aware continuous noise learner & profiles
+│   │   ├── latency.py           # Loopback chirp cross-correlation & breakdown
+│   │   ├── ring.py              # Lock-free ring buffer
+│   │   └── metrics.py           # RMS, peak hold, clipping, spectrum
+│   ├── commands/
+│   │   ├── live.py              # Live dashboard & background runner
+│   │   ├── help_cmd.py          # Dynamic categorized command guide & usage deep-dive
+│   │   ├── latency_test.py      # End-to-end latency benchmark CLI
+│   │   ├── preset_cmd.py        # Preset CLI suite (list, save, export, import)
+│   │   ├── test_mic.py          # Record, compare and A/B playback
+│   │   ├── doctor.py            # Audio driver diagnostics & zip export
+│   │   └── files.py             # Offline WAV processing
+│   ├── dsp/
+│   │   ├── 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
+│   │   ├── denoise.py           # Classical Spectral Wiener fallback
+│   │   ├── biquad.py            # Pure NumPy Second-Order Sections (SOS) engine
+│   │   ├── gate.py              # Soft downward expander / noise gate
+│   │   ├── compressor.py        # Fast feed-forward compressor & peak limiter
+│   │   ├── deesser.py           # Split-band de-esser
+│   │   └── leveler.py           # Slow RMS speech leveler
+│   ├── ui/
+│   │   ├── dashboard.py         # Live Studio Inspector & Gamer HUD
+│   │   ├── settings_gui.py      # Multi-tab native Control Center (Simple/Advanced)
+│   │   ├── tuning.py            # 4-knob macro schema & deterministic mappings
+│   │   ├── hotkeys.py           # OS-level keyboard hook manager
+│   │   └── tray.py              # Windows system tray daemon & dynamic icon
+│   ├── diagnostics.py           # Telemetry collection, secret redaction & zip bundler
+│   ├── presets.py               # Preset CRUD, validation & built-in definitions
+│   └── cli.py                   # Command-line entry point
+├── docs/
+│   └── TROUBLESHOOTING.md       # Centralized diagnostic & OS troubleshooting guide
+├── scripts/
+│   ├── compare_two.py           # Dual-file comparison, metrics & A/B listening
+│   └── compare_audio.py         # Automated WAV processing evaluation
+├── tests/                       # 125 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
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Testing
+
+The test suite runs with a mocked PortAudio backend, requiring no physical audio hardware:
+
+```bash
+pip install -e .[dev]
+pytest -v
+```
+
+---
+
+## License
+
+Micforge is released under the **MIT License**; see `LICENSE`. Third-party components are governed by their own licenses, including the bundled `cofilite.onnx` model (derived from the official CoFi-Lite checkpoint), VB-CABLE, and BlackHole.

micforge-1.3.0/README.md

@@ -0,0 +1,290 @@
+# Micforge
+
+[![Version](https://img.shields.io/badge/version-1.3.0-0284c7.svg)](verison%20notes/v1.3.0.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/)
+[![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.**  
+> Built and maintained by **[Parth Sadaria](https://github.com/Parthsadaria)**.
+
+---
+
+## What is Micforge?
+
+Most budget desk mics and gaming headsets sound thin, pick up room reflections (that hollow "talking in an empty bathroom" ring), bleed keyboard clatter, and capture speaker audio. 
+
+**Micforge** is an open-source, local real-time DSP engine designed to run silently on your machine and make your microphone sound clean, warm, and broadcast-ready before it reaches Discord, OBS, Zoom, or your game.
+
+It pairs an **11-stage modular audio processing rack** with an ultra-lightweight neural speech model based on **[CoFi-Lite](https://arxiv.org/abs/2607.10142)** (~83k parameters). 
+
+### 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.
+- **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`).
+- **Simple vs. Advanced Tuning UX (v1.3.0):** 4 intuitive macro knobs (Clarity, Warmth, Noise Removal, Room Cleanup) for casual streamers, plus deep parametric controls for engineers.
+- **Redacted Diagnostics (.zip):** One-click diagnostic bundle export with zero telemetry and automatic secret/path redaction (`micforge doctor --export`).
+- **Zero audio-thread heap allocations:** Critical DSP loops operate with pre-allocated scratch buffers to ensure zero clicks, pops, or garbage collection spikes.
+- **Acoustic Echo Cancellation (AEC):** Ingests game/speaker audio directly via native Windows WASAPI loopback without needing third-party cables, eliminating Discord voice echo.
+- **Room Dereverberation:** Strips out late room flutter and untreated wall reflections.
+- **Voice Proximity Effect:** Adds warm chest resonance (80–180 Hz) and even-order harmonics, giving cheap mics the presence of a broadcast dynamic mic.
+- **Esports Gamer HUD (`Tab`):** A minimalist terminal overlay designed for second monitors, featuring a Voice Activity Detector badge, mini-presence wave, and bold mute alert banner.
+
+```
+                  ┌────────────────────── 11-Stage Modular DSP Rack ─────────────────────┐
+                  │                                                                      │
+Microphone Input ─┼─▶ High-Pass Filter (Rumble removal, 90 Hz default)                   │
+                  │   └─▶ Acoustic Echo Cancellation (WASAPI speaker loopback reference) │
+                  │       └─▶ CoFi-Lite AI Denoiser (or classical Spectral Wiener)       │
+                  │           └─▶ Room Dereverberation (Late reflection tail decay)      │
+                  │               └─▶ Soft Noise Gate / Downward Expander                │
+                  │                   └─▶ Voice Proximity (Chest resonance & warmth)    │
+                  │                       └─▶ Parametric EQ (De-mud / Presence / Air)    │
+                  │                           └─▶ Split-Band De-Esser (Sibilance tame)   │
+                  │                               └─▶ Slow RMS Auto-Leveler              │
+                  │                                   └─▶ Fast Feed-Forward Compressor   │
+                  │                                       └─▶ Peak Limiter (-1.5 dBFS)   │
+                  └───────────────────────────────────┬──────────────────────────────────┘
+                                                      │
+                                                      ├──▶ Virtual Cable Output ──▶ Discord / OBS / Games
+                                                      └──▶ Headphone Monitor (with isolated audio cues)
+```
+
+---
+
+## Realistic Expectations
+
+Let's be engineer-honest:
+- **Micforge cleans up noise, room flutter, and tone balance.** It can remove fan drone, quiet loud keystrokes, cancel speaker bleed, and add chest warmth.
+- **It cannot fix bad physics.** If your microphone is 3 feet away near a mechanical keyboard, software can only do so much before your voice sounds watery. Keeping your mic 4–6 inches from your mouth will always do more than any plugin on earth.
+
+---
+
+## Quick Start
+
+### 1. Prerequisites
+- **Python 3.10** or higher
+- A virtual audio cable to route processed sound into Discord/games:
+  - **Windows:** [VB-CABLE Driver](https://vb-audio.com/Cable/) *(free, recommended)*
+  - **macOS:** [BlackHole 2ch](https://github.com/ExistentialAudio/BlackHole) (`brew install blackhole-2ch`)
+  - **Linux:** PulseAudio/PipeWire null sink (`pactl load-module module-null-sink sink_name=micforge`)
+
+### 2. Installation
+```bash
+git clone https://github.com/Parthsadaria/MicForge.git
+cd MicForge
+pip install -e .
+```
+*(Debian/Ubuntu: `sudo apt install libportaudio2` · macOS: `brew install portaudio`)*
+
+### 3. Setup & First Run
+```bash
+micforge doctor      # check audio drivers and environment
+micforge setup       # pick your real mic, virtual cable, and headphones
+micforge calibrate   # sample room silence for 3s to set gate threshold
+micforge run         # start the live interactive dashboard
+```
+
+> **Windows Tip:** In `micforge setup`, always select the **WASAPI** entries for your mic and `CABLE Input`. The legacy MME entries add 40+ ms of driver latency and drift.
+
+### 4. Application Configuration
+In Discord, OBS Studio, Steam, or Zoom:
+1. Set **Input Device** to `CABLE Output (VB-Audio Virtual Cable)`.
+2. Disable downstream **Noise Suppression** (e.g. Discord Krisp) and **Automatic Gain Control** to avoid double-processing artifacts.
+3. Keep Discord's **Echo Cancellation** disabled if you use headphones; leave it enabled if you play on open speakers.
+
+To run Micforge silently in the background:
+```bash
+micforge --tray
+```
+
+---
+
+## Live Monitoring & Gamer HUD
+
+Micforge includes two live view modes in the terminal (`micforge run`):
+
+### 1. Studio Inspector Mode (Full View)
+A comprehensive broadcast monitor displaying live input/output levels, sweet-spot meter, real-time reduction telemetry, dual FFT spectrum, and hardware diagnostics:
+
+```
+┌────────────────────────────── micforge v1.3.0 ──────────────────────────────┐
+│  MIC ENHANCER    ● PROCESSED   preset [gaming]                              │
+│ mic Microphone (Realtek Audio)  →  CABLE Input (VB-Audio)                   │
+│ Rack: HPF● AEC● AI● VERB● GATE· BODY● EQ● DEESS● LVL● COMP● LIM●            │
+│                                                                             │
+│ IN   ██████████████████████████················   -24.2 dB                  │
+│ OUT  ████████████████████████████████··········   -16.1 dB   [SWEET SPOT]   │
+│ REF  ··········································   silent (Clean/Headphones) │
+│                                                                             │
+│ ┌─ processing & dsp reductions ───────────────────────────────────────────┐ │
+│ │ noise   █████████████████████████  -24.5 dB                             │ │
+│ │ de-verb █████                       -3.2 dB                             │ │
+│ │ body    ████                        +2.5 dB                             │ │
+│ │ gate    OPEN                         0.0 dB                             │ │
+│ └─────────────────────────────────────────────────────────────────────────┘ │
+│                                                                             │
+│ latency   ~ 68 ms        noise floor  -64.2 dBFS   uptime   01h 14m         │
+│ dsp load  ███·····  18%  input gain   +0.0 dB      memory   85.4 MB         │
+│ glitches  0 (SYNCED)     clock fixes  0            profile  Active          │
+│                                                                             │
+│  Tab  HUD │  1-6  Preset │  x  Mute │  b  Bypass │  s  GUI │  ?  Help │  q    │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 2. Esports Gamer HUD (`Tab` Key)
+Press `Tab` to switch to an ultra-compact overlay designed for minimal distraction on a second monitor:
+- **Voice Activity Badge:** Instant state feedback (`[🎙️ VOICED SPEECH]`, `[👂 LISTENING]`, `[💤 IDLE NAP]`).
+- **Mini Vocal Waveform:** Live ASCII vocal presence and body resonance monitor.
+- **Double-Border Muted Warning:** A bold red alert panel appears when muted so you never accidentally talk on mute during matches.
+
+### In-Console Live Hotkeys
+| Key | Action | Key | Action |
+|:---:|:---|:---:|:---|
+| `Tab` | Toggle Studio Inspector ⟷ Gamer HUD | `1`–`6` | Direct preset jump (`discord`, `gaming`, `broadcast`, `studio`, `noisy_room`, `de_muffle`) |
+| `b` | A/B Bypass (hear raw mic vs processed) | `e` | Toggle Acoustic Echo Cancellation (AEC) |
+| `x` | Mute / unmute microphone | `w` | Cycle Voice Proximity warmth (Off → 35% → 55% → 75%) |
+| `s` | Open Native Multi-Tab Control Center GUI | `v` | Cycle Room De-Verb (Off → 30% → 50% → 70%) |
+| `+` / `-` | Denoise strength (±10%) | `c` | Recalibrate room noise (3s silence) |
+| `[` / `]` | Input gain (±1 dB) | `?` / `h` | Toggle hotkey cheatsheet overlay |
+| `q` | Clean quit | | |
+
+---
+
+## Native Multi-Tab Control Center (`micforge settings` or `s` key)
+
+For visual tuning without editing configuration files, Micforge features a sleek, dark native Control Center (`560x680`):
+
+1. **Tab 1: 🎛️ Presets & DSP Rack**
+   - Built-in vs Custom preset management (`[➕ New]`, `[💾 Save]`, `[🗑 Delete]`, `[📤 Export]`, `[📥 Import]`).
+   - Grouped into 3 clean logical cards:
+     - **Voice Character & Room:** Proximity intensity, warmth saturation, chest fundamental pitch (F0), anti-mud notch, and room decay (RT60).
+     - **Noise & Echo:** CoFi-Lite AI strength and AEC power.
+     - **Dynamics:** Gate threshold/range and Compressor ratio/makeup gain.
+2. **Tab 2: ⚡ Global Hotkeys & Audio Cues**
+   - Bind OS-wide hotkeys (Mute, Push-to-Talk, Push-to-Mute, Bypass) with one-click key recording.
+   - Adjust volume and test headphone feedback chimes.
+3. **Tab 3: 🎙️ Audio Hardware & Windows System**
+   - Select physical mic, virtual cable, and monitor headphones from dropdowns.
+   - Toggle Windows Boot Autostart and Minimize to System Tray.
+
+---
+
+## Custom Preset Engine (`micforge preset ...`)
+
+Save, duplicate, share, and backup custom vocal chains from the command line:
+
+```bash
+micforge preset list                         # view built-in & custom presets
+micforge preset save my_stream --from gaming # clone and customize
+micforge preset export my_stream preset.json # export to share with friends
+micforge preset import preset.json           # import community preset
+micforge preset show my_stream               # inspect all 11 stages
+micforge preset delete my_stream             # delete custom preset (built-ins protected)
+```
+
+---
+
+## Under the Hood: Engineering Highlights
+
+### 1. ~50% RAM Optimization (v1.2.1)
+Standard Python scientific audio tools easily pull in 150–200 MB of RAM because `scipy` imports massive compiled BLAS/LAPACK runtimes and optimization suites. 
+
+In v1.2.1:
+- Replaced `scipy.signal.sosfilt` with a vectorized pure NumPy Direct Form II Transposed biquad engine ($< 10^{-8}$ difference, 0 memory allocations).
+- Replaced SciPy FIR decimation/interpolation with NumPy sinc windowing and valid-mode convolution.
+- Disabled ONNX Runtime CPU memory arena (`enable_cpu_mem_arena = False`), preventing ONNX from hoarding 30–50 MB of idle heap caches.
+- **Result:** Live streaming process RAM dropped from **165.4 MB down to ~85 MB** with zero degradation in audio quality.
+
+### 2. Clock Drift Phase Centering & Anti-Glitch Architecture
+When Windows initializes two independent audio devices (USB microphone and virtual cable), they start asynchronously with an initial ~15–30 ms phase difference. 
+
+Earlier drift detectors misidentified this harmless startup offset as physical crystal clock drift, firing hundreds of false 1-sample corrections and pulling the ring buffer into starvation.
+- **Dynamic Phase Centering:** After the stream establishes a 60-block (~600 ms) steady state, Micforge calibrates its center point to the real hardware offset. Clock fixes stay at **0** during normal sessions.
+- **Guaranteed Cushion Re-Arming:** If a heavy background game causes an underrun, the buffer instantly re-arms with 30 ms of cushion and a 500 ms quiet window, completely preventing cascading frame drops (`glitches: 0 (SYNCED)`).
+
+### 3. Isolated Procedural Cues
+When you mute or unmute, Micforge synthesizes a clean, logarithmic sine sweep with half-Hann envelopes (*blip* on mute, *chirp* on unmute). The audio cue is mixed exclusively into your headphone monitor—it is never sent down the virtual cable to Discord or your stream.
+
+### 4. Smart Idle Nap Mode
+During silent pauses or when the mic is muted, CoFi-Lite's neural inference engine automatically enters a low-power nap mode, dropping inference CPU usage to 0% and instantly waking up on the very first speech syllable.
+
+---
+
+## Repository Structure
+
+```
+micforge/
+├── src/micforge/
+│   ├── audio/
+│   │   ├── engine.py            # Stream lifecycle, phase centering, cushion re-arming
+│   │   ├── loopback.py          # WASAPI loopback speaker capture for AEC
+│   │   ├── cues.py              # Procedural sine-sweep feedback chimes
+│   │   ├── devices.py           # Device discovery & virtual-cable detection
+│   │   ├── device_watch.py      # Hot-plug watcher daemon & auto-recovery
+│   │   ├── noise_profile.py     # Voice-aware continuous noise learner & profiles
+│   │   ├── latency.py           # Loopback chirp cross-correlation & breakdown
+│   │   ├── ring.py              # Lock-free ring buffer
+│   │   └── metrics.py           # RMS, peak hold, clipping, spectrum
+│   ├── commands/
+│   │   ├── live.py              # Live dashboard & background runner
+│   │   ├── help_cmd.py          # Dynamic categorized command guide & usage deep-dive
+│   │   ├── latency_test.py      # End-to-end latency benchmark CLI
+│   │   ├── preset_cmd.py        # Preset CLI suite (list, save, export, import)
+│   │   ├── test_mic.py          # Record, compare and A/B playback
+│   │   ├── doctor.py            # Audio driver diagnostics & zip export
+│   │   └── files.py             # Offline WAV processing
+│   ├── dsp/
+│   │   ├── 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
+│   │   ├── denoise.py           # Classical Spectral Wiener fallback
+│   │   ├── biquad.py            # Pure NumPy Second-Order Sections (SOS) engine
+│   │   ├── gate.py              # Soft downward expander / noise gate
+│   │   ├── compressor.py        # Fast feed-forward compressor & peak limiter
+│   │   ├── deesser.py           # Split-band de-esser
+│   │   └── leveler.py           # Slow RMS speech leveler
+│   ├── ui/
+│   │   ├── dashboard.py         # Live Studio Inspector & Gamer HUD
+│   │   ├── settings_gui.py      # Multi-tab native Control Center (Simple/Advanced)
+│   │   ├── tuning.py            # 4-knob macro schema & deterministic mappings
+│   │   ├── hotkeys.py           # OS-level keyboard hook manager
+│   │   └── tray.py              # Windows system tray daemon & dynamic icon
+│   ├── diagnostics.py           # Telemetry collection, secret redaction & zip bundler
+│   ├── presets.py               # Preset CRUD, validation & built-in definitions
+│   └── cli.py                   # Command-line entry point
+├── docs/
+│   └── TROUBLESHOOTING.md       # Centralized diagnostic & OS troubleshooting guide
+├── scripts/
+│   ├── compare_two.py           # Dual-file comparison, metrics & A/B listening
+│   └── compare_audio.py         # Automated WAV processing evaluation
+├── tests/                       # 125 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
+├── pyproject.toml
+└── README.md
+```
+
+---
+
+## Testing
+
+The test suite runs with a mocked PortAudio backend, requiring no physical audio hardware:
+
+```bash
+pip install -e .[dev]
+pytest -v
+```
+
+---
+
+## License
+
+Micforge is released under the **MIT License**; see `LICENSE`. Third-party components are governed by their own licenses, including the bundled `cofilite.onnx` model (derived from the official CoFi-Lite checkpoint), VB-CABLE, and BlackHole.