Vibresia

Vibresia

A free macOS app for visual worlds that move with your music. It listens to whatever your Mac is playing and turns it into live scenes, from neon waveforms to a pixel-art band that walks on stage when it hears their instrument — and you can write a world of your own, or have an AI assistant write it for you.

Website & install: https://vibresia.com

curl -fsSL https://vibresia.com/install.sh | bash

Or ask an AI assistant: *"install vibresia from https://vibresia.com"*.

If you enjoy it, you can buy me a coffee.

Found a bug or have an idea? File an issue. Pull requests are very welcome, especially new vibescapes: see CONTRIBUTING.md.

Repository layout

Developing

cd VisualiserMac

./build-app.sh debug # build/Vibresia.app open build/Vibresia.app

Custom vibescapes and the local MCP server

A vibescape is a fragment shader — one function, vec3 render(vec2 p, float t) — and the app supplies the uniforms, the helpers and everything else.

Vibresia ships a local MCP server, so an AI agent can write a vibescape, check it compiles, look at the picture and try again without anybody copying code by hand:

claude mcp add vibresia -- "/Applications/Vibresia.app/Contents/MacOS/Vibresia" --mcp

It's the same binary run with --mcp, speaking JSON-RPC over stdin — no window, no port, no analytics. It reads and writes the same files the app does, so a vibescape an agent writes shows up in the app within a second. See VisualiserMac/README.md for the tools it offers.

Version numbers

The build version is the date it was built, so there's no number to bump:

MAJOR.MINOR.PATCH

MAJOR counts years since 2026, MINOR is the month, and PATCH is the day of the month followed by the build number of that day — 0.10.201 is the 20th of October 2026, the first build of that day.

VisualiserMac/version.sh computes it, and build-app.sh bakes it into the app. release.sh records it in VisualiserMac/VERSION and the landing page before tagging the release, so the app, the site and the git tag always agree.

Landing page analytics

site/analytics.js is a ~180-line PostHog client — no SDK, no session replay, no cookies — reporting into the same PostHog project as the app, separated by a surface property (web vs mac_app).

Events: $pageview, demo_played, vibescape_card_viewed (which vibescape cards got scrolled to), download_clicked, install_command_copied (ask-ai or curl — the interesting split, since they are different audiences), coffee_clicked (by placement) and outbound_clicked.

To see them without touching production, point the meta tag at a local sink:

python3 - <<'PY'

p='site/index.html'; s=open(p).read() open(p,'w').write(s.replace('https://us.i.posthog.com">','http://127.0.0.1:8099">')) PY (cd site && python3 -m http.server 8098) # then open http://127.0.0.1:8098

The footer has a one-click opt-out, and Do Not Track is honoured: both stop the page sending anything at all.

Download notifications (Discord)

Every download goes through /download on the Worker, which 302s to the latest GitHub release and posts an embed to Discord. Server-side rather than from the page, for two reasons: a webhook URL in the HTML would be public, and a click that never completes isn't a download.

The embed carries source, city/country (from Cloudflare's geo), referrer, browser, and whether that browser has downloaded before.

npx wrangler secret put DISCORD_WEBHOOK_URL     # once; the webhook URL in Discord

npx wrangler deploy curl https://vibresia.com/api/health # {"discord":"configured"}

Errors from the app. The app can't hold the webhook (it's in the app bundle, where anyone can read it), so it posts to POST /api/notify on this site and the Worker forwards it. Set the shared token as a second secret, then bake the same value into the app:

npx wrangler secret put NOTIFY_TOKEN          # any random string

REPORT_TOKEN= ./build-app.sh release

Three things arrive: audio_error (the audio source failed or was cut off — the failure a stack trace will never show you), source_failure and app_crash (with the top frames). A denied permission prompt is a choice, not a fault, so it isn't reported.

The two audio reports are not behind the in-app toggle: the user asked for that source explicitly, and a dead input is a bug nothing else will show. app_crash is: it goes out with the crash upload to PostHog, which waits for "Share anonymous usage" to be on, so switching that off stops both. What's sent is app state — vibescape, genre, error text — never audio or track names. Errors get their own cooldown (one a minute, 60/hour) so a broken install can't flood the channel, and DISCORD_ERRORS_ENABLED = "false" turns them off without touching download alerts.

