Skip to main content
Glama

Waveform MCP

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

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


它能为你带来什么

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

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

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

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

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

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

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


Related MCP server: ableton-mind

状态

在 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})。只需微调一次表格,所有作曲家都会重新平衡。

参考来源:


已知限制

  • 轨道音量 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 匹配)。

Available Tools

129 tools
arp_patternB

Generate an arpeggio over a chord. Returns notes for the given length. direction ∈ {up, down, up_down, down_up, random, octave_alternate}. rate ∈ {quarter, eighth, sixteenth, triplet}. octaves controls how many octaves the cycle spans.

Inputs: length_beats (required), chord_pitches (required), rate, octaves, +4 more.

arrangement_planA

Produce a section list for a song. genre selects characteristic form; target_length_seconds + tempo set total bars; energy_curve shapes the intensity pattern. Returns sections with bar counts, roles, and an energy 0..1 the composer can use to gate layers / set velocities.

Inputs: genre (required), tempo (required), target_length_seconds (required), energy_curve, +2 more.

audio_clip_importA

Place an audio file as a clip on a track. warp_mode controls time-stretch behavior. Optional clip-level gain (dB), fade in/out (beats), and offset_in_source (beats — skip the first N beats of the source file, useful for trimming silent intros).

Inputs: track_id (required), file_path (required), start_beats (required), length_beats (required), +6 more.

audio_compareA

Compare two audio files: returns LUFS / peak / DR diffs and a per-band spectrum diff in dB. Positive numbers mean file_a is louder/brighter than file_b in that dimension.

Inputs: file_a (required), file_b (required), bands.

audio_detect_keyA

Detect the musical key of an audio file. Returns root note + mode (major/minor) with confidence 0..1. Uses chromagram + Krumhansl-Schmuckler key profiles. Reliable on tonal pop/jazz; less reliable on percussion-heavy or atonal material.

Inputs: file_path (required).

audio_detect_tempoA

Detect the BPM of an audio file via onset autocorrelation. bpm_range bounds the search (default 60..180). Returns a single BPM with confidence 0..1. Works well on EDM/pop loops with a kick on every beat; less reliable on free-tempo or sparse music.

Inputs: file_path (required), bpm_max, bpm_min.

audio_loudness_lufsA

Measure integrated LUFS, true peak (dBTP), and dynamic range (LRA) for an audio file using ffmpeg's loudnorm filter. Reference targets: Spotify -14 LUFS, Apple -16, broadcast -23. True peak should stay under -1.0 dBTP.

Inputs: file_path (required).

audio_spectrumA

Return RMS energy per frequency band. bands defaults to a 10-band log-spaced layout (sub, low, low-mid, mid, hi-mid, presence, brilliance, air). Useful for 'compared to my reference, this song is 4 dB heavier in the low-mid region.'

Inputs: file_path (required), bands.

automation_addA

Add an automation lane to a track. target ∈ {'volume', 'pan', 'plugin/<plugin_id>/'}. points = [{beat, value, curve?}]. Replaces any existing lane on the same target.

Inputs: points (required), target (required), track_id (required).

automation_clearA

Remove all automation lanes from a track, or just the lane on a given target.

Inputs: track_id (required), target.

automation_envelopeA

Convenience: ramp a target from start_value to end_value between start_beat and end_beat. shape ∈ {'linear', 'exp_in', 'exp_out', 'sine'}. exp_in starts slow then speeds up; exp_out is the inverse; sine is a smooth S-curve. Appends to an existing lane on the same target if one exists, otherwise creates a new lane.

Inputs: target (required), end_beat (required), track_id (required), end_value (required), +4 more.

automation_listA

List automation lanes on a track (or all tracks if track_id omitted).

Inputs: track_id.

aux_return_addA

Add an auxreturn plugin to a track so it receives audio from the given bus number (0..15). Pair with send_add(bus_num=N) on source tracks for parallel routing — e.g. drum tracks all send to bus 0, aux-return track applies a single reverb.

