moontide

Moontide

月亮指引潮汐。

一个业余项目：Claude 为你现场演奏音乐。描述一种情绪、一个主题或一个想法，Claude 就会编写 Strudel 代码，在浏览器中播放，并持续变化，永不停歇。

▶ 在 YouTube 上观看演示（3 分钟，含声音）

制作缘由

Moontide 是一个个人项目。大部分代码、研究和文档都是由一位 AI 编码助手在我的指导下编写的。我设定目标，听每一处改动，用自己的乐器试奏，凭耳朵判断效果，并做出决定。这里的所有内容，包括错误在内，都由我负责。

初衷

出于好奇。我想看看，如果给 AI 助手一件好乐器，它能把真正的音乐创作做到什么程度，而不只是做技术演示。Strudel 就是这件乐器：它是一种现场编程语言，改动会在下一个循环中生效，不会中断播放；音乐以纯文本呈现，我们双方都能读懂。

Claude 编写代码，代码在播放时始终显示在屏幕上。你可以观看、手动编辑、回到任何早期版本，也可以指着页面上的某个元素，请它做出改动。

功能

• 你可以提出请求（“用 D 小调创作一段梦幻风格的音乐”“更阴暗一些”“加一段贝斯”）。Claude 会编写 Strudel 代码，浏览器页面随即播放。每次改动都会在不到一秒内生效，音乐不会中断。
• 代码始终可见且可编辑。每个播放过的版本都会保留，Claude 也可以恢复其中任意一个版本。
• 页面围绕代码提供多种音乐视图：可编辑音符的命名音轨时间线、显示乐曲各部分的歌曲网格、以列表或树状结构呈现的历史记录、带有分组和指示灯的混音器（操作控件会改写代码），以及在钢琴或吉他上显示音阶的即兴视图。如果音符符合多个音阶，即兴视图会推荐一个，并说明原因。
• Claude 可以在若干小节内逐渐加快或放慢节奏，而不是突然改变。
• 在页面中的任意内容上单击右键，即可将该内容作为上下文发送给 Claude。顶部栏中的 Requests 列表会显示每个请求的处理结果。
• 通过 Web MIDI，同一段代码也可以在页面中演奏真实的 MIDI 乐器。

Moontide 并非从零开始。它的音乐引擎是 Strudel，这是 Felix Roos、Alex McLean 和 Strudel 贡献者开发的 TidalCycles JavaScript 移植版。Moontide 是 Claude 与 Strudel 页面之间的桥梁。

工作原理

 you ──talk──► Claude ──MCP (stdio)──► Moontide ──WebSocket (localhost)──► browser page
                                          │                                 Strudel plays
                                          └─ history file on your disk      the code, sound
                                                                            and Web MIDI out

1. Moontide 以 MCP 服务的形式运行，Claude 会连接到它。在你请求播放音乐或说“start Moontide”之前，它不会启动任何内容。

2. 随后，它会在浏览器中打开一个带有 Strudel 编辑器的页面。

3. Claude 编写代码，页面播放音乐，你可以看到代码焕发生机。

4. Claude 可以随时停止音乐。页面本身也有 Play 和 Stop 按钮。

5. 在页面中的任何位置右键点击，即可向 Claude 询问相关内容。在时间线中右键点击，还会发送指针所在时刻的信息：周期和节拍、当时播放的版本、在该处发声或从同一个十六分音符开始的音符及其力度；如果是 MIDI 音轨，还会发送乐器和通道。Session 抽屉（顶栏中的 Session 按钮）会说明页面请求是实时发送（立即到达 Claude），还是等待 Claude（在 Claude 执行下一项操作时到达）。其中的 (i) 会说明如何切换。

   顶栏中的 Requests 按钮会显示仍在处理中的请求数量，并打开一个列表：每个请求占一行，显示处理情况和经过的时间。请求状态会先显示 Sent，随后显示 Waiting for Claude's next action 或 Received，接着显示 Claude has started on it，表示 Claude 在请求到达后发起了调用。为请求所做的更改会先显示 Waiting for its line，表示正在等待下一个小节或乐句，随后显示 Applied as v12（即 History 视图中的版本）；失败的更改会显示 Failed 和错误信息，被更新的更改取代或被 Stop 取消的更改也会注明。Claude 用文字回复的请求会显示 Answered 或 Declined，并附上 Claude 的回复。只有 Claude 在说明更改时明确提到某个请求，该请求才会显示为已应用，单凭时间先后不会判定为已应用。30 秒内没有新消息时，状态会显示 No change yet，并继续计时：这不表示失败。如果页面断开连接，未完成的请求会显示 Connection lost。点击一行即可查看完整请求及其状态说明。完成的请求会在 30 秒后移至简短的 Recent 列表。Moontide 服务停止后不会保留任何内容。

