Waveform MCP

一个 MCP 服务器，为 LLM 智能体提供对 Tracktion Waveform 的控制能力。让 Claude 编写歌曲、平衡混音或渲染为 MP3 —— 并观察 Waveform 的执行过程。

通过 MCP 工具调用创作的 64 小节合成波器乐曲 —— 包含鼓、贝斯、两个铺底、对位、琶音、主旋律。包含分段标记、速度自动化、侧链抽吸效果、板式混响、片段级淡入淡出、完整的母带链。

它能为你带来什么

• 107 个 MCP 工具，涵盖编辑生命周期、轨道、MIDI、音频片段、插件、自动化、音乐理论、混音平衡、渲染、循环库、VST 发现、模式捕获和 Waveform UI 控制

• 两个端到端作曲家 —— compose_lofi_track 和 compose_synthwave_track —— 可编写完整编曲、混音并渲染的歌曲

• 一个环境音作曲家 —— compose_rainstorm —— 用于雨声 + 风声 + 雷声的音景创作

• 音乐理论知识层 —— 音阶、和弦进行、终止式、歌曲结构、声部导向规则、各流派混音平衡参考电平

• 内存模型与 Waveform 的 .tracktionedit XML 之间的验证性往返

• 片段级淡入淡出、增益、偏移、自动化曲线 —— LLM 可用于进行音乐迭代的成熟原语

• 可靠的工作流循环 —— 创作 → 写入 → 通过文件重新加载 → 恢复到已保存状态 → 试听 → 微调

状态

在 Windows + Waveform 13 上可端到端工作。macOS / Linux 路径已存在用于内容发现（预设、循环库、VST 列表），但目前 UI 控制仅限 Windows（通过 UIA / pywinauto）。

通过与 Claude 进行约 30 小时的“人在回路”迭代构建和测试。两位作曲家已多次渲染为 MP3，用户已对最终曲目表示认可。

快速开始

安装

cd "C:\path\to\waveform MCP"
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .

连接到 Claude（Code、Desktop 或任何 MCP 客户端）

~/.claude.json 或你客户端的 MCP 配置：

{
  "mcpServers": {
    "waveform": {
      "command": "waveform-mcp"
    }
  }
}

尝试一下

Open Waveform, then ask Claude:

  "Use compose_synthwave_track to make a synthwave song,
   save it to my Documents/Waveform folder, and reload it
   in Waveform so I can hear it."

LLM 调用 compose_synthwave_track → waveform_revert_to_saved，然后你按下播放键。接着进行迭代：“调低贝斯” → LLM 更新 MIX_BALANCE["synthwave"]["bass"] 并重新加载。

架构

四层结构，每一层都有明确的契约：

┌──────────────────────────────────────────────────────────────┐
│  LLM (Claude / any MCP client)                               │
└────────────────────────────┬─────────────────────────────────┘
                             │ MCP stdio
┌────────────────────────────▼─────────────────────────────────┐
│  MCP server (server.py) — 107 tools                          │
└────────────────────────────┬─────────────────────────────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
      ┌──────────────┐ ┌──────────┐ ┌──────────────┐
      │ Edit model   │ │ Knowledge│ │  Waveform    │
      │ (in-memory)  │ │  (data)  │ │  UI control  │
      ├──────────────┤ ├──────────┤ ├──────────────┤
      │ Tracks       │ │ Scales   │ │ pywinauto +  │
      │ Clips        │ │ Chords   │ │ UIA + ffmpeg │
      │ Notes        │ │ Forms    │ │              │
      │ Plugins      │ │ Mix      │ │ Menu invoke  │
      │ Automation   │ │ Velocity │ │ Revert       │
      │ Markers      │ │ Rhythm   │ │ Render→MP3   │
      └──────┬───────┘ └──────────┘ └──────┬───────┘
             │                             │
             ▼                             ▼
   ┌──────────────────┐          ┌────────────────────┐
   │ xml_writer.py    │          │ Waveform 13        │
   │ xml_reader.py    │ ◀──────▶ │ (the running app)  │
   │ ↓ .tracktionedit │          └────────────────────┘
   └──────────────────┘

关键设计选择： 模型并非 Tracktion ValueTree 的 1:1 映射 —— 它是 LLM 想要操作的形态，在保存时投影到 XML，在加载时投影回来。这使得工具变得简单（例如 audio_clip_import(track_id, file_path, start_beats, length_beats, fade_in_beats, ...)），而不是强迫 LLM 以 JUCE 内部逻辑进行思考。

工具目录

编辑生命周期 (edit.py)

edit_create · edit_open · edit_save · flush · edit_summary · edit_inspect · undo · narrate

轨道 + 混音 (tracks.py)

track_add · track_remove · mix_set · mix_apply_reference · send_add · marker_add · tempo_set · key_set

mix_apply_reference(track_id, genre, role) 从精选的混音平衡表 (MIX_BALANCE[genre][role]) 中查找 dB 目标 —— 将“底鼓是锚点，贝斯低 5-6 dB”的参考标准提炼为可调用的函数。

