Stims

Open toil.fyi and something is already moving — the first-run preset animates on load, audio-silent until you bring music. A deep link skips straight into a full session: demo audio auto-starts and the named preset is playing, no landing page, nothing to click.

toil.fyi/?preset=krash-rovastar-cerebral-demons-stars — Krash & Rovastar — Cerebral Demons (Stars Remix), the same measured pick that greets every first run.

The address bar is a promise: whatever you're watching — a preset you found in browse, a song playing in another tab, a YouTube link — is exactly what a copied URL reopens. The in-app Share button packages the same link with preset-titled copy when you're not near an address bar.

Send it to someone · Why Stims · Breakthrough Pillars · What works today · How Stims differs · Compatibility and evidence · Technical foundations · Quick start

Stims brings Winamp's MilkDrop back as a kept tool, not a port you run once. It is an independent browser-native visualizer in the lineage of Ryan Geiss's MilkDrop, Butterchurn, and projectM. It is built as a complete creative product rather than only an embeddable renderer:

• Explore a 1,787-preset library with previews, fast pre-compiled search, collections, favorites, queues, history, and deep links.
• Author & Remix directly in .milk with live editing, compiler diagnostics, parameter controls, instant A/B snapshotting, import, and export.
• Verify compatibility through backend-aware captures and checked-in projectM reference comparisons.
• Extend the format through a guarded WebGPU path without treating a newer graphics API as proof of visual fidelity.

The goal is not to claim that every imported preset is visually exact. The goal is to make compatibility visible, improve it systematically, and provide a better browser workflow around the visuals.

Anyone who remembers the Winamp visuals has a home here, and the presets are only half of it. Bring music you already listen to — a tab playing a song, a YouTube link, a mic, a local file — and Stims reacts to measured features of that audio (frequency bands, transients, beat timing), not a canned loop. It is also built around control, not only spectacle: nothing plays until you start it, one action stops everything, motion scales with your operating system's reduce-motion setting, and preset changes either cut or crossfade over a duration you choose. Those controls are a plain product decision, not a medical claim — here is the plain-language story and the research program behind them.

Unlike web ports that require presets to be pre-transpiled offline into proprietary JSON files, Stims compiles raw .milk code on the fly in the browser:

• EEL2 Intermediate Representation (IR): Parses equations into a structured AST and intermediate representation that lowers to an interpreter, high-performance CPU JIT, or WebGPU WGSL compute pipelines.
• Hot-Path Scope Optimization: Eliminates redundant property stores when per-point and per-pixel equations share execution scope.
• Unified Guest Memory Model: Implements MilkDrop's 4MB megabuf (per-VM) and 4MB gmegabuf (shared globally across preset switches throughout process lifetime) with coherent CPU/GPU buffer synchronization.

Author and tweak equations during active audio-reactive playback:

• CodeMirror Integration: Full syntax highlighting, MilkDrop completions, snippets, and real-time AST compiler diagnostics.
• Live Tune Sliders & Shadowed Variable Detection: Direct sliders for zoom, warp, rot, decay, dx, dy. Static analysis detects when a preset's own equations will overwrite a parameter adjustment.
• Instant A/B Snapshot Comparison: Capture baseline state into Slot A, experiment with code in Slot B, and toggle between them in real-time (Cmd/Ctrl+Shift+B or toolbar button) to compare visual iterations on stage.

Stims replaces visual guesswork with reproducible empirical evidence:

• Headless C++ Reference Harness: Captures gold-standard frames from native projectM (C++/SDL2/OpenGL) in offscreen contexts with hash-bound provenance sidecars.
• Empirical Noise-Banded Diffing (parity:noise): Measures each preset's natural run-to-run variance floor so real mathematical deltas are separated from harmless procedural jitter.
• Deterministic Clock Pumping: Bit-exact simulation stepping (renderFrames({ holdAfterPump }) and frozen clocks) ensures exact frame-by-frame synchronization.

• Zero-Hitch AudioWorklet: Computes FFT waveforms, frequency bands, transient envelopes, and energy dynamics in a dedicated audio worklet thread off the main JS loop.
• GPU Spectral Textures: Packs audio frequencies and waveforms directly into a shared GPU texture for single-pass sampling in warp and composite shaders.
• Flexible Input Routing: Seamlessly switch between demo audio, live microphone input, browser tab audio, YouTube audio streams, and local files.

Everything here ships in the browser today — no account, no server, no converted preset format.

Butterchurn and projectM are the projects most people arrive from, and both are good at what they were built for. Stims occupies a different slot: they are renderers you embed or run, while Stims is the workflow around one.

What that buys you in practice:

• Runtime work is measured at the frame seam. Production browser benchmarks use repeated trials and record delivered cadence, simulation time, render time, resolved WebGPU hardware time when available, backend selection, and adaptive-quality state instead of treating a successful load as proof of speed.
• Hot equation loops avoid redundant work. When per-point and per-pixel equations share their runtime scope, the JIT writes each ordinary local result once while retaining differential tests against the interpreter.
• Rhythm and melody read separately. Presets can react to percussive and harmonic energy bands independently — transients versus sustained tones — without claiming to separate instruments.
• Rendering pressure has an explicit fallback path. Hardware-timed WebGPU pressure can trim render and feedback resolution continuously inside a quality tier; sustained broader pressure can still reduce visual density through the discrete adaptive-quality ladder.
• Startup work is staged around the first paint. Renderer-selection probes stay on the critical path; telemetry, automation, and gamepad services load after the shell. The measured cold-load and deploy-build method lives in the front-end performance audit.
• Presets stay presets. A .milk file loads, runs, edits, and exports as .milk. There is no conversion step to run before a preset is usable, and no converted artifact to keep in sync with the original.
• Editing is part of playback. The compiler diagnostics, parameter controls, and inspector act on the preset that is on screen right now, so a change is visible in the same session that found the problem.

