wpav

wpav (Wayland PipeWire Audio Visualizer) is a native Rust audio visualizer using PipeWire audio capture and OpenGL rendering through SDL2.

Run

The application starts fullscreen by default. Use --windowed for a normal resizable window:

cargo run --release
cargo run --release -- --windowed
cargo run --release -- --educational
cargo run --release -- --transition flow
cargo run --release -- --transition manual --start-mode 34
cargo run --release -- --transition flow --shuffle
cargo run --release -- --start-mode 68 --waveform /path/to/waveform.kvwf --warp /path/to/warp.kvwm

When launched from a terminal, keyboard input is read in raw mode so commands do not require pressing Enter. Terminal input is optional. With non-interactive stdin, the visualizer still follows PipeWire's active/default audio routing and can be controlled through SDL.

Controls

Input	Action
q, Esc, Ctrl-C	Quit
f	Toggle fullscreen
Left / Right	Previous / next palette
Down / Up	Previous / next symmetry mode
[ / ]	Previous / next response profile (Ambient, Balanced, Dynamic, Immersive)
, / .	Previous / next motion director profile (Conductor, Hypnotist, Percussionist, Surrealist)
PageUp / PageDown	Previous / next PipeWire audio source (terminal and SDL)
n / p or Tab / Shift-Tab	Next / previous visual mode
e / i	Toggle educational / instructional scene guidance in console
- / =	Decrease / increase visual sensitivity
Space	Pause / resume the visual timeline (frame-accurate; audio keeps playing)
.	While paused, step forward one frame
1 / 2	Decrease / increase output brightness (mpv-style)
3 / 4	Decrease / increase contrast
5 / 6	Decrease / increase gamma
7 / 8	Decrease / increase saturation
9 / 0	Decrease / increase volume
?	Toggle the on-screen help / keybinding overlay
l	Toggle scene loop (hold this scene, fresh palette/symmetry per take)
x	Toggle shuffle (choose a different mode at each automatic boundary)
j / k	Arm previous / next scene tunable
; / '	Decrease / increase the armed tunable
Backspace	Reset the armed tunable to its default
s	Save tunable overrides to $XDG_DATA_HOME/wpav/tunables.json
m	Toggle the terminal control panel (browser, inspector, mixer, presets, keys, sequencer, help)
c	Cycle camera: off / auto (audio-driven cinematography) / free (mouse + wheel)
v	Cycle atmosphere: off / fog / ember / mist
Shift-1 .. Shift-7	Toggle post-fx: bloom, chromatic aberration, grain, ACES tone map, dithering, strobe, crossfade hold
Shift-8 / Shift-9	Scrub the A/B crossfade back / forward (holds the dissolve automatically)

Keybindings follow mpv conventions where possible. Every binding can be reassigned by creating an input.conf file at $XDG_CONFIG_HOME/wpav/input.conf (or ~/.config/wpav/input.conf), with one key command pair per line:

space toggle-pause
l toggle-loop-scene

; tunable-decrease
' tunable-increase

Run with --input-conf /path/to/file to load a different file. Comments start with #. White-space separate the key token from the kebab-cased command name; see ? in-app or docs/man/wpav.1 for the full command list. Run --help for the generated option reference, --completions bash|zsh|fish to print a completion script for your shell, and --explain QUERY (alias --help-search) to fuzzy-search options and all scenes by name, math, or mood. Typo a flag and wpav suggests the closest match before you ever open the manual. Brightness, contrast, gamma, saturation and volume are remembered across runs in $XDG_DATA_HOME/wpav/session.json; start with --pause to begin paused. A custom shader body at $XDG_CONFIG_HOME/wpav/fs_source.frag hot-reloads the visuals live as you edit; alternatively drop individual scene-shader parts (fs_header.frag, fs_scenes_149_165.frag, ...) into $XDG_CONFIG_HOME/wpav/glsl/ and only that part is reassembled and recompiled — the whole-file override wins when both are present.

MIDI controllers can drive the same parameters: create $XDG_CONFIG_HOME/wpav/midi.conf with one cc <number> <param> line per knob, for example cc 1 brightness, cc 21 tunable0, or cc 50 strobe. Params: brightness, contrast, gamma, saturation, volume, sensitivity, symmetry, tunable0..7, bloom, ca (or chromatic-aberration), grain, aces, dither, strobe, crossfade-hold. wpav listens on every MIDI input port; the file is read at startup.

