Vibresia

Vibresia

一款免费的 macOS 应用，让视觉世界随音乐律动。它会聆听 Mac 播放的任何内容，并将其变成实时场景：从霓虹波形，到听见乐器声时走上舞台的像素艺术乐队。你也可以编写自己的世界，或让 AI 助手为你编写。

网站与安装： https://vibresia.com

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

也可以向 AI 助手提出请求：“从 https://vibresia.com 安装 vibresia”。

如果你喜欢它，可以请我喝杯咖啡。

发现 Bug 或有想法？提交问题。非常欢迎提交 Pull Request，尤其是新的 vibescape：请参阅 CONTRIBUTING.md。

仓库布局

路径	内容
VisualiserMac/	macOS 应用（Swift、SwiftUI、OpenGL）。请参阅其 README。
site/	落地页、安装程序（install.sh）和 AI 安装说明（install.md、llms.txt）。
site/analytics.js	落地页的匿名页面浏览／点击跟踪。
site/github.js	从 GitHub API 获取的更新日志和未解决的问题，在滚动到相应位置时加载。
worker/index.js	Cloudflare Worker：提供 ./site，并处理 /download（重定向并发送 Discord 通知）。
worker/share.test.js	共享 vibescape 端点的测试。
migrations/	D1 架构——一张表，每个共享 vibescape 占一行。
site/sitemap.xml、site/robots.txt	提交给 Google 的内容。只有一个 URL；纯文本 Agent 页面特意允许爬取，但不列入其中。
site/_headers、site/_redirects	Cloudflare 响应标头（缓存、安全）和规范路径重定向。
scripts/check-vibescapes.sh	如果落地页缺少某个 vibescape，或其结构化数据中的版本已过时，则报错。
scripts/check-posthog.sh	如果网站和应用向不同的 PostHog 项目上报，则报错。
scripts/check-no-webhook-leak.sh	如果树中的任何位置包含 Discord webhook URL、通知令牌或共享令牌，则报错。
wrangler.toml	将 Worker（以及通过它提供的 site/）部署到 Cloudflare。

开发

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

自定义 vibescape 和本地 MCP 服务

vibescape 是一个片段着色器——只有一个函数 vec3 render(vec2 p, float t)—— 其余部分，包括 uniform 和辅助函数，都由应用提供。

Vibresia 自带本地 MCP 服务，因此 AI Agent 可以编写 vibescape、检查它能否编译、查看效果并反复尝试，无需任何人手动复制代码：

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

它是同一个二进制文件，只是通过 --mcp 运行，并通过 stdin 使用 JSON-RPC——没有窗口、没有端口、没有分析数据。它读写与应用相同的文件，因此 Agent 编写的 vibescape 一秒内就会显示在应用中。请参阅 VisualiserMac/README.md 了解它提供的工具。

版本号

构建版本就是构建日期，因此无需递增版本号：

MAJOR.MINOR.PATCH

MAJOR 表示从 2026 年起经过的年数，MINOR 表示月份，PATCH 表示当月日期后接当天的构建编号——0.10.201 表示 2026 年 10 月 20 日当天的首次构建。

VisualiserMac/version.sh 会计算版本号，build-app.sh 会将其写入应用。release.sh 会在打上发布标签前，将版本号记录到 VisualiserMac/VERSION 和落地页中，因此应用、网站和 git 标签始终保持一致。

落地页分析

site/analytics.js 是一个约 180 行的 PostHog 客户端——不使用 SDK、不进行会话回放、不使用 Cookie——数据发送到与应用相同的 PostHog 项目，并通过 surface 属性（web 与 mac_app）区分。

事件：$pageview、demo_played、vibescape_card_viewed（滚动到哪些 vibescape 卡片）、download_clicked、install_command_copied（ask-ai 或 curl——这两类用户群体不同，这种区分很有参考价值）、coffee_clicked（按展示位置区分）和 outbound_clicked。

无需触及生产环境即可查看这些数据，只需将 meta 标签指向本地接收端：

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

页脚提供一键退出选项，并遵守 Do Not Track：两者都会阻止页面发送任何数据。

下载通知（Discord）

每次下载都会经过 Worker 上的 /download，该端点会将请求 302 重定向到最新的 GitHub 版本，并向 Discord 发送一条嵌入消息。通知由服务端发送，而不是由页面发送，原因有二：HTML 中的 webhook URL 会公开，而且未完成的点击不算下载。

嵌入消息包含来源、城市/国家/地区（来自 Cloudflare 的地理位置信息）、引荐来源、浏览器，以及该浏览器之前是否下载过。

npx wrangler secret put DISCORD_WEBHOOK_URL     # once; the webhook URL in Discord
npx wrangler deploy
curl https://vibresia.com/api/health   # {"discord":"configured"}

来自应用的错误。 应用无法保存 webhook（它会放在应用包中，任何人都能读取），因此应用会向此站点的 POST /api/notify 发送请求，再由 Worker 转发。将共享令牌设为第二个密钥，然后将相同的值写入应用：

npx wrangler secret put NOTIFY_TOKEN          # any random string
REPORT_TOKEN=<the same string> ./build-app.sh release

会收到三类报告：audio_error（音频源故障或中断——这是堆栈跟踪永远无法显示的故障）、source_failure 和 app_crash（包含顶部堆栈帧）。拒绝权限提示是一种选择，而非故障，因此不会上报。

两种音频报告不受应用内开关控制：用户明确选择了该音源，而输入设备失效属于其他方式无法发现的 bug。app_crash 则受开关控制：它会随崩溃报告上传到 PostHog，而上传需要启用“分享匿名使用数据”，因此关闭该选项会同时停止这两类数据的上传。发送的内容是应用状态——vibescape、流派、错误文本——绝不会包含音频或曲目名称。错误报告有独立的冷却限制（每分钟 1 次、每小时 60 次），因此故障安装不会刷屏；将 DISCORD_ERRORS_ENABLED = "false" 设为 false 即可关闭错误报告，不影响下载提醒。

在本地，.dev.vars（已加入 gitignore）会将 webhook 指向一个存根：

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

注意：

• webhook URL 和通知令牌都属于凭据。 如果 scripts/check-no-webhook-leak.sh 在项目目录中发现其中任意一项，就会失败——delphina 曾遇到同样的问题，最终这些凭据被写入了数十个版本标签中。如果发生泄漏，请在 Discord 中重新创建 webhook，并使用 wrangler secret put 设置新的 webhook。
• 系统会过滤机器人和链接预览器；双击按钮只会发送一次通知（5 秒防抖，每小时最多 30 次）；通知通过带超时和一次重试的 ctx.waitUntil 发送，因此 Discord 宕机不会拖慢或中断下载。
• 如需关闭通知，请在 wrangler.toml 中将 DISCORD_NOTIFICATIONS_ENABLED 设为 "false" 并重新部署；无论开关状态如何，网站都能正常运行。
• install.sh 仍会直接从 GitHub 下载，因此通过脚本安装不会生成通知。

共享 vibescape

自定义 vibescape——也就是某人编写的 vibescape——过去会将内容作为载荷放在链接中： vibresia.com/share/?d=<base64 of the deflated shader>。这种方式完全不需要后端， 所以当初才这样设计。但链接大约有 370 个字符，而且服务器会用 307 响应将其重定向到 带末尾斜杠的地址；WhatsApp 的链接预览爬虫不会跟随这个重定向，因此预览一片空白， 链接在聊天中看起来像是坏掉了。

现在，载荷会被存储起来，链接也变短了：

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

• 同一个 vibescape 始终对应同一个链接。 过去每次分享都会新建一条记录——一个新行、 一个新 ID、一个新 URL——所以同一个 vibescape 分享两次会得到两个链接，而重新分享 别人发给你的 vibescape 又会得到第三个链接。应用会对 vibescape 的内容（名称、作者、 URL、shader）进行哈希，并发送这个哈希；Worker 会查找哈希相同且载荷相同的分享， 并返回找到的记录，而不是再创建一条。key 列上有一个部分唯一索引，因此两台设备 同时分享时也会落到同一条记录上。
• 通过链接收到的 vibescape 会保留它收到时所用的链接。 页面会将分享的 ID 放进深层 链接，应用会将它与 vibescape 一起记下；分享时，应用会返回这个链接：发送给你的人 用的就是这个链接，而你转发给的人也应该收到同一个链接。编辑 vibescape 后，哈希会 改变，因此它会得到自己的链接。
• 图片会标明创作者。 应用会在上传的图片上加上 Vibresia 标志和署名，网站内置的 图片也由同一段代码绘制——参见 VisualiserMac/Sources/VibresiaBrand。

画廊

vibresia.com/vibescapes 会在同一个列表中展示内置 vibescape 和用户分享的 vibescape， 并按最新优先排序。

分享 vibescape 一直都会生成任何人都能打开的链接。画廊则不同：它会列出这些 vibescape，因此任何人都能找到其中的内容——名称和作者也会公开。分享面板会说明这一点， 并提供一个默认勾选的复选框。

