For power users
Automation & API
Spiralyst Lab is scriptable. Every on-screen control has a programmatic twin, so a script, a MIDI/OSC bridge, an AI agent, or an automated QA harness can drive what the app shows and read what it hears — in real time, without faking mouse clicks.
Local only. The automation surface runs entirely on your Mac — no remote control, no telemetry, nothing leaves your machine.
This page documents the creative subset of the surface: read and set the whole scene, switch fractals and wire reactivity, inspect the live audio, run Auto-Reactivity, run a show fullscreen, save presets, drive the 3D Flows, and export stills and video. It ends with a short recipe for recording a demo video of your own.
Who it's for
- Power users who want to script setups and batch-export art.
- DJs & VJs bridging a MIDI or OSC controller to colors, motion, and fractal parameters.
- AI agents that read the live audio and current look, decide what should happen next, and apply it.
- QA & measurement: drive a known scene, render, read pixels + audio + state, and grade against a baseline.
How to drive it
Two paths into the same surface — the HTTP API for code (any language, any tool) and a set of reference Claude Code skills we publish here for anyone who wants a ready-to-install agent integration.
HTTP — http://127.0.0.1:<port>/api/*
The app's embedded localhost server. Drive it from any language — curl, a
Python script, a Node process, a MIDI/OSC bridge, an AI agent. Dozens of endpoints
across state, UI, window, presets, 3D Flows, audio, and export. Changes apply within one ~250 ms poll
tick.
Localhost-only, with a per-launch bearer
token — by design. The server binds 127.0.0.1 on an OS-assigned port,
and every request needs a secret token that's regenerated every time the app launches. The
port + token are written to a private file in your home folder, readable only by you — so
only software running as you can find them and call the API. Same model
Jupyter
and VS Code use. It is not a remote-control surface — don't expose it off the machine.
Read the port + token (written to ~/.spiralyst-lab/api-port.json at launch)
# the file lives at ~/.spiralyst-lab/api-port.json — 0600, user-only:
# { "url": "http://127.0.0.1:54321", "port": 54321, "token": "…", "version": "3.9.1", … }
P=~/.spiralyst-lab/api-port.json
BASE=$(jq -r .url "$P")
AUTH="Authorization: Bearer $(jq -r .token "$P")"
Both the port and the token rotate on every launch — re-read the file each run, don't hard-code either. The same two values are also shown in-app under About ▸ Spiralyst Lab with Copy buttons, for when a human wants to grab them without opening a file.
~/.spiralyst-lab/api-port.json on every launch — pick whichever path
your workflow prefers.
Quickstart
A complete drive-and-capture loop over HTTP: read the port + token, fetch the scene, switch fractal + enable audio, wait for it to land, export a 4K still, and read where it landed.
# 1. read $BASE and $AUTH (see above) — one jq line each from ~/.spiralyst-lab/api-port.json
# 2. read the current scene
curl -s -H "$AUTH" "$BASE/api/state" | jq '{ type, hueStart: .color.hueStart }'
# 3. switch fractal + enable system audio (the 202 answer carries an action id)
ID=$(curl -s -H "$AUTH" -XPOST "$BASE/api/state/apply" -H 'Content-Type: application/json' \
-d '{"type":"fractal-phyllotaxis","audio":{"enabled":true,"source":"system"}}' | jq -r .id)
# 4. poll the result until it lands: status "done", or "error" with the reason
while curl -s -H "$AUTH" "$BASE/api/actions?id=$ID" | jq -e '.status == "queued" or .status == "running"' >/dev/null
do sleep 0.1; done
curl -s -H "$AUTH" "$BASE/api/actions?id=$ID" | jq -c '{ status, error }'
# 5. export a 4K still (exports need a licence; a trial copy answers with the reason)
curl -s -H "$AUTH" -XPOST "$BASE/api/export/png" -H 'Content-Type: application/json' -d '{"res":"4K"}'
# 6. read where it was written
curl -s -H "$AUTH" "$BASE/api/export/png" | jq '.path' # → ~/.spiralyst-lab/qa/<file>.png
Every request needs the Authorization: Bearer … header
— a request without the right token returns 401 Unauthorized.
Reference — creative subset
Path · method · purpose · params, with the window.__spiral.*
equivalent. This is the creative subset only; see Full reference
for advanced/agent endpoints.
Results (v3.8.2). A route that queues work
answers 202 with an id: {"status":"queued","kind":"presets.load","id":"a42"}.
Poll GET /api/actions?id=a42 until status is done (with
result) or error (with the reason the app refused: an unknown preset, a
hidden control, a licence the action needs). A recording, a heal or a model load stays
running until it finishes; GET /api/actions lists the last 50. Most actions
land within half a second — poll rather than sleep.
State
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| GET /api/state | Last pushed scene snapshot (or null at boot before the first push). | — | __spiral.state.get() |
| POST /api/state/apply | Apply a full scene snapshot, or a partial that merges over the live scene (within ~250 ms). A partial of numbers only — a camera angle, a colour, a slider value — is set in place without rebuilding anything else (v3.7.0). A number lands inside the slider’s operating range, as a drag does (v3.8.1). Switching type resets only the new scene’s own controls; shared ones (colour, transform, effects, layers) keep their values and audio or sine bindings, as the Type menu does. List what is still moving with GET /api/sliders and jq '.sliders[] | select(.mode != "off") | .key'; clear one with POST /api/sliders/reset {key, part:"all"} (its value, range and animation), or everything with POST /api/scene/reset. | snapshot blob, full or partial (JSON body) | __spiral.state.set(snap) / .patch(partial) |
| POST /api/state/undo | Step back in history. | — | __spiral.undo() |
| POST /api/state/redo | Step forward in history. | — | __spiral.redo() |
| GET /api/state/stack | { undo, redo, canUndo, canRedo } | — | __spiral.stack() |
Sliders
v3.8.1 — read and set each slider’s operating range: the span a sine or audio sweep covers, and where writes land.
A slider’s key is group:name — effect:glow,
transform:jitter, render:stroke, render:density,
color:hueStart — and GET /api/sliders lists every key with the label you see in
the panel and the tab it sits on. The ones that move a scene most visibly:
view:scale (zoom, on the Camera tab), transform:rotation,
transform:jitter, effect:trails, layer:count and
layer:centerOffset; each scene’s own controls are typespec:<param>.
Two keys share a name: effect:glow is the Glow slider under Effects (the halo on the lines,
a soft bloom by default, or square with {"effects":{"glowStyle":"square"}}), and
lighting:glow is Glow falloff, a lighting control for the 3D scenes.
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| GET /api/sliders | Every slider’s operating range and hard limits: { type, sliders: [{ key, group, tab, name, label, min, max, defaultMin, defaultMax, step, scale, overridden, mode }] }. Since v3.8.2 also its live value (right while ▶ or 🔊 animate it, unlike /api/state), defaultValue, freq, wave, muted, soloed, inverse, audioBand, and whether its min/max row (rangeOpen) and audio popover (audioPopoverOpen) are open. | — | __spiral.sliders.list(group?) · .get(key) |
| POST /api/sliders/range | Set a slider’s operating range, or reset it to the limits. Clamped to the limits, one undo step, live on a running animation, and carried to a detached control panel. Answers 202; 400 for a bad body. | { key, min?, max? } or { key, reset: true } | __spiral.sliders.setRange(key, min, max) · .resetRange(key) |
| POST /api/sliders/range-row | Open (the default) or close a slider’s min/max fields, as its … button does — in a detached control panel too. | { key, open? } | __spiral.sliders.openRange(key, open) |
| POST /api/sliders/set | v3.8.2 — one slider’s binding and value in one undo step, without a whole-scene restore. mode off·sine·audio; wave sine·loop; freq 0.01–1.5 cycles/s (0.02–0.05 reads as a slow drift; wave:"loop" on transform:rotation spins forever); audioBand is merged over the current band: { lo, hi } in Hz, signal (e.g. flux, the hits), gain, attackMs, releaseMs, scale (linear or log; null = the signal’s default), noiseFloor. A value needs mode:"off". | { key, value?, mode?, freq?, wave?, muted?, soloed?, inverse?, audioBand? } | __spiral.sliders.set(…) |
| POST /api/sliders/audio-popover | v3.8.2 — open (or close) a slider’s 🔊 audio-band popover in the panel you see, detached too. Opening shows the band without switching the slider to audio mode. | { key, open? } | __spiral.sliders.openAudio(key, open) |
| POST /api/sliders/reset | v3.8.2 — a ↩ button: value (default), range, speed, or all (stops the animation too). | { key, part? } | __spiral.sliders.reset(key, part) |
The scene’s own controls
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| GET /api/types | v3.8.2 — every scene: [{ key, label, group, renderer, usesSeed, locked, svg }] (group 2d·3d·scopes·flows). | — | __spiral.types() |
| GET /api/type/controls | v3.8.2 — the current scene’s own settings: its dropdowns (with their options), toggles, sliders, sections and buttons. | — | __spiral.type.controls() |
| POST /api/type/control | v3.8.2 — set one of the scene’s own controls the way the panel does, so its side effects run (the Wind Flow body list, the harmonograph’s Live monitor). A hidden control is refused. | { key, value } | __spiral.type.set(key, value) |
| POST /api/type/action | v3.8.2 — press one of the scene’s buttons (⌂ Home, ↻ Reseed, 🎵 React, 🗑 Delete). Buttons that open a file picker are refused: load a model with POST /api/flows/model. | { id } | __spiral.type.action(id) |
| POST /api/scene/seed | v3.8.2 — the seed box (with seed) or 🎲 (without): a new shape from that seed. A seed in POST /api/state/apply only changes the number, not the shape. | { seed? } | __spiral.reseed(seed?) |
| POST /api/scene/recolor | v3.8.2 — 🎨: a random palette; the result has the colours. | — | __spiral.recolor() |
| POST /api/view/reset | v3.8.2 — the scene’s own default view: the orbit camera on a 3D scene, the zoom and pan on a 2D scene. | — | __spiral.view.reset() |
| POST /api/camera/face | v3.9.0 — the view cube: glide the orbit camera square onto a face (front, back, left, right, top, bottom), to a three-quarter view from a corner (top-front-right, one word per axis in any order; iso = top-front-right), or turn the view 90° left or right. Front is the camera upstream, looking down the wind. Distance, FOV and pan are kept; one undo step when it lands. 3D scenes only; the result has { view, yaw, pitch, glide }. | { view } or { turn: "left" | "right" }, glide? (false jumps) | __spiral.camera.face(view) · .turn(dir) · .views() |
| POST /api/brush/import | v3.8.2 — Import SVG as stamp, with the SVG’s text instead of a file; the result’s id is the new brush. Imported stamps come back after a relaunch. | { svg, name? } | __spiral.brush.importSvg(svg, name) |
UI
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| POST /api/state/tab | Switch the sidebar tab — in a detached control panel too (v3.8.1). | { name: "source" | "visual" | "camera" | "export" } | __spiral.ui.tab(name) |
| POST /api/state/scroll | Scroll a control into view (auto-activates its tab) — in a detached control panel too (v3.8.1). Since v3.8.2 it unfolds the folded group the control is in; the result lists unfolded, inView and the panel’s scrollTop, and the action ends in error when the control can’t come into view (hidden in this scene). A panel group scrolls into view by its element id, <section>-group: { target: "presets-group" } brings up Presets on the Visual tab. | { target: "color:hueStart" } | __spiral.ui.scrollTo(target) |
| POST /api/ui/section | v3.8.2 — fold or unfold a panel group (ids from panel.sections in the window status). | { id, collapsed } | __spiral.ui.section(id, collapsed) |
| GET /api/ui/dialogs | v3.8.2 — the dialogs open in either window: [{ id, window, kind, title, message, buttons, answerable }]. scene.ready is false while one is open. | — | __spiral.ui.dialogs() |
| POST /api/ui/dialog | v3.8.2 — answer an open dialog with one of its button ids. Licence and agreement dialogs are listed but never answered over the API: those choices stay yours. | { id, choice } | __spiral.ui.answerDialog(id, choice) |
Audio
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| GET /api/audio/snapshot | Latest audio-input frame: { source, active, peak, rms, spectrum[32], pitchHz, ... } — the values the artwork reacts to. | — | __spiral.audio.snapshot() |
| POST /api/audio/source | Pick the audio source, the same as the Source picker: system audio, the microphone, or off. Turning audio off or switching it is done here; loading a scene or preset can turn audio on but never turns it off. | { source: "system" | "mic" | "off" } | await __spiral.audio.source("system") |
| GET /api/audio/bands | Live per-reactive-slider levels — see whether a band is maxed out or barely moving: { bands: [{ key, level, peak, saturated, lowDynamics, lo, hi, gain, attackMs, releaseMs, signal, min, max }] }, level 0–1. | — | — |
| POST /api/audio/heal | Run Auto-Reactivity (AGC). Runs in-app over a few seconds; poll GET /api/audio/heal for the report. Needs music playing. | { policy?, keys?, targetPeak? } | await __spiral.audio.heal({ policy: "auto" }) |
| GET /api/audio/status | Whether audio is coming through; since v3.8.2 also input: { source, device, devices } — the Source picker and the mic input device. | — | — |
| POST /api/audio/device | v3.8.2 — the Mic input picker ("" = the system default); names come from input.devices. | { name } | __spiral.audio.device(name?) |
| GET /api/audio/band/library | v3.8.2 — your saved audio bands (the chips in the popover). | — | — |
| POST /api/audio/band/delete | v3.8.2 — a band chip’s ×. | { name } | __spiral.audio.deleteBand(name) |
Export
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| POST /api/export/png | Render the active viewport to a PNG (exact pixels, not a screen grab). Writes to ~/.spiralyst-lab/qa/. | { res: "4K" | "1440p" | "1080p" | "720p" } or { w, h, ppi } | await __spiral.export.png({ res: "4K" }) |
| GET /api/export/png | The last export report: { path, w, h, ppi, bytes } — poll after the POST. | — | — |
| POST /api/export/video | Record a video of the art without opening the Export tab. Video only, no audio track; the recording runs for the length of the clip. | { frames, fps, bitMbps, res: "4K" … "360p" | "native", format: "mp4" | "mov" | "webm", name } — all optional | — |
| GET /api/export/video | The last video report: { path, bytes, frames, fps } — poll after the POST. | — | — |
| GET /api/export/status | v3.8.2 — a recording in progress, whether you or an agent started it: { video: { active, by, w, h, fps, frames, format, bitMbps, elapsedS, pct }, still: { active }, ui }. | — | __spiral.export.status() |
| POST /api/export/video/stop | v3.8.2 — stop the recording now; save:false drops it unsaved. | { save? } | __spiral.export.stopVideo(save) |
| POST /api/export/svg | v3.8.2 — Download SVG, written next to the PNG exports. Only the 2D line scenes have vector output. | { res?, w?, h?, name? } | __spiral.export.svg(opts) |
| GET /api/export/svg | v3.8.2 — the last SVG export: { path, w, h, bytes } — poll after the POST. | — | — |
Output location. Exported PNGs and videos
are written to ~/.spiralyst-lab/qa/. The POST starts the export; the
matching GET returns the report with the path once it lands. Exports need a
license, just as in the Export tab.
Window & presentation
Run the show from a script: the art fullscreen for the room, the control panel pinned in the shot for a tutorial, or the panel on its own window for a projector.
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| POST /api/window/fullscreen | Art fullscreen on or off. Fullscreen hides the control panel, so the audience sees only the art. | { on: true | false } | await __spiral.ui.fullscreen(on) |
| POST /api/window/panel | Pin the control panel on screen while fullscreen — a demo that shows the controls in use — or unpin it for a clean picture. | { pinned: true | false } | __spiral.ui.panel(pinned) |
| GET /api/window/status | Which layout is live: { fullscreen, detached, panelPinned, panelVisible }, plus the scene’s Math Mode state in scene.math; since v3.8.1 scene.math.audio is { typeKey, section } while a narration plays, else null. Since v3.8.2 also panel (the panel you are looking at, attached or detached: its tab, folds, open rows, open audio popover, selected preset), bounds, feed, eulaGate and scene.preset (the active preset). | — | __spiral.ui.window() |
| POST /api/window/detach | Move the control panel into its own window — for a second screen or a projector setup. | — | — |
| POST /api/window/reattach | Bring the control panel back into the main window. | — | — |
| POST /api/window/maximize | v3.8.1 — maximize or restore the render window (main) or the detached controls window (controls). Answers { window, maximized }. | { on?, window?: "main" | "controls" } | — |
| POST /api/ui/math | v3.8.1 — Math Mode: the formula tile on or off, the info card, and the reading level (simple · standard · detailed · technical). | { on?, info?, level? } | __spiral.ui.math(on) · .mathInfo(on) · .mathInfoLevel(level) |
| POST /api/ui/math/audio | v3.8.1 — play an info-card section’s narration (main · math · app · fact) at the reading level on screen, or stop it. | { section } or { stop: true } | __spiral.ui.mathAudio.play(section) · .stop() |
| GET /api/window/bounds | v3.8.2 — a window’s size and position in points: { x, y, w, h, innerW, innerH, scaleFactor, maximized, minimized, fullscreen, visible }. | ?window=main|controls | — |
| POST /api/window/bounds | v3.8.2 — size and place a window (give w with h, x with y), or minimize it. 409 while it is fullscreen or maximized. | { window?, w?, h?, x?, y?, minimized? } | — |
| GET /api/ui/math | v3.8.2 — Math Mode’s whole read: the formula tile’s text and live values, and the info card’s text. | — | __spiral.ui.mathRead() |
| GET /api/quality | v3.8.2 — the adaptive-quality governor: mode, frame budget and time, resolution and particle scale, estimated fps. | — | __spiral.quality.status() |
| POST /api/quality | v3.8.2 — Safe ("adaptive") or Full power ("full"), or the Quality group’s ⤺. | { mode?, reset? } | __spiral.quality.mode(m) · .reset() |
Presets
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| POST /api/presets/save | Save the current scene to your preset library, exactly as the Save button does — ready to load by hand at the gig. A preset with the same name is replaced; since v3.8.2 the result says overwrote, and it becomes the active preset. | { name: "Ocean opener" } | __spiral.presets.save(name) · __spiral.presets.list() |
| GET /api/presets | v3.8.2 — the sample presets (★), your saved library, and the preset in effect: { active, demos, library, lastSave, lastLoad } — library is a list of names, demos a list of { name, locked }. | — | __spiral.presets.status() |
| POST /api/presets/load | v3.8.2 — ↓ Load: a sample or a saved preset; it becomes the active preset. | { name } | __spiral.presets.load(name) |
| POST /api/presets/delete | v3.8.2 — × Delete (samples can’t be deleted). | { name } | __spiral.presets.delete(name) |
| POST /api/presets/export | v3.8.2 — Export…: the result’s bundle is the file the button would save. | — | __spiral.presets.exportBundle() |
| POST /api/presets/import | v3.8.2 — Import…: merges the bundle’s presets and replaces the band library, as the button does. | { bundle } | __spiral.presets.importBundle(bundle) |
3D Flows
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| GET /api/flows/status | The active flow's live numbers and its part-by-part truth labels. For the ocean wave: wave heights, wavelength and speed, and on the beach where the wave breaks and which kind of breaker it is. For Wind Flow: the wind speed, the body and tunnel in use, the shedding rate, the blockage, a loaded model's state and panel count, and the honesty label of every part. null when the scene isn't a flow. | — | __spiral.flows.status() |
| POST /api/flows/restart | Restart or reseed the active flow (the ↻ button). | — | __spiral.flows.restart() |
| POST /api/flows/react | Switch the flow's React to music set on or off — the 🎵 button: controls, bands and ranges in one go. The ocean wave and Wind Flow have one. | { on: true | false } | await __spiral.flows.react(on) |
| POST /api/flows/model | v3.8.0 — load a 3D model into Wind Flow from a file on your Mac, exactly as the 📂 Load… button does: an STL or OBJ up to 50 MB, cleaned and reduced to about 1,500 panels, solved while the old scene keeps flowing. Switches the scene to Wind Flow first if another type is on. Poll /api/flows/status for model.state (ready or refused, with the reason). Since v3.8.1 a file refused before the scene changes (too large, too many triangles, unreadable) also reads refused with the reason until the next load, while model.bodyState reports the model still on screen; OBJ files start “Y up” (STL stays “Z up”). | { path, name? } | await __spiral.flows.loadModelPath(path) |
| GET /api/flows/model | v3.8.0 — the model in the scene and the files the app has kept from earlier loads (a preset or a scene can name one of them and it loads again without the bytes). | — | await __spiral.flows.model() |
| DELETE /api/flows/model?key= | v3.8.0 — forget one kept model file. | ?key= from the GET | await __spiral.flows.forgetModel(key) |
| POST /api/flows/home | v3.8.2 — Wind Flow’s ⌂ Home: the body back on the tunnel’s axis. | — | __spiral.flows.home() |
App
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| POST /api/app/quit | v3.8.1 — quit the app the way the Quit menu does: a clean exit that removes the crash-recovery marker and the port file. Answers 202, and the app exits a moment later. | — | __spiral.app.quit() |
| GET /api/app/info | v3.8.2 — the app’s version and how this launch started (a restored session, crash recovery, or fresh). It never includes the token. | — | __spiral.app.info() |
Activity notices
| Endpoint | Purpose | Params | JS equivalent |
|---|---|---|---|
| GET /api/feed | v3.8.2 — the last 100 activity notices, kept even while the notices are switched off: { enabled, entries: [{ at, label }] }. | — | __spiral.feed.entries() |
| POST /api/feed | v3.8.2 — switch the activity notices on. Switching them off is refused (403): the notices are how you see what an agent is doing, so only you can turn them off, from File ▸ Show Agent Activity. | { on: true } | __spiral.feed.enable(true) |
| POST /api/feed/note | v3.8.2 — post the agent’s own notice (up to 200 characters). | { text } | __spiral.feed.note(text) |
Examples
From the WebView devtools console — window.__spiral (instant)
__spiral.state.patch({ type: "fractal-phyllotaxis", audio: { enabled: true, source: "system" } });
__spiral.state.patch({ color: { hueStart: 0.9 } }); // set one field → re-renders
__spiral.state.patch({ camera: { yaw: 1.57 } }); // numbers only → set in place, pitch untouched (v3.7.0)
await __spiral.audio.heal({ policy: "auto" }); // tune reactivity to the music
await __spiral.export.png({ res: "4K" }); // → ~/.spiralyst-lab/qa/
Switch a fractal + tune reactivity over HTTP
# enable system audio + Fractal Phyllotaxis (for the plain sunflower Phyllotaxis, send "type":"phyllotaxis")
curl -s -H "$AUTH" -XPOST "$BASE/api/state/apply" -H 'Content-Type: application/json' \
-d '{"type":"fractal-phyllotaxis","audio":{"enabled":true,"source":"system"}}'
# auto-tune, then poll the report (music must be playing)
ID=$(curl -s -H "$AUTH" -XPOST "$BASE/api/audio/heal" -H 'Content-Type: application/json' -d '{"policy":"auto"}' | jq -r .id)
while curl -s -H "$AUTH" "$BASE/api/actions?id=$ID" | jq -e '.status == "queued" or .status == "running"' >/dev/null
do sleep 0.5; done
curl -s -H "$AUTH" "$BASE/api/audio/heal" | jq '.healed'
Make a reaction hit harder (v3.8.2)
# starting bands: the kick about 30–120 Hz, the hi-hats about 6–14 kHz, both on signal "flux";
# a shorter releaseMs makes a reaction snappier and easier to see
# pinned? saturated:true, or a level that sits near 1 with lowDynamics:true, means too much gain
curl -s -H "$AUTH" "$BASE/api/audio/bands" | jq -c '.bands[] | { key, level, saturated, lowDynamics }'
# punchier: less gain so it stops pinning, a short attack and release so each hit rises and drops,
# and a wider range so a hit can travel further
curl -s -H "$AUTH" -XPOST "$BASE/api/sliders/range" -H 'Content-Type: application/json' \
-d '{"key":"effect:glow","min":2,"max":25}'
curl -s -H "$AUTH" -XPOST "$BASE/api/sliders/set" -H 'Content-Type: application/json' \
-d '{"key":"effect:glow","mode":"audio","audioBand":{"lo":20,"hi":120,"gain":7,"attackMs":5,"releaseMs":150}}'
# flat? lowDynamics:true below the top means the band has no hits to show: more gain won't add movement.
# switch its signal to "flux" (the onsets), or let the app tune it: POST /api/audio/heal {"policy":"auto"}
# small but moving (lowDynamics:false, level well below 1)? that one wants more gain
Pick the audio source
# system audio on (or "mic", or "off")
curl -s -H "$AUTH" -XPOST "$BASE/api/audio/source" -H 'Content-Type: application/json' -d '{"source":"system"}'
# read it back
curl -s -H "$AUTH" "$BASE/api/audio/status" | jq '.active'
Inspect the live audio (what the artwork hears)
curl -s -H "$AUTH" "$BASE/api/audio/snapshot" | jq '{ peak, rms, pitchHz }'
curl -s -H "$AUTH" "$BASE/api/audio/bands" | jq '.bands[] | { key, level, saturated, lowDynamics }'
Run the show fullscreen
# clean fullscreen for a venue or a capture — only the art on screen
curl -s -H "$AUTH" -XPOST "$BASE/api/window/fullscreen" -H 'Content-Type: application/json' -d '{"on":true}'
curl -s -H "$AUTH" -XPOST "$BASE/api/window/panel" -H 'Content-Type: application/json' -d '{"pinned":false}'
# tutorial recording — keep the controls in the shot
curl -s -H "$AUTH" -XPOST "$BASE/api/window/panel" -H 'Content-Type: application/json' -d '{"pinned":true}'
# check what's live
curl -s -H "$AUTH" "$BASE/api/window/status" # → { fullscreen, detached, panelPinned, panelVisible }
Ocean wave, riding the music, saved as a preset
# with the ocean wave on screen and the music playing:
curl -s -H "$AUTH" -XPOST "$BASE/api/flows/react" -H 'Content-Type: application/json' -d '{"on":true}'
curl -s -H "$AUTH" "$BASE/api/flows/status" | jq '{ type, scene, particles, significantHeight }'
curl -s -H "$AUTH" -XPOST "$BASE/api/presets/save" -H 'Content-Type: application/json' -d '{"name":"Ocean opener"}'
Your own model in Wind Flow, turning to the music (v3.8.0)
# load an STL from your Mac; the app switches to Wind Flow, cleans the mesh and solves the air round it
curl -s -H "$AUTH" -XPOST "$BASE/api/flows/model" -H 'Content-Type: application/json' -d "{\"path\":\"$HOME/Documents/models/duck.stl\"}"
# wait for model.state to reach "ready" (or "refused", with the reason)
curl -s -H "$AUTH" "$BASE/api/flows/status" | jq '{ model: .model.state, panels: .model.panels, body: .body.kind }'
# bind the wind to the music, then set the yaw turning on the loop wave
curl -s -H "$AUTH" -XPOST "$BASE/api/flows/react" -H 'Content-Type: application/json' -d '{"on":true}'
curl -s -H "$AUTH" -XPOST "$BASE/api/state/apply" -H 'Content-Type: application/json' \
-d '{"sliders":{"typespec:bodyYaw":{"mode":"sine","wave":"loop","freq":0.05,"min":-180,"max":180}}}'
Export a 30-second video
curl -s -H "$AUTH" -XPOST "$BASE/api/export/video" -H 'Content-Type: application/json' \
-d '{"frames":900,"fps":30,"res":"1080p","format":"mp4","name":"ocean-demo"}'
sleep 32 # the recording runs for the length of the clip
curl -s -H "$AUTH" "$BASE/api/export/video" | jq '{ path, bytes, frames, fps }'
Record a demo video of your own
Two ways, depending on what the video is for.
The art on its own — use Export. The Export tab (or
POST /api/export/video from a script) renders the canvas straight to MP4, MOV or
WebM at up to 4K: exact pixels, no screen capture, no desktop in the frame. Exports are
video-only, so add your soundtrack in any video editor afterward, using audio you have the
rights to.
A performance, with the sound and the controls — screen-record it. macOS's screen recorder (Shift-Command-5) or any capture app records the screen. The part that takes setting up is the sound, because macOS doesn't give a screen recorder the system audio on its own. A few tips:
- Route the system audio through a loopback device — for example BlackHole, a free, open-source audio driver; any loopback device works. In Audio MIDI Setup, create a Multi-Output Device that sends to both your speakers or headphones and the loopback device, and choose it as your sound output, so you still hear the music while it records. Then pick the loopback device as the recorder's audio input.
- Set the stage first: art fullscreen, control panel pinned if you want the sliders in the shot, unpinned for a clean picture. An agent can do this for you with the presentation calls above.
- If the soundtrack is a file you have, lay the original file under the video in your editor instead of keeping the recorded sound. A loopback recording can drop bits of audio now and then — you hear a click, and the music slowly runs ahead of the picture. Use the recorded track only to line the original up, then mute it.
Full reference
This page covers the creative subset only. The complete contract — file read/write, save/open dialogs, the calibration suite, and the full 50+ endpoint list for advanced and agent use — lives in the agent-control reference, hosted here for direct read access from agents, scripts, and integrations.
Reference — Claude Code skills
Four reference skills exist for Claude Code
(Anthropic's CLI agent). Claude Code resolves slash commands like /spiral-observe to
a local skill folder under ~/.claude/skills/<name>/; the skill's
SKILL.md tells Claude what the command does and how to drive it.
Not bundled. Spiralyst Lab does not ship these skills, and they are not installed by Claude Code. They are reference examples, published here, demonstrating how to drive the API above. Install them yourself with the steps below, or read them as worked examples and write your own. Nothing about the API is Claude-specific — any agent that can speak HTTP can drive Spiralyst Lab.
/spiral-observe— read the live audio (snapshot, per-band reactivity, full-rate frames), read the scene state, capture a PNG of the rendered viewport, and report what the app is currently doing. [SKILL.md]/spiral-scene— build a scene programmatically from a natural-language description: fractal type + params, effects, layers, background, and wire sliders to audio bands or sine animation, then verify with a screenshot. [SKILL.md]/spiral-calibrate— run the calibration suite (audible by design): play ground-truth tones, grade pitch / gain / beat timing / settings round-trip / visual render against a baseline. [SKILL.md]/spiral-heal— auto-tune (AGC) the audio-reactive bands so sliders stop pinning at max or sitting at zero. Tunes gain, squelch, and signal together. [SKILL.md]
Setup
- Install Claude Code and sign in.
- Create the skills directory if it doesn't exist:
mkdir -p ~/.claude/skills - For each skill, create a folder and drop in a
SKILL.md. Withcurl:
Eachfor name in spiral-observe spiral-scene spiral-calibrate spiral-heal; do mkdir -p ~/.claude/skills/$name curl -fsSL "https://spiralyst.com/skills/$name/SKILL.md" \ -o ~/.claude/skills/$name/SKILL.md doneSKILL.mdis the literal file the agent reads — open the [SKILL.md] links above to inspect the source before you install. - Restart Claude Code. The four slash commands resolve on next session start.
- Launch Spiralyst Lab (the skills drive the app's local HTTP server documented above; if the app isn't running there's nothing to talk to).
Inspect before you install. Each
skill is a single Markdown file with a YAML frontmatter (name,
description) and a body of plain instructions plus shell snippets that call
the public HTTP API documented above. Read the source from the
SKILL.md links next to each skill name —
nothing is obfuscated, and there are no hidden binaries or daemons.
Caveats
- Localhost only. The HTTP server binds
127.0.0.1— it is not a remote-control surface. Don't expose it off the machine. - Latency. HTTP changes apply within one ~250 ms poll tick. The
window.__spiralobject (accessible via the app's WebView devtools console — Develop → Web Inspector → Console) is synchronous and instant; it's documented in the reference table above for developers who want zero-latency control without leaving the app's runtime. A queued write answers 202 with an id: pollGET /api/actions?id=…for its result rather than waiting a fixed time. - One instance. Drive a single running app instance at a time; the port is per-launch and OS-assigned.
- Exports need a license. PNG and video export over the API follow the same rule as the Export tab. Everything else on this page — the scene, audio, presentation mode, presets, 3D Flows — works in the free trial too (20 minutes per launch, every type). After an unlicensed session ends, the actions that change the picture are refused, and the preset library follows its buttons: saving, loading from your library, deleting, importing and exporting need a licence; the samples stay loadable.