Kaleidoscope Enhanced — Music Visualizer

A real-time, audio-reactive kaleidoscope / tunnel visualizer for Windows and Linux. It listens to whatever is playing on the system (Spotify, browser, foobar2000, a live mic, …), analyses it in real time, and drives a huge library of GLSL shaders whose motion, colour and structure follow the music's rhythm, timbre and mood — beat-driven Rock/Pop/EDM and beatless ambient/drone alike, calming down automatically for speech.

⬇ Download the latest release — no Qt / Visual Studio needed, just run the installer or unzip the portable build. See Quick start.

Four of the 865 scenes in the scene catalogue — a photograph folded into a kaleidoscope, a loaded 3D model used as a mirror, one used as a shadow puppet, and a hardware-tessellated fjord under the northern lights.

Highlights

• 865 scenes + 29 overlay effects + 110 scene transitions, all audio-reactive and image-driven — see the scene catalogue.
• Real signal analysis (beat/onset detection, key & mood, song-structure tracking) drives the visuals, not a generic FFT bar graph — see how it listens to the music.
• A photo library and 157 3D models it can fetch and install for you — see Extra content.
• Synced lyrics, artist photos and the official music video can play alongside the visuals — see Optional online features.
• Control it from a phone: a web remote with zero-config LAN pairing, plus an Android app — see Remote control.
• Stereo-3D output, MIDI control, Spout output for OBS/VJ software, a German or English UI, and an unattended kiosk mode with a crash watchdog.

---

Contents

• Quick start
• Extra content: photos and 3D models
• Controls
• Mood detection, and OSC output for VJ tools
  • Score cues: letting a generator say where the bars are
• Presets
  • Reviewing the shader library
• Recording
• Setup tool
• Remote control
• Optional online features
• Language
• Build
• Deployment
• Project layout
• Credits and license
• Further reading

---

Quick start

Download the latest release:

• KaleidoscopeVisualizer-Setup.exe — regular installer, Start-menu shortcuts for the visualizer, the Preset editor and the Setup tool.
• KaleidoscopeVisualizer-portable.zip — unzip anywhere, double-click Kaleidoscope-starten.bat. No installation, nothing written outside the folder.

The installer offers the photo and model packs as ticked options and installs them for you; see Extra content for the portable build and for pointing it at your own pictures. It runs without them either way. Press h any time for the full keyboard reference in-app.

---

Extra content: photos and 3D models

The scenes that fold photographs need photographs, and some scenes place a real 3D model in the shot — a station against a nebula, a capital ship making a slow pass, a chrome torus on a plinth. Both are optional downloads rather than part of the installer: together they run to about 2.5 GB, thirty times the program, and most of it is of no use to someone who only wants the classic visualizer.

The installer offers all four packs as ticked options and puts them in place for you. Afterwards — or for the portable build, which has no installer — Download extra content in the Setup tool does the same. By hand: unpack into the program's Images and Models folders and restart.

Pack		Contains
Photos	977 images, 593 MB	agate, rust, pigment, soap film, sediment, aurora, craquelure, woven fibre
Models: ships	77 models, 699 MB	capital ships, freighters, couriers, drones
Models: stations	30 models, 259 MB	space stations — the six station families
Models: objects	62 models, 517 MB	sculptures, hi-fi gear, sea creatures, eroded rock, gongs, pierced lattices, and the real-object scenes: rocket and pad, peacock, organ, aqueduct, bells, candles, gears, pendulums, metronomes, seismograph, foundry

Nothing breaks without them. A scene whose model is missing is skipped when the catalogue is read, the photo scenes fall back to a procedural texture, and the startup log says how many and which folder it looked in. Once the models are there, every genre preset simply has more scenes to draw from.

All of it is generated for this purpose, so there are no rights questions, no faces and no recognisable subjects to be mangled by a mirror. The models were mostly generated FOR the scene family that uses them, which is why the fit is close: the resonant bodies are thin-walled because ModalVibration displaces along a plate's thickness, and the pierced lattices exist because a shadow play wants a complicated shadow.

