SoundFlix/Fractal_Audio_Visualizer_Spec.md

Fractal Audio Visualizer

Technical Specification

Platform: Windows 10/11
Runtime: .NET 10
Framework: MonoGame (WindowsDX)
Audio Library: NAudio (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.

The application listens to currently playing system audio (Spotify, YouTube, etc.) and renders procedural fractal graphics driven by frequency spectrum analysis.

---

2. Core Functional Requirements

2.1 Audio Capture

• Use NAudio WASAPI Loopback Capture
• Capture default output device
• Support 44.1kHz and 48kHz
• Automatic device rebind if default device changes
• Buffer size: 1024--4096 samples
• PCM float format internally

Output

Audio sample stream → Ring buffer → AudioAnalyzer

---

2.2 Audio Analysis

Performed continuously in background thread.

Processing Steps:

1. Apply Hann window
2. FFT (2048 or 4096)
3. Compute:
   • RMS (Level)
   • Bass band energy (20--200Hz)
   • Mid band energy (200--2000Hz)
   • High band energy (2000--16000Hz)
4. Beat detection (energy spike detection)
5. Exponential smoothing (attack/release)

Output Model

public struct AudioFeatures
{
    public float Level;
    public float Bass;
    public float Mid;
    public float High;
    public float Beat;
    public float[] Spectrum; // 64 bins
    public float TimeSeconds;
}

---

3. Rendering Architecture

3.1 Framework

MonoGame WindowsDX template
Rendering via HLSL shaders (.fx)

3.2 Rendering Pipeline

Game Loop:

Update(): - Pull latest AudioFeatures snapshot - Update shader parameters

Draw(): - Render fullscreen quad - Apply fractal shader - Optional post-processing

---

3.3 Shader Uniforms

float Time;
float Level;
float Bass;
float Mid;
float High;
float Beat;
float2 Resolution;
float Spectrum[64];

---

4. Fractal Presets

Minimum 3 presets:

4.1 Julia Set (2D)

• Parameter C modified by Mid
• Zoom pulse from Bass
• Glow from High

4.2 Mandelbulb (3D Raymarch)

• Power modulated by Bass
• Rotation by Mid
• Detail iterations influenced by High
• Beat triggers camera pulse

4.3 Kaleidoscope Tunnel

• Spectrum drives radial distortion
• Beat triggers color shift

---

5. Performance Strategy

• Render to scaled RenderTarget (0.5x--1x resolution)
• Adjustable iteration count
• Target: 60 FPS at 1080p (Medium preset)

---

6. UI Controls

Keyboard: - F11 → Fullscreen toggle - ESC → Exit fullscreen - SPACE → Pause animation - LEFT/RIGHT → Switch preset - TAB → Toggle HUD

Optional: Myra UI for settings overlay

---

7. Threading Model

Audio Thread: - WASAPI callback - Push samples to ring buffer

Analysis Thread: - FFT + feature extraction - Publish snapshot (lock-free)

Main Thread: - MonoGame Update/Draw

---

8. Project Structure

FractalVisualizer.sln
 ├── FractalVisualizer
 │     ├── Game1.cs
 │     ├── Audio/
 │     │     AudioCapture.cs
 │     │     AudioAnalyzer.cs
 │     ├── Rendering/
 │     │     FractalRenderer.cs
 │     │     Shaders/
 │     ├── Models/
 │     │     AudioFeatures.cs
 │     ├── UI/
 │     └── SettingsManager.cs

---

9. MVP Scope

MVP Includes: - WASAPI loopback capture - FFT + 3-band energy extraction - Julia shader - Preset switching - Fullscreen mode

Estimated implementation time: 5--7 development days.

---

10. Future Enhancements

• Advanced beat & tempo detection
• Preset editor (live tweak UI)
• Video export (visual-only recording)
• MIDI input support
• Multi-monitor support

---

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.

---

End of Specification