MIDI (midi.py)

midi_clip_add · midi_notes_add · midi_notes_clear · midi_clip_quantize

音频片段 (audio.py, clips.py)

audio_clip_import (带有 gain_db, fade_in_beats, fade_out_beats, offset_in_source_beats) clip_list · clip_set · clip_move · clip_resize · clip_duplicate · clip_remove

插件 (plugins.py, preset_library.py)

plugin_list · plugin_add · plugin_set_param · plugin_remove plugin_add_reverb (板式 / 自然 / 非线性，带有合理的默认值) plugin_add_drum_kit (基于采样器，每个打击垫对应一个 SOUND) plugin_add_modifier (LFO / 包络 / 侧链 —— 待 Waveform 完全支持后确定模式) plugin_discover (解析 knownPluginList64.settings 以列出已安装的 VST) waveform_preset_list · waveform_preset_read · waveform_plugin_types

自动化 (automation.py)

automation_add · automation_envelope · automation_clear · automation_list

目标：pan 和 plugin/<plugin_id>/<param>。音量目标在 API 层面被禁用 —— Waveform 的音量插件不支持我们的 <AUTOMATIONCURVE> 模式，会导致轨道静音。请使用 mix_set/mix_apply_reference 进行静态电平设置，使用 clip_set(fade_in_beats|fade_out_beats) 进行淡入淡出。（MCP 会拒绝 target="volume" 并给出明确的错误提示，指向替代方案。）

音乐理论知识 (music_theory.py, music_theory_data.py)

17 个查询工具：theory_scale · theory_modes · theory_diatonic_chords · theory_chord_progression · theory_cadences · theory_song_form · theory_section · theory_genre · theory_arrangement_layers · theory_velocity · theory_rhythm · theory_voice_leading_rules · theory_heuristics · theory_surprise_devices · theory_borrowed_chords · theory_mix_balance · theory_search

背后的数据：

• 13 种音阶（大调模式、和声小调、五声音阶、蓝调等）

• 25+ 种和弦进行（axis_pop, ii_V_I, andalusian, lament_bass 等）

• 终止式、歌曲结构、具有角色/密度/动态配置的分段

• 14 种流派，包含典型的 BPM、调性倾向、乐器、标志性进行

• 力度 / 节奏映射（摇摆比例、重音凸起、幽灵音符范围）

• 13 种作曲启发式规则（三法则、对比需求、惊喜配额等）

• 7 种惊喜装置（转调、伪终止等）

• 混音平衡参考表 —— 7 种流派 × 14 种角色，已完全标注

作曲家 (composer.py)

• compose_lofi_track —— 32 小节 lofi，包含鼓、贝斯、键盘、铺底、旋律、对位；感知分段的力度包络；速度自动化；lofi 母带链

• compose_synthwave_track —— 64 小节合成波，包含 7 条轨道；9 段式结构（前奏/主歌/副歌/主歌/副歌/桥段/积聚/副歌终章/尾奏）；分段贝斯律动（半速 / 8分音符抽吸 / 行进）；分段琶音主题；侧链式滤波抽吸；分段标记；片段淡入淡出

• compose_rainstorm —— 环境音景，包含雨声 + 风声 + 低通滤波的远雷声；片段级增益随机化；偏移修剪；轨道 FX

渲染 (render.py, waveform_workflows.py)

waveform_render_export · waveform_render_to_mp3 (使用捆绑的 ffmpeg + libmp3lame)

Waveform UI 控制 (waveform_workflows.py)

waveform_new_project · waveform_save · waveform_revert_to_saved (迭代循环解锁器) · waveform_close_active_tab · waveform_active_tab · waveform_project_loaded · waveform_menu_invoke · waveform_add_track · waveform_select_track · waveform_insert_clip_on_track · waveform_build_skeleton

应用生命周期 (waveform_app.py)

waveform_locate · waveform_status · waveform_launch · waveform_focus · waveform_quit · waveform_settings_dir

循环库 (loops.py)

loop_search (按速度 / 小节 / 名称) · loop_drop (自动长度，适配速度)

模式捕获 (schema_capture.py)

schema_snapshot_current_edit · schema_diff_snapshots · schema_list_snapshots

底层 UI / 桌面 (win_input.py, desktop.py)

18 个用于窗口管理、UIA 检查、按键/点击发送、截图的原语。

布局