Your own pictures instead: set Photo folder in the Setup tool. That writes imageDirectory into kaleidoscope_settings.ini, which outranks the presets — the right place for it, since Presets\*.xml are generated and would lose the change. Subfolders are searched; .jpg, .jpeg and .png are recognised. For one run only, Kaleidoscope.exe -f <folder> beats both. What actually suits this program — format, tone, contrast, composition — is written down in docs/photo-set-spec.md, with a checker that scores any folder against it (Tools/check_image_set.py).

Building the packs yourself, from folders you have filled:

.\Tools\make_image_pack.ps1
.\Tools\make_model_pack.ps1

---

Controls

Key	Action
Q	Quit
Esc	Quit after asking (closes the help box first if it is up)
Enter, Menu	Open the on-screen menu (remote control, see below)
media keys	⏭/⏮ next scene, ⏯ freeze, ⏹ blackout
h	Toggle the on-screen help (keyboard reference)
0	Open/close the preset menu (see below)
↑ ↓	Move the cursor in whichever overlay menu is open
Enter	Take the highlighted entry (cross-fades)
type	Narrow an open menu to matching entries
wheel	Scroll an open menu; click picks, click outside closes
i	Toggle the live audio-feature overlay (incl. FPS)
d	Choose the audio source (output / microphone) — overlay
↑ ↓	Also drive the audio-source cursor while that overlay is open
p	Toggle the now-playing track title display
w	Lyrics (Internet): off / credits scroll / karaoke — on by default
Shift+w	Toggle the karaoke kinetic line-slam pop-in (off by default)
o	Artist images (Internet): rotating inset + colour grade — on by default
n	Manually advance to the next effect (musical scene change)
v	Show the active shader names (debug overlay)
l	Toggle the stage lamps / light show (corner cones etc.)
[ / ]	Reactivity — less / more audio-driven motion
, / .	Trails — shorter / longer feedback trails
- / =	Mood — weaker / stronger colour grading
; / '	Latency — visuals earlier / later vs. the heard beat
b	Blackout — soft fade to black and back (VJ)
e	Freeze — hold the picture (VJ)
t	Tap tempo — tap the beat to override tempo detection
u	Pin — hold the current effect (no automatic switches)
f	Favourite the current effect (persistent selection bonus)
Space	Mark / unmark the current scene (shortlist for review)
Shift+Space	Save all marked scenes as the Marked preset
z	Stereo 3D — cycle off / side-by-side / top-bottom / anaglyph
c / m	Stereo depth — weaker / stronger
a	Toggle auto-config-by-mood (auto-switch configs)
g	Toggle adaptive render scale (auto-FPS)
j	MIDI learn — bind knobs/pads to the controls
r	Toggle recording (full render resolution → mp4)
y / x	Arm the instant replay ring / save it as an mp4
k	Save the current look and UI state as the startup default
s	Save a PNG screenshot of the window
mouse drag	(when not fullscreen) trackball / interaction

Remote control (HTPC)

Everything can also be reached from a hardware remote on a living-room PC. Such remotes send ordinary keys: arrows, OK (Enter), Back (Back or Backspace), Esc, usually a Menu key, and the media keys.

OK or the Menu key opens the on-screen menu, drawn large enough to read from the sofa. ↑/↓ select a row, OK opens a submenu, runs an action or flips a switch, ←/→ change sliders and choices (and → also opens submenus), Back goes one level up, Esc closes it. It hides itself after 20 seconds without a key.

Menu	Contains
Presets	every preset; the running one is marked, OK switches to it
Scene	next scene, hold scene, favourite, mark, save marked
Picture & overlays	blackout, freeze, stage lamps, now-playing title, lyrics mode, line slam, artist images, music videos
Fine tuning	reactivity, trails, mood colour, latency lead (sliders)
Audio	audio source, tap tempo
Stereo 3D	mode, depth
Automation	pick preset by mood, adapt resolution
Capture	record, instant replay armed / save, screenshot
Info & diagnostics	shader names, audio analysis + FPS, keyboard shortcuts
System	language, save settings as default, install update (when one is found), quit