The visualizer automatically advances through all 163 standard and 3D modes using the slow profile by default. Each mode holds for 30 seconds and crossfades into the next one over 5.0 seconds. Use the faster flow profile for a continuous, high-motion tour, or disable automatic cycling when you want to explore a single mode manually:

cargo run --release -- --transition flow
cargo run --release -- --scene-seconds 8 --start-mode 34
cargo run --release -- --transition manual --start-mode 35

--flow is a shortcut for --transition flow; flow holds each mode for 9.0 seconds and uses a 1.8-second eased crossfade, giving each scene room to develop and bask before moving on. --scene-seconds overrides the hold time for the automatic profiles. Add --shuffle to choose a different mode at each automatic boundary instead of walking the bank sequentially. In shuffle mode, n/p (and Tab/Shift-Tab) randomly explore new scenes with fresh palette / symmetry / camera picks, mirroring the automatic --shuffle behavior; without shuffle they walk the bank sequentially, with p traversing playback history. > / < always step deterministically forward / backward in the numbered mode list, independent of shuffle, and never re-roll palette or symmetry. Press x at any time to toggle shuffle live. --transition manual keeps the selected mode until Tab or Shift-Tab changes it.

Cinematic showcases stitch a scene, an atmosphere, and the auto-camera into a directed shot for casual vibe-setting. Run --showcase temple-descend (temple god-rays in fog), city-flyover (neon dusk city from the sky), forest-rise (forest in mist), aurora-dream (aurora swarm melting into a reaction-diffusion garden), or arena-descent (kinetic cage dissolving into a sound spiral); --vibe fog|ember|mist|clear applies an atmosphere to any scene. The camera and atmosphere can also be cycled live with c and v; per-scene opt-in keeps both off where they do not help.

--waveform <path> loads a .kvwf waveform shader file (wpav-compatible kviz ecosystem format) for the Composer mode. --warp <path> loads a .kvwm warp map shader file. When both are omitted, the Composer mode uses a built-in sine waveform and spiral warp. If one is specified and the other is not, the missing one uses its built-in default.

The same arrow, F, and Esc controls work when the SDL window has keyboard focus. PipeWire normally connects to the active default sink monitor. The source shortcuts cycle monitor-capable PipeWire nodes and reconnect the capture stream to the selected node. This is useful when an external graph controller changes the active route on a headless machine; wpav does not start an interactive wiremix session itself.

The default palette is Opal Tide. Other gentle starting points include Calm Dream, Moonlit Aurora, Soft Nebula, Biolume Garden, Rose Nebula, Copper Moon, Ultraviolet Garden, Rich Night Sky, and Rich Lavender. More saturated palettes are also available; use the left and right arrows to browse all 46 palettes.

Performance & Adaptive Quality

The engine tracks GPU frame time with OpenGL timer queries and adapts continuously (a toggles auto, g cycles manually, --quality 0..3 locks):

Rung	Scale	Detail	Notes
0	100%	100%	full quality, all post effects
1	83%	75%	post effects intact
2	66%	55%	CA/grain halved, bloom reduced
3	50%	35%	post chain skipped (linear blit), loop caps engaged

The ladder drops a rung after a short streak above 90% of the current frame budget (or above 34 ms) and raises one only after a long stretch below 55% of the budget, with a 600-frame cooldown; rung changes are deferred until a scene transition so resolution pops never appear mid-scene. Because headroom is measured against the cadence's own target, a GPU that saturates while still hitting vsync reads as loaded and the ladder keeps it in check. Scene-level loop caps scale with u_quality (qcap), so heavy scenes shed iterations before pixels.

Per-mode cost is measurable with:

wpav --benchmark --quality 0 --start-mode 183 --no-musical-transitions

Software-rendered reference (Mesa llvmpipe, Xvfb, 1280x1024, quality 0), indicative of relative scene cost rather than absolute performance:

Mode	Scene	Frame time
0	Aurora	25 ms
197	Neon Topo City	76 ms
150	Collision Chamber	109 ms
183	Mycelium Grove	134 ms
183	Mycelium Grove (rung 3)	132 ms