waveform-mcp/
├── src/waveform_mcp/
│   ├── server.py                  MCP server entry (stdio)
│   ├── model.py                   Edit / Track / Clip / Note / AutomationLane dataclasses
│   ├── xml_writer.py              Edit → .tracktionedit
│   ├── xml_reader.py              .tracktionedit → Edit
│   ├── audio_convert.py           ffmpeg-backed MP3→WAV cache for Sampler sources
│   ├── music_theory_data.py       SCALES, PROGRESSIONS, GENRES, MIX_BALANCE, ...
│   ├── events.py                  event bus + JSONL log
│   ├── diff.py                    Edit-diff for change events
│   ├── tools/
│   │   ├── edit.py                Edit lifecycle
│   │   ├── tracks.py              Tracks + mix balance
│   │   ├── midi.py                MIDI clips/notes
│   │   ├── audio.py               Audio clip import
│   │   ├── clips.py               Clip mutators (move, resize, duplicate, set)
│   │   ├── plugins.py             Plugin add + reverb / drum kit / modifier helpers
│   │   ├── automation.py          Automation lanes (pan + plugin params)
│   │   ├── preset_library.py      Factory preset browser
│   │   ├── loops.py               Loop library search + drop
│   │   ├── render.py              Render stubs
│   │   ├── waveform_app.py        App lifecycle
│   │   ├── waveform_workflows.py  UI workflows (revert, render-to-mp3, etc.)
│   │   ├── desktop.py             Generic desktop primitives
│   │   ├── win_input.py           Windows UIA + keystroke primitives
│   │   ├── schema_capture.py      Hand-fixture capture for schema reverse-engineering
│   │   ├── music_theory.py        Theory query tools
│   │   ├── composer.py            compose_lofi_track, compose_synthwave_track, compose_rainstorm
│   │   └── common.py              @op decorator (apply + diff + event)
│   └── preview/
│       ├── app.py                 FastAPI + websocket
│       └── static/                HTML / JS piano-roll
├── tests/
├── docs/
│   ├── img/synthwave_arrangement.png
│   ├── ARCHITECTURE.md
│   ├── EVENT_SCHEMA.md
│   └── EDIT_MODEL.md
├── pyproject.toml
└── README.md

真正有效的迭代循环

在经历了多次失败的尝试后，以下循环让 LLM 和用户能够在不每轮重启 Waveform 的情况下协作创作曲目：

1. Compose / mutate            → composer.compose_*  or clip_set / mix_apply_reference
2. Save to disk                → edit_save / flush  (writes .tracktionedit)
3. Reload in Waveform          → waveform_revert_to_saved
                                  (File → Revert to saved state, auto-confirms popup)
4. User listens                → "turn the arp up"
5. Update MIX_BALANCE or run a clip mutator
6. → goto 2

杀手锏是发现了 Waveform 的 文件 → 恢复到已保存状态 菜单项：它强制打开的编辑项目从磁盘重新加载，这使得外部修改无需关闭/重新打开项目即可生效。waveform_revert_to_saved 自动化了该路径并带有重试机制。

混音平衡参考

mix_apply_reference 读取一张精选表，内容为“底鼓是锚点；贝斯低 5-6 dB；主旋律与贝斯相似；铺底/琶音比主旋律低 6-9 dB；环境音最深” —— 这是从流派教程、母带博客和听觉调优迭代中提炼出来的：

MIX_BALANCE["synthwave"] = {
    "drums": -7, "kick": -6, "snare": -10, "hat": -16,
    "bass": -25, "sub_bass": -28,           # background-level texture
    "lead": -15, "pad": -19, "arp": -8,     # arp-driven mix
    "counter": -14, ...
}

作曲家每条轨道调用一次 tracks.mix_apply_reference({track_id, genre, role})。只需微调一次表格，所有作曲家都会重新平衡。

参考来源：

• Mastering The Mix — 如何平衡底鼓和贝斯

• Mastering The Mix — 如何混音贝斯合成器

• eMastered — 平衡所有元素

已知限制

• 轨道音量 AUTOMATIONCURVE 已禁用。 Waveform 的 volume 插件不支持我们的曲线模式，会导致受影响的轨道静音。MCP 会拒绝该目标并给出明确错误，指向可行的替代方案（片段淡入淡出、带有片段增益的多个片段、静态 mix_set）。

• 插件修改器矩阵处于探索阶段。 plugin_add_modifier 写入通用的 modmatrix 形态；在 LFO 调制能可靠用于 4OSC 等插件之前，需要手动编辑的固定装置来确认每个插件的模式。

• 尚未构建无头渲染。 waveform_render_to_mp3 驱动 Waveform 的 UI 导出 —— 可以工作，但需要 Waveform 保持运行。最终的修复方案是链接 tracktion_engine 的 C++ 辅助程序。

• 缺少 Linux/macOS UI 控制。 内容发现（预设、循环库、VST 列表）是跨平台的；UI 自动化仅限 Windows。

下一步迭代的构建块

• 为 <AUTOMATIONCURVE paramID="volume"> 捕获真实的 Waveform 固定装置，以便重新启用音量自动化

• 基于 tracktion_engine 的 C++ 无头渲染辅助程序

• 鼓采样器 / 微型鼓采样器真实固定装置（目前回退到普通采样器）

• 侧链修改器捕获

• 片段启动器 (v13) 支持

• 一旦 UIA 不再是唯一路径，通过 xdotool/wmctrl 实现 Linux UI 控制

许可证

GPL-3.0-or-later（如果/当 C++ 渲染辅助程序链接到它时，与 tracktion_engine 匹配）。