From 9b071ccf91ee138c03c87d9f33f67322460d160d Mon Sep 17 00:00:00 2001
From: Michal Vrba <m.vrba@retailsoft.sk>
Date: Fri, 13 Feb 2026 18:58:26 +0100
Subject: [PATCH] added spec

---
 Fractal_Audio_Visualizer_Spec.md | 205 +++++++++++++++++++++++++++++++
 1 file changed, 205 insertions(+)
 create mode 100644 Fractal_Audio_Visualizer_Spec.md

diff --git a/Fractal_Audio_Visualizer_Spec.md b/Fractal_Audio_Visualizer_Spec.md
new file mode 100644
index 0000000..da265f0
--- /dev/null
+++ b/Fractal_Audio_Visualizer_Spec.md
@@ -0,0 +1,205 @@
+# 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
+
+``` csharp
+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