On a real GPU the post chain and resolution ladder are the dominant wins; the software renderer is shader-ALU bound, so its rung-3 number does not reflect fill-rate savings.

Variable frame rate (VFR)

The app runs a true variable frame rate driven by the live music stream (default on; --vfr off or --no-idle-render disables it, --benchmark forces it off). A musical activity score (energy + spectral flux + band flux) maps to render cadence through eased bands:

Activity score	Cadence
< 0.08 (silence)	20 fps
< 0.25 (ambient)	20 fps
< 0.50 (moderate)	33 fps
< 0.75 (energetic)	45 fps
else (peak)	60 fps

The score uses fast-attack/slow-release smoothing and band changes step at most one level per 400 ms, so cadence ramps smoothly instead of jumping. --min-fps / --max-fps clamp the range; pausing drops the render rate to 2 fps. The current band appears in the window title as VFR n.

Audio analysis off the realtime thread

All DSP (FFT, chromagram, RTA, cava bars, stereo metering, flux, beat detection, pitch) runs on a dedicated analyzer thread fed by a small bounded channel. The PipeWire process callback only accumulates samples and applies volume, so it never blocks other PipeWire clients (e.g. mpv) with DSP work or with the old O(N^2) autocorrelation pitch tracker. Pitch is now detected with an FFT autocorrelation (Wiener-Khinchin, O(N log N)) and can be computed every N chunks with --pitch-interval N. --debug-dsp logs analyzer timing (avg/p95/max of 50 chunks). The startup log reports the actual PipeWire capture source.

Psychoacoustic Engine & Musical Transitions

wpav features a real-time psychoacoustic audio-responsiveness engine inspired by advanced Music Information Retrieval (MIR) research:

• 6-Band Psychoacoustic Auto-Tuning: Sub (20-90 Hz), Bass (90-300 Hz), Mid (300-2500 Hz), Treble (2500-8000 Hz), Air (8000-16000 Hz), and Master Loudness.
• Dual-EMA Loudness Invariance: Dynamically normalizes band levels around 1.0 using fast-attack/slow-decay short-term envelopes (~50ms/180ms) and long-term averages (~12s) with noise-floor rejection. Visual dynamics scale consistently across quiet and loud music tracks without manual sensitivity tweaking.
• Multi-Band Transient Detection: Discrete onset tracking for Kick, Snare, and Hi-Hat with independent adaptive thresholds and sub-pixel edge sharpening.
• Musical Section Classifier: Identifies Ambient, Buildup, Drop, Groove, and Breakdown sections in real time using rule-based hysteresis or multi-state score evaluation.
• Drop- & Phrase-Aligned Auto-Transitions: Seamlessly aligns scene cuts with musical drops and structural phrase boundaries:
  • --transition-engine timer|musical|blend (default: blend)
  • --musical-transitions / --no-musical-transitions (enabled by default)
  • --classifier rule|score (default: rule)
  • --min-hold-seconds SECONDS (default: 5.0)
  • --transition-sensitivity MULTIPLIER (default: 1.0)
• Musical Motion Director Engine: Decouples underlying organic flow from percussive embellishments to eliminate transient glitching:
  • Base scene motions (camera paths, coordinate rotations, fluid advection, wave integrals) are driven by smooth, asymmetric multi-band envelopes (flow_levels), continuous soft-PLL groove tracking (groove_phase), and C¹ time-warp integrals (u_flow_bass_phase, u_flow_mid_phase).
  • Percussive transients (kicks, snares, hats) are routed exclusively to tasteful embellishments (lighting, specular hits, crest foam, sparks) and dynamic spring bounce.
  • Per-scene personality profiles (fluidity, structure, percussive affinity, drama) tailor responsiveness to every visualization.
  • Multi-director profiles selectable via --director or keys , / .:
    • conductor (default): Balanced adaptive hybrid with musical glides between flow and groove.
    • hypnotist: Deep fluid trance emphasizing oceanic flow and subtle accents.
    • percussionist: Tight metric structure with crisp accented geometry.
    • surrealist: Slow-cycling multi-minute mood waves with cinematic dynamic contrast.
  • Director-governed transition pacing: each director also choreographs when scenes change — a hold-time scale (patient in Ambient/Breakdown, leashed during a Drop), a scene-length scale (calm sections earn longer arcs that resolve), and a cut allowance that grants surprise cuts a credit budget (rising-edge drop credits; hard-cut surge threshold scales 0.65×–1.35× with allowance, 0.5 = legacy). Scene-arc completion is respected: rapid-fire cutting is reserved for drops and grooves instead of interrupting a scene's progression.
