impl

Fractal_Audio_Visualizer_Spec.md

@@ -5,19 +5,24 @@
 **Platform:** Windows 10/11\
 **Runtime:** .NET 10\
 **Framework:** MonoGame (WindowsDX)\
-**Audio Library:** NAudio (WASAPI Loopback)
+**Audio Library:** NAudio (WASAPI Capture + WASAPI Loopback)
 
 ------------------------------------------------------------------------
 
 # 1. Project Overview
 
 Fractal Audio Visualizer is a real-time Windows desktop application that
-captures system audio output (loopback) and generates GPU-accelerated
-fractal visualizations that react dynamically to music.
+captures audio and generates GPU-accelerated fractal visualizations that
+react dynamically to sound.
 
-The application listens to currently playing system audio (Spotify,
-YouTube, etc.) and renders procedural fractal graphics driven by
-frequency spectrum analysis.
+The application uses exactly 2 audio input presets:
+
+1.  **Microphone (Default):** Listen to microphone input in real time.
+2.  **System Output:** Listen to sound played by any application on the
+    PC (Spotify, YouTube, games, browser audio, etc.).
+
+Captured audio drives procedural fractal graphics via frequency spectrum
+analysis.
 
 ------------------------------------------------------------------------
 
@@ -25,10 +30,18 @@ frequency spectrum analysis.
 
 ## 2.1 Audio Capture
 
--   Use **NAudio WASAPI Loopback Capture**
--   Capture default output device
+Input preset modes (exactly 2):
+
+-   **Microphone (Default):** Capture default microphone in real time
+    using NAudio WASAPI capture (shared mode, with WaveIn fallback if
+    needed)
+-   **System Output:** Use NAudio WASAPI Loopback Capture for audio
+    played by any application on the PC
+
+Common requirements:
+
 -   Support 44.1kHz and 48kHz
--   Automatic device rebind if default device changes
+-   Automatic device rebind if default input/output device changes
 -   Buffer size: 1024--4096 samples
 -   PCM float format internally
 
@@ -138,7 +151,8 @@ Minimum 3 presets:
 # 6. UI Controls
 
 Keyboard: - F11 → Fullscreen toggle - ESC → Exit fullscreen - SPACE →
-Pause animation - LEFT/RIGHT → Switch preset - TAB → Toggle HUD
+Pause animation - LEFT/RIGHT → Switch fractal preset - TAB → Toggle HUD
+- M → Toggle audio input mode (Microphone/System Output)
 
 Optional: Myra UI for settings overlay
 
@@ -146,7 +160,8 @@ Optional: Myra UI for settings overlay
 
 # 7. Threading Model
 
-Audio Thread: - WASAPI callback - Push samples to ring buffer
+Audio Thread: - Active input callback (Microphone or Loopback) - Push
+samples to ring buffer
 
 Analysis Thread: - FFT + feature extraction - Publish snapshot
 (lock-free)
@@ -175,8 +190,9 @@ Main Thread: - MonoGame Update/Draw
 
 # 9. MVP Scope
 
-MVP Includes: - WASAPI loopback capture - FFT + 3-band energy
-extraction - Julia shader - Preset switching - Fullscreen mode
+MVP Includes: - Exactly 2 input presets: Microphone (default) and
+System Output (switchable) - FFT + 3-band energy extraction - Julia
+shader - Preset switching - Fullscreen mode
 
 Estimated implementation time: 5--7 development days.
 
@@ -194,11 +210,13 @@ Estimated implementation time: 5--7 development days.
 
 # 11. Acceptance Criteria
 
-1.  App reacts to Spotify/YouTube playback without microphone.
-2.  Bass drops visibly affect zoom/intensity.
-3.  Preset switch occurs without frame drop.
-4.  60 FPS at 1080p (medium quality).
-5.  No crashes on device change.
+1.  App starts in Microphone mode and reacts to live mic input.
+2.  User can switch to System Output mode and app reacts to
+    Spotify/YouTube playback without microphone.
+3.  Bass drops visibly affect zoom/intensity.
+4.  Preset switch occurs without frame drop.
+5.  60 FPS at 1080p (medium quality).
+6.  No crashes on device change.
 
 ------------------------------------------------------------------------