The menu works on the same state as the keys and the web remote, so all three always agree. Esc outside the menu asks before quitting, because on a remote it sits right next to Back; Q on a keyboard still quits at once. The keyboard shortcuts all stay as they were -- the menu is for the remote, the letters are for debugging and live work.

Both overlay menus — the preset picker (0) and the audio-source picker (d) — scroll, so they reach entries the digit keys cannot. Anything past the ninth used to be unselectable, and in the audio menu it was not even drawn: the hidden-preset debug switch and a saved Marked preset both push the preset list past nine, and a machine with a few virtual audio cables has well over nine sources. Each opens on the entry that is currently in use, ↑/↓ (plus PgUp/PgDn/Home/End) move the cursor, Enter selects, and Esc (or 0 / d) closes without changing anything. The highlight bar is where Enter would take you; the marker shows what is actually in use.

Typing narrows a menu to entries containing what you typed — useful once the device list runs past twenty. Backspace takes a character back, Esc clears the filter first and closes on the second press. The mouse works too: the wheel scrolls, a click takes an entry, a click outside closes.

1–9 used to jump straight to a preset and are now unbound: the menu reaches every entry, so nine keys no longer have to be spent on a shortcut that only covered part of the list.

Double-click toggles fullscreen. It used to quit the app outright, which made a slip of the hand end the show; quitting is Esc or q.

Press k to persist the tuning keys (plus render scale) to kaleidoscope_settings.ini, so they're restored next launch. The i overlay shows the current FPS — handy for tuning render scale on a target machine.

One key in that file has no hotkey: calmMotion (default true) keeps the host's virtual camera completely still — no downbeat punch-in, no kick shake, no bar sway, no drop rewind, no bass shockwave, no beat-pumped trail warp. It is on by default because whole-frame jolts make some viewers ill; set calmMotion=false for the older, livelier camera.

---

Mood detection, and OSC output for VJ tools

The analyzer estimates the music's mood on Russell's two axes — valence (positive/negative) and arousal (calm/energetic) — and uses it everywhere: scene selection is biased toward matching mood tags, pacing follows arousal, and a global colour grade follows the empirically grounded mapping canon (happy = warm and vivid, sad = bluish and muted, dissonant = harder edges). Every ingredient was measured against an 80-track corpus rather than guessed.

Other software can consume the analysis live: set oscPort in the settings (or the Setup tool) and the visualizer streams OSC/UDP — /mood/valence, /mood/arousal, /mood/quadrant, /beat, /audio/bands, /tempo/bpm and more — to TouchDesigner, Resolume, Max/MSP or anything else that speaks OSC.

The full story, with the literature and the measurements, is in docs/mood-and-mapping.md.

Score cues: letting a generator say where the bars are

Everything above is an estimate of music the visualizer only ever hears. A software generator playing its own composition does not have to be guessed at: it knows the bar line exactly and it knows a drop is coming before it lands. If one is driving the sound, it can say so over OSC/UDP, and the scheduler stops guessing:

[General]
cuePort=9000
cueBind=0.0.0.0

cuePort=0 (the default) means the feature is off and nothing listens. cueBind is the interface — 127.0.0.1 for a generator on the same machine, 0.0.0.0 to let one on the LAN (a headset, say) reach it.

Five messages are understood, and nothing else on that port is acted on:

message	effect
/phos/bar i	the bar line a due scene change is quantized to
/phos/beat i	traffic only; a beat never causes a cut
/phos/section s f	a section starts (type and energy 0..1) → a scene change
/phos/drop	a drop lands on this instant → a hard cut
/phos/key s	the key from here, e.g. F# Phrygian

The cues feed the same two rising-edge triggers the audio analysis has always fed, so everything that guards them still guards them: a cue that lands during a cross-fade cannot retarget it, a cut still has its minimum solo, and camera, zoom and rotation remain untouched by anything the music does. If the sender stops — or was never there — the audio analysis takes over again after two seconds and the program behaves exactly as it did before. Kaleidoscope.exe -q checks all of that and exits 0 or 1, without opening a window.