安装

简要步骤，适用于已安装 Node 22 或更高版本以及 Claude Code 的用户：

claude mcp add --scope user moontide -- npx -y moontide-mcp

然后启动一个新的 Claude 会话并请求播放音乐。以下步骤会解释各个环节。

1. 准备事项

• Node 22 或更高版本，以及 npm 和 npx（随 Node 一同安装）。
• Claude Code 或 Claude Desktop。 Moontide 是 MCP 服务，由 Claude 与其交互。
• Chrome，Moontide 已在此浏览器中测试。使用 MIDI（Web MIDI）时，请使用 Chrome 或 Edge。
• 互联网访问：Strudel 及其音效从网上加载。
• 扬声器或耳机。

2. 检查 Node

在终端中运行：

node --version

输出必须为 v22 或更高版本。如果未安装 Node 或版本较低，请从 nodejs.org 安装 LTS 版本。在使用 Homebrew 的 macOS 上，也可以运行 brew install node。之后打开一个新终端并再次检查。

3. 获取 Claude

从 claude.com 安装 Claude Code 或 Claude Desktop，并登录一次。Moontide 两者都支持；测试最多的是 Claude Code。

4. 将 Moontide 添加到 Claude

claude mcp add --scope user moontide -- npx -y moontide-mcp

claude mcp get moontide

{
  "mcpServers": {
    "moontide": {
      "command": "npx",
      "args": ["-y", "moontide-mcp"]
    }
  }
}

claude mcp add --scope user moontide -- cmd /c npx -y moontide-mcp

git clone https://github.com/konni-arcadia/moontide.git
cd moontide
npm ci
npm run build

claude mcp add --scope user moontide -- node <folder>/dist/index.js

5. 播放第一段音乐

1. 启动一个新的 Claude 会话。此时不会打开任何内容：Moontide 会等你提出需求。
2. 请求播放音乐，例如“播放一些适合开启新一天的舒缓音乐”或“来点缓慢、温暖的律动”。也可以说“启动 Moontide”。在 Claude Code 中，/mcp__moontide__start 的作用相同。
3. 页面会在新标签页中打开，地址为 http://localhost:5757；如果 5757 端口正忙，则会使用其他端口。Claude 的回复会显示地址。标签页标题会显示 Claude 运行所在的文件夹和端口，例如“Moontide · my-project · 5757”。
4. 在页面任意位置点击一次。浏览器只有在点击后才会开始播放声音。
5. 请求进行更改：“更暗一些”“加点贝斯”“慢一点”。

在环境中设置 MOONTIDE_NO_BROWSER=1 后，启动 Moontide 不会打开标签页。你可以自行打开 Claude 回复中提供的地址。

更新

要查看正在运行的版本，请运行 npx -y moontide-mcp --version。版本发布记录见 CHANGELOG.md。npx 可能会继续使用已下载的副本；要升级到最新版本，请使用 @latest 再次添加 Moontide：

claude mcp remove moontide --scope user
claude mcp add --scope user moontide -- npx -y moontide-mcp@latest

卸载

claude mcp remove moontide --scope user

在 Claude Desktop 中，从配置文件中删除 moontide 条目，然后重启。Moontide 会将历史记录和设置保存在数据文件夹中（参见“历史记录”）；如果也想删除这些内容，请删除该文件夹。

MIDI 乐器（可选）

Moontide 可以通过 Web MIDI 播放代码中的 MIDI 乐器。它已内置 Roland MT-32 和 SC-55 的模型。你可以描述自己的乐器和模型、添加音色目录并发送 MIDI 时钟。设置说明见 docs/midi.md。

无需权限提示的页面请求