• 3D Traversal Transitions & Organic Dissolves: Instead of a flat crossfade, scenes blend along nuanced mathematical trajectories:
  • --transition-visual crossfade|traverse|morph|liquid|bloom|gyroid|wave|rotation|mobius (default: traverse; traverse evaluates scene perceptual similarity and musical drop/phrase triggers to choose the ideal flow, or force one style).
  • --transition-seconds SECONDS (override transition blend duration; default follows pacing mode, e.g. 5.0s slow / 3.0s flow).
  • Styles include Gyroid Gate (analytic TPMS front with chromatic pull), Wave Lens (refractive circular wavefront), 4D Rotation (hypersphere perspective projection), Möbius Fold (non-orientable half-twist sweep), Morph Dissolve (shared flow warp with fractal noise threshold), Liquid Flow (curl-advected fluid handoff), and Bloom Dissolve (luminous multi-scale threshold burn). The extra capture and composite passes run only while a transition is blending, so steady-state cost is unchanged.

Visual Modes

Visual modes change the shader-generated pattern independently of the palette:

Mode	Character
Aurora	Flowing audio-reactive ribbons
Nebula	Slow radial rings and haze
Orbit	Faster musical elliptical orbit bands
Lattice	A faster, trippy warped geometric grid
Plasma	Layered domain-warped fields
Kaleido	Seam-safe mirrored rays and breathing petals
Moire	Gentle interference patterns
Journey	Continuously morphing composite landscape
Tidal	Broad bass-driven currents
Bloom	Radial petals and a breathing center
Vortex	A slow spiral with a soft eye
Silk	Crossing low-contrast wave fields
Prism	Mirrored color facets
Drift	Floating domain-warped bands
Cathedral	Tall arches and columns
Mosaic	Liquid rounded-cell tessellation
Fluid	GPU-simulated dye with audio-driven force
Strings	Clean resonant string bank
Planets	Glowing orbital system
Molecules	Orbiting nodes and soft bonds
Constellation	Gravity-like bodies and luminous paths
Helix	Double-helix strands with cross links
Rabbit Hole	Logarithmic spiral tunnel
Singularity	Rotating accretion disk and event horizon
Pendulum	Double-pendulum motion
Fractal Garden	Iterated blooming fractal field
Fireflies	Orbiting particle swarm
Wonderland	Folding perspective corridor
Mandelbrot	Bounded escape-time coastline
Julia Bloom	Pulsing Julia attractor
Burning Ship	Warm absolute-value fractal
Orbit Trap	Rotating orbit-trap filaments
Newton Flow	Smooth Newton basin field
Fractal Coral	Repeated-folding branching reef
Roller Coaster	Banked rails rushing through a changing landscape
Starflight	Accelerating star streaks from a vanishing point
Ocean Speed	Underwater currents and forward-rushing caustics
Air Rush	Wind bands and converging flight streaks
Orbital Mechanics	Resonant bodies moving through a gravitational field
Molecular Dynamics	Spring-bonded particles in a force-driven molecule
Gravity Web	N-body constellation trails and gravitational lensing
DNA Helix	Perspective double helix with paired bases
Fractal Spin Garden	Iterated fractal folding spiraling into infinity
Fractal Bloom Spiral	Riskier rotating floral fractal with nested petals
Newton Turbulence	Swirling Newton basins with unstable boundaries
Newton Cascade	Layered Newton attractors cascading through scales
Pure Strings	Traveling-wave string instrument with resonant harmonics
Fractal Strings	Recursive folded strings for a deliberately trippy variant
Plucked Aurora	Physically inspired triangular pluck waves traveling along a ribbon
Fine Lattice	High-frequency fine grid with clean resonant intersections
Lattice Drift	Purposeful bent lattice with layered directional flow
Realistic Planets	Lit orbital bodies with rings, trails, and gravitational detail
Molecular Bonds	Spring-like molecular network with tension and collision response
Constellation Dynamics	Gravity-driven bodies with curved paths and changing links
Helix Bloom	Depth-shaded biological helix with luminous paired bases
String Fracture	Older-style recursive fractal strings with intense folded detail
String Fracture Bloom	Recursive strings opening into bright asymmetric fractal petals
String Fracture Drift	Folded string filaments carried through a slow directional field
Spin-In Fractal	Logarithmic recursive fractal spiraling toward infinitesimal detail
Fractal Emergence	A smooth field that progressively forms recursive fractal structure
Precision Aurora	Crisp layered ribbons with high-definition filament highlights
Crystal Lattice	Antialiased geometric crystal planes with shifting intersections
Particle Forge	Coherent particle orbits with bright trails and collision sparks
Orbital Bloom	Detailed resonant orbits blooming around a luminous central mass
Fractal Filaments	Recursive threadwork with sharp self-similar edges and flow
Chromatic Current	Layered streamlines with clear depth and continuous current motion
String Fracture Cathedral	Recursive string vaults with branching arches and bright filaments
String Fracture Vortex	Fractured strings spiraling through nested rotating scales
String Fracture Prism	Spectrum-dispersed recursive folds mapping each octave to a different palette region
Fractal Strings Cathedral	Crisp geometric arches and vaulted ceilings built from folded string foundations
String Fracture Spiral	Logarithmic spiral arms wrapping the recursive string field into a deep vortex
Fractal Strings Resonance	Multiple interacting string banks at different harmonics creating shimmering interference
String Fracture Weave	Perpendicular banks of recursive filaments interleaving like woven fabric
Fractal Strings Aurora	Sweeping vertical curtains of recursive folds that ripple across the entire field
String Fracture Inferno	Chaotic high-temperature folds with rapid rotation, turbulence, and flame-like dynamics
Fractal Strings Mandala	Radial mandala symmetry wrapping the recursive string field into concentric rotating rings
Cityscape Drift	Cool blue night skyline with slow parallax drift, scattered window lights, and smooth gradient sky
Cargo Bloom	Warm crimson organic forms blooming from a bright central core with deep surrounding shadow
Ridge Flow	Neutral fractal terrain ridges flowing like contour lines across a topographic landscape
Void Light	Vast near-black deep space pierced by sparse cool luminous points and faint scattered light rays
Fractal Strings Tapestry	Dense woven fabric of resonant fractal strings with perpendicular secondary threads
Fractal Strings Echo	Cascading harmonic trails where each recursive octave echoes into the next
Fractal Strings Veil	Translucent curtain-like layers of folded filaments sweeping across the string field
Fractal Strings Core	Deep recursive folds converging toward a bright central mass with ever-finer detail
Composer	Modern composable mode with dynamic waveform injection and warp displacement
Smoky Physics	Buoyant audio-fed smoke simulation with curling plumes
Smoky Fractal	Folded self-similar smoke with recursive vapor detail
Smoke Vortex	Rotating smoke rings and vortex wake
Jellyfish Physics	Soft-body jellyfish bell and simulated tentacle trails
Jellyfish Fractal	Nested jellyfish bells and self-similar tendrils
Cellular Growth	Game-of-Life-like audio-seeded biological colony
Growth Fractal	Recursive cellular lattice and branching colony
Coral Colony	Coral-like growth filaments layered over the living state
Neuron Development	Directional neuron and axon development field
Neuron Fractal	Recursive neurite branching and growth trails
Axon Forest	Dense developmental axon forest with audio-guided drift
Guitar 4-String	Four independently plucked, damped resonant strings
Guitar 6-String	Six-string guitar simulation with harmonic response
Guitar 8-String	Full eight-string resonant bank
Guitar Chord	Simultaneous multi-string chord excitation
Guitar Arpeggio	Sequential one-string-at-a-time picking across the guitar
Guitar Soundfield	Pluck energy radiating outward as concentric sound waves
Floral Phyllotaxis	Golden-angle spiral seed patterns with audio-reactive floret blooms
Petal Geometry	Layered Fibonacci petal symmetries with vein detail and center glow
Cactus Geometry	Ribbed cactus columns with areoles, spines, and succulent rosette overlay
Poincaré Disc	Hyperbolic {7,3} regular tessellation in the conformal unit disc with sub-pixel geodesic arcs and Mobius drift
Quantum Vortex Lattice	Abrikosov flux lattice of quantized vortices in a rotating superconductor with sub-pixel supercurrent streamlines
Raymarched Gyroid Prism	Triply periodic minimal surface (TPMS) with analytical normal gradient contouring and chromatic dispersion
Resonant Chladni Plate	High-frequency 2D nodal line acoustic plate physics with sub-pixel sand particle lines and anti-node vibrations
Cosmic Filament Web	Multi-scale cosmic web structure of dark matter filaments, Voronoi cluster nodes, and sparkling galaxies
Lichtenberg Fractal Arcs	High-voltage dielectric breakdown tree with recursive branching discharge leaders and crisp return-stroke luminescence
Vinyl Groove Chrono-Spiral	Photorealistic turntable deck with brushed plinth, 33/45 RPM strobe dots, modulated stereo cutting microgrooves, anisotropic sheen, vintage label, tonearm, and ruby stylus acoustic transduction ripples
Holographic Laser Turntable	Levitating optical crystal disc with tri-color laser scanning heads, 64-bar radial CAVA laser perimeter teeth, cylindrical holographic audio visualizer, and pitch f0 target reticle
Radial Polar Spectrogram Vinyl	360-degree rolling polar time-frequency spectrogram where the vinyl disc physically encodes historical playback audio, with live laser needle playhead, spark trails, and VU meters
Oscilloscopic Chladni Turntable	Spinning resonant Chladni plate with 2D modal Bessel vibration fields excited by chromagram and RTA bands, accumulating luminous cymatic sand particles, transducer tonearm, and center Lissajous phase scope
Cosmic Celestial Turntable	Galactic accretion disc turntable with logarithmic spiral arms, planetary orbital groove tracks with exoplanet nodes orbiting at Keplerian speeds, pulsar singularity spindle, and constellation tonearm
Retro Synthwave Turntable	80s Outrun aesthetic with scrolling 3D neon horizon grid, glowing synthwave sun, chamfered retro chassis, dual analog illuminated VU meters, neon magenta/cyan vinyl with sunburst grooves, and wireframe tonearm