Inputs: track_id (required), bus_num.

bassline_generateB

Generate a bassline under a chord progression. feel ∈ {pump, walking, half_time, sub, octave_jumps, dub}. Each chord lasts chord_duration_beats. Roots are the chord-root MIDI pitches (typically octave 2-3).

Inputs: roots (required), chord_duration_beats (required), feel, start_beats, +1 more.

bus_createC

Create a submix / aux track other tracks can route to. kind ∈ {submix, folder}.

Inputs: name (required), kind.

bus_routeA

Route a track's output to a bus instead of master. Stack drums onto a 'Drum Bus' for one comp/EQ.

Inputs: dest_bus_id (required), src_track_id (required).

clip_duplicateA

Clone a clip onto the same track at start_beats + offset_beats. Returns the new clip_id. Notes are deep-copied for MIDI clips.

Inputs: clip_id (required), offset_beats (required).

clip_listA

List clips on a track (or all tracks). Returns id, kind, name, start, length, plus per-clip gain/fade/offset for audio clips.

Inputs: track_id.

clip_moveA

Shorthand: change a clip's start_beats. Length unchanged.

Inputs: clip_id (required), new_start_beats (required).

clip_removeB

Delete a clip by id.

Inputs: clip_id (required).

clip_resizeA

Change a clip's length. anchor='start' (default) keeps start_beats fixed and moves the right edge. anchor='end' keeps the right edge fixed and moves start_beats so total duration changes from the left.

Inputs: clip_id (required), new_length_beats (required), anchor.

clip_setB

Modify any field on an existing clip. Pass only fields you want changed. For AudioClip: name, start_beats, length_beats, gain_db, fade_in_beats, fade_out_beats, offset_in_source_beats, warp_mode. For MidiClip: name, start_beats, length_beats, gain_db.

Inputs: clip_id (required), name, gain_db, warp_mode, +5 more.

compose_and_reloadB

Dispatch one of jazz/synthwave/lofi generative composers AND revert in Waveform with one call. Avoids the compose-then-manually-revert dance during iteration.

Inputs: composer (required), out_path (required), seed, tempo, +3 more.

compose_djent_realA

Djent track using REAL VST3 instruments + amp/cab simulators (sforzando + Karoryfer Emilyguitar SFZ → The Anvil drive → Mercuriall Metal Area amp → TSC cab) instead of synthetic 4OSC. Returns a manual_step_required note explaining you must load the SFZ in sforzando once after opening the project — sforzando state isn't preserved in our .tracktionedit writer yet.

Inputs: out_path (required), seed, tempo.

compose_djent_trackB

Generate a progressive metal / djent instrumental in B minor. Form: intro → riffA → riffB → breakdown → riffA2 → buildup → solo (8 bars) → riffFinal → outro. Tracks: drums (polyrhythmic 3-3-2 kicks), bass, dual rhythm guitars panned hard L/R for the wall, lead solo over solo section, atmospheric pad. ~140 seconds at 110 BPM.

Inputs: out_path (required), seed, tempo.

compose_from_primitivesB

Build a song bottom-up from composition primitives — the recipe demonstrating arrangement_plan + progression_generate + voice_lead + drum_pattern + bassline_generate + arp_pattern + melody_generate + motif_develop wired together. Genre selects drum patterns, bass feels, and mix-balance reference. energy_curve drives velocity scaling per section.

Inputs: out_path (required), mode, root, seed, +4 more.

compose_jazz_generativeA

Generate a jazz/jaunty track with authentic walking bass (7-pattern Paul Chambers vocabulary), Charleston-rhythm Rhodes comping, and Salamander Grand Piano lead treated like a vocal (call/response motifs, vocal range, dynamic phrasing). Drums comp for the soloist (ghost rim shots on piano off-beats, phrase-end fills, sparse ride on solo phrases). Section-wide ensemble dynamics and per-section bass feels (two-feel for heads, walking for blowing, anticipations into the bridge).