在 Claude 应用的 Code 标签页中，让 Claude 开启或关闭页面请求。Claude 会调用 Moontide 的 set_page_requests 工具。在终端中的 Claude Code 里，输入 /mcp__moontide__page-requests-on 让请求立即生效，或输入 /mcp__moontide__page-requests-off 让请求等待。请求立即生效时，Claude 会启动监控程序，最长持续 30 分钟；当工具回复要求时，监控程序会再次启动。请求等待时，工具回复会停止提供启动监控程序的选项，直到再次开启页面请求。页面请求需要打开的页面，因此请先启动 Moontide。这些名称假定服务已添加为 moontide。

Claude Code 在启动页面请求的监控程序前会请求权限，因为它会运行命令。你可以每次都批准。如果你想改用范围更窄的权限规则，请参阅 Claude Code 文档中的权限部分。请勿允许宽泛的 node 命令。

音乐参考

Claude 通过 get_strudel_reference 工具（也以 MCP 资源的形式提供）获取页面运行的确切 Strudel 版本的事实性参考，涵盖九个主题：Strudel 与 TidalCycles 的比较、迷你记谱法、模式函数、效果和声音控制、音色库、Strudel 中的乐理、过渡、歌曲结构和 MIDI 输出。它只包含事实：有哪些内容以及如何编写。Moontide 不提供情绪词汇、风格素材或示例作品；Claude 会运用自己的乐理知识，将你的文字转化为音乐，然后用一句话告诉你它做了什么选择。用你自己的话提出一个惊喜要求：没有相应的菜单命令。为本次创作设定一个方向，例如渐进变化，Claude 就会在每次修改时遵循这个方向，直到你取消。告诉 Claude 你在意什么（旋律、节奏），它就会保留这些内容，并在彻底改写前征求你的意见。

小幅修改与和声

Claude 可以通过 edit_code 工具修改长篇作品中的几行代码，而无需重新发送整段代码；对于需要等到小节开始才生效的修改，Claude 会等到小节开始时再编辑，并保留你手动所做的编辑。

代码可以通过一行顶层代码声明所指的和声，例如 const harmony = 'C:minor'，并将其放在模式上方。它不会播放任何声音，也不会成为音轨。Jam 视图随后会并排显示两行：“已声明：”和“实际听到：”。

当音符适用于多个音阶时，Jam 视图会推荐一个音阶，并用一句话说明原因，例如“推荐：C 大调，听到的 C 音最多。”如果正在播放的段落声明的音阶也属于适用音阶，它会采用该音阶；否则会采用音符最支持的音阶。警告仍会显示。“适用音阶，点击切换：”会列出这些音阶，点击一次或按 Enter 即可切换整个视图。只要适用的音阶不变，你选择的音阶就会保留；重新加载后则会重置。如果适用音阶的音符各不相同，且代码声明的音阶不属于其中任何一个，则不会显示警告：视图会说明原因并列出这些音阶，但不提供切换选项。钢琴会像吉他一样着色，使用相同的图例；此外，每个声部都有形状或文字提示，因此即使不看颜色也能辨认。

歌曲结构

Claude 编写的每首新作品都会在顶部以一个 const song 开始。它会列出各个段落及其循环长度，说明每个段落中每条音轨播放哪个版本（变体），或该音轨是否休止，还可以将音轨分组。它仍是普通的 Strudel，同一段代码也能在纯 Strudel 中播放。对旧作品提出的小幅修改会直接在原处完成，不会重构作品。没有歌曲结构的作品播放和显示方式与之前相同。

对于包含歌曲结构的作品，Parts 视图称为 Song。Song 网格会将音轨显示在可折叠的分组下，每个段落占一列，并标记正在播放的段落。

• 点击段落标题，即可在工具栏指定的下一条边界处启动该段落：当前播放段落结束、下一乐句开始，或下一小节开始。再次点击可取消。
• 点击单元格，可为该音轨和段落选择其他变体或休止。它会按照你平常手动编辑的时机接管。
• 固定变体会显示其音符是否符合该段落的和声：符合、不符合或无法检查。它只作提示，不会阻止播放。
• 点击 Stop 后再点击 Play，会从第一个段落开始播放。Jam 视图中的 Declared 行会随正在播放的段落更新。

Mixer 会将各分组显示为边框，并与网格同步折叠。点击分组的 M 或 S，一次即可将其下的所有音轨静音或独奏。没有分组推子，因为纯 Strudel 不支持分组增益。每条通道和每个分组上的小指示灯会在听到音符时闪烁。在 Session 抽屉中关闭动态效果后，音符持续出现时，指示灯会保持亮起。