Raymarched 3D Volume & Bubble Modes

Mode	Character
Bubble Film	Translucent raymarched metaball bubbles with thin-film iridescence and feedback history shining through the membrane
Glass Orbs	Opaque glass marbles with crisp specular glints that refract the on-screen history around each silhouette
Foam Cavity	Inside-out bubbles: a glowing solid wall carved into spherical pockets that deepen on kicks
3D Swarm	Fifty-six depth-faded luminous orbiters with true perspective projection, kick-driven cohesion, and treble scatter
Vent Plume	Hydrothermal deep-sea vent bubbles rising with buoyancy acceleration and heat shimmer
Sky Aerostats	Weightless translucent iridescent giant orbs drifting across twilight cloudscape
Morning Dew	Surface-tension liquid droplets trembling on plant leaf veins, casting caustics and sun-glints
Bowling Orbs	Heavy obsidian/chrome billiard spheres transferring momentum on reflective floor with bass shockwaves
Cosmic Boiling	Self-similar recursive inflationary Apollonian bubble foam expanding in infinite rhythm
Pigment Burst	Elastic color-filled bubbles that stretch and detonate into explosive radial pigment splatters
Magritte Mirages	Surrealist levitating mirror spheres reflecting infinite checkerboard vistas in harmonic gyration
Abyssal Biolume	Bioluminescent deep-sea jellyfish bubbles with pulsating internal organelles and electric cilia
Plateau Foam	3D Voronoi bubble foam lattice showing 120-degree Plateau-border iridescent soap film walls
Mercury Pearls	Liquid metal gallium beads rolling on magnetic substrate, fusing and snapping on transient flux
Bubble Cavern	Subterranean crystal geode cavern with floating luminous crystal orbs emitting bounce lighting
Orbital Cascade	Choreographed dance-flow spheres traversing a 3D trefoil knot in phase-locked musical harmony