Inputs: no named parameters.

compose_lofi_generativeA

Generate a UNIQUE lofi track on every call. Unlike the old compose_lofi_track which hardcoded everything, this one uses progression_generate, arrangement_plan, drum_pattern, melody_generate, and bassline_generate primitives. Each seed produces a meaningfully different song: different chords, section layout, drum density, melody contour, bass feel, and tempo (within lofi range).

Inputs: no named parameters.

compose_lofi_trackB

Generate a complete lofi track .tracktionedit file: 4 tracks (drums, bass, keys, pad), Fmaj7-Am7-Dm7-Cmaj7 progression, real 808 drum samples, master FX bus. Bass / keys / pad presets are configurable so you can A/B sounds without editing the composer. Saves to the given path.

Inputs: out_path (required), bars, seed, tempo, +4 more.

compose_rainstormA

Generate a rainstorm ambient .tracktionedit: continuous rain bed, tiled wind/breeze layer, occasional distant-muffled thunder rumbles (lowpass + EQ + low gain). 60 BPM (1 beat = 1 second). No music.

Inputs: out_path (required), seed, length_seconds.

compose_synthwave_generativeA

Generate a UNIQUE synthwave track on every call. Drives progression_generate / arrangement_plan / drum_pattern / melody_generate primitives with seed-driven variation across tempo (100-128 BPM), key, form, chord progression, drum density, melody contour, and bass feel. Different seeds = meaningfully different songs.

Inputs: no named parameters.

compose_synthwave_trackC

Generate a 64-bar synthwave instrumental .tracktionedit at 110 BPM in A minor. Properly developed song form: intro → verseA → chorus → verseB (variation) → chorus2 (with counter) → bridge (new chord set + walking bass + descending arp) → chorusFinal (peak) → outro (progressive instrument drop with pad chord ring-out). Per-section chord progressions, bass feels (verse=half-time, chorus=8th pump, bridge=walking), and arp themes (verse / verseB syncopated / chorus pump / bridge descending). Showcases the full MCP toolset.

Inputs: out_path (required), seed, tempo.

compose_variationsA

Run a composer N times with different seeds, saving each output to a numbered file. Returns the list of paths so you can render all and pick the best.

Inputs: count (required), composer_name (required), out_path_prefix (required), extra_args.

compress_glueB

Gentle bus 'glue' compressor. amount 0..1 (0=barely-there, 1=noticeable).

Inputs: track_id (required), amount.

compress_smashC

Aggressive parallel-style compressor for drum-bus / NY-style smash. No params — preset values.

Inputs: track_id (required).

desktop_clickA

Click at screen coordinates. Use desktop_screenshot first to know what's where. button ∈ {left, right, middle}.

Inputs: x (required), y (required), button, clicks.

desktop_keyA

Press a single key or chord. Examples: 'enter', 'esc', 'ctrl+s', 'ctrl+shift+n', 'f5'. Sent to whatever window currently has focus.

Inputs: keys (required), presses, interval.

desktop_moveA

Move the mouse to (x, y) without clicking.

Inputs: x (required), y (required), duration.

desktop_screenshotA

Capture the current screen (or a region) to a PNG file under state/screenshots/. Returns the path. Use this to verify that a UI action had the expected effect before sending the next.

Inputs: name, region.

desktop_screen_sizeA

Return current screen resolution.

Inputs: no named parameters.

desktop_typeC

Type a string of text into the focused window.

Inputs: text (required), interval.

desktop_waitA

Sleep for seconds seconds. Use sparingly; prefer screenshot-then-act.

Inputs: seconds (required).

drum_patternA

Generate drum notes for a section. (genre, role) selects from a library of 50+ named patterns. role ∈ {verse, chorus, fill, intro, breakdown, outro, buildup}. density 0..1 scales note count (0.5 drops half the hats; 1.0 is the full pattern). length_bars tiles the pattern. Returns notes ready to drop on a Sampler track.

Inputs: role (required), genre (required), length_bars (required), seed, +4 more.

drum_pattern_listA

List all available (genre, role) patterns in the library.

Inputs: no named parameters.

edit_createA

Create a new empty Edit (song). Sets tempo, time signature, and key. Replaces the in-memory Edit; does not write to disk until edit_save or flush.

Inputs: name, tempo, key_mode, key_root, +3 more.

edit_export_chord_chartA

Export a chord-chart text file from the markers + tempo of the current Edit. format ∈ {lead_sheet, nashville}. Markers should be named with section labels (e.g. 'verse', 'chorus').

Inputs: out_path (required), format.

edit_export_midiB

Export all MIDI clips in the current Edit to a Standard MIDI File (.mid). One MIDI track per Edit MIDI track. Format-1 SMF with the Edit's tempo + time signature in track 0. Drop into any DAW for editing/printing/learning.

Inputs: out_path (required).

edit_inspectA

Detailed structural dump of the current Edit. Heavier than edit_summary — includes every plugin's params, clip gain/fade/offset, automation lane counts, master chain. Use after edit_open to understand a song before mutating it.

Inputs: no named parameters.

edit_openB

Load an existing .tracktionedit file from disk into the model.

Inputs: path (required).

edit_saveA

Serialize the current Edit to a .tracktionedit file. Sets the flush target.

Inputs: path (required).

edit_save_stemA

Save a stem-mix copy of the current Edit: only named tracks audible, all others muted. Pass track_ids or track_names (list). Use in a loop to produce per-track stems for rendering.

Inputs: out_path (required), track_ids, track_names.

edit_set_tempoB

Change the project tempo. preserve_pitch is informational (audio clips don't get pitch-shifted by this tool).

Inputs: bpm (required), preserve_pitch.

edit_summaryA

Return a JSON summary of the current Edit (tracks, clips, markers, tempo).

Inputs: no named parameters.

edit_transposeA

Transpose every MIDI note in the Edit by semitones. Audio clips are NOT pitch-shifted.

Inputs: semitones (required).

ensemble_dynamicsA

Return per-section velocity multipliers for a sections_plan. Apply uniformly to drums, bass, keys, lead notes so the whole ensemble breathes together (quiet intro, building verses, peak chorus/bridge, soft outro).

Inputs: no named parameters.

eq_high_passA

Add a high-pass filter at freq Hz to a track. slope is dB/oct (12, 18, 24).

Inputs: track_id (required), freq, slope.

eq_low_passA

Add a lowpass filter at freq Hz to a track for darkening/muffling.

Inputs: track_id (required), q, freq.

eq_tiltB

Single-knob bright/dark EQ. brightness -1=dark, 0=neutral, +1=bright.

Inputs: track_id (required), brightness.

flushA

Write the current Edit to the previously-opened/saved .tracktionedit path. Use this between batches of mutations so Waveform (when open) sees a single, coherent update instead of mid-edit flicker.

Inputs: no named parameters.

key_setD

Set the project key.

Inputs: mode (required), root (required).

loop_dropA

Drop a loop onto a track. mode='fit' time-stretches to song tempo, 'original' uses natural tempo. start_beats defaults to end of existing clips on that track. Auto-detects file duration.

Inputs: track_id (required), loop_path (required), mode, start_beats.

marker_addB

Drop a marker (verse, chorus, drop, etc.) at a beat position.

Inputs: name (required), start_beats (required), length_beats.

master_chain_applyA

Replace the master chain with a named template. template ∈ {clean_pop, loud_edm, lofi_warm, cinematic_dynamic, podcast_voice, no_processing}. Each is an EQ + Comp + Limiter chain tuned for its target use case.

Inputs: template (required).

melody_generateB

Generate a melody from a scale and contour. Returns notes (pitch/start_beats/length_beats/velocity) ready to drop into a MIDI clip. contour ∈ {arch, descending, ascending, wave, question_answer, static}. density ∈ {sparse, medium, busy}. Notes are rhythmically diverse — quarter, eighth, dotted, with rests — humanized for natural feel.

Inputs: mode (required), root (required), length_beats (required), seed, +3 more.

midi_clip_addC

Create an empty MIDI clip on a track.

Inputs: track_id (required), start_beats (required), length_beats (required), name.

midi_clip_quantizeA

Snap note start times in a clip to the nearest grid division. Grid is in beats: 0.25 = 16th notes, 0.5 = 8ths, etc. Strength 0..1.

Inputs: clip_id (required), grid_beats (required), strength.

midi_notes_addB

Add notes to an existing MIDI clip. Pass an array of {pitch, start_beats, length_beats, velocity?, colour?}. Pitch is MIDI 0-127. Channel is per-clip, set when the clip is created (not per-note).

Inputs: notes (required), clip_id (required).

midi_notes_clearB

Remove all notes from a MIDI clip.

Inputs: clip_id (required).

mix_apply_referenceB

Set a track's volume_db (and optional pan) to the genre+role reference from the MIX_BALANCE table. Use this once per track after creating it instead of hand-tuning levels. Genres: synthwave, lofi, edm, pop, hip_hop, cinematic, ambient. Roles: drums, kick, snare, hat, bass, sub_bass, lead, pad, keys, arp, counter, melody, ambience, fx. Returns the dB value applied.

Inputs: role (required), genre (required), track_id (required), pan, +1 more.

mix_match_referenceA

Compare a rendered file against a genre's reference spectrum and return a per-band diff in dB plus a plain-English diagnosis ('low end is +4 dB hot vs synthwave reference; consider HP filter on bass'). Use after render to inform mix adjustments.

Inputs: genre (required), file_path (required).

mix_setA

Set track volume (dB), pan (-1..1), mute, solo. Pass only the fields to change.

Inputs: track_id (required), pan, mute, solo, +1 more.

motif_developB

Transform a motif (set of notes) into a variation. transformation ∈ {transpose, invert, retrograde, augment, diminish, sequence_up, sequence_down}. transpose: shift by semitones. invert: mirror around axis_pitch. retrograde: reverse note order. augment: stretch durations by factor. sequence_up/down: transpose by semitones AND repeat.

Inputs: notes (required), transformation (required), factor, semitones, +2 more.

narrateA

Tell the user (via the event stream / preview UI) what the agent is about to do, in plain English. Call this before a batch of mutations so the user can follow along.

Inputs: text (required).

plugin_addA

Add a plugin to a track's chain. For built-ins, pass the type name (e.g. '4OSC', 'Wavetable'). For external VSTs, also pass preset_path.

Inputs: type (required), track_id (required), name, preset_path.

plugin_add_drum_kitA

Add a Sampler-backed drum kit to a track. pads is a list of {midi_note, sample_path, name?, gain_db?, pan?, decay?}. Each pad becomes one SOUND mapped to a single MIDI note. Replaces the manual Sampler+sounds boilerplate in compose_lofi_track.

Inputs: pads (required), track_id (required), name.

plugin_add_macroA

Add a MacroParameter (single 0..1 knob) to a plugin. Macros are the canonical Tracktion way to expose a single control that drives multiple underlying params via assignments.

Inputs: name (required), track_id (required), plugin_id (required), value, +1 more.

plugin_add_modifierA

Add a TRACK-LEVEL modifier (LFO/envelope/random/step_lfo) and assign it to a plugin parameter. Real Tracktion schema — wires both on the track AND on the plugin. depth: 0..1 (modulation amount). rate: Hz when rate_type=0, beat multiplier when rate_type=1 (default = beat-synced). shape ∈ {sine, triangle, square, saw}.

Inputs: track_id (required), target_param (required), target_plugin_id (required), rate, +5 more.

plugin_add_reverbA

Add a built-in reverb to a track. type ∈ {plate, natural, non_linear}. All other params are normalized 0..1: size, decay, mix (wet amount), pre_delay, diffusion, definition, high_damp, low_damp, high_cut. Defaults to a tasteful 25% wet plate.

Inputs: track_id (required), mix, name, size, +8 more.

plugin_discoverA

List third-party VST/AU plugins Waveform has scanned. Optional filters: kind ('instrument'|'effect'), format ('VST3'|'VST'|'AU'), manufacturer (substring), name (substring). Use the returned uniqueId as the type arg to plugin_add for VST3 instantiation.

Inputs: kind, name, format, manufacturer.

plugin_listA

Return the curated list of built-in instruments and effects available by name.

Inputs: no named parameters.

plugin_removeB

Remove a plugin from a track's chain by id.

Inputs: track_id (required), plugin_id (required).

plugin_set_paramC

Set a named parameter on a plugin in a track's chain.

Inputs: param (required), value (required), track_id (required), plugin_id (required).

plugin_set_vst_stateA

Apply a base64 VST state blob (from plugin_state_capture) to an existing plugin in the in-memory Edit. Lets you copy one configured VST onto every other instance.

Inputs: state (required), track_id (required), plugin_id (required).

plugin_state_captureA

Read a saved .tracktionedit file and extract a VST plugin's base64 state blob by plugin_name (substring match) or unique_id. Used to copy a manually-loaded plugin's configuration (e.g. an SFZ loaded into sforzando) for re-use programmatically.

Inputs: unique_id, plugin_name, edit_file_path.

progression_generateA

Invent a chord progression in a key and mode. Returns a list of chord dicts ({roman, root_note, root_midi, chord_pitches, quality}). Constraints: end_cadence ∈ {authentic, plagal, deceptive, half}; allow_borrowed enables modal interchange (bIII/bVI/bVII in major, V/VII for minor); style ∈ {pop, jazz, modal, synthwave, sad, uplifting} biases the chord palette.

Inputs: mode (required), root (required), length_chords (required), seed, +4 more.

reference_song_listA

List all known reference songs in the curated database.

Inputs: no named parameters.

reference_song_lookupA

Look up musical hints for a song. Pass name (one of the keys in REFERENCE_SONGS) OR genre to list all references in that genre. Returns BPM, key, form, energy curve, signatures the composer can use as inputs.

Inputs: name, genre.

reference_spectrum_lookupA

Get the target spectral profile (RMS dB per log-spaced band) for a genre — a mastering-engineer-cheat-sheet target for what a well-mixed track in this genre should look like spectrally. Bands: 60 / 133 / 296 / 657 / 1460 / 3243 / 7204 / 16000 Hz.

Inputs: genre (required).

renderA

Render the current Edit to a WAV file. NOT YET IMPLEMENTED — requires the wf-engine-helper binary which is not built. Use this tool to check status; it will return ok=False with a clear message so the agent can fall back to telling the user to render from inside Waveform.

Inputs: out_path (required), bit_depth, sample_rate.

render_and_auditC

Render the active edit to MP3, run the analyzer, and return both paths plus a balance/rhythm summary in one call. Replaces the manual revert→render→analyze chain.

Inputs: bitrate, mp3_path, revert_first, trim_trailing_silence.

render_stemsB

Render per-track stems. NOT YET IMPLEMENTED.

Inputs: out_dir (required).

send_addA

Add an aux send (parallel routing) on a track. Tracktion routes via numbered buses 0..15 — pass bus_num explicitly, or pass dest_track_id to auto-pick a bus. Pair with aux_return_add on the receiving track. Emits a real element with proper slider position from amount_db.

Inputs: src_track_id (required), bus_num, pre_post, amount_db, +1 more.

snapshot_listA

List all saved snapshots in this session.

Inputs: no named parameters.

snapshot_recallC

Restore a previously-saved snapshot as the active Edit.

Inputs: name (required).

snapshot_saveA

Save the current Edit as a named snapshot for later A/B compare or recall.

Inputs: name (required).

step_clip_addB

Add a step clip (drum-machine grid) to a track. channels is a list of {midi_note, name?, velocity?} dicts — one per drum row. patterns is a list of pattern dicts: each pattern has rows parallel to channels, where each row has a pattern string of '0'/'1' steps and optional velocities list. step_length is duration of each step in beats (0.25 = 16th notes). Way cleaner than 80 individual MidiClip notes.

Inputs: channels (required), patterns (required), track_id (required), start_beats (required), +4 more.

tempo_setA

Set the project tempo in BPM (currently single global tempo; per-bar curves later).

Inputs: bpm (required).

theory_arrangement_layersA

Return arrangement layers: foundation, harmonic_glue, lead, counter_melody, atmosphere, ear_candy. Optional section returns per-section presence values for each layer (0..1) from LAYER_PRESENCE_BY_SECTION — drives the 'which layers should be active' decision.

Inputs: section.

theory_borrowed_chordsA

Return the borrowed-chord (modal interchange) palette for major keys with usage notes.

Inputs: no named parameters.

theory_cadencesB

Return cadence types — pattern, feel, and use. Optional name for one specific cadence.

Inputs: name.

theory_chord_progressionA

Look up a named chord progression. Returns the Roman-numeral sequence + tags + examples. Without args, lists all 24 named progressions.

Inputs: tag, name.

theory_diatonic_chordsB

Return the 7 diatonic chords for a key/mode. Set sevenths=true for 7th-chord qualities (Imaj7, ii7, etc.) instead of triads (I, ii, etc.). Returns Roman numerals + the actual chord pitches (MIDI) for each.

Inputs: mode (required), root (required), octave, sevenths.

theory_genreA

Return genre conventions: BPM range, time signature, key tendency, instruments, form, hallmark progressions. Without args, lists all 22 genres.

Inputs: name.

theory_heuristicsA

Return the 13 songwriting heuristics (rule_of_3, contrast_required, etc.).

Inputs: no named parameters.

theory_mix_balanceA

Return reference track-volume dB targets for a genre. Without args, returns the full table of (genre, role) → dB. With genre, returns the role→dB map for that genre. With genre AND role, returns the single dB value with a brief rationale. Roles: drums, kick, snare, hat, bass, sub_bass, lead, pad, keys, arp, counter, melody, ambience, fx. Genres: synthwave, lofi, edm, pop, hip_hop, cinematic, ambient.

Inputs: role, genre.

theory_modesB

List the 7 church modes with their characteristic degree, vibe, and typical use.

Inputs: mode.

theory_rhythmA

Return rhythm/meter info: time signatures, syncopation patterns, swing ratios. Pass time_sig for one specific time signature, syncopation for one pattern, or neither for the full reference.

Inputs: time_sig, syncopation.

theory_scaleA

Return the notes of a scale starting at a root. Returns MIDI numbers, note names, and interval pattern. mode is one of: major, natural_minor, harmonic_minor, melodic_minor_asc, ionian, dorian, phrygian, lydian, mixolydian, aeolian, locrian, major_pentatonic, minor_pentatonic, blues, whole_tone, half_whole_dim, whole_half_dim, chromatic, hungarian_minor, phrygian_dominant.

Inputs: mode (required), root (required), octave.

theory_sectionA

Return song section info: typical bar counts, role, dynamic level, valid next sections. Without args, lists all 15 section types (intro, verse, chorus, bridge, drop, etc.).

Inputs: name.

theory_song_formA

Return a macro song form layout. Without args, lists all 14 forms. With name, returns the section sequence, applicable genres, and total bar range.

Inputs: name.

theory_surprise_devicesC

Return the 7 surprise devices (truck_driver_modulation, deceptive_cadence, etc.).

Inputs: no named parameters.

theory_velocityA

Convert dynamic markings (ppp/pp/p/mp/mf/f/ff/fff) to MIDI velocity values, or look up all of them. Includes ACCENT_BUMP and GHOST_NOTE_MAX_VEL constants.

Inputs: dynamic.

theory_voice_leading_rulesA

Return the 10 codified voice-leading rules + scoring guidance.

Inputs: no named parameters.

tool_historyA

Return the last N tool calls made in this session for self-audit.

Inputs: last_n.

track_addB

Add a new track. kind ∈ {audio, midi, folder, submix, automation}.

Inputs: name (required), pan, kind, volume_db.

track_removeB

Delete a track by id.

Inputs: track_id (required).

undoB

Roll back the most recent mutation.

Inputs: no named parameters.

voice_leadA

Voice the next chord with minimal voice motion from the previous voicing. Standard SATB-style voice leading: each voice moves the smallest interval to a target chord tone. Returns the new voicing as a list of MIDI pitches (same length as prev_voicing).

Inputs: next_chord (required), prev_voicing (required).

waveform_focusA

Bring Waveform's main window to the foreground. Required before desktop_key / desktop_type send keystrokes to the app.

Inputs: no named parameters.

waveform_launchA

Launch Waveform, optionally opening a .tracktionedit file. If Waveform is already running and a file path is provided, opens the file in the existing instance via OS file association (Waveform registers itself as the handler for .tracktionedit on install).

Inputs: exe_path, file_path.

waveform_locateA

Find the installed Waveform binary on disk. Returns the path. Searches running processes first, then well-known install locations. Run this before launch/focus tools so the rest of the chain has a path to use.

Inputs: no named parameters.

waveform_plugin_typesA

Return the friendly-name → Tracktion-type-code map for built-in plugins. These codes are what the .tracktionedit XML expects in .

Inputs: no named parameters.

waveform_preset_listA

List available factory presets. Without args, returns the plugin category folders (4OSC, Compressor, etc.). With category, lists individual .trkpreset files in that category.

Inputs: category.

waveform_preset_readA

Read a .trkpreset XML and return its element contents — the type, parameters, and any nested elements. Use this to grab a known-good instrument or effect configuration to drop into a generated edit.

Inputs: path (required).

waveform_quitA

Politely close Waveform (sends WM_CLOSE to the main window).

Inputs: no named parameters.

waveform_settings_dirA

Return the path to Waveform's settings directory (where Waveform.settings, knownPluginList64.settings, Templates/, etc. live). Useful for the planned settings-file editor surface.

Inputs: no named parameters.

waveform_statusA

Is Waveform currently running? Returns pid + exe path if so.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 129 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but several near-duplicates exist (tempo_set vs edit_set_tempo, compose_lofi_track vs compose_lofi_generative, audio_clip_import vs loop_drop). Some descriptions reference flows (e.g. 'revert→render→analyze' in render_and_audit) that don't map to explicit tools, which could confuse an agent.

    Naming Consistency4/5

    The dominant snake_case verb_noun / domain_action pattern is consistent (midi_clip_add, automation_clear, waveform_launch, theory_scale). However, a few outliers break the pattern: tempo_set and key_set lack the domain prefix that edit_set_tempo has for the same concept, and verbs are mixed (list/lookup/get/add/create) without a strict rule.

    Tool Count1/5

    With 129 tools, this is far beyond the 3-15 well-scoped range and even beyond the 50+ 'extreme' threshold. The breadth spans DAW control, music theory, generation, audio analysis, and desktop automation, but the sheer count makes it unwieldy for an agent to navigate; many tools (e.g. the numerous compose_*_track variants, granular desktop_* actions) could be consolidated behind parameters.

    Completeness3/5

    Coverage is broad across edit, clip, MIDI, audio, plugin, automation, rendering, theory, generation, and analysis domains. However, notable gaps exist: there is no way to list tracks (only track_add/remove), no bus listing, no marker add/list management, no plugin chain reorder/bypass, and no way to change time signature after edit creation.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers