A GPU-accelerated real-time music visualizer with Aurora Borealis aesthetics.
_{Captures system audio. Renders reactive visuals at 60fps. Pure Python + OpenGL.}

Think planetarium laser show crossed with a rave — everything reacts to your music in real time.

Quick Start

git clone https://github.com/stefanbocane/Audio-Visualizer-.git
cd Audio-Visualizer-
pip install -r requirements.txt
python3 main.py

Picks up system audio automatically if BlackHole is configured, otherwise falls back to microphone input. Runs in demo mode if no audio device is available.

---

Visual Elements

The visualizer layers 8 distinct visual systems that each react to different aspects of your music — bass, treble, beats, drops, stereo width, and overall energy.

Aurora Background 3-layer flowing curtains using domain-warped fractal noise with a twinkling starfield and cosmic dust. Colors shift from cool teals during quiet passages to intense violets during loud sections.	Central Orb A morphing energy sphere with noise-distorted edges and internal plasma swirl. Pulses outward on beats with colored ripple rings. Never flashes white.
Particle System 3,500 particles in four spiral arms with murmuration-like flocking. Scatter on beats, explode outward on drops. Colored through the aurora palette by speed and distance.	DNA Double Helix Stereo waveform (L/R channels) as two intertwined glowing ribbon strands with 64 energy bridge rungs. Twist rate accelerates with energy.
Frequency Bars 128 spectrum analyzer bars in a gentle arc. Aurora color gradient from teal base to violet peaks, glowing edges, tip caps with trails, and mirror reflections.	Warp Tunnel Corkscrew spiral rays in 3 parallax depth layers with nebula noise texture. Activates at moderate energy, dramatically accelerates on drops.
Shockwave Rings Expanding colored rings triggered by bass drops. Teal-tinted, never white.	Lissajous Scope Small stereo phase oscilloscope in the corner showing L/R channel correlation.

Post-Processing Chain

Effect	Description
Bloom	Soft colored extraction with 13-tap Gaussian blur at half resolution
Chromatic Aberration	RGB channel split that pulses with beat intensity
Color Grading	Shadows tinted teal, highlights shifted violet
Motion Blur	Frame-to-frame feedback for smooth trails
Film Grain	Subtle noise texture weighted to dark areas
Vignette	Edge darkening that breathes with energy

---

Audio Setup (BlackHole)

BlackHole is a free virtual audio driver that captures system audio digitally — no microphone, zero noise, works with headphones.

1. Install

brew install blackhole-2ch

2. Approve & Restart

Go to System Settings > Privacy & Security, click Allow next to the BlackHole message. Restart your Mac (required).

3. Create Multi-Output Device

1. Open Audio MIDI Setup (Cmd+Space → "Audio MIDI Setup")
2. Click + in the bottom-left → Create Multi-Output Device
3. Check both your speakers/headphones AND BlackHole 2ch
4. Ensure speakers are listed first (Primary Device)

4. Set as Output

Right-click the Multi-Output Device in the sidebar → "Use This Device For Sound Output"

Note

Multi-Output Devices disable macOS volume keys. Control volume from your music app instead (Spotify, Apple Music, etc.).

Without BlackHole

Without BlackHole, the visualizer falls back to your default microphone:

• Picks up room noise
• Doesn't work with headphones
• Quieter music may not register

If no audio device is found, the app runs in demo mode with synthetic animated data.

---

Controls

python3 main.py

A launch menu lets you pick resolution (720p / 1080p / Fullscreen).

Key	Action
Q / Esc	Quit
F	Toggle fullscreen

The HUD displays BPM (detected) and FPS in the top-left corner.

---

Architecture

aurora-visualizer/
├── main.py                     # Launch menu, game loop, audio→render bridge
├── audio/
│   ├── capture.py              # Sounddevice stream, ring buffer (256-frame blocks)
│   ├── analyzer.py             # 1024-sample FFT, 6-band decomposition, stereo width
│   └── beat_detector.py        # Adaptive beat/drop detection (1.3σ / 2.2σ thresholds)
├── renderer/
│   ├── context.py              # ModernGL context, FBOs, shader loading
│   ├── pipeline.py             # Orchestrates all renderers + post-processing
│   ├── bloom.py                # Extract → 2-pass 13-tap Gaussian blur
│   ├── background.py           # Aurora curtains (FBM noise)
│   ├── orb.py                  # Central orb + beat ripple state machine
│   ├── particles.py            # 3500 particles, CPU physics (NumPy vectorized)
│   ├── dna_helix.py            # Stereo waveform helix with bridge rungs
│   ├── frequency_bars.py       # 128-bar spectrum analyzer
│   ├── warp_tunnel.py          # Radial corkscrew tunnel overlay
│   ├── shockwave.py            # Expanding ring on drops
│   ├── lissajous.py            # Stereo phase scope
│   └── hud.py                  # BPM/FPS text overlay
├── shaders/
│   └── *.vert / *.frag         # GLSL 4.1 shaders for each element
├── utils/
│   ├── math_utils.py           # Exponential smoothing, SmoothedAudioState
│   └── color_palette.py        # Aurora color definitions
└── requirements.txt

Render Pipeline

Audio In ──→ FFT ──→ Beat Detection ──→ Smoothing ──→ Scene Render ──→ Bloom ──→ Composite ──→ Display
  ~6ms        23ms        <1ms              <1ms         per element     half-res    + post-fx      vsync
                                                         additive blend

Total audio-to-visual latency: ~25ms

---

Performance

Metric	Value
Target framerate	60fps (vsync), capped at 120fps
Particle count	3,500 with 6-position trails (21,000 GL_POINTS/frame)
Particle physics	CPU — NumPy vectorized (no compute shaders on macOS)
Bloom resolution	Half (for performance)
Tested hardware	M1/M2 MacBook Air @ 1080p — solid 60fps

If performance is low

• Use 720p instead of 1080p from the launch menu
• Close other GPU-intensive apps (Chrome, etc.)
• Reduce NUM_PARTICLES in renderer/particles.py

---

Troubleshooting

"No audio device found" / Demo mode

• Ensure BlackHole is installed and the system extension was approved
• You must restart after approving the extension
• Verify the Multi-Output Device is set as system output in Audio MIDI Setup

Volume keys don't work

macOS limitation with Multi-Output Devices. Use your music app's volume slider instead.

Shader compile error

• Requires OpenGL 4.1 (all Macs from 2012+ support this via Metal)
• Check that shader files aren't corrupted

Choppy / laggy visuals

• Lower the resolution via the launch menu
• Close Chrome and other GPU-heavy apps
• Ensure you're on the discrete GPU if your Mac has one

---

Dependencies

Package	Version	Purpose
moderngl	>= 5.8	OpenGL 4.1 context, shaders, FBOs, VAOs
pygame	>= 2.5	Window management, event loop, HUD text
sounddevice	>= 0.4	Real-time audio capture from system devices
numpy	>= 1.24	FFT analysis, particle physics, array math

---

License

MIT — do whatever you want with it.

---

_{Built with Claude Code}