The fixed-tier browser benchmark compares code changes at the same renderer, viewport, preset, audio source, and adaptive-quality step. On an Apple M1 Max in Chromium/WebGPU at ×ばつ720, the eos-apocalypse stress case produced the following before/after result for commit ac2b354d:

These numbers are one preset on one host, not a device-wide FPS promise. The×ばつ tier was too scheduler-sensitive to promote as a stable result. See docs/RUNTIME_PERFORMANCE.md for the exact 2-second warmup, 8-second capture, quality lock, reproduction command, and interpretation rules. Current runs default to a production build and three trials, report median/min/max frame work, and reject renderer validation or device errors as incomplete evidence. Frame cost is also not visual fidelity; that oracle is the projectM reference workflow in the next section.

Successful compilation is not the same as visual parity. Catalog entries distinguish runtime evidence from measured visual evidence, and the checked-in certification workflow requires:

1. a Stims capture on the requested backend;
2. a provenance-checked projectM reference;
3. an image-diff result within the declared tolerance; and
4. promotion of that result into the measured manifest.

Most catalog entries currently have runtime evidence only and should not be read as visually certified. The current sources of truth are:

• public/milkdrop-presets/catalog.json for shipped catalog metadata;
• src/data/milkdrop-parity/measured-results.json for promoted visual results;
• src/data/milkdrop-parity/webgpu-certification-report.json for the bounded WebGPU certification snapshot; and
• docs/MILKDROP_PROJECTM_PARITY_PLAN.md for the evidence workflow.

flowchart TB
 subgraph InputLayer ["Audio & Preset Inputs"]
 Audio["Audio Source<br/>demo · mic · tab · file · YouTube"]
 Milk[".milk Preset<br/>catalog · import · live editor"]
 end
 subgraph ProcessingLayer ["Analysis & Compilation"]
 Worklet["AudioWorklet Processor<br/>FFT · bands · transients · buffer pooling"]
 Compiler["Preset Compiler & JIT<br/>EEL2 AST → IR → GLSL/WGSL"]
 end
 subgraph RuntimeLayer ["Execution & Graphics"]
 VM["EEL2 Runtime VM<br/>per-frame · per-vertex · megabuf"]
 Renderer["Dual-Backend Renderer<br/>WebGL2 Baseline · WebGPU Compute"]
 Fallback["Automatic Failover & DRS<br/>adaptive density · quality ladder"]
 end
 subgraph OutputLayer ["Presentation & Verification"]
 Canvas["Live 120/240Hz Canvas"]
 Record["In-Browser Recording Beta<br/>(MediaRecorder)"]
 Diff["Deterministic Capture<br/>→ projectM Parity Diff"]
 end
 Audio --> Worklet
 Milk --> Compiler
 Worklet --> VM
 Compiler --> VM
 VM --> Renderer
 Renderer -.-> Fallback -.-> Renderer
 Renderer --> Canvas
 Canvas --> Record
 Canvas --> Diff

See Technical Foundations for the implementation map.

Prerequisites: Bun 1.3.14+ and a browser with WebGL2 support. WebGPU is optional.

git clone https://github.com/zz-plant/stims.git
cd stims
bun install
bun run dev

Open http://localhost:5173.

bun run check:quick # Fast lint, types, metadata, and claim-drift checks
bun run test # Unit, integration, and compatibility test profiles
bun run check # PR gate (unit + compat + parity corpus — 2,800+ tests)
bun run check:all # Adds the serial, browser-backed e2e suite
bun run build # Production bundle build

The quality gate verifies that the visible preset count matches the public catalog and rejects public README wording that promotes known experimental foundations as shipped features.

The repository includes Cloudflare Worker routes for generation, blending, visual search, and community presets. They are optional enhancements rather than requirements for local playback or editing. See the API reference for deployment requirements and endpoint contracts.

Architecture, authoring, parity, and QA docs are indexed at docs/README.md.

Contributions and compatibility reports are welcome. Start with CONTRIBUTING.md, and include the tests and evidence appropriate to the surface you change.

Star History Chart

Stims is built with deep gratitude for the creative, mathematical, and technical giants whose work pioneered real-time audio visualization:

• Ryan Geiss & MilkDrop: For creating the original MilkDrop visualizer, Winamp plugin, and per-pixel math expression language that defined an entire digital art form.
• Jordan Berg (jberg) & Butterchurn Contributors: For pioneering web-based MilkDrop rendering in WebGL and establishing open-source web preset parsing patterns.
• Carmelo Piccione, Mischa Spiegelmock & projectM Maintainers: For building and maintaining projectM, the open-source C++ reference implementation used as our gold-standard visual parity reference target.
• The MilkDrop Preset Author Community: Gratitude to the authors whose math and artistic vision power the 1,787 catalog presets. The most-credited handles in the shipped catalog, counting every appearance in an accretive credit chain rather than only solo bylines, are Geiss, Flexi, Martin, Rovastar, Eo.S., Stahlregen, Unchained, fiShbRaiN, Phat, Aderrasi, Shifter, Zylot, ORB, suksma, Cope, Goody, and Krash — alongside roughly 120 more.
• Nullsoft & Winamp: For providing the legendary software platform that brought music visualization to millions worldwide.

Stims is an independent implementation. MilkDrop, Butterchurn, and projectM are credited as creative and technical lineage; no official affiliation is implied. See Lineage and Credits.

Licensed under the Unlicense — public domain.