The sender this was built for is the Phosphene psytrance generator (its docs/PLAN.md, section 8.3); the wire format is plain OSC 1.0, so anything that can send those five messages works.

Presets

Presets\*.xml define which shaders are in rotation, their probabilities, mood tags, and the photo folder (ImageDirectory, shipping as ..\Images) they draw on. These files are GENERATED, so change the folder in the Setup tool rather than in here — see Extra content. Switch between them with the number keys. Included presets:

• Allround — the full modern arsenal, balanced; a safe default
• Club — aggressive & bright: tunnels, godrays, lattices, analyzers
• Ambient — calm drift: fluid ink, lava, drones, liquid light shows
• SpaceAmbient — sci-fi & deep space: starships, planets, space stations, nebulae, black holes, alien worlds
• Galerie — the photos star: kaleidoscopes, image tunnels, gentle folds
• Psychedelic — breathing fractals, pills, chrome, plasma, mushrooms
• Noir — dark, high-contrast: noir fractals, dark tunnels, deep drones
• Komplett — every scene and overlay in one rotation, mainly used as the master reference the other presets and the editor start from

Every scene re-rolls its own parameters each time it's picked, so one shader yields many different looks over a session rather than repeating itself identically.

Browse the full scene catalogue — all 865 scenes, 29 overlay effects and 110 transitions, each with a description and three example frames. A printable Katalog.pdf ships with every release.

Building your own presets: PresetEditor.exe (its own small Qt app, bundled with every release) edits Presets\*.xml with a live shader preview — browse every scene, add it to a preset with its timing/probability, tune per-parameter ranges against a real preview, and save. It also carries the project's self-tests (--validate, --roundtrip, --transcheck, --render) used to catch broken presets and transitions before they ship. Build it with msbuild PresetEditor\PresetEditor.vcxproj /p:Configuration=Release /p:Platform=x64.

A handful of shaders (ChromeDreams, DiscoGodrays, FlowingWires, FractalBloom, InsideSystem, NeonTubes, PsychedelicPills, SphereGrid, TheCore, Vortex, Voyager) are adapted from community shaders by kishimisu on Shadertoy, CC BY-NC-SA 4.0 — see Credits and license.

---

Reviewing the shader library

Two pieces that work together when you want to look at the shaders rather than enjoy them:

• TestAlle — the review bench: every scene, 25 s each, walked in a fixed order (all 2D scenes alphabetically, then all 3D ones), with FxPlain as the only overlay and Crossfade as the only transition, so nothing is ever painted over the scene you are judging. It also brings its own silent audio (AudioFile= in the preset), so the same shader looks the same on every pass — live audio would make each run different, which is the one thing a review must not do. Regenerate it after adding shaders:

  python Tools/make_genre_configs.py

  The ordered walk and the 8 s come from the preset's Test name prefix, which switches the engine into review mode — keep the prefix or it silently goes back to random selection. Start it with -c TestAlle; it is hidden from the normal preset list on purpose.

• Marking — press Space while a scene is up to shortlist it, and Shift+Space to write every marked scene to Presets\Marked.xml as a playable preset. Both are on the remote too, so you can mark from a phone while the show runs on a TV. Marks live in kaleidoscope_settings.ini and survive restarts, so an inspection pass can span several sessions. The v overlay shows whether the current scene is marked.

So: run TestAlle, tap Space on anything that looks wrong, then Shift+Space and switch to Marked to work through the shortlist.

Recording

Recording captures at the full render resolution (not a fixed 720p) and encodes once, in hardware where available: raw frames are piped straight into a running ffmpeg, and on stop the video is copied into the container beside the audio rather than re-encoded. ffmpeg must be on the PATH; without it the recorder falls back to writing JPEG frames plus a make_video.bat you can run by hand.