Locally, .dev.vars (gitignored) points the webhook at a stub:

npx wrangler dev --port 8787

curl -s 'http://127.0.0.1:8787/download?src=hero&seen=0' -A 'Mozilla/5.0' npm test # 13 tests, no network

Notes:

• The webhook URL and the notify token are both credentials. scripts/check-no-webhook-leak.sh fails if either appears in the tree — delphina had the same problem and it ended up baked into dozens of release tags. If it ever leaks, recreate the webhook in Discord and put the new one back with wrangler secret put.
• Bots and link previewers are filtered out, a double-clicked button only posts once (5s debounce, 30/hour), and the post goes out via ctx.waitUntil with a timeout and one retry — so Discord being down can't slow down or break a download.
• Switch it off by setting DISCORD_NOTIFICATIONS_ENABLED to "false" in wrangler.toml and redeploying; the site keeps working either way.
• install.sh still downloads straight from GitHub, so script installs don't produce notifications.

Shared vibescapes

A custom vibescape — one somebody wrote — used to travel as its payload in the link: vibresia.com/share/?d= . That works with no backend at all, which is why it was built that way. But the link was around 370 characters, and the server answered it with a 307 to add the trailing slash, which WhatsApp's link-preview crawler did not follow — so the preview was blank and the link looked broken in a chat.

Now the payload is stored and the link is short:

POST /api/share   {payload, name, author, image, key}   →  {"url": "https://vibresia.com/s/k3f9x2"}

GET /s/k3f9x2 the share page, with the payload inlined GET /og/k3f9x2.jpg a picture of this vibescape

• The same vibescape always gets the same link. A share used to be made fresh every time — a new row, a new id, a new URL — so sharing the same vibescape twice gave you two links, and re-sharing one somebody sent you gave you a third. The app hashes the vibescape's contents (name, author, url, shader) and sends the hash; the Worker looks for a share with that hash, and for one with the same payload, and returns the row it finds rather than making another. The key column has a partial unique index on it, so two devices sharing at once land on one row.
• A vibescape that arrived on a link keeps the link it arrived on. The page puts the share's id in the deep link, the app remembers it with the vibescape, and sharing it on hands that link back: the person who sent it to you sent you that link, and the person you send it to should get the same one. Edit the vibescape and the hash changes, so it gets a link of its own.
• The picture says who made it. The app stamps the Vibresia mark and the credit onto the picture it uploads, and the built-in pictures on the site are drawn by the same code — see VisualiserMac/Sources/VibresiaBrand.

The gallery

vibresia.com/vibescapes lists the built-in vibescapes and the ones people have shared, in one list, newest first.

Sharing a vibescape has always made a link anybody can open. The gallery is different: it lists them, so anything in it is findable by anybody at all — and the name and the author on it are public. The share sheet says so, and has a tickbox, on by default.

• The app asks. POST /api/share takes public, and the share sheet has a tickbox next to the name.
• The Worker stores it in an is_public column and serves the list at /vibescapes (the page) and /api/gallery (the same thing as JSON). The cards are built on the server, so the page works with no JavaScript and a crawler sees the list.
• The built-ins are in it too, dated by the day they first appeared — the commit that first mentioned the vibescape — so they can be sorted against the shares people have made. scripts/generate-share-pages.py works that date out and writes it into the share manifest. Their cards use the clean still, the same as everybody else's, rather than the framed share graphic.
• The shares that were made before the gallery existed are not in it. They were never offered the choice, and publishing them without asking would put somebody else's name on the front page of the site. Sharing one again with the tickbox on puts it in.

The admin

vibresia.com/admin — unlinked, and not in any sitemap. It asks for a token and then lists every share, the ones in the gallery and the ones hidden, with three things you can do to each:

• Hide takes it out of the gallery and leaves the link working. The right one for a share that is fine but should not be listed.
• Show puts it back.
• Delete takes the row, and the link with it: the picture and the name go too. It asks first, because it cannot be undone.

The token is a Worker secret called ADMIN_TOKEN, an