• 应用会征求同意。 POST /api/share 接受 public 参数，分享面板中的名称旁边 有一个复选框。
• Worker 会将其存储在 is_public 列中，并通过 /vibescapes（页面）和 /api/gallery（同一内容的 JSON 格式）提供列表。卡片由服务器生成，因此页面无需 JavaScript 也能正常工作，爬虫也能看到列表。
• 内置 vibescape 也会列在其中，日期设为它们首次出现的那一天——也就是首次提到该 vibescape 的提交日期——以便与用户分享的内容一同排序。scripts/generate-share-pages.py 会计算出这个日期，并将其写入分享清单。它们的卡片使用干净的静帧，与其他人的卡片 一样，而不是带边框的分享图。
• 画廊创建之前分享的内容不会列入其中。 当时并未让用户选择；未经询问就发布，会 把别人的名字放到网站首页上。再次分享时勾选该复选框，就会将其列入画廊。

管理页面

vibresia.com/admin — 不提供链接，也不在任何站点地图中。它会要求输入令牌，然后列出每个分享项，包括图库中的和隐藏的，并提供三种操作：

• 隐藏会将其从图库中移除，但链接仍然有效。适用于内容没问题、但不应列出的分享项。
• 显示会将其重新放回图库。
• 删除会移除该行及其链接：图片和名称也会一并删除。此操作无法撤销，因此会先要求确认。

该令牌是一个名为 ADMIN_TOKEN 的 Worker 密钥，不是分享令牌——分享令牌会随应用发布，因此任何人都能从应用包中读出它。管理令牌永远不会离开服务器，是公网上的访客与图库之间唯一的屏障。页面会将其保存在 sessionStorage 中，因此它只存在于该标签页，不会存到其他地方。

npx wrangler secret put ADMIN_TOKEN

• 使用 D1，而不是 Workers KV。 KV 是最终一致的——分享后十秒打开链接，可能会连接到一个尚未看到写入内容的边缘节点并返回 404，这意味着链接恰好在被使用时失效。D1 基于 SQLite，具有强一致性，因此链接一创建就能使用。它是免费的：每天可写入 100,000 行、读取 5,000,000 行，存储空间为 5 GB。一条分享记录包含一个负载和一张约 120 KB 的图片。
• 页面由服务器提供，而不是重定向过去。 预览爬虫不会跟随重定向。Worker 会获取 /share/，并改写特定于该分享项的部分：标题、描述，以及指向已存储图片的 og:image。爬虫不会运行页面的 JavaScript，因此这些内容必须直接写在 HTML 中。
• 图片就是 vibescape。 应用会在绘制分享页面静态画面的同一时刻，以 1200x630 的尺寸渲染它（进入第六秒时，因此所有由时间驱动的内容都已进入状态），所以聊天中的预览图就是接收者得到的图片。
• 长链接仍然有效。 它自身包含负载，因此无需存储任何内容。如果无法连接网站，应用会回退到使用长链接——分享不能依赖网络。

该端点需要令牌，但它只是提高了操作门槛，并非真正的锁：令牌会随应用发布，因此任何人都能从应用包中读出它。它能阻止的是脚本创建分享项，耗尽每日写入配额。

npx wrangler secret put SHARE_TOKEN        # once; the same value goes in VisualiserMac/.env
npx wrangler d1 migrations apply vibresia-shares --remote
node scripts/backfill-share-payload-hashes.mjs

顺序很重要。 迁移会添加 Worker 用于查找分享项的列，而回填会为这些列创建之前生成的分享项填入哈希值。先运行迁移，再运行回填，最后部署 Worker。即使数据库尚未迁移，Worker 仍能运行——它会退回到单独存储每个分享项，这正是它以前的做法——但相同链接行为需要这些新列。

SHARE_TOKEN 与 NOTIFY_TOKEN 属于同一类凭据，因此如果它出现在代码库中，scripts/check-no-webhook-leak.sh 就会失败。

公共 MCP 服务

https://vibresia.com/mcp — 一个远程 Model Context Protocol 服务，因此，在浏览器中运行的 Agent 可以编写 vibescape，无需安装应用，也无需任何地方配备 GPU。

它与应用自己的本地服务理念相同，只是省去了需要 Mac 的部分：它无法绘制，因此无法显示预览或检查着色器能否编译，也无法感知 Mac 上正在播放的音乐。它能做的是编写 vibescape、对其进行 lint 检查，并返回链接。

• 由浏览器负责绘制。 着色器无法在 Worker 中运行，但分享页面会通过 WebGL 实时绘制 vibescape，因此工具返回的是一个链接，打开后即可看到正在运行的世界——无论是否安装应用，任何人打开都能使用。
• 创建和分享是两个操作。 create_vibescape 会创建分享并将其设为未列出；share_vibescape 会将其加入公共画廊，这正是它该去的地方，因为分享的目的就在于此。
• 无需身份验证。 两个目录都提供该服务，而要求账户的服务会把人们拒之门外，无法实现它的存在目的。写入操作按地址限流，并且会设为未列出，因此滥用造成的成本有限，也不会影响画廊。
• /.well-known/mcp.json 是 MCP 注册表读取的发现文件，也是该域名证明其拥有所声明服务的方式。

scripts/check-mcp-reference.py 会在两份 vibescape 参考文档（应用内和网站上的）出现偏差时阻止发布，确保 Agent 无论询问哪一份，都不会得到不同的信息。

npx wrangler secret put SHARE_TOKEN    # only for the app's own sharing
python3 scripts/check-mcp-reference.py  # and --write to copy the app's text over

更新日志和未解决问题

着陆页上的这两个部分会在运行时从 api.github.com 读取内容，而不是将内容硬编码在页面中，因此不会在两次部署之间过时。以下三点确保这一机制可靠：

• 缓存在 sessionStorage 中，有效期为 15 分钟。GitHub 未经身份验证的 API 每个 IP 每小时允许 60 次请求，而所有访客都会共用同一个 IP 的额度。
• 延迟加载——当该部分滚动进入视野时才开始获取内容。
• 绝不造成致命错误——如果 GitHub 宕机、对我们限流，或 JSON 格式发生变化，该部分会说明情况，并保留指向仓库的链接。问题标题通过 textContent 而非 innerHTML 渲染，因为标题内容是用户在文本框中输入的任何内容。

SEO

• 在 Search Console 中提交站点地图一次 — https://vibresia.com/sitemap.xml。网站部署后重新提交；站点地图还包含 lastmod。
• index.html 中的结构化数据是 SoftwareApplication + Organization JSON-LD。版本号取自构建日期，因此无需手动更新 — VisualiserMac/version.sh --write 会将版本写入 index.html 和 VisualiserMac/VERSION，而 scripts/check-vibescapes.sh 会在两者不一致时阻止发布。
• 在 vibresia.com 的 Cloudflare 区域中启用“Always Use HTTPS”。Worker 自带的 http: → https: 重定向也能实现同样的效果，但区域设置才能避免重复提供内容。旧的 audiovane.minithlabs.com 名称仍关联到 Worker，以便进行重定向 — 请参阅下方说明。
• 旧域名用于重定向，不是另一个站点。 audiovane.minithlabs.com 关联到同一个 Worker，Worker 会以 301 状态码将其重定向到 vibresia.com 并保留路径 — 因此旧的安装命令和任何旧链接仍然有效。为此，其 DNS 必须继续指向 Cloudflare。更改域名无法沿用的一项设置是：分析退出选项存储在浏览器的 localStorage 中，该存储按来源隔离，因此任何曾在旧站点退出分析的人都必须在新站点再次退出。
• Worker 通过路由关联，而非自定义域名。 vibresia.com 在 Worker 创建之前就已指向 Cloudflare，因此其 DNS 记录并非由 Cloudflare 创建；自定义域名需要接管这些记录，并会拒绝覆盖它们。路由会将主机名绑定到 Worker，同时保留 DNS 不变。出于相同原因启用了 run_worker_first：重定向由 Worker 决定，如果资源直接由边缘节点提供，就会绕过重定向。
• Cloudflare 使用默认的缓存设置（max-age=0, must-revalidate），而 site/_headers 中的 Cache-Control 规则会在此基础上追加，而非替换，因此无法通过这种方式更改设置。再次访问时会根据 ETag 重新验证并返回 304，而不是重新下载 5.9MB；关键就在于此。
• 页面是一个静态文件：一个 H1、16 张延迟加载且带有描述性替代文本的图片，没有框架。请保持这样 — 在此之前，本地测得的 LCP 约为 0.08s，CLS 约为 0.005。

导出视频

分享面板可以将 vibescape 最近十秒的画面和音乐保存为影片，放入“下载”文件夹。

画面由应用自身的渲染器生成 — 与窗口当前所绘制的内容相同，取自应用时钟最近十秒的时间段 — 因此它就是 vibescape 本身，而不是 vibescape 的图片。声音是应用最近十秒听到的内容，也就是当时的音乐。

片段时长取决于应用已有的音频：如果已有十秒音乐，就导出十秒；如果没有，就导出已有的时长。应用必须正在听某些内容，才能导出片段。

./build/Vibresia.app/Contents/MacOS/Vibresia --export-video band /tmp/out.mp4

歌曲及其流派

当应用能够识别正在播放的内容时，乐队的流派信息取自歌曲。有两种方式，各自并行：

• 按名称识别。 Apple Music 和 Spotify 都会在曲目切换时发布通知，其中包含标题和艺人。应用会在 Apple 的公开目录中查找歌曲，该目录包含流派信息 — 因此舞台是根据曲目选择的，而不是根据波形猜测。 VisualiserMac/Sources/VisualiserMac/Audio/SongIdentifier.swift。
• 通过聆听识别。 ShazamKit 会将声音特征与 Shazam 的目录进行匹配，因此适用于任何能发出声音的内容 — 浏览器、电影等 — 而不只适用于会发布通知的播放器。VisualiserMac/Sources/VisualiserMac/Audio/ShazamIdentifier.swift。

第一种方式已随应用发布。第二种方式由功能标志控制，因为要与 Shazam 的目录匹配，应用必须获准发起请求；是否获准由开发者门户中针对应用标识符的 ShazamKit 服务决定。

ShazamKit 需要什么，以及为什么默认不启用

Apple 会为使用配置描述文件签名的应用签发 com.apple.developer.shazamkit 权限。此应用使用 Developer ID 证书签名并经过公证，因此必须手动在签名中声明该权限——而声明团队尚未获批的权限，并不是构建无法匹配，而是构建出来的应用根本无法启动。macOS 会终止进程：

$ SHAZAMKIT=1 ./build-app.sh debug && ./build/Vibresia.app/Contents/MacOS/Vibresia
Killed (exit 137)

不带此权限的同一应用可以运行，但匹配结果会返回 com.apple.ShazamCore error 102——意思是“未获准”，而不是“未找到”。

因此，此权限需要手动启用（SHAZAMKIT=1），而且只有在开发者门户中为 com.minithlabs.visualiser 启用了 ShazamKit 服务，并且 Apple 为 Developer ID 签名授予了该权限后，才值得开启。

这项探索仍然保留在这里，因为这个问题值得一个答案，而不是一篇论坛帖子：

./build/Vibresia.app/Contents/MacOS/Vibresia --shazam-spike

哪些内容会离开设备

音频不会离开设备——它会在本地分析并在本地绘制，乐队的舞台则根据着色器对音频的处理结果绘制。

当音乐应用告知正在播放什么歌曲时，歌曲的名称会离开设备：歌曲标题和艺人会在 Apple 的公共目录中查询，这与 iTunes Store 使用的搜索相同。不会发送其他内容，也不涉及任何账户。目录返回的结果是曲风，之后的判断都在本地进行。

查询必须同时匹配标题和艺人。目录会欣然将《Me and Your Mama》作为《Redbone》的结果返回——艺人相同，歌曲不同——而匹配到错误的歌曲会导致舞台显示错误的曲风，因此会舍弃不明确正确的结果，而不会使用它。当目录中没有这首歌时，应用会退回到一直以来使用的音频启发式方法，不会损失任何功能。

若要在不使用音乐应用的情况下试用查询：

./build/Vibresia.app/Contents/MacOS/Vibresia --song-lookup "bad guy" "Billie Eilish"

调校乐队

VisualiserMac/Tests/band-fixtures.yaml 列出了标注了曲风和演奏者的 YouTube 视频。scripts/band-eval.py 会在 Vibresia 聆听时让 Chrome 播放每个视频，然后打印评分表（曲风是否正确？舞台上的乐手是否正确？），并将检测器特征和各曲风评分保存到 VisualiserMac/Tests/eval-results/，以便调校。Vibresia 必须先获得系统音频权限；运行期间请关闭其他音频。

scripts/band-eval.py --check     # validate the fixtures file
scripts/band-eval.py             # run them all (about a minute each)
scripts/band-eval.py --only jazz

发布

1. 在 site/index.html 中添加任何新的 vibescape（一个带有 data-vibescape="<case name>" 的卡片）。
2. VisualiserMac/release.sh 会运行两项网站检查，根据日期确定版本，将版本记录到 VisualiserMac/VERSION 和落地页中，进行构建，压缩 Vibresia.app，并发布 GitHub 版本 v<VERSION>。安装程序和应用的更新检查始终使用最新版本。如果钥匙串中有 Developer ID 证书，发布流程也会进行公证——公证票据会在构建后、压缩前装订到应用上，因为再次签名会使其失效。请参阅签名与公证。
3. 如果网站或 worker 有更改，请运行 npx wrangler deploy，然后重新提交站点地图。克隆后首次部署需要运行 npx wrangler secret put DISCORD_WEBHOOK_URL（请参阅下载通知）。