The encoder is probed at runtime, preferring the discrete GPU's block, then Intel Quick Sync, then software. The output codec defaults to H.264 — the one every player and editor opens — and can be changed in the Setup tool or via the videoCodec key in kaleidoscope_settings.ini:

videoCodec	Notes
h264 (default)	Plays everywhere
hevc	Roughly 2.5–3× smaller at the same quality; needs the HEVC extension on Windows
av1	Smallest in principle, but on NVIDIA hardware HEVC beat it on both size and quality in our measurements

If the requested codec has no working encoder on the machine, it says so and falls back to H.264 rather than failing the recording. KALEIDO_VIDEO_CODEC overrides the setting for one run, KALEIDO_VIDEO_ENCODER forces one specific encoder (still verified before use).

---

Setup tool

KaleidoscopeSetup.exe (Start-menu shortcut Setup, or Setup-starten.bat in the portable build) is a small standalone editor for kaleidoscope_settings.ini — the optional extras have grown numerous enough (lyrics, artist images, music video, language, web-remote port, render tuning, …) to deserve a proper on/off panel instead of hunting through keyboard shortcuts. Changes are saved to the same settings file the main app reads on startup and take effect the next time it launches, except the language dropdown, which retranslates the Setup tool's own form immediately so you can see the result before saving.

Download extra content lives here: tick the photo pack and whichever model packs you want, and it fetches them from the release page and unpacks them into Images\ and Models\. Packs already on disk show as installed and are unticked, so a second visit does not propose re-downloading two gigabytes. This is the portable build's route to them, since it has no installer.

Photo folder lives here too, and this is the only sensible home for it: the presets carry a default (..\Images) but they are regenerated from the catalogue, so a path typed into them would not survive. Leave the field empty for the bundled images.

Debug: show hidden presets puts Komplett and the TestAlle review bench back into the menu, onto the digit keys and into the remote, so you can reach them without a command line. They are out of the way by default because one is a reference catalogue and the other an inspection bench — neither is something to land on while enjoying the show. The same switch is one line in the ini if you would rather not open the tool:

[General]
showHiddenPresets=true

The settings file is resolved relative to the working directory, one level up from the exe: Release\Kaleidoscope.exe reads the copy in the repository root, the packaged bin\Kaleidoscope.exe the one in the package root. A copy sitting next to the exe is never read. The startup log names the file it actually used (Settings: <full path>), so check there first if an edit seems to have no effect.

Build it with msbuild SetupTool\SetupTool.vcxproj /p:Configuration=Release /p:Platform=x64 (no GL/audio dependency — a plain Qt Widgets app).

---

Remote control