Kinetic Travel & Performance Modes

Mode	Character
Tunnel Run	Analytic flight through a segmented tunnel with hashed wall styles, banking snares, and kick-fed thrust
Ocean Soar	Low-altitude flight over Gerstner-dispersion deep-water swells with Fresnel sky reflection, sun glitter, and crest foam
Blast-Off	Cyclical mission from floodlit pad through max-Q buffet and stage separation to an orbital sunrise
Wormhole	Infall through a Kerr-style black hole - lensed star arcs, photon ring, frame-dragged accretion, chromatic throat, rebirth bloom
Juggling	True siteswap cascade kinematics with beat-locked throws, upgrading from a 3-ball to a 5-ball pattern with musical intensity
Contact Juggling	A refractive crystal sphere rolling palm circles, butterflies, and waterfalls while bending the scene's own light-trail history through its body
Rube Goldberg	A looping chain-reaction machine - chute, lever, dominoes, pendulum, gears, balloon pop, pinwheel, bell - that rewinds itself every cycle

Elemental, Cosmic & Relativistic Modes

Mode	Character
Ember Veil	Rising turbulent embers with convective heat trails and combustion smoke
True Fire	Dynamic domain-warped volumetric combustion flame with incandescent core
Water Veil	Overlapping refractive aquatic caustic networks with sunbeam glints
Fireworks	High-altitude pyrotechnic aerial shells with explosive ballistic particle sparks
Neon Plasma	Relativistic electric arc discharges with high-frequency lightning crackle
Lava Lamp	Raymarched buoyant molten wax blobs circulating in a heated column
Star Drift	Multi-layer stellar parallax field with transient relativistic warp streaks
Nebula Veil	Volumetric interstellar emission nebula gas clouds excited by stellar radiation
Galaxy Spiral	Logarithmic spiral galaxy disk with core bulge and stellar dust lanes
Black Hole	Gravitational lensing accretion disk around a Schwarzschild event horizon
Pulsar	Relativistic rotating neutron star with sweeping synchrotron radiation beams
Mitosis	Biological cellular division showing metaphase spindle elongation and pinching
Heart Field	Mathematical cardioid manifold pulsating with biomechanical rhythm and ECG trace
Bubble Universe	Multiverse bubble nucleation with thin-film quantum membrane interference
Digital Rain	Cascading cryptographic phosphor glyph matrix streams with lead-character glare
Virus Bloom	Raymarched coronavirus capsid with glycoprotein spikes and satellite virions
Smooth Life	Continuous cellular automaton evaluating Gaussian ring neighborhood potentials
Flow Ribbons	Laminar fluid streamlines weaving in phase-locked sinusoidal harmony
Collision Chamber	Counter-propagating relativistic particle streams colliding with energy release
Drum Membrane	2D circular acoustic vibrating membrane displaying modal Bessel eigenmodes
Hopf Fibration	4D hypersphere Villarceau circle stereographic projection into nested tori
Möbius Flow	Non-orientable single-sided 3D manifold with circulating iridescent energy
Etcher Lines	Classical architectural cross-hatch engraving morphing between 3D solids

Scientific DSP Studio Modes

Launch with --dsp or --dsp-only to explore the scientific audio measurement studio:

Mode	Character
Master DSP Dashboard	Broadcast telemetry console: 3-band spectral display, stereo goniometer, correlation bar, 31-band RTA, and true-peak/RMS master meters
HD Log Spectrogram	High-definition logarithmic spectrogram with rolling history, ISO octave grid lines, live spectral curve, and transient novelty flash
3D Waterfall Spectrogram	48 isometric perspective depth slices receding into distance with continuous rolling frequency ridges and perspective grid floor
12-TET Chromagram Wheel	Circular 12-tone equal temperament pitch class harmonic wheel, Circle of Fifths polygon linkages, and f0 fundamental pitch tracking needle
Stereo Vectorscope & Goniometer	Continuous 128-segment Lissajous electron beam trajectory, calibrated polar reticle, phase correlation meter, and tri-band energy perimeter rings
31-Band 1/3-Octave RTA	Standard 31-band ISO 1/3-octave real-time acoustic analyzer with LED ladder bars and floating peak-hold needles
CAVA Dynamic Spectrum	64-band continuous responsive frequency spectrum with floating peak indicators, floor mirror reflections, and transient onset glow
Polar Radar Spectrogram	360-degree radial radar sweep displaying circular spectrogram history with persistence decay and range graticules
Mel & Formant Analyzer	Dual-view perceptual analysis: Mel-scale auditory filterbank envelope on top, linear overtone harmonic comb on bottom
Transient Flux & Novelty	Real-time onset novelty flow ribbons and radial transient shockwaves driven by spectral flux detection
CQT Harmonic Note Cascade	84-semitone Constant-Q waterfall and live interactive piano-roll HUD with chromatic note classification and octave grid lines

Educational & Living Documentation Mode

wpav includes a built-in educational engine that explains the scientific and artistic theory behind every scene:

• Enable at launch with --educational, --edu, -e, or --scene-info.
• Choose glossary density with --edu-glossary MODE: selfcontained (every card defines every shared term), inlinegloss (one-line glosses plus a primer), or sparse (primer only; default inlinegloss).
• Toggle dynamically at any time by pressing e or i in the terminal or visualizer window.
• For practical & scientific DSP views, it outputs "🔍 How to read it" (interpreting axes, phase correlation, octave bands, formant combs, transient metrics) and "📐 The math of it" (exact equations such as STFT, ANSI S1.11 filterbanks, CQT, Lissajous phase correlation, Mel scale, Hilbert transform, Chladni eigenmodes).
• For abstract & synesthetic views, it outputs "👁 How to feel it" (somatic and perceptual guidance on experiencing geometry, fluid dynamics, reaction-diffusion, and relativistic curvature) and "📐 The math of it" (the underlying physical simulation formulas, Navier-Stokes vorticity, Poincaré hyperbolic metric, TPMS gyroids, Mandelbrot fractals, FitzHugh-Nagumo dynamics).
• For complete offline reading, see SCENES_AND_PRESETS.md.

The modes are intentionally restrained rather than using a full-screen white beat flash. Tab and Shift-Tab cycle all 196 standard and 3D modes (or all 207 modes with --dsp) without changing the palette. Changing modes smoothly traverses or dissolves between the outgoing and incoming shader fields instead of replacing the frame abruptly. The travel scenes are more kinetic and are especially effective with --transition flow.

Sensitivity starts at 1.75x and is bounded from 0.25x to 3.0x. It changes temporal speed, simulation force, and pulse response without changing the topology of the patterns. The current mode and sensitivity are shown in the window title.

Audio response profiles reshape how strongly the music drives every scene. Ambient keeps motion smooth and gentle, Balanced is the default, Dynamic sharpens beat and treble punch, and Immersive couples energy and bass into almost every motion term. Cycle them with [ and ] (SDL or terminal) to match the current track's character without changing the visual mode.

The Fluid, smoke, jellyfish, cellular-growth, and neuron modes are portable OpenGL 3.3 fragment-shader simulations using ping-pong RGBA8 state textures. It avoids vendor-specific compute features and runs on Intel, AMD, and NVIDIA OpenGL drivers. Audio acts primarily as a smooth force and color envelope, so the geometry flows instead of snapping on every beat. A shared decaying beat envelope and faster music phase keep the scenes moving with the track, while preserving continuous motion between detected beats instead of snapping on each transient.

Development

Everything outside of cargo is installed by ./scripts/build.sh (apt table for Debian/Ubuntu, --doctor to triage a broken machine, --completions bash|zsh for tab completion). The project deliberately has no hosted CI; the full check ritual is cargo aliases declared in .cargo/config.toml:

cargo fmtc    # formatting check (cargo fmt -- --check)
cargo lint    # clippy over all targets with warnings denied
cargo test    # unit suite + the 1000-line source budget test
cargo smoke   # real X11/Wayland/PipeWire/GL tests (Xvfb + headless weston)

cargo smoke boots the actual display and audio stack: each scenario opens a GL context, renders a few frames, and asserts on the app's own log lines (including an end-to-end PipeWire capture check). It also runs the in-suite GL surface test that drives the real apply_command/panel-action surface — shader compile, render, tunable/preset/crossfader state transitions — against a self-hosted Xvfb. It skips automatically when xvfb-run/weston/pw-cli are missing, and honors WPAV_STRICT_WAYLAND=1 on machines where a clean Wayland shutdown is expected. Run ./scripts/build.sh --check to execute the whole ritual in order, or ./target/release/wpav --benchmark for per-mode timings. Coverage is available with cargo cov (cargo-llvm-cov test --summary-only).