feat: Next-Gen Audio DSP Stack Architecture (Multi-Laptop Auto-Detection, 5.0ms Parallel Lookahead FIR, & Zero-Drop Stream Migration) #7

steve · 2026-09-01T11:19:20-04:00

steve commented

2026-09-01 11:19:20 -04:00

Summary of Changes

This Pull Request introduces the Next-Gen Audio DSP Stack Architecture to main:

1. 💻 Multi-Laptop Profile Hierarchy & DMI Auto-Detection (Phase 1)

Created laptop-configs/<vendor>/<model>/ hardware profile structure holding baseline driver WAVs, graph topology, and profile.json metadata.
Authored detect_hardware.py to dynamically query Linux /sys/class/dmi/id/ sysfs metadata (sys_vendor and product_name) to match hardware profiles automatically.
Added CLI flags to detect_hardware.py: --help, --list-configs, --model, --manual, --profile, --json, and --quiet with fallback warning reporting.

2. ⏱️ Parallel 5.0ms Lookahead Sidechain FIR Limiting (Phase 2)

Enhanced bake-graph.py to generate parallel advance control taps (baked-lookahead-*.wav) alongside main audio path FIRs (baked-*.wav).
Main Path FIR: Trims pre-delay lead to 5.0 ms.
Lookahead Sidechain FIR: Trims directly to peak index (0.0 ms lead), delivering advance peak warnings to post-convolver limiters (wlim / tlim) 5.0 ms before physical speaker output with 0.0 ms added listener buffer latency.

3. 🎛️ User EQ Graph Merging & Hardware Interoperability

Fixed apply.sh so jq always merges user_eq.json into both --bake (graph_simple.json) and un-baked graphs.
Moved capture.volumes inside capture.props in PipeWire schema for loudness:volume control binding.
Hardware media keys (F11/F12 / Touch Bar) smoothly control the DSP Speakers virtual sink.

4. 🔄 Zero-Drop Stream Migration & Robust Service Reloads

Added pactl move-sink-input iteration upon cold restart (HOT=0 default).
Active application streams (Firefox/YouTube, Spotify, Chrome) automatically migrate to the new DSP sink without requiring a browser tab reload or app restart.
Added wp() helper with 1.5s timeout and copy_file_safe() helper for smooth IPC and permission handling.

5. 📄 Comprehensive Documentation (`ARCHITECTURE.md`)

Authored ARCHITECTURE.md documenting single-pass LTI convolution, Mermaid processing flow diagrams, single-pass FIR baking steps, multi-laptop profile structures, and "Digital Surround" active crossover terminology.

## Summary of Changes This Pull Request introduces the **Next-Gen Audio DSP Stack Architecture** to `main`: ### 1. 💻 Multi-Laptop Profile Hierarchy & DMI Auto-Detection (Phase 1) - Created `laptop-configs/<vendor>/<model>/` hardware profile structure holding baseline driver WAVs, graph topology, and `profile.json` metadata. - Authored `detect_hardware.py` to dynamically query Linux `/sys/class/dmi/id/` sysfs metadata (`sys_vendor` and `product_name`) to match hardware profiles automatically. - Added CLI flags to `detect_hardware.py`: `--help`, `--list-configs`, `--model`, `--manual`, `--profile`, `--json`, and `--quiet` with fallback warning reporting. ### 2. ⏱️ Parallel 5.0ms Lookahead Sidechain FIR Limiting (Phase 2) - Enhanced `bake-graph.py` to generate parallel advance control taps (`baked-lookahead-*.wav`) alongside main audio path FIRs (`baked-*.wav`). - Main Path FIR: Trims pre-delay lead to 5.0 ms. - Lookahead Sidechain FIR: Trims directly to peak index (0.0 ms lead), delivering advance peak warnings to post-convolver limiters (`wlim` / `tlim`) 5.0 ms before physical speaker output with **0.0 ms added listener buffer latency**. ### 3. 🎛️ User EQ Graph Merging & Hardware Interoperability - Fixed `apply.sh` so `jq` always merges `user_eq.json` into both `--bake` (`graph_simple.json`) and un-baked graphs. - Moved `capture.volumes` inside `capture.props` in PipeWire schema for `loudness:volume` control binding. - Hardware media keys (F11/F12 / Touch Bar) smoothly control the DSP Speakers virtual sink. ### 4. 🔄 Zero-Drop Stream Migration & Robust Service Reloads - Added `pactl move-sink-input` iteration upon cold restart (`HOT=0` default). - Active application streams (Firefox/YouTube, Spotify, Chrome) automatically migrate to the new DSP sink without requiring a browser tab reload or app restart. - Added `wp()` helper with 1.5s timeout and `copy_file_safe()` helper for smooth IPC and permission handling. ### 5. 📄 Comprehensive Documentation (`ARCHITECTURE.md`) - Authored `ARCHITECTURE.md` documenting single-pass LTI convolution, Mermaid processing flow diagrams, single-pass FIR baking steps, multi-laptop profile structures, and "Digital Surround" active crossover terminology.

steve added 11 commits 2026-09-01 11:19:21 -04:00

feat(Phase 1): implement multi-laptop profile hierarchy laptop-configs/ and DMI hardware auto-detection tool ab621482d2

feat: add --help, --model, --manual, and --list-configs flags with fallback warning reporting to detect_hardware.py 1a6d819def

feat(Phase 2): implement parallel lookahead sidechain FIR impulse generation for zero-added-latency peak limiting fb0827dc7a

fix: move capture.volumes inside capture.props and set wpctl default sink binding for desktop volume keys 023ea3c532

chore: add profile graph.json to laptop-configs/apple/mbp15_1/ 4d1a373469

fix: default apply.sh to single-stage baked pipeline and add explicit (requires sudo) prompt notices f2d87a1580

fix(graph & apply): merge user_eq into baked graph, migrate active streams on cold restart, and bind volume keys 56f4c7477b

docs: add ARCHITECTURE.md detailing compressed-chain FIR engine, 5.0ms lookahead sidechain limiting, and multi-laptop profile framework 78fb42948d

docs: update ARCHITECTURE.md diagram to show 4-channel VirtualBass direct feed and baked User EQ convolution flow 7cafe63395

docs: add single-pass FIR baking process diagram to ARCHITECTURE.md 74d243e40b

docs: update ARCHITECTURE.md title and add Digital Surround vs Active Crossover explanation c7ccd5c4fc