A phone-friendly web remote (-t <port>, on by default at http://<pc>:8080/) gives you a live preview image, preset buttons, next-effect, blackout, favourite, mark/save-marked, replay, a scene browser you can tap straight into, and sliders for reactivity/trails/mood/latency — plus all the toggles from the Setup tool (lyrics mode, artist images, music video, auto-preset, auto-scale, …). LAN convenience only — no auth, don't expose it to the internet.

Zero-touch pairing: the running instance broadcasts itself on the LAN (UDP discovery), so a client never needs the PC's IP typed in by hand. Several PCs or several instances on one PC show up as a picker.

Android app (AndroidRemote\, build instructions) wraps the same remote in a fullscreen WebView with its own icon and auto-discovery — no typing an address, and it never needs updating when the remote grows new controls, since all the logic lives on the PC. Requires Android 8.0+; allow Kaleidoscope.exe through the Windows firewall (private networks) the first time so the phone can reach it.

---

Optional online features

All on by default, all individually switchable from the Setup tool or the web remote, all cached locally so a repeat play needs no network:

• Now playing (p): the track title/artist is woven through the picture with one of 24 reveal styles, matched to the music's mood. Reads the Windows system media session (Spotify, browsers, most modern players); foobar2000 needs its free Media Controls component; VLC is read from its window title as a fallback.
• Lyrics (w): synced lyrics fetched from a fallback chain of free services (no API key), shown as a scrolling credits band or karaoke-style with the active line highlighted.
• Artist images (o): photos of the current artist, fetched and deduplicated from a few free services, rotating as a small inset with a colour grade pulled from the image.
• Music video: for tracks under 20 minutes, the official video is searched on YouTube (matched by duration and channel, official-video scoring) and, if found, downloaded once via yt-dlp and played in sync in the same corner artist images use. Needs yt-dlp on PATH; the app runs normally without it, it just skips this one feature.

---

Language

The UI (on-screen overlays, the web remote page, and the Setup tool) speaks German or English, switchable from a dropdown in the Setup tool — German is the default. The Android app isn't part of that switch; it follows the phone's own system language, the standard Android behaviour.

---

Build

Windows is the reference build and the only one the releases are made from. Linux and macOS build from CMake; see below.

Requirements

• Qt 6.11 (kit msvc2022_64), installed at C:\Qt\6.11.1\msvc2022_64
• Visual Studio 2026 (or 2022) — platform toolset v145, target x64

Visual Studio: open Kaleidoscope.sln, select Release | x64, build. QTDIR defaults to C:\Qt\6.11.1\msvc2022_64 (set in the project); override it if your Qt is elsewhere.

Command line

$env:QTDIR = "C:\Qt\6.11.1\msvc2022_64"
cmd /c '"C:\Program Files\Microsoft Visual Studio\18\Community\VC\Auxiliary\Build\vcvars64.bat" && msbuild Kaleidoscope.vcxproj /p:Configuration=Release /p:Platform=x64'

Qt Creator — Kaleidoscope.pro mirrors the VS project, so the code can also be browsed and built from Qt Creator with a Qt 6 / MSVC kit; the VS project remains the primary build (it also runs the auto-deploy).

Run — the exe needs the Qt 6 DLLs on PATH (or run windeployqt):

$env:Path = "C:\Qt\6.11.1\msvc2022_64\bin;" + $env:Path
.\Release\Kaleidoscope.exe                    # windowed 1920×1080
.\Release\Kaleidoscope.exe -b                 # fullscreen (2nd monitor if present)
.\Release\Kaleidoscope.exe -c darkambient -s 0.5   # named config, half render scale

Command-line options

Option	Meaning
-b	Start fullscreen (2nd monitor if present)
-s <factor>	Internal render scale 0.25–2.0 — lower for weak GPUs, adapts automatically at runtime (key g)
-c <name>	Start with the named configuration (e.g. darkambient, normal)
-m <index>	Fullscreen on monitor <index> (0-based; implies -b)
-l	Log to kaleidoscope.log instead of the console (kiosk)
-r	Start recording immediately on launch
-w <wav>	Offline: analyze this WAV instead of capturing live audio (test)
-o	Spout output: publish the frame as sender "Kaleidoscope"
-t <port>	Web remote port (default 8080; -t 0 disables it)
-x <wav>	Batch render: record this WAV to an mp4, then exit
-i <sender>	Spout input: a live sender replaces the photos
-v <path>	Play a video (or folder of videos) as the image source
-3 <mode>	Stereo 3D: sbs, tb or ana(glyph)
-f <dir>	Photo folder for this run (outranks the Setup tool's setting)
-h	Print usage and exit

For an unattended installation/kiosk, combine -m, -c, -s and -l; the app suppresses the screensaver/standby while it runs, and the packaged fullscreen launcher restarts it automatically after a crash (5 s delay, gives up after 5 rapid crashes in a row). If the default output device changes (headphones unplugged, outputs switched), audio capture reconnects on its own — no manual restart needed. A missing image folder or Presets folder degrades gracefully (fallback texture / clear error) instead of crashing.

Shaders and Presets\*.xml load from the exe's parent folder, so run it from Debug\ / Release\.

Linux and macOS

Kaleidoscope.vcxproj stays the Windows build; everywhere else there is a CMakeLists.txt, which refuses to configure on Windows so the two cannot drift apart.

Debian/Ubuntu:

sudo apt install qt6-base-dev qt6-base-dev-tools qt6-multimedia-dev \
                 libgl1-mesa-dev libglu1-mesa-dev libpulse-dev cmake

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j

The program looks for its assets one level above the working directory, the same convention the Windows package uses, so run it from a subfolder: cd build && ./Kaleidoscope.

What differs from Windows:

	Linux	macOS
Audio capture	the default sink's PulseAudio monitor (PipeWire's pulse server serves it too)	needs a virtual loopback device (e.g. BlackHole) plus PulseAudio; without one, use -w/-x
Compute-shader effects	yes (OpenGL 4.3)	no — macOS froze OpenGL at 4.1, so those effects take their fragment fallbacks
Spout in/out (-o, -i)	no — Windows-only technology	no
Track title / lyrics / artist images	no — these read the Windows now-playing service	no
MIDI input	no	no

Everything else — the full scene catalogue, the 3D models, recording, the web remote, the OSC output — is the same.

macOS is untested: the code compiles for it and the platform branches are written, but no one has run it on a Mac yet.

---

Deployment

deploy.ps1 builds a fully self-contained package that runs on any 64-bit Windows PC without Qt or Visual Studio installed:

powershell -ExecutionPolicy Bypass -File .\deploy.ps1 -Build

This produces dist\KaleidoscopeVisualizer\ (verified to run with Qt removed from PATH) and dist\KaleidoscopeVisualizer-portable.zip. If Inno Setup is installed, it also compiles installer.iss into dist\KaleidoscopeVisualizer-Setup.exe; otherwise build that later with ISCC.exe installer.iss. Both the Preset editor and the Setup tool are bundled automatically when their own Release builds exist.

---

Project layout

Top-level folders:

• Source\ — the C++ core: audio capture/analysis (AudioAnalyzer), now-playing/lyrics/artist-image/video fetching (NowPlaying, TrackMedia, VideoPiP), MIDI, the render pipeline (RenderPipeline, EffectShader), config loading, the web remote (WebRemote), Spout I/O, and the shared UI-string table (Strings).
• Scene2D\ / Scene3D\ — 352 + 241 scene shaders (fragment-only effects vs. real vertex/geometry/tessellation-shader 3D scenes).
• FX\ — 29 full-time overlay passes (incl. FxPlain, the neutral pass-through most of the time uses).
• Transitions\ — 83 shaders that blend outgoing → incoming scene on a scene change.
• Engine\ — internal pipeline passes (mood grade, feedback trails, bloom, the GPU fluid/reaction-diffusion/smoke simulations, compute kernels).
• PresetEditor\ and SetupTool\ — the two standalone companion tools (see above, above).
• AndroidRemote\ — the Android remote app (no Gradle; plain SDK tools).
• Presets\*.xml — presets; ThirdParty\SpoutGL\ — vendored Spout2 SDK; docs\ — this repo's documentation and the scene catalogue; Tools\ — verify.ps1 (smoke/roundtrip/transition self-tests) and the catalogue/icon generators.

Full engine architecture and per-technique notes (OIT, shadow maps, compute → indirect draw, tessellation, …): docs/engine-internals.md.

---

Credits and license

MIT, with one exception: the eleven adapted Shadertoy shaders named in Presets remain under kishimisu's original CC BY-NC-SA 4.0 (non-commercial, share-alike); see LICENSE and each file's own header.

External services used by the optional online features: lyrics from LRCLIB, NetEase, and lyrics.ovh; artist images from Deezer, TheAudioDB, and iTunes; music videos via yt-dlp against YouTube; Spout output/input via the vendored Spout2 SDK (BSD-2).

Built and tested on Qt 6.11.1 / Visual Studio 2026 (toolset v145), x64, NVIDIA OpenGL 4.6. Rendering targets OpenGL 4.3 core; all shaders are GLSL 330 core.

---

Further reading

• docs/engine-internals.md — how the audio analysis actually works (beat/onset/key/mood/section detection, the mapping layer), and per-scene engineering notes (graphics techniques, debugging stories) for contributors and the curious.
• docs/Catalog/Katalog.md — every scene, overlay and transition with a description and example frames.