在 Timeline 上，点击音符即可选中它。向上或向下拖动，或按 Up 和 Down 键，可按半音改变音高。按 Delete、Backspace 或选择“Make a rest”，可将音符变为休止。两个按钮可按十分之一的幅度改变其力度。页面会在写入前检查编辑内容；如果一次编辑会在多个位置改变音符，会先告知你，并沿用你手动编辑的时机。页面无法编辑的音符会显示原因。随后，你的操作会打开 Ask 框，其中已填好请求；只有按 Enter 后才会发送给 Claude。拖动以选中单条音轨上的范围，或按住 Shift 并按 Left 或 Right 键，即可选中整数个循环的范围，然后使用“Ask Claude”发送。

右键点击段落、音轨、单元格或分组，即可向 Claude 询问相关内容。

速度渐变

请 Claude 在若干小节内加快或减慢速度，例如“在八小节内逐渐加速到 140”。Claude 会在 set_code 或 edit_code 中发送新代码，以及要达到的速度和 glideBars。glideBars 是一个介于 1 到 64 之间的整数，表示小节数。随后，速度会从当前播放速度以均匀的小步逐渐变为代码中的速度，并精确停在该速度上。渐变会立即开始，或在更改等待下一个小节或乐句时，从对应边界开始。

渐变过程中，顶部栏中的速度会显示实时速度、箭头和目标速度。将鼠标悬停在其上，可查看剩余小节数。

你对 Mixer、Song 网格单元格、Timeline 和手动编辑所做的更改不会中断渐变。包含其他速度的代码会取消渐变，并立即按新速度播放。未指定速度的代码会取消渐变，速度保持不变。新的 glideBars 会替换当前设置。Stop 也会取消渐变；下次点击 Play 时，会按代码中的速度开始播放。重新加载页面或由另一个标签页接管播放也会结束渐变。渐变没有专用的取消按钮。

如果没有内容正在播放、代码未设置速度，或代码设置的速度与当前播放速度相同，系统会拒绝渐变请求且不作任何更改。渐变不会成为一个版本：它不会写入代码或历史记录。

MIDI 时钟会跟随渐变的每一步。尚未验证跟随该时钟的硬件（例如琶音器或步进音序器）对速度渐变的响应方式。

历史记录

每个播放过的版本都会保留下来：Claude 自己做的修改，以及你按 Ctrl+Enter 做的编辑，每个版本都附有时间、修改者和简短标签。失败的代码和停止播放不算版本。

你可以向 Claude 提出类似这样的要求：“回到上一个版本”“回到 3 次修改之前的版本”“回到有贝斯的那个版本”或“保留这个版本，命名为 Take two”，也可以说“列出我收藏的版本”。Session 抽屉会在“上次更改”卡片中显示当前播放版本的编号，例如 v42。

历史记录文件位于操作系统的用户数据文件夹中：

• macOS：~/Library/Application Support/moontide/history.jsonl
• Linux：$XDG_DATA_HOME/moontide/history.jsonl，或 ~/.local/share/moontide/history.jsonl
• Windows：%APPDATA%\moontide\history.jsonl

设置 MOONTIDE_DATA_DIR 可使用其他文件夹。历史记录是一个文本文件，每行一条记录，即使 Claude 会话结束后也会保留。

历史记录最多保留最近 1000 个版本；更早的版本会分批删除，并通知 Claude。收藏的版本永远不会被删除。

如果文件中有一行无法读取，Claude 会收到无法读取的行号；这些行会原样保留在文件中。如果文件完全无法读取或写入，音乐仍会继续播放，并会通知 Claude。

使用同一个历史记录文件时，一次只运行一个 Moontide。同时运行两个可能会导致两个版本使用相同的编号。

故障排除

安装后立即显示“Failed to connect”。 首次启动时会下载软件包，而 Claude Code 会在 30 秒后放弃。稍等片刻，然后运行 claude mcp list 再次检查。如果仍然失败，请延长超时时间后启动 Claude Code：MCP_TIMEOUT=60000 claude。在 PowerShell 中，使用 $env:MCP_TIMEOUT = "60000"; claude。

在另一个文件夹中找不到 Moontide。 添加时没有使用 --scope user。请使用 Install 行重新添加。

页面没有打开。 Claude 的回复中会显示页面地址。你可以自行打开，也可以让 Claude 再次启动 Moontide：如果没有已连接的页面，它会提供地址并打开新标签页。

打开了多个 Moontide 标签页。 每个启动了 Moontide 的 Claude 会话都有自己的页面和端口。标签页标题格式为“Moontide · · ”，其中包含该会话运行所在的文件夹；Session 抽屉中也会显示相同的信息。询问 Claude 哪个标签页属于它：它会告知你地址、端口和标签页标题。

没有声音。 在页面中单击一次。检查浏览器标签页是否处于静音状态，并保持页面打开。

Claude Desktop 找不到 npx。 将完整路径填入 "command"：在 macOS 上运行 which npx 或在 Windows 上运行 where npx 所显示的路径，此处写作 <full path printed by which npx>。这是常见建议，但尚未在此处尝试。macOS 上的 Claude Desktop 日志位于 ~/Library/Logs/Claude，Windows 上位于 %APPDATA%\Claude\logs。

MIDI 提示使用 Chrome 或 Edge。 该浏览器不支持 Web MIDI。

状态

目前处于早期阶段，仅供个人使用。它只在一套环境中运行过：Mac、Chrome、Claude Code 和 Claude Desktop；MIDI 方面则使用 Roland SC-55、Munt MT-32 模拟器和 Roland JUPITER-Xm。尚未在其他环境中尝试过。测试套件会在 CI 中运行于 Windows、Linux 和 macOS，但还没有人在 Windows 或 Linux 上用它播放过音乐。已知存在一些错误。欢迎反馈，但我无法承诺提供支持。

已知限制：

• 仅在 macOS 上手动测试过，使用的是 Chrome、Claude Code 和 Claude Desktop。
• 尚未在 Windows 和 Linux 上手动测试。Edge、Safari 和 Firefox 也尚未测试。
• 需要访问互联网。
• MIDI 需要 Chrome 或 Edge。
• 尚未验证跟随 Moontide MIDI 时钟的硬件（例如琶音器或步进音序器）对渐变速度的响应。
• 使用同一个历史记录文件时，一次只运行一个 Moontide。
• 首次通过 npx 启动时会下载软件包，可能需要较长时间。

网络与隐私

• 服务仅监听 127.0.0.1，并拒绝任何其他主机名的请求。
• Moontide 自身的服务代码不会发出任何出站请求，也不会发送遥测数据。
• 页面从 unpkg 加载 @strudel/repl 1.3.0 和 acorn 8.18.0，并固定为精确版本且带有完整性哈希。
• 随后，Strudel 会从 raw.githubusercontent.com 和 cdn.jsdelivr.net 获取声音列表和采样。它们不受哈希校验保护。
• Claude 编写的代码会在页面中运行，并可能从其他地址加载采样。
• 历史记录保存在上文所述的本地数据文件夹中。

贡献与安全

欢迎通过问题（使用错误报告表单）提交错误报告和想法。拉取请求的处理方式请参阅 CONTRIBUTING.md。

安全问题请通过私密报告渠道提交，切勿公开创建问题。请参阅 https://github.com/konni-arcadia/moontide/security/policy。

致谢

本项目基于其他人的工作构建：

• Felix Roos、Alex McLean 和 Strudel 贡献者：Strudel （源代码：https://codeberg.org/uzu/strudel），这是一个能演奏每个音符的实时编码引擎。
• Alex McLean 和 TidalCycles 社区：TidalCycles，这是一种 Strudel 移植到 JavaScript 的模式语言。
• 制作采样的创作者：Strudel 默认加载了他们的采样集，包括 TidalCycles Dirt-Samples 和 Versilian Community Sample Library (VCSL)。
• Anthropic：Model Context Protocol 及其 TypeScript SDK，让 Claude 能够与 Moontide 通信。
• acorn 作者：页面用来读取代码的 JavaScript 解析器。

许可证

Moontide 可演奏 Strudel，而 Strudel 使用 AGPL-3.0-or-later 许可证。Moontide 也使用相同的许可证。它会在运行时从 unpkg 加载 Strudel，不会随附 Strudel。许可证文本见 LICENSE。Moontide 与 Strudel 或 TidalCycles 项目以及 Anthropic 均无关联，也未获得它们的认可。

Konni — 使用 AI 编码助手构建。