cakewalkmcp
Summary: An MCP server that drives a running Cakewalk SONAR from an AI agent — menu commands, MIDI file/live-MIDI writes, CAL macros, UIA clicks on track strips, note-edit dialog plans, and a heavy "what actually works" honesty layer (CakeScript/T1 tools are present but non-functional on current builds).
Diagnose the host first —
cw_doctor,cw_status,cw_document_state,cw_save_state,cw_list_overlays/cw_close_overlays,cw_benchmark,cw_latency.Run SONAR menu commands by id —
cw_list_commands(live vs index),cw_run_command,cw_run_command_classified,cw_command_support,cw_command_evidence,cw_verify_commands,cw_view_commands,cw_insert_commands.Document lifecycle —
cw_project(new/open/save/saveAs/close/exportAudio/importMidi/revert, destructive ones needconfirm), pluscw_file_dialogfor driving the MFC file dialog.Transport & timing —
cw_transport_command(play/stop/record/loop/metronome/tempo & meter views),cw_transport,cw_timing(posture only; state changes aren't confirmable).Navigation & markers —
cw_navigate(selection, now-time, marker insert/remove),cw_markers(writable MFC dialog + table readback).Note/audio editing —
cw_edit(quantize, transpose, split, merge, gain, normalize, reverse, fade...), with plans/proofs:cw_quantize_plan,cw_transpose_plan,cw_check_quantize,cw_quantize_dialog,cw_note_edit_help.CAL macros (free licence) to create/delete/read notes and set track name, mute, routing —
cw_cal_plan,cw_cal_run,cw_cal_help,cw_cal_cleanup.Standard MIDI files as the data layer —
cw_write_midi_file(notes, programs, CC7/CC10 baked in),cw_read_midi_file(names, channels, notes, pan/volume).Live MIDI over a virtual cable —
cw_midi_note/chord/cc/send/panic,cw_set_pan/cw_set_volume/cw_apply_mix, plus port setup:cw_midi_status,cw_midi_devices,cw_midi_config,cw_enable_midi_port,cw_mixer_targets/cw_mixer_support.Track strip read/write via real UI clicks —
cw_get_track_control,cw_set_track_mute/solo/arm,cw_set_track_name,cw_list_track_templates+cw_insert_track_template(only practical route to a plug-in chain).Tracks & inserts —
cw_add_track,cw_add_song_tracks(slow, ~19s/insert),cw_track_controls(accessibility contract for computer-use agents).Plugins —
cw_plugins,cw_find_plugin,cw_song_instruments,cw_plugin_insert_recipe(discovery works; insertion into a track does not).Undo/redo —
cw_undo,cw_redo,cw_history,cw_history_help.Project-state observation cache for computer-use agents —
cw_probe_state,cw_report_state,cw_get_state,cw_list_state,cw_surfaces,cw_ui_recipe.Pure arithmetic & job control —
cw_convert/cw_convert_help(ticks ↔ bar:beat:tick ↔ seconds),cw_job,cw_jobs,cw_job_abandon,cw_job_clear,cw_job_help.Not usable on current builds:
cw_list_tracks,cw_get_track,cw_get_clips,cw_get_notes,cw_set_track_volume/cw_set_track_pan,cw_locate(all require CakeScript/T1, which is undispatchable); plug-in insertion and automation envelopes also have no scripting route.
Provides tools for controlling a running Cakewalk SONAR DAW via MCP, including transport, views, dialogs, CAL, MIDI files, real-time MIDI, track/mixer operations, and native menu commands.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cakewalkmcp start playback in Cakewalk SONAR"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cakewalkmcp
从介绍视频过来的朋友: 下载 0.2.1 便携包,
解压并运行 双击部署.cmd,然后打开 连接提示词,
只填安装路径,复制给支持本地 MCP 的 Agent。里面也有「四小节轻快旋律+和弦+低音」、
转调、力度/时值调整与轨道整理的可复制示例。
0.2.1 prerelease: start with QUICKSTART.md and the current release notes. The detailed measurements below include historical experiments; the release notes take precedence for current limits.
The 2026-10-23 acceptance report records actual SONAR MIDI import/export, CAL editing, real-time MIDI recording, track writes and WAV rendering. A Free License session exposed working track controls after loading a CWP, so earlier paid-only explanations below are historical observations, not a reliable availability rule. Inspect the current control tree.
For Chinese CP936 SONAR, choose textEncoding:"gbk" explicitly when writing or
reading track names; UTF-8 remains the default. Import a new arrangement into
an empty CWP or open its MIDI file directly. Import into an existing selected
track can merge content and override routing/mix. Select all before a whole
MIDI export. A synth template's created track name may differ from its filename;
inspect an unverified insert before retrying it.
Upgrade from 0.2.0: its cw_save_state can incorrectly call an imported MIDI
document safe to close. 0.2.1 reads the document tab, keeps positive dirty
evidence, and refuses close-safety when the state is unknown. This observation
does not authorize discarding work. Overlay results also distinguish attempted
closes from panels observed gone; track readiness reflects exposed controls.
Tests are offline by default: npm test or npm run test:full substitutes the
DAW/MIDI process boundary with a no-host fixture, while installer fixtures still
run in real PowerShell. Only node run-tests.mjs --full --live-host may send
commands to SONAR; use a disposable project. An offline pass is not a live-host
or audible-output certification.
The optional surface listener now requires the same 64-hex CW_SURFACE_TOKEN
in the SONAR and MCP process environments. With no valid token it does not
listen. Raw memory reads and vtable calls are permanently disabled, including
when authenticated. See release notes before enabling it.
MCP server that gives an AI agent control over a running Cakewalk SONAR — transport, views, dialogs, CAL, MIDI files and real-time MIDI. This adapter detects CakeScript (T1) but does not implement its IPC dispatch; T1-only tools return an explicit error and explain available alternatives.
SONAR's automation surface has changed between builds, so this server does not assume one mechanism. It probes the running build and uses the best transport that actually works, and when a tool cannot run it says why and what to use instead, rather than timing out.
阅读指南:想安装使用 → QUICKSTART.md(中文,3 分钟);是 AI agent → AGENTS.md(工具选择与恢复手册);要部署给别人 → deploy/README.md。本文件是完整技术参考。
Architecture
ZCode / Claude / etc. MCP (stdio, JSON-RPC)
│
▼
cakewalk-mcp.js ──┬── powershell bridge (user32) ──┬── Sonar.exe
│ │
│ ┌────────────┴────────────┐
│ │ │
│ T1 window-message T2 wm-command
│ XCDLLMSERVER + WM_COPYDATA GetMenuItemID + WM_COMMAND
│ │ │
│ ▼ ▼
│ CakeScript (Lua 5.4) native menu handlers
│
└── powershell shim (winmm) ──► loopMIDI cable ──► SONAR MIDI in
T4 realtime-midiTwo PowerShell shims run side by side, both long-lived so per-call cost is one JSON round trip rather than a process start: a user32 bridge for windows and menus, and a winmm shim that holds the MIDI port handle open so sends stay flat. The Node side never touches Win32 directly. Two details make this work on Windows where the obvious approaches fail:
Every
DllImportthat takes a string is declaredCharSet.Unicode. PowerShell 5.1'sAdd-Typedefaults to ANSI, and without the attributeFindWindowW("Sonar", "Cakewalk Sonar")silently returns 0.GetMenuTreereads ids from the live process. Hardcoding them would break on the next build; the ids differ between 32.08 and 32.10.
Related MCP server: Logic Pro MCP
Transports
The server probes these in order and reports the result in cw_status.
T1 — window-message (fastest, richest)
SONAR's own embedded LLM agent talks to the app over IPC: a XCDLLMSERVER
window plus the registered messages --*LLM_INIT*-- and --*LLM_TOOL_CALL*--.
Commands arrive as write_cakescript / run_cakescript tool calls into the
embedded CakeScript (Lua 5.4) engine, and print() output comes back.
This is the only transport that returns structured results, so every track/note/mixer tool was designed around it.
This build detects T1 but does not dispatch it. The bridge implements
status,menu,runmenu,overlays,probeandmsgids— there is noinit/toolcalloperation, so thewrite_cakescript/run_cakescriptIPC is not wired. On a host that exposes the Assistant,runTemplatefails withT1_CHAIN_UNIMPLEMENTEDrather than pretending. Everything that works here works through T2 (menu commands), T4 (MIDI) and the editing dialogs.
It only exists when the build ships the Assistant panel. SONAR creates the window lazily when the panel is first opened. Present in 2026.08 (32.08.0.040). Removed in 2026.10 (32.10.0.021) — see below.
T2 — wm-command (version-independent, fire-and-forget)
SONAR's client area is JUCE/Direct2D drawing, but the menu bar is a real Win32
menu. GetMenuItemID reads the live ids and
PostMessage(hwnd, WM_COMMAND, id, 0) executes them. Because the ids come from
the running process rather than a hardcoded table, this works across versions.
Verified working on 32.10.0.021: 0x882D Preferences, 0xE140 About,
0xA798 Video Engine Settings, 0xA783 Assistant panel toggle.
cw_list_commands and cw_run_command use this. Two caveats, both learned
from testing:
Modal panels swallow menu commands. While the Assistant / command-palette panel is open,
WM_COMMANDposts are dropped. The bridge closes those panels first (cw_close_overlays, or automatically insidecw_run_command).Registering a command is not the same as handling it. A build can list a command in its menu and its command index while shipping no handler. Posting such an id succeeds and does nothing.
cw_run_commandtherefore diffs the window list before and after and reportsnone-observedwhen nothing opened, which is how you tell the two cases apart.
T3 — computer-use (not driven by this server)
An agent with a computer-use runtime can drive the GUI directly. This process cannot, so it only reports that the option exists.
T5 — uia-click (reads and writes the track strips)
This one is new, and it is what made three long-dead tools work.
SONAR's track strips expose every control to accessibility — with a project open,
a plain UIA client sees 139 elements, 82 of them track controls, each named
<label> on Track <N> and carrying a live value. Reading that way has always
worked. Writing did not:
controls advertise AXSetValue / AXToggle / AXPress
the runtime accepts the call ......... success
the value afterwards ................. unchangedThat is true, and it is only half the picture. A real mouse event at the control's own centre does change it, and the value then reads back changed. So T5 is three things together, and all three are needed:
Locate by name through accessibility —
手动静音 on Track 3.Act with a genuine click at the element's
BoundingRectanglecentre.Verify by re-reading the value from a freshly resolved element.
native/uia/cw_uia.ps1 does all three; lib/track-ui.js drives it. Proven on
mute, solo and arm, each toggled both ways and read back changed:
{ "control": "mute", "track": 2, "requested": "打开",
"before": "关闭", "after": "打开", "clicked": "922,642",
"changed": true, "alreadyThere": false, "verified": true }verified is the field to trust: it is true only when the value read back equals
the one requested. An idempotent write reports alreadyThere: true and
verified: true without clicking — changed: false there means "already right",
not "failed", and a caller that conflated the two would retry forever.
Two things it cannot do. A track scrolled out of the Track view is refused
rather than clicked, and the refusal explains why: SONAR still reports a
BoundingRectangle for a strip outside the view's clip region, and still reports
IsOffscreen = false for it, so a click at its centre lands on whatever the window
shows there. Measured on track 58 of a 71-track project — the button reported
[905,378,33,33] while the Track view's client area began at y=474. The guard
is therefore geometric, against the CTRACKVIEW container's own rectangle; an
IsOffscreen check alone is not enough and was tried first. And sliders
(音量 / 声像 / 增益) plus the routing buttons (输入 / 输出) are not driven here —
the sliders take a value through a pattern SONAR ignores, and the routing buttons
open a picker. Use cw_midi_* for volume and pan.
A coordinate trap worth naming, because it silently breaks every click: UIA
bounds and SetCursorPos are both physical screen pixels and agree as-is, but
only from a DPI-aware process. An unaware process gets virtualised coordinates
and every click lands 1.5x off on a 150% display — which is indistinguishable
from a control that ignores clicks. native/uia/Mouse.cs calls
SetProcessDPIAware, and boundsToClick returns the centre unchanged while
boundsToRaster is the one that divides.
The PowerShell file must keep its UTF-8 BOM. Strip it and PowerShell 5.1
reads the script as the ANSI codepage; the Chinese labels are then mis-decoded,
the clicks still work, and only the comparison against the requested state fails
— so verified comes back false on a write that actually succeeded.
Two more hardening rules found the hard way. First, a synthesised click has
no owner — it goes to whatever window sits at that screen point, and every early
success happened only because SONAR was in front. Mouse.cs now checks which
process owns the point, raises SONAR once if something else is on top, and
refuses rather than clicking into the wrong application (a misdirected click is
a wrong action elsewhere, worse than a failed one). Second, the first click of a
run can be consumed activating the window; the set verb retries once and
reports attempts, and its success test is the read-back, so a click that
already worked is never repeated.
Renaming (cw_set_track_name) rides the same mechanism but is not a single
click: double-click opens the strip's name editor, the text goes in through the
clipboard (SendKeys cannot type Chinese, and track names here usually are),
then Enter. Verified by reading the strip's name back — ASCII, Chinese, and
idempotent (a name already correct is reported alreadyThere: true without
touching anything).
Plug-in chains arrive via track templates. The Plug-ins pane shows all 275
plug-ins but is drawn, not exposed — with the browser open it contains no
accessibility elements at all, so clicking into it cannot confirm which plug-in
landed. A .cwx track template avoids that entirely: it carries a whole
pre-built strip (instrument, FX chain, sends, routing), SONAR names the new strip
after the template, and cw_insert_track_template finds that name in the strip
tree as its confirmation. 184 templates ship with the content installed —
instrument chains for Bass/Drums/Guitar/Vocals, multiband chains, Session
Drummer multi-outs. One limit, stated where the tool throws it: opening the
导入音轨模板 dialog is not scriptable (0x8536 dispatches unreliably and the
menu-bar element names do not match what is drawn), so the dialog is opened by
hand first and the tool drives everything after that point.
Hardening for SONAR updates, which is the difference between a demo and a tool you can keep:
cw_doctor— one command, five transport probes, a verdict and a remedy per channel. Run it FIRST after any SONAR upgrade: it names what degraded (label text changed? surface not re-added? modal dialog holding the menu?) and what to update. Its probes carry hard deadlines, so a hung path degrades tounavailableafter 20s instead of hanging the diagnosis.Label and state words are config, not code. The strip labels (手动静音 / 独奏 / 录制), the toggle words (打开 / 关闭) and the dialog confirm word live in one word-list block in
native/uia/cw_uia.ps1, with English fallbacks (Mute/Solo/Record, On/Off, Open) tried in order, each overridable throughCW_UI_*environment variables. A UI-text change across a SONAR version is a config override, not a code edit.The minimized-window trap is detected. A minimized SONAR reports element coordinates around −21000 (measured: strip at −21132 while the window rect was at −21333). Reads still work there; no click can land.
cw_doctorreportssonarMinimized: trueand says to restore the window, instead of leaving every write mysteriouslyverified: false.The "ghost frame" state is named. On 2026.10, after external foreground operations, the Sonar.exe process can stay alive while its main frame window is destroyed — audio and MIDI keep working, every UI path is dead, and the title probe used to read the HUD's caption.
Find-SonarMainnow refuses to fall back to HUD windows, andcw_doctorreportsframeGhost: truewith the one-sentence remedy: restart SONAR.
Deploying this for someone else is deploy/: install.ps1 (prerequisites,
npm, then cw_doctor so installed means verified) and uninstall.ps1 (removes
any registration, verifies the registry is clean). There is no per-session
manual step. See deploy/README.md for the ship list and for why the
control-surface DLL — formerly a required install step with a manual re-add
after every SONAR launch — is now opt-in and unused.
T4 — realtime-midi (works on every build)
A loopMIDI virtual cable is a real Windows MIDI device, so it does not depend on
SONAR's scripting engine or on any menu command being handled. The server opens
the cable's OUT port through winmm and SONAR reads its IN port. This is the
transport that still changes a project on builds where CakeScript is gone, and
its latency is the MIDI driver's — milliseconds, independent of PowerShell.
On this machine the cable is Studio One AI Notes (MIDI out index 4, MIDI in
index 3). cw_status selects it automatically; the server also looks for any
port named loopMIDI or Cakewalk before falling back.
The receive side is scriptable — no UI needed. SONAR keeps which ports are
enabled in %APPDATA%\Cakewalk\Sonar\TTSSEQ.INI, not in the registry and not in
the project file:
[MIDI Input Devices]
0=Steinberg UR22C-1
1=Studio One AI Notes
MaxInPort=1
[MIDI Output Devices]
0=Steinberg UR22C-1
1=Studio One AI Notes
MaxOutPort=1So cw_enable_midi_port writes that file (idempotent, keeps a .bak), and
cw_midi_config reads it back. This matters more than convenience: it is the
only way to verify the receive side. A send always returns rc=0 whether or
not anything is listening, so without reading this file cw_midi_status could
only report that a port is open, never that SONAR is tuned to it.
cw_midi_status now reports sonarReceives, derived from this file.
SONAR reads the file at startup and when its MIDI Devices dialog is applied, so a change here is not live in a running session until one of those happens.
Two limits to be honest about. MIDI cannot read project state, so there is no MIDI
equivalent of cw_get_track / cw_get_notes — see the next section for how that
gap is handled. And what a message does depends on the track or control that
receives it: a CC 7 moves a fader only where something is listening for it, which
means an armed track or an ACT assignment. Nothing in the message says which.
A note on testing this: loopMIDI does not loop a cable back to the same
process. Writing to Studio One AI Notes OUT delivers to other applications'
IN — and while SONAR is running it owns that IN, so a capture opened from here
gets nothing. bridge/loopback.js can capture a cable, but only one nothing else
holds. Do not read "0 messages captured" as a broken transport; check
sonarReceives instead.
The one condition that decides everything: is a project open?
This is the single most important finding in this project, and an earlier round of this work got it wrong. SONAR builds its menu bar and its track strips from the open document:
no project open | project open | |
Window title |
|
|
Menu entries | 43 | 270 |
Menus present | 文件 编辑 工具 帮助 | + 视图 插入 处理 工程 窗口 |
Accessibility elements | 33–37 | 173 |
Track controls | none | every strip, readable |
Commands that respond | app-level only | + view, document, transport, per-track |
An earlier measurement was taken with no document open. It saw 43 menu
entries, concluded the 视图 menu and the CakeScript group were "registered
without handlers", and wrote that CakeScript had been removed from the build.
All of that was an artifact of the empty state. With a 16-track project open,
视图 > CakeScript View, 处理 > 运行 CakeScript 程序 and 视图 > AI Assist all
respond — they open the membership panel on a free licence, which is a different
finding from "nothing happens".
cw_document_state reports which case you are in, read from the caption. It is
the first thing to check when a command appears to do nothing.
Reading tracks works; writing needs a different transport
With a project open, the accessibility tree exposes every track control under
the name "<label> on Track <N>":
slider "音量 on Track 1" = "101" actions=[AXSetValue]
slider "声像 on Track 1" = "0% 中" actions=[AXSetValue]
button "录制 on Track 1" = "关闭" actions=[AXToggle,AXPress]
button "输出 on Track 1" = "1-Steinberg UR22C-1"
button "输入 on Track 1" = "全通道"
button "手动静音 on Track 1" = "关闭"Reading is accurate. Writing through accessibility does nothing. A survey across 3 tracks and 15 controls (声像 / 音量 / 力度+ / 手动静音 / 独奏) attempted a write on each: every call was accepted, none changed the value, and a screenshot confirmed the button state was genuinely unchanged rather than a stale read. SONAR's accessibility layer reports mixer state for screen readers; it does not accept it.
So the working split on this build is:
Want | Use | Why |
read track/mixer state | accessibility ( | accurate snapshots |
change volume / pan |
| reaches the engine, not the UI |
change project structure |
| insert commands are dispatched |
write notes |
| no note-level element exists |
edit existing notes |
| the dialog accepts writes; the export proves it |
create / delete notes |
| CAL is a note-level API and is not paywalled |
read notes |
| no side effect; every field, every note |
Setting volume and pan: two verified paths
Path 1 — live CC over the cable (cw_set_pan, cw_set_volume, cw_apply_mix).
CC7 is volume, CC10 is pan (0 = hard left, 64 = centre, 127 = hard right). The
message is addressed to the MIDI channel the track listens on, which is not
its position — read it from the strip's MIDI 通道 on Track N value. A channel
message only applies where a track is listening (armed, channel-assigned, or
bound to ACT); without a destination it is delivered and dropped.
Path 2 — bake the values into a .mid and import it. This is the more reliable
of the two because it needs no live routing. cw_write_midi_file emits CC7/CC10
at tick 0, which SONAR adopts as the track's initial volume and pan.
Verified end to end. A file written with:
Melody ch1 program 0 volume 100 pan 64 (centre)
Bass ch2 program 33 volume 112 pan 33 (49% left)
Pad ch3 program 89 volume 86 pan 99 (56% right)imported into SONAR and read back from the track strips:
Track 1 声道=1 音色=Acoustic Grand Piano 声像=0% 中 音量=100
Track 2 声道=2 音色=Electric Bass (finger) 声像=48% 左 音量=112
Track 3 声道=3 音色=Pad 2 (warm) 声像=56% 右 音量=86Channel, GM patch name, pan position and volume all matched. SONAR routes a
CC to the track carrying that channel, so a track's notes, program change and
CCs must all share one channel — cw_write_midi_file checks this and warns
rather than writing a file whose mix lands on the wrong strip.
The data level
There are no note, clip or event elements anywhere in the accessibility tree
— verified across a live 3-track project. What is exposed is the track-control
layer, not the data layer. On a build with no CakeScript transport, a .mid file
is therefore the only way to move notes in or out:
Tool | Direction |
| compose notes and CCs, write a format-1 file, import it |
| parse a file — track names, channels, note counts, CC7/CC10 with the pan position spelled out |
Import is fully scriptable: 0xE101 (文件 > 打开) opens a standard MFC dialog,
and its filename field does accept AXSetValue — the contrast with the
track strips is what shows the limitation is in SONAR's drawn controls, not in
accessibility as such.
Two mechanics worth knowing:
Coordinate spaces differ. Element bounds come back in window pixels (1920×902 here) while a click needs render-frame pixels (1280×601). Divide by
windowWidth/frameWidth(1.5). Passing bounds straight through is refused asoutside 1280x601.Values go stale. A second read of the same element can return the old value after an action. Confirm changes from a fresh screenshot.
Driving SONAR's UI (measured)
Not everything is reachable, and the split is not obvious. What was actually tested on 32.10.0.021 with a computer-use runtime:
Surface | Reachable? | How |
Menu bar (文件/编辑/工具/帮助) | yes |
|
Standard MFC dialogs (Preferences, any | yes | read elements by index; |
Project views (track list, mixer, piano roll) | no | drawn with Direct2D; nothing in the tree — read from pixels |
JUCE dialogs (Quick Start, 新建工程文件, palette) | partial | only title + close button appear; click by screenshot coordinate |
Keyboard | no | synthetic key events are swallowed by SONAR |
Two of those are worth spelling out because they cost the most to discover.
The menu bar works even where WM_COMMAND does not. Expanding 文件 makes
every entry appear as a clickable element — including 新建(N)..., which opened
the new-project dialog. The 视图 menu and the CakeScript group are the same
kind of command that WM_COMMAND cannot reach, so this is the path to them.
Synthetic keystrokes do not reach SONAR. Alt+1, Ctrl+Shift+I, typing
into a panel — all swallowed, repeatedly, with the window verified foreground via
SetForegroundWindow and an input-thread attach. Do not script SONAR by
keystroke. Click elements, or click coordinates.
When the UI locks up
A JUCE modal dialog holds SONAR's UI thread. While one is open:
computer-use calls time out (observed repeatedly)
WM_COMMANDto the main frame is silently dropped
Recovering needs Win32, against the dialog's own hwnd — in this order, checking after each:
SendMessage(hwnd, WM_COMMAND, 2 /* IDCANCEL */, 0)
SendMessage(hwnd, WM_COMMAND, 1 /* IDOK */, 0)
SendMessage(hwnd, WM_CLOSE, 0, 0)WM_COMMAND/IDOK is what cleared the stuck dialog that was blocking everything.
WM_CLOSE alone did nothing to it.
Recipes for the operations that need the UI
cw_probe_state carries these alongside the read plan. They are written from
having done them, including what failed:
newProject — Quick Start's caret, or 文件 > 新建. The 新建工程文件 dialog is JUCE: read the form from a screenshot. Pick a multi-track template (16-Track, 4-Track) — an empty one leaves nothing to arm.
确定stays disabled until位置exists on disk, and the dialog does not always re-validate after the directory appears, so it may need a field re-touched.armTrackForMidi — enable the cable (
cw_enable_midi_port), then arm a MIDI track's R button, or assign the input to ACT. Without an armed destination the messages are delivered and valid but have nowhere to go.insertMidiTrack — needs the Track view open first.
Plugins: discovery works, insertion does not
Detection is accurate and covers three sources, because SONAR registers plugins in three different places and reading only one made searches disagree with SONAR's own plugin browser:
Source | Count | What it holds |
Registry inventory, named | 653 |
|
Registry inventory, scanned but unnamed | 293 | real and loadable — |
Menu layout only | 262 | the DX-era effects ( |
Searchable total | 1208 |
A spot check across formats returns 12/12: Archetype Mateus Asato (VST3),
EZdrummer 3, Kontakt 8, Massive X, Boost11 (DX), Compressor/Gate (DX),
Melodyne, Battery 4 and others — each with its format, kind, and whether the
file is still on disk.
Two read optimisations worth noting. The inventory read was 10 415 ms with
reg query /s (which recurses into all 946 subkeys for their values) and 74 ms
with the top-level query (which returns the subkey names, where the path and
plugin name already live). CLSIDs are now fetched per-plugin at ~10 ms when
actually needed.
What cannot be done: attaching a plugin to a track
Measured on 32.10.0.021, and this is a real limitation:
Step | Result |
Open the plugin browser ( | works — a JUCE panel docks on the right with a category tree |
Expand a category | works — Dynamics lists |
See each plugin's format | works — rows are tagged |
Read which plugin is selected | works — the status bar reports |
Insert it onto a track | does not work — single click, double click and drag all leave the FX bin empty |
The reason is consistent with everything else here: the plugin panel is drawn,
not laid out. The window reports 144 accessibility elements whether the browser
is open or closed — the category rows, plugin rows and the 音源架 / Fx Audio FX
tabs carry no elements at all. And the track strips expose no FX-slot element
either, so there is nothing to drop onto by name.
cw_plugin_insert_recipe reports this. The workarounds, in order of how well
they work:
Insert the plugin by hand — fastest and most reliable.
cw_add_track— inserts a track with SONAR's default instrument attached, which is enough to hear a MIDI part.Write the part as a .mid — the program change picks a GM sound, so a recognisable instrument plays without loading any plugin at all. This is how the song in this repo gets its piano, bass and pad.
Mixing: what is reachable
Track volume and pan are readable through accessibility and not writable (see the survey above). Two levers actually move them:
Lever | Status |
Live CC7/CC10 over the cable ( | reaches SONAR, but does not move the strip unless the track is monitoring that channel — and arming cannot be set through automation either |
CC7/CC10 baked into a .mid, then imported | works, verified end to end |
The distinction is not obvious and cost time to establish: a live CC is delivered
to SONAR and reported ok, so it looks like it worked. Reading the strip back
after sending a mix showed the old values still in place — the message had gone
nowhere because nothing was listening.
Measured end to end. A file written with:
Melody ch1 program 0 volume 100 pan 64 (centre)
Bass ch2 program 33 volume 112 pan 46 (29% left)
Pad ch3 program 89 volume 78 pan 82 (29% right)imported and read back from the strips:
Track 1 声像=0% 中 音量=100 音色=Acoustic Grand Piano
Track 2 声像=28% 左 音量=112 音色=Electric Bass (finger)
Track 3 声像=29% 右 音量=78 音色=Pad 2 (warm)Volume matched exactly on all three; pan matched to within SONAR's rounding.
A gotcha that will bite anyone iterating on a generated file: opening a
filename that is already the loaded document does nothing — SONAR treats it as
already open and skips the reload. Verified by rewriting song.mid with new
values and re-opening it (strips unchanged), then copying to song-mix-v2.mid
and opening that (new values appeared immediately). Write to a new filename each
time, or close the document first.
On the honest limits of "mixing" here: with no way to insert plugins, there is no
EQ, compression or reverb to dial. What remains is the balance — level and
placement of the parts. mix.mjs writes a full arrangement with that balance
baked in.
Coverage: what is exposed, and where the gaps really are
Measured by taking SONAR's own command index (1208 searchable entries, of which 257 appear in the live menu bar) and subtracting what the adapter exposes. The gaps fall into two very different kinds, and telling them apart is most of the work:
Area | Commands | Exposed | Why the rest is missing |
Transport / timing | 32 | 14 | the rest are transport buttons — no elements, no readback |
Project files | 28 | 9 | export and import need a selection; the rest are covered |
Track management | 64 | 11 | most are per-track menu items with no distinct capability |
Views | 84 | 9 | opening a view is one operation; the other 75 are layout variants |
Note / MIDI | 39 | 4 | note-level data has no accessibility surface at all |
Selection / navigation | 63 | 12 | added this round — see below |
Markers / arranger | 46 | 12 | markers added; the arranger is unprobed |
Mixing / routing | 22 | 2 | sends and buses are drawn — readable, not writable |
Editing | 30 | 3 | most need a selection first, and several are destructive |
Plugins | 24 | 0 | insertion cannot be driven — see the plugin section |
Two of those deserve spelling out, because "not covered" means something different in each case.
Note-level data has no surface — for READING. It does for WRITING. A
project's notes are drawn in the clip area and there is no Note element
anywhere in the tree — verified across a 3-track project. That is why
cw_write_midi_file / cw_read_midi_file exist: a .mid file is the only way
notes cross the boundary.
An earlier version of this section stopped there and implied notes could not be
edited either. That was wrong, and the cost of the mistake is worth recording:
the claim was copied from the reading limitation without being tested. Editing
notes works, through the dialog behind 处理 > 量化 — see
Editing notes. Reading
them still has no surface, so the only way to confirm an edit is to export and
parse the file, which is what the adapter does.
Editing commands are precondition-gated. 量化 / 移调 / 拆分 probed as
unconfirmed — but an edit command on an empty selection is expected to do
nothing, so unconfirmed here does not distinguish "broken" from "nothing was
selected". Satisfying the precondition turned all three into open dialogs; see
the next section.
What this round added
Markers, and the pattern behind them. 工程 > 插入标记 (0x807F) opens a
standard MFC dialog titled 标记, and accessibility can write to it:
// 13 textfield "名称(N):" => setValue "Intro"
// 10 textfield "时间(T):" => setValue "1:01:000"
// 5 button "确定"That created a marker, which was then read back from the marker list — 视图 > 标记 shows a table with columns 时:分:秒帧 / Lk / 小节:节拍:嘀嗒 / 音高 / 名称,
and a table is readable. So the round trip closes: write through a dialog, read
through a table.
That is the generalisable finding. SONAR's own controls are drawn and ignore writes; a dialog behind them is not. Whenever a drawn surface has a command that opens an MFC dialog, use the dialog — it is the one place writes land.
Selection and navigation. cw_navigate covers 19 commands across selection
(all / none / by time / from-now / to-now / to-end), now-time movement (next and
previous bar, next and previous marker) and markers (insert, project start/end,
remove). Each record says how it can be confirmed: dialog for the two that open
one, screenshot for the rest, with what to look at named — because a selection
and a now-time change are drawn and this process cannot see either.
cw_markers carries the dialog's element names, the readback path, and the limit:
deleting a named marker has no command and no dialog — only the project
start/end markers have remove commands. Removing an arbitrary marker needs the
list UI.
The editing layer, and why "nothing happened" has three causes
This round found the other half of the measurement problem. Probing 量化 / 移调 /
分割剪辑 with no selection reported unconfirmed for all three — and the tempting
reading was "these do not work". They work. An edit on an empty selection is
supposed to do nothing:
no selection 0x8061 处理>量化 unconfirmed
after 编辑 > 选择 > 全部:
0x8061 处理>量化 opens #32770 「量化」
0x8066 处理>移调 opens #32770 「移调」
0x8012 分割剪辑 opens #32770 「分割剪辑」All three dialogs are standard MFC, so their fields accept AXSetValue — the
same property that makes the file and marker dialogs writable. cw_edit
satisfies the selection precondition automatically, which is the difference
between a command that looks broken and one that opens its dialog.
So a probe result of "nothing happened" has three causes on this build, and only one of them is a limit of the adapter:
Cause | How to tell | What it means | What to do |
| it is a toggle, transport action, selection or fader | it worked; the result is pixels | confirm with a screenshot |
| it is an edit, an export, or acts on a selection | the command is fine, the state was not | satisfy the precondition and retry |
| a | needs a paid tier on this install | report it and stop |
cw_no_effect_causes carries this taxonomy. The third cause is new: two arranger
commands (添加编曲音轨 0xA63B, 复制编曲音轨 0xA63E) open the membership panel,
which is a licence gate rather than a missing feature — an arranger track
nonetheless appeared in the tree, so the arranger itself is present.
Destructive edits (split, merge, normalize, reverse, remove-silence, fade) require
the caller to name the command, on the same reasoning as cw_project:
cw_edit({command:'normalize'}) is refused; {confirm:'normalize'} runs.
Editing notes: the one round trip that proves itself
This is the only place in the adapter where a change to project data is both made and verified, so it is worth spelling out end to end.
Notes cannot be read through any automation surface. They can be edited, because the edit commands open real MFC dialogs and accessibility writes to those land. That splits the problem in two: make the change through the dialog, prove it from the file.
编辑 > 选择 > 全部 0x804C gives the edit something to act on
处理 > 量化 0x8061 opens #32770 「量化」 — 46 readable elements
AXSetValue 时值(U): 43/textfield "16 分音符" ← the textfield, NOT the combobox at 41
AXSetValue 强度(S): 31/textfield "100" ← must be set explicitly; it persists
AXSetValue 灵敏度(W): 25/textfield "100"
AXPress 确定 11/button commits; the close is ASYNCHRONOUS
文件 > 导出 > 标准 MIDI 文件 0xA659 writes 保存副本 → the tick positions are now data
cw_read_midi_file reads them backThe measurement, with a control group. A test file was written with eight notes deliberately off every grid:
ticks | on the 16th grid? | |
written by us | 30 530 935 1477 1877 2461 2862 3404 | no |
exported with no edit | 30 530 935 1477 1877 2461 2862 3404 | no |
quantized at 100% | 0 480 960 1440 1920 2520 2880 3360 | yes |
The middle row is the control, and it is what makes the bottom row mean
something: export alone moves nothing (zero drift), so every tick in the third
row is the edit. cw_check_quantize reproduces the third row from the first by
arithmetic alone.
Two mistakes, both recorded because both produced a wrong answer.
Measuring too early. AXPress on 确定 is accepted, the dialog closes, and the
window list is checked in the same breath — which still shows the dialog. The
obvious reading is "the press did nothing". It did. The close is asynchronous;
wait, then look.
No control group. The first run used the dialog's persisted default of 50% strength, which moves each note only part of the way to the grid: 30 → 16, 530 → 506, 935 → 948. Those deltas (10–30 ticks, mixed directions) look exactly like export rounding noise, and "quantize is broken" was the conclusion — until exporting the same file with no edit returned the source ticks unchanged. That control made the movement real, which pointed at the strength setting, which was the actual cause.
How well "half way" actually describes 50% is worth stating precisely, because
the model in predictQuantize is linear and the measurement is not quite:
source | measured @50% | model | difference |
30 530 935 1477 1877 2461 2862 3404 | 16 506 948 1460 1899 2432 2872 3383 | 15 505 948 1459 1899 2491 2871 3382 | 1 1 0 1 0 59 1 1 |
Seven notes agree to within a tick of rounding. One — the 2461 → 2432 case —
does not, by 59 ticks. One sample cannot say whether that is 灵敏度
interacting with strength, a grid-line tie, or something else, and fitting a
constant to it would be inventing precision. So the model is marked exact only
at 100% strength (where it matched all eight notes) and approximate otherwise.
That labelling is what keeps a mismatch at partial strength from being read as a
failure.
The general rule this leaves behind: when a change looks like noise, export a no-edit control before concluding anything. It costs one file write.
cw_note_edit_help carries the whole procedure, cw_quantize_plan states the
field writes for a given setting, and cw_check_quantize judges a result from
two tick lists.
What is still not established: only 量化 has been measured field by field. 移调 and 分割剪辑 open the same class of dialog and should behave identically, but their element indices are not recorded. Checkbox state inside the dialog is not exposed either — which boxes are ticked must be read from a screenshot.
A measurement trap worth knowing: the window diff is blind
cw_verify_commands decides a command worked by diffing the top-level window list.
That test cannot see a change that happens inside the existing frame — which is
most of SONAR's UI. Probing the uncovered commands showed the cost directly:
Command | Window diff | What actually happened |
| no change | a tempo track appeared ( |
| no change | the track view repainted |
| no change | it is a toggle — it can never open a window |
An earlier round read "no window change" as "nothing happened" and concluded several commands were unhandled. That was a measurement artefact, not a property of the build.
The fix is not a better heuristic — it is admitting the limit. From this process,
a non-window-changing command cannot be confirmed. cw_command_evidence
records which commands are confirmed and which are not, grouped by what kind of
change they make, and names the witness that would settle each unconfirmed one:
Evidence class | Who can observe it | Example |
| this process |
|
| computer-use runtime |
|
| computer-use runtime |
|
| nobody — posting is not confirming | any toggle with no readback |
cw_run_command_classified returns confirmed / did-nothing / unconfirmed
with the class behind it, instead of claiming success from "nothing errored".
Transport and timing
The transport buttons are the one surface no automation reaches: they are drawn, so they carry no elements, and computer-use key events need SONAR frontmost. What is reachable is the command layer:
Command | id |
播放/停止 / 停止 / 录制 |
|
循环开关 / 设置循环选区 |
|
节拍器(回放 / 录制) |
|
视图 > 速度 / 拍号调号 |
|
插入速度变更 / 拍号变更 |
|
Every one changes state without opening a window, so cw_transport_command
posts and reports intent — it does not claim the transport moved. It returns the
expectedVisibleEffect naming what a runtime should look at.
For tempo and time signature specifically, there are two routes and they are not
equivalent. Writing them into a .mid and importing sets the piece's tempo map
exactly with no interaction (verified: a file written at 120 BPM imported and the
transport reported 120.00 / 4/4). Inserting a change at the now-time is a
different operation and only affects the position it lands on.
Document lifecycle, with a guard on the destructive parts
cw_project runs new / open / save / saveAs / close / exportAudio / importMidi /
revert. The commands that discard work require the caller to name what it is
destroying:
cw_project({ command: 'close', confirm: 'close' }) // runs
cw_project({ command: 'close' }) // refused: NEEDS_CONFIRMATION
cw_project({ command: 'close', confirm: true }) // also refusedA bare boolean is deliberately not enough — the point is that the caller has to
say which command it means. This guard exists because probing closed the open
project with no prompt at all (a clean project closes silently) and there was no
undo. cw_save_state reports the modified flag first, so a caller can see what is
at stake before choosing.
Reading project state on 2026.10
This build exposes nothing about project content through any automation interface. Verified on 32.10.0.021:
Interface | Result |
| empty string — no track, clip or mixer text anywhere |
UIA | 19 elements, all containers ( |
MSAA | control bars only, ≤16 children |
computer-use on the main view | 31 elements: menu bar, toolbar captions, pane names — no project content |
computer-use inside the Preferences dialog | 136 elements, fully readable and clickable |
The split is the useful part: standard MFC dialogs are fully automatable — that is how the MIDI input port was enabled, by reading the checkbox rows and toggling them — while project views are drawn, not laid out as windows, so they are invisible to every accessibility client and only readable as pixels.
The server therefore does not pretend to read state. Three tools handle the gap:
Tool | What it does |
| A plan for a topic ( |
| Accepts what a computer-use agent observed and caches it, in the same shape the CakeScript tools returned ( |
| Read the cache back, with staleness (30 min) and an explanation when empty. |
| Reference: every surface that carries state and what can be read from each. |
This keeps the MCP server's job honest — it automates what is automatable — and leaves the pixel reading to whatever agent has a computer-use runtime, with the knowledge of where to look shipped from here.
Status as of SONAR 2026.10 (32.10.0.021)
Tested 2026-10-12. What is true, after correcting an earlier misreading:
The 助理 (Assistant) menu entry opens the command palette, not an AI chat panel.
XCDLLMSERVERis never created, so thewrite_cakescript/run_cakescriptIPC has nowhere to land. The T1 transport is gone.The CakeScript commands are not gone. They are absent from the menu bar only because no project was open at the time. Open one and
视图 > CakeScript View(0xA797) and处理 > 运行 CakeScript 程序(0xA78D) are both present and both respond — on a free licence they open the membership panel. Whether CakeScript would actually run on a paid licence could not be established on this machine.
Both halves of that were re-checked against the binary and the live UI later, and the picture is firmer than "the entry point is gone":
write_cakescript(6 hits),run_cakescript(5),get_project_summary(7) andCakeScript(3,704) are all present as string literals in Sonar.exe, together with their full tool descriptions (invalid_tool_call,permission_denied,script_write_failed, …) and anAnthropicAPI URL.The engine is bound via sol2: the binary is full of
sol::detail::ctti_get_type_name<CakeScript::ITrack>/IClip/IMIDIEventAdv/IAutomation/IArrangement/ITakeLane/IClipboardsymbols, plus the literalLua 5.4.XCDLLMSERVERstill appears once as a string, but no such window is ever created, andLLM_INIT/LLM_TOOL_CALLdo not appear as literals at all — they areRegisterWindowMessageids, which is why scanning for them finds nothing. (An earlier note in this project claimed "24--*LLM_*--registered window messages"; that was wrong and is corrected here.)Posting
0xA78Dwith a project open raises aJUCE_1a13a4b5ecfwindow titledPaywallWindow, whose rendered content is the Sonar Membership upsell ("Unlock Sonar's complete toolset and features with Membership" — unlimited samples, Pro guitar tools, Elastique Pro, POWR dithering, early access).
So the correct statement is gated, not removed. The distinction is not
pedantic: a licensing gate lifts with a subscription, while a removed engine
needs a new build. And it explains the shape of the rest of this adapter — the
whole reason the editing dialogs (AXSetValue on #32770) and the MIDI cable
carry the write path is that the one broad, structured API is behind that panel.
What the paywall actually blocks — and what it does not
The licence banner is visible in the app: Free License Upgrade your experience with Membership, with a Get Membership button. On that licence,
处理 > 运行 CakeScript 程序 opens the upsell instead of a file chooser. So the
question that matters is: which capabilities are lost with it?
The answer came from SONAR's own command index. cwsearch.dat (SQLite, at
%APPDATA%\Cakewalk\Sonar\) holds 1,315 rows; 481 carry a live CMD_ID
— a Win32 menu command id, postable with WM_COMMAND — and 186 of those are
on the running build's menu bar right now. The index also has a SCRIPT_CMD
column naming the CakeScript verb behind each id, so the paywalled API can be
matched, entry by entry, against what the menu can reach anyway.
Mining the 处理 (Process) menu for rows with a live id gives 30 commands,
and roughly a third of them are note-level processors. Every one of the nine
below was opened on 2026-10-15 and its field table recorded; four were driven end
to end and the result read back out of an exported file:
Command | id | What it does to notes | Measured |
量化 Quantize |
| start times → grid | round trip verified |
移调 Transpose |
| pitch by an interval (signed) | round trip verified |
力度 Scale Velocity |
| velocities, as a percentage ramp | round trip verified |
音长 Length |
| durations and/or start times, scaled | round trip verified |
倒置 Retrograde |
| mirrors the pitch contour in place | round trip verified |
时间匹配 Fit to Time |
| stretches the selection to a target end time | fields |
律动量化 Groove Quantize |
| timing/duration/velocity against a groove | fields |
移动 Slide |
| shifts events by a signed amount in a chosen unit | fields |
轻移 Nudge ×8 |
| pitch (up/down) and time (left/right) | no dialog; step sizes measured |
查找/更改 Find/Change |
| selects events by a filter — it does not edit | fields |
This corrects the project's earlier claim that note editing needs CakeScript. It does not. Note editing has been reachable all along through these commands.
The verified four, with the arithmetic that makes them proofs rather than
impressions. Source material was a generated C-major scale at
60,62,64,65,67,69,71,72, velocities 100, durations 400 ticks on a 480 grid:
量化 — source ticks
30 530 935 1477 1877 2461 2862 3404at 100% became0 480 960 1440 1920 2520 2880 3360; a no-edit control export showed zero drift.移调 — wrote
3into数量(A)(element 25), pressed 确定, exported:63,65,67,68,70,72,74,75— every note +3 semitones, control unchanged.力度 — wrote
50into both开始(B)(element 9) and结束(E)(element 7), pressed 确定, exported: every velocity100 → 50.音长 — wrote
50into按照(B)(element 24) and pressed 确定: every duration400 → 200and every start tick0,480,960… → 0,240,480…, because时值(D)and开始时间(S)are both ticked by default. A caller wanting only the durations to change must untick element 27 first.倒置 — no dialog at all. Afterwards the pitches read
75,74,72,70,68,67,65,63at the same ticks: it mirrors the pitch contour and leaves the rhythm alone. The earlier description ("reverses the order of the notes") was wrong, and 倒置 is fully automatable without any GUI runtime.
Two corrections the measurements forced
Both were plausible-sounding claims that survived review and were still wrong.
查找/更改 is a selector, not a replacer. The record said "batch-replaces event
properties". Opening it shows a dialog titled 事件过滤器 - 搜索 with 141
elements: per-event-type rows (音符, 控制器, RPN, 弯音轮, 音色 …) each carrying
包含/排除 checkboxes and min/max ranges for 音高, 力度, 时值, 通道, 拍 and 嘀嗒.
It narrows a selection for another command to act on. Nothing in it modifies an
event.
轻移 > 设置 is not a nudge dialog — it is the global preferences window.
Posting 0x8532 opens 参数设置 on its 轻移 page. The three steps are
independently configurable, not a small/medium/large ramp:
轻移 1 = 10 毫秒 轻移 2 = 1 帧 轻移 3 = 2 帧each with 绝对时间 / 音乐时间 / 使用对齐设置 radios. That explains something that had looked like a broken command: a nudge appears to do nothing because step 1 moves 10 ms, far below one MIDI tick at ordinary tempos. It is also a preference write, which undo does not cover and which outlives the project — so the command is marked destructive with that reason stated.
The one limit that shapes all of this
Every number in these dialogs is backed by SONAR's CC:SpinCtrl, and the
Edit beside it is a shadow control. A raw WM_SETTEXT on that Edit reads
straight back — and then GetWindowText on the same handle returns empty again,
because the value the dialog uses lives in the SpinCtrl. The write must go
through an accessibility runtime (AXSetValue, or computer-use's setValue),
which is exactly what the field tables are for, and why a pure-Win32 path cannot
replace one.
A companion finding that makes this cheap to exercise: these dialogs open regardless of whether the selection contains anything. Select-all on a project whose tracks are all empty still opens 量化 and 移调 with every field readable and writable. Only the commit needs real notes to be meaningful.
What each capability actually needs
Capability | Requirement |
Track / note / mixer tools ( | T1 — unavailable on 2026.10 |
Note editing with a dialog (quantize, transpose, velocity, length, fit, groove, slide) | a selection + an accessibility runtime — no CakeScript, no licence |
Note editing without a dialog (retrograde, nudge ×8) | a selection — posting the id is the whole operation |
Creating, deleting and reading notes | CAL — a selection + the file dialog. No licence. See below |
Selecting events by filter ( | a project open; it changes no data |
| a project open, for the view/document commands |
| the cable enabled as a SONAR input — verified via TTSSEQ.INI |
Reading track state | a project open + a computer-use runtime |
Changing track state | MIDI; the UI path is read-only |
Track rename, mute, channel/port routing | CAL's track builtins — no licence |
Solo / record-arm | selection-based menu commands ( |
Undo / redo / inspect the undo stack |
|
Plugin insertion | no scripting route; a control-surface COM plugin can set it by strip index |
Two rows carry the weight. Nine note operations are available on a free
licence through the edit dialogs, five verified end to end, and two of those
(倒置 and the nudges) need no GUI automation at all — they are plain
WM_COMMAND posts. And CAL closes the three gaps the dialogs cannot reach:
creating, deleting and reading notes. That is a far larger surface than "no note
editing", which is what this project claimed before measuring.
CAL — notes can be created, deleted and read on a free licence
The 处理 menu has a second macro language, and it is not behind the
paywall. 处理 > 运行 CAL 程序 (0x806A) opens an ordinary file dialog listing
*.CAL — not the membership panel that 0xA78D (CakeScript) opens — and the
interpreter behind it reads and writes note data directly.
Measured 2026-10-15, every result read back out of an exported .mid parsed by
cw_read_midi_file. Source material was a generated C-major scale,
60,62,64,65,67,69,71,72, velocities 100, durations 400 ticks:
Operation | CAL | Result |
modify |
| 8 notes, every velocity |
create |
| 8 → 32 notes; each new pitch exactly |
delete |
| 32 → 16; exactly the 16 above the threshold, none left |
read | summary written into the track name |
|
cw_cal_plan writes nothing and posts nothing; cw_cal_run writes the script
into the CAL folder, posts 0x806A, and reports the dialog steps for an
accessibility runtime; cw_cal_help carries the language reference.
The language, as far as the 37 shipped scripts establish it
There is no CAL documentation on this machine — no help file, no reference, and the CakeScript guide mentions CAL only as what CakeScript replaced. Everything below is read out of the scripts themselves, and where a thing is not observable there it says so rather than guessing.
Structure. A sequence of parenthesised expressions. The
prolog / body / epilogsplit in the shipped scripts is a convention, not grammar: the body slot is re-evaluated once per selected event, and a script may equally be one(do …)or one bare(if …).TICKINFO.CALproves the body slot is a slot — it putsNILthere with a comment saying this makes the routine run once instead of per event.(forEachEvent expr)is the explicit form;LEGATO.CALuses both.Variables.
(int name init),(dword …),(word …),(string …). A prolog variable persists across the walk — that is the only cross-event state, andSINGLE.CALuses it (with a-1sentinel) to reach the previous event's fields, which no builtin offers.Fields.
Event.Kind,Event.Time,Event.Chan,Note.Key,Note.Vel,Note.Dur,Control.Num,Control.Val,Wheel.Val,ChanAft.Val.Event.KindandEvent.Chanare read-only in every shipped usage;Event.Time,Note.Key,Note.Vel,Note.DurandControl.Valare written. Observed kinds:NOTE,CONTROL,WHEEL,CHANAFT;KEYAFTandPATCHare addressable through the filter API though no script branches on them.Arithmetic is integer —
/truncates, which is why every percentage in the shipped scripts is(* x pct)followed by(/ … 100).++ -- += -= *= /=return the new value, so they nest inside an expression.Reporting is the weak point. The only outputs are
message(status line) andpause(modal), and no shipped script writes a file. So a note list cannot come back as text: a string accumulated across the per-event walk does not survive it — measured, the count arrived and the data did not.
The trap that silently corrupts output
insert resets the in-flight event's fields. HARMONYZ.CAL says so in a
comment: "insertion reset Event.Time during the building of the same chord."
Any field read after the first insert is not the value that was there before it,
so a second and third insert land at the wrong time — with no error, just
misplaced notes. Every generated script copies Event.Time/Chan and
Note.Key/Vel/Dur into variables before its first insert, and a test
asserts that ordering (test/cal-script.test.mjs).
Two smaller ones: durations are 16-bit and wrap at 65535 (recorded in
STRUM-IT.CAL), and pause/getInt are modal, so no generated script prompts.
Reading notes back
Three options, in order of preference, and the reasons are not symmetric:
Export and parse —
0xA659thencw_read_midi_file. No side effect, already verified, and it returns every field of every note. This is the answer for reading note data.queryNotes— encodes a fixed-format summary into the track name, which is readable from an export. It works, but it renames the track, socw_cal_runrefuses it withoutallowRename: true.Returning a note list as text from CAL — measured to fail, and recorded as such rather than left as an implied possibility.
Two operational notes about running CAL
A run leaves a file behind. cw_cal_run writes MCP-<program>.CAL into the
real CAL folder — the same folder that holds the 37 shipped scripts. The name is
derived from the program, so a re-run with the same parameters overwrites rather
than accumulating, and identical content is detected and skipped
(changed: false). It still lands among the stock scripts, so anything listing
that folder will show it; delete it when done with removeScript or by hand.
The dialog's filename field index is not stable. Measured twice on the same
dialog: the 文件名(N): textfield was element 33 in one observation and
32 in the next, because a shell control appears or disappears while the
folder list loads. The 打开(O) button held at 26 both times. So the plan tells
a runtime to resolve the textfield by property — title 文件名(N):, kind
textfield, with a set-value action — rather than by the number, and a test
pins that instruction. Trusting the index would fail intermittently, which is
worse than failing outright.
The gaps the paywall really does hold
Three of the four things this section used to list turned out not to be gated, and the reasoning that put them here was wrong in a way worth recording, because it was wrong twice over.
The original argument was: every candidate command for these operations exists
in the index with no CMD_ID, therefore it is not on the menu and cannot be
posted. Both halves of that were unsound:
The premise about
CMD_IDwas a misgeneralisation. The index has 481 rows withACTION_TYPE_ID = 1(Execute Command), and all 481 carry a realCMD_IDthat matches the live menu exactly — verified against ids this adapter already posts (0x82A6insert MIDI track,0x806Arun CAL,0x804Cselect all,0xE101open…). What produced the "index ids are not WM_COMMAND ids" warning was a different set of rows: the view-menu mirrors (音轨视图->音轨->…,控制台视图->…) areACTION_TYPE 6/7/8withCMD_ID = 0and the real id inACTION_ID. Posting theirCMD_IDposts 0. The top-level rows do not have that problem.The conclusion ignored CAL entirely. Mute/solo/arm have postable ids that the adapter itself already listed as working in
commands.js.
So the list shrinks to one entry, and this is what it is now:
Plugin insertion. No indexed command inserts a plugin into a track's FX bin;
IncrementPluginPreset/DecrementPluginPresethave no id. CakeScript'sPlugins:InsertAtis the only in-process route. Two alternatives exist and neither is a scripting path: a control-surface plugin (the interface is real —IControlSurface/2/3inD:\CAKEWALK\Shared Surfaces\GenericSurface.dll, discovered throughHKCR\CakewalkControlSurfaces— note that this is notHKLM\SOFTWARE\Classes\CakewalkControlSurfaces, which is empty; an earlier revision of this file gave the wrong path and a round of work was built on it, see The control-surface bridge below), or authoring a.cwxtrack template, which is the same binary container as.cwp.
The control-surface bridge: what was built, and what it proved
This is worth reading in full, because the outcome is a negative result and the negative result is the useful part. The surface plugin was expected to be the key that unlocked mute, solo, record-arm, routing, patch and the FX bin on a free licence. It is not, and the reason is now measured rather than assumed.
What works, verified end to end:
Step | Result |
Find SONAR's real discovery key |
|
Register a sixth entry | works, no elevation — writing through |
Build a COM object of the right shape | works — 44-slot vtable ( |
Survive the deepest slot | works — slot 43 ( |
Appear in the picker | works — |
Get instantiated by SONAR | works — |
Why this adapter no longer uses the surface (the decision and its evidence).
The surface must be re-added once per SONAR launch, and that is now understood at function level rather than by observation:
Sonar.exeexportsCCtrlSurface::PersistSurfaces— the function that writesctrlsurface.dat— and contains noLoadSurfaces,RestoreSurfacesorInitSurfacessymbol anywhere. It persists the list and never reads it back at startup.Measured consequence:
ctrlsurface.datheld the bridge's CLSID (written 00:09), SONAR started at 00:16, and the resulting process module list did not containcw_surface.dll. The file listed the bridge while the new process had never loaded it.
So the surface exists only between "user presses 确定" and "SONAR exits". It can be re-added by automation — that walkthrough is below and every step in it is reachable, because these dialogs are MFC and expose accessibility (unlike the JUCE ones) — but doing so requires a computer-use runtime driving SONAR's foreground UI after every launch, which is exactly what a one-click deployment must not depend on. It also cannot be fixed from outside without patching the host, which this project does not do.
Nothing needs it any more. Exactly one tool (cw_surface_set) required it to
write, and every one of those writes now has a file-based path: volume and pan
through CC7/CC10 baked into an imported .mid (verified end to end), mute /
rename / channel+port through CAL, and mute/solo/record-arm through a real click
on the track strip. The eight cw_surface_* tools are hidden unless
CAKEWALK_MCP_SURFACE=1 is set, and install.ps1 leaves the DLL alone unless
-WithSurface is passed.
The scripted walkthrough below is kept because it is the measurement record, and
because it is what makes -WithSurface usable on a session where you want the
diagnostics:
cw_close_overlays PaywallWindow / Quick Start must go first,
or the menu is inert
cw_run_command 0x882D 编辑 > 参数设置
click the MIDI tree row expands it
click the 控制界面 row
click the second header button the 'a' button beside 已连接的控制器/界面
ComboBox 控制器/界面(C) setValue "Cakewalk MCP Surface Bridge"
确定, then 确定 commits and loads the pluginNo project needs to be open — verified by doing exactly this on a session with no document. The dialog's input-port combo only lists MIDI devices that are enabled in 参数设置 > MIDI > 设备, which is why setting it to a loopback port silently fails until that device is enabled first.
What the first sweep showed, and why its conclusion was wrong:
Connect: pUnknown=0000000008042F60 hwndApp=0000000000020E60
QI IDispatch -> 0x80004002 (E_NOINTERFACE)
probe IControlSurface -> 0x80004002
probe IControlSurface2 -> 0x80004002
probe IControlSurface3 -> 0x80004002For a while this was read as "the host object implements IUnknown and nothing
else", and that reading was wrong in a way worth recording: every E_NOINTERFACE
above is evidence about the IIDs I guessed, not about the object. A
QueryInterface failure only ever means "not this one", and four misses were
mistaken for a property of the host. The conclusion drawn from it — that
SetTargetParam was unreachable — was therefore premature.
What the object actually is (measured, and it was recoverable all along)
The way through was static analysis of Sonar.exe, not more guessing:
The log file gave absolute addresses, and the module base made the vtable RVA exact:
0x1433505D8 - 0x140000000 = 0x33505D8.On disk that RVA lands in
.rdata, and[vtable-8]is an MSVCRTTICompleteObjectLocator. Following it to the TypeDescriptor gave the class name:.?AVCCtrlSurface@@.Its
ClassHierarchyDescriptorlisted the bases — and they identify the object's role:CUnknown,INonDelegatingUnknown,CBaseObject,CMidiInputMonitor::CObserver,CCtrlSurfaceBase. It is a MIDI-input observer, i.e. the object that feeds MIDI to a surface.Disassembling its slot 0 showed it is
QueryInterface— the code doesmov rax,[rdx]and compares against IID pointers. That also explains the crash of the earlier blind probe: passing(1, 2)made the function dereference1as an IID.The three IID addresses it compares against were extracted from that disassembly, and all three now return
S_OK:
probe HOST_IFACE_1 -> 0x00000000 {ED0C14F0-40F3-4459-813C-CB5B5A5E4958}
probe HOST_IFACE_2 -> 0x00000000 {85F8BB17-75F8-497F-8319-EF33A632C380}
probe HOST_IFACE_3 -> 0x00000000 {55507DE1-C037-4682-A4EC-65B1D2E86B53}
accepted iface 0: vtable=0x14340ECF8 slots=5
accepted iface 1: vtable=0x14340EC98 slots=6
accepted iface 2: vtable=0x14340EC28 slots=8So the host object does expose usable interfaces. The plugin now captures
each accepted interface and its vtable, and cw_surface_diag / op:"probe"
report them. Nothing about the earlier four E_NOINTERFACE lines was wrong as a
measurement; only the generalisation from them was.
The question is now closed by disassembly — and the answer is that these methods were never there
Following the host object down to its vtable settled it, and closed the search
rather than leaving it open. The full analysis is in
native/surface/ANALYSIS.md; the finding is:
CCtrlSurface has exactly 13 slots, and they line up with IControlSurface:
slot 0 QueryInterface compares IIDs (mov rax,[rdx])
slot 1 AddRef lock inc [rcx+0x10]
slot 2 Release lock xadd [rcx+0x10]
slot 3 GetStatusText
slot 4 MidiInShortMsg
slot 5 MidiInLongMsg
slot 6 Connect
slot 7 Disconnect
slot 8 RefreshSurface
slot 9 GetNoEchoMask
slot 10 GetVersion
slot 11 GetNoEchoStatusMessages
slot 12 (IControlSurface2 begins)So the object SONAR hands to Connect is itself an IControlSurface
implementation with 13 slots — not the 44-slot IControlSurface3, and not the
59-slot CSonarMixer. SetBaseTrack and SetTargetParam are not in it at
all. No amount of guessing its IIDs could have found them, which is exactly
what the four earlier E_NOINTERFACE results were really saying.
Disassembling the shipped GenericSurface.dll then showed the interface runs in
the opposite direction from what the plan assumed:
Method | Shipped implementation | Meaning |
| reads | SONAR notifies the surface that a value changed, so it can move its fader |
|
| the surface does not declare a MIDI mapping |
| reads | the host asks the surface what it is displaying |
The surface interface is host → surface notification. A surface does not push
values into SONAR through it. cw_surface_set still refuses, and now for a
reason that is established rather than unknown.
What does work, and it is now exposed as a tool: MIDI
A surface's channel back into SONAR is MIDI, and it needs exactly one thing — the surface must be assigned the right input port. The default is the audio interface, which is why the first attempts saw nothing.
Measured, after setting 输入端口 to the loopback port:
before: 0
after : 11
0xB0 d1=7 d2=20 CC7 volume
0xB0 d1=7 d2=35
...
0xB0 d1=10 d2=64 CC10 pan
0xB0 d1=1 d2=10 CC1 modulation
0x90 d1=0 d2=100 Note On11 of 11 messages arrived, with status, data bytes and arrival tick. This is
a genuine, verified two-way link between a process inside SONAR and the adapter,
and it is available as cw_surface_midi_in.
What is still missing is the interpretation: mapping "CC7 on channel 1" to
"set volume on base track + N" needs mixer access, which lives in
CGenericSurfaceStrip (12 slots) behind an indexed global table — one of its
failure paths returns 0x8002000B = DISP_E_BADINDEX, an IDispatch error code,
which is evidence the lookup is by index rather than by name.
Closing that needs the SURFACEFRAMELib type library or more disassembly of the
strip's mixer path. The type library is confirmed unavailable: it is not on disk,
not registered, and no DLL in the set will load with LoadTypeLibEx — all
return 0x80029C4A (TYPE_E_CANTLOADLIBRARY) and LoadRegTypeLib returns
0x8002801D (TYPE_E_LIBNOTREGISTERED). It was a compile-time #import only.
The earlier probing attempt, and why calling was abandoned
Before accepting the above, three more attempts were made to identify the host object, and the last one crashed SONAR. All of it is recorded because the conclusion is stronger than "we did not find it":
Recover the interface from the binary.
GenericSurface.dlldoes contain the method-name strings —GetTargetParam,SetTargetParam,SetBaseTrack,GetTrackCount,SetBankWidth— but they are its own vtable entries, the ones SONAR calls on the surface. They name the parametermixerParamanddwParamNumfrom the callee side. Nothing there reveals what SONAR passes in, and the referenced typelib (SURFACEFRAMELib) has no resource table in the DLL and no.tlbanywhere on disk.Recover the class from RTTI. The vtable was attributed to
Sonar.exeand the first twelve slots all resolve into it, so the object is a real C++ class in the host. But the MSVCRTTICompleteObjectLocatorread back empty, and Sonar.exe is stripped — 7 symbols — so the class name could not be recovered that way.Identify the setter by behaviour. Call each vtable slot and see which one moves a track's mute state; no name needed. This was implemented and run twice:
First run deadlocked the bridge. Calling slot 0 from the bridge's own worker thread never returned, and every later request timed out. SONAR was fine — project intact, menu working, document not even modified — but the channel was dead until restart.
Second run isolated each call on its own thread with a timeout, which fixed that exactly as intended: nine slots reported "did not return" without touching the bridge, three returned values consistent with an
IUnknownprefix (slot 1 = 6, slot 2 = 5 — reference counts; slot 3 = a heap pointer), and the bridge answeredpingafterwards.And SONAR then raised its own crash dialog:
C0000005, access violation, dumped toMiniDumps\Untitled_10162026_020341.dmp.
Isolation protected the bridge, not the host. The harmful call happened inside SONAR on a thread that could not be recalled. Recovery was offered and declined, so no project file was written.
The general lesson, which is the real result here: an unknown C++ interface cannot be discovered by calling it. Every guard available from the caller — memory protection, thread isolation, timeouts — protects the caller and never the callee. A wrong-but-executable slot runs at full privilege inside the host, and this host crashes on the wrong guess rather than returning an error. All of that probing code has been removed rather than left switchable: an operation that can silently kill the host is worse than no operation.
What was kept, and why it is still worth having:
cw_surface_status/cw_surface_diag/cw_surface_params/cw_surface_help— the status separatesnot-installedfromneeds-user-setupfromready, and the diagnostics are what produced the measurement above. Anyone re-attempting this on a future build should start fromcw_surface_diag.The plugin source and build. If a later SONAR hands over a richer object, the sweep shows it immediately and the write path can be completed.
A JSON-escaping fix in the DLL, found because the first error message contained a bare
"and the client reported "unparseable JSON" instead of the error. A protocol that mangles its own error messages is worse than one that has none; there is now a regression test on both sides.
Two by-products that matter more than the negative result:
RefreshSurfaceis a real, configurable heartbeat — 75 ms default, set in 参数设置 > MIDI > 控制界面 → 刷新频率(毫秒). A surface that only needed to read or tick could use it.The accessibility path already covers what the surface was meant to give. The track strips expose
手动静音,独奏,录制,输出,输入,音色,音色库andMIDI 通道as named, settable elements — see Reading tracks works; writing needs a different transport. The surface was an attempt to reach these without a UI dependency, and it failed; the UI path is the one that works.
The operational cost, stated plainly: a registered surface is not remembered
for free. It appears in the picker persistently, but the DLL only loads once the
surface has been added in Preferences for that session, so a fresh SONAR has no
bridge listening. cw_surface_status reports that as not-installed, and
native/surface/install.ps1 is how it comes back.
What was wrong about rename, mute, solo and arm
Track rename is not gated — CAL has
(TrackName "string" idx), and it was measured end to end:(TrackName "MCP-VERIFY" 2)ran through0x806Aand the exported.midcame back with that track renamed. The index genuinely has no rename command, which is what made this look impossible; CAL has one anyway, because CAL is a language the index does not describe.Mute is not gated — CAL has
(TrackActive TRUE|FALSE idx). The semantics are pinned by a shipped comment rather than assumed:Split Channel to Tracks.cal:40reads; Un-mute the trackdirectly above(TrackActive TRUE nTrk), soTRUEis audible andFALSEis muted.Mute, solo and arm also have postable menu commands after all:
MuteSelectedTracks0x80E1(32993),SoloAllSelectedTracks0x809F(32927),ArmSelectedTracks0x80E2(32994), plus theToggle*AllTracksfamily at0x8202–0x8204, two of whichcommands.jsalready records as working. They act on the selection, so the precondition is a selected track, not a dialog. (They were never actually id-less: the index row carries the id.)CAL routing —
(TrackChannel chan idx)and(TrackPort port idx)are proven in the shipped scripts.
What CAL still does not have, as a clean negative from grepping every shipped
script: TrackSolo, TrackArm, TrackVolume, TrackPan, TrackPatch,
TrackBank, TrackOutput, TrackInput — zero hits each. So solo and record-arm
are reachable only through the menu commands above, and volume/pan through MIDI
or the COM surface interface.
The one structural rule that cost two failed runs
A top-level expression in a CAL file is the per-event body slot, not a
statement. A track builtin written loose there fails with
CAL Error 016: 无效的事件信息或主体表达式 naming the builtin. The shape that
works — and it is what every generated track program now emits — is:
(do ; prolog: declarations
(include "need20.cal")
(int trk 2)
)
NIL ; body: the event walk, empty here — REQUIRED
(TrackName "MCP-VERIFY" trk) ; epilog: runs once
(pause "...")Wrapping the prolog and the track call in a single (do …) fails too,
because then the call is no longer in the epilog position. Both mistakes were
made and measured; a test now pins the shape.
The two earlier entries that were withdrawn
Note add / delete / read was on this list because every note command in the
index is a piano-roll display toggle with CMD_ID = 0. The reasoning was sound
and the conclusion was still wrong: CAL is a note-level API the index does not
describe as one. Its menu entry is filed under 处理 as a macro runner, and
nothing in the index hints that the language behind it writes Note.Key. It was
found by reading the 37 shipped .CAL scripts, not by mining commands.
Track rename, mute and arm were on this list for the same structural reason — looked for in the index, not found there, declared absent. Rename genuinely has no command; CAL provides it anyway. Mute and arm turned out to have commands, and the search that missed them was reading the wrong column of the index.
So the honest summary, after measuring both layers: transformation of existing notes is available through the edit dialogs (nine operations, five verified end to end); creation, deletion and reading through CAL (four operations, four verified); and track rename, mute, routing, solo and arm through CAL builtins and selection-based menu commands. What the paywall actually holds, as far as this investigation reached, is plugin insertion — and even that has a non-scripting alternative in the control-surface COM interface.
Routes to CakeScript that were tried and do not work
Recorded so nobody spends the time again. Each was tested on 2026.10, and the negative result is the finding:
Command-line switches. The binary contains the literal strings
/cakeScriptand/script(one occurrence each), which looked like an unattended entry point. They are not. Five invocation forms were tried against the real script engine —/cakeScript <file>,/script <file>,-script <file>,/run <file>, and a bare<file>argument — each in a fresh process with a 15 s window, and the script was written to make a file as proof of execution (both via Luaio.openandcakeapp.filesystem, so either path would count). No form executed the script. SONAR starts to its normal frame and ignores the argument, so those strings belong to something other than argument parsing.File association.
.luahas noassoc/ftypeentry on this machine, so there is no shell verb to invoke and double-clicking a script is not wired up.Driving the dialog controls with
WM_SETTEXT. This looked promising and half worked. UIA cannot see the dialog fromRootElement(it is a child of the SONAR frame, not a desktop top-level), but it can be bound — enumerate the process's#32770windows, thenAutomationElement.FromHandle. That yields the real HWND of every control:331254|Edit(the 数量 field),2624150|Button|确定,7210576|Button|取消, and723106|CC:SpinCtrl. The catch is what those controls are: SONAR's number fields areCC:SpinCtrl, a custom control, and theEditbeside it is a shadow.WM_SETTEXT "7"on that Edit reads straight back as'7'— and a freshGetWindowTexton the same handle returns empty again, because the value the dialog uses lives in the SpinCtrl, not in the edit's text buffer. This is the same shape as the track strips: the control accepts the write and ignores it.WM_SETTEXTis therefore not a way in for these fields.XCDCakeServices. Appears once as a string in the binary, so the helper process the original plan went looking for is named there — but no process or window of that name is ever created, matching the earlier finding that the XCD/LLM surface is not running on this build.
What remains as the working path is the one already proven: post the menu
command, then drive the resulting MFC dialog with an accessibility runtime that
can set values on real controls — which is what cw_quantize_dialog and
cw_note_edit_help describe, and what computer-use does when it calls
setValue on element 25 of the 移调 dialog.
Working around the missing T1
MIDI for changes.
cw_midi_*sends are verified end to end, and the receive side is enabled and confirmed through TTSSEQ.INI. This is the path that actually alters a project on this build.Accessibility for reads. With a project open,
cw_track_controlsgives the exact element naming for volume, pan, routing and the mute/solo/arm flags. Reading is accurate; writing is a no-op (see the section above).Menu commands for navigation.
cw_run_commandopens views, inserts tracks and drives transport once a document exists.A build that restores the Assistant panel brings T1 back with no changes here. It was present in 32.08.0.040.
How this compares to other DAW/tool MCP surfaces
Measured 2026-10-15 against two mature references available on this machine: the
ACE Studio MCP (63 tools, enumerated live from ace-mcp-server.exe) and the
After Effects adapter (36 tools). The point of the comparison was to find
out whether this one is missing something a user would notice, rather than
assuming its coverage was adequate.
The honest summary
Coverage is the thinnest of the three; the honesty layer is the strongest.
That is not a consolation prize. This host hides almost everything — the broad scripting API is paywalled, the track strips are drawn rather than exposed, and most commands change state with no window to diff. The other two hosts expose real APIs, so their tools can simply return values. Here, a tool that cannot confirm its own effect is the default case, which is why so much of this adapter is about stating what could and could not be established.
What the comparison found missing, and what was done about it
Gap | Reference | Verdict |
Undo / redo / history | ACE | Closed — |
Clip CRUD | ACE | Partial — split and merge exist as dialogs ( |
Plugin insert → params → presets → editor UI | ACE (the richest surface of the three) | Blocked — no insertion path exists; |
Automation envelopes, sends/buses | ACE | Blocked — drawn, not writable, and CAL has no envelope builtin. |
Async job handles | ACE | Open — this adapter blocks and pushes budget management onto the caller ( |
Tick/time/bar conversion | ACE | Open — pure arithmetic, no host involvement needed. |
One docs index | ACE | Partial — this adapter has 12 measured help tools; discoverability is weaker than one index, correctness is stronger. |
Where this adapter is ahead
cw_run_command_classifiedreturnsconfirmed/did-nothing/unconfirmedwith the evidence class behind it. Neither reference does this — both report success from "the call returned", which on a drawn UI is a guess.cw_no_effect_causes— the three-cause taxonomy (drawn-not-exposed, precondition-missing, gated-by-licence) came from being wrong twice, and it is the cheapest guard against concluding "broken" when it is a toggle.cw_verify_commands— command ids change between builds (32.08 vs 32.10), so the ids are read from the live menu and can be re-measured.The
confirm: '<command-name>'guard — a destructive tool refuses a bare boolean, so the caller must name what it destroys.
Two design ideas worth copying from ACE
Pair read/edit per domain rather than a flat tool list. The split encodes a safety boundary and makes the surface discoverable one level down.
Return a job handle for slow work. This adapter already knows which operations are slow — it budgets them — and used to make the caller wait.
cw_job/cw_jobs/cw_job_abandon/cw_job_clearnow exist for it.
What is deliberately not attempted
Plugin insertion and automation envelopes. Each was investigated and the negative result is recorded, so nobody spends the time again.
Plugin insertion in particular now has a closed route rather than an
untried one. The control-surface COM interface was built, registered, loaded and
driven end to end — and the host object SONAR passes to Connect implements
IUnknown and nothing else, so SetTargetParam has no reachable vtable slot.
Details and the raw QueryInterface results are in
The control-surface bridge. The remaining non-scripting route is authoring a
.cwx track template, the same binary container as .cwp.
Tools
Tool | Transport | What it does |
| — | Health check across all five transports with verdicts and remedies — run first after a SONAR upgrade |
| — | Host, version, transports, real-time MIDI state, recommended path |
| — | Whether the open project has unsaved changes |
| T2 | newProject / open / save / saveAs / close / exportAudio / importMidi / revert |
| — | How to drive the file dialog, and why it IS scriptable |
| T2 | play / stop / record / loop / metronome / tempo & meter views |
| — | How to set and read tempo and time signature |
| T2 | Selection, now-time movement, and markers |
| T2 | quantize / transpose / split / merge / gain / normalize / reverse / fade |
| — | The editing layer, its preconditions and its dialogs |
| — | How notes are edited: the dialog route, the export check, and the two mistakes behind it |
| — | The exact dialog writes for a given quantize, and how to prove it landed |
| — | Judge a quantize from two tick lists — pure arithmetic, no SONAR needed |
| — | The 量化 dialog as measured: fields, element kinds, traps |
| — | The CAL language: fields, operators, builtins, the run procedure, and the traps |
| — | The exact plan for a CAL run — source, dialog write, verification. Pure |
| T2 | Write a CAL program, post 0x806A, and report the dialog steps. No licence needed — notes and track properties |
| — | Delete the CAL scripts |
| T2 | Rewind the last operation. Silent — it cannot be confirmed from the screen |
| T2 | Reapply the last undone operation |
| T2 | Open the undo stack (0x8044) and report how to read and rewind it |
| — | How undo works here, and the trap in verifying a rewind |
| — | Convert between ticks, bar:beat:tick and seconds. Pure arithmetic |
| — | The time units, the 1-based/0-based trap, and what conversions cannot do |
| socket | Opt-in ( |
| socket | Opt-in. The plugin's log, counters, and the interface sweep that established what the host object is |
| socket | Opt-in. The parameter vocabulary the plugin accepts, with each kind |
| socket | Opt-in. Set a mixer parameter. Refuses on this build — the host object has no |
| socket | Opt-in. MIDI that SONAR forwarded to the surface, decoded — needs the input port assigned |
| — | Opt-in. How the bridge works, how SONAR discovers a surface, and what it cannot do |
| — | Read one background job: state, elapsed, progress trail, result or error |
| — | List recent jobs, newest first, without payloads |
| — | Discard a job's result. Does not stop work already posted to SONAR |
| — | Forget finished jobs; running ones are kept |
| — | Why background jobs exist, and the one thing the API cannot do |
| — | Why a command can report nothing happened — three causes |
| — | The marker dialog (writable), its commands, and the readback path |
| — | Which commands are confirmed, which are unconfirmed and why |
| T2 | Run a command and report what could and could not be established |
| — | Which commands |
| — | Re-measure command ids against the running SONAR after an update |
| — | How to drive the UI, what is unreachable, and how to recover a lockup |
| T2 |
|
| T2 | Run a menu command by id; reports whether the window list changed |
| — | Modal panels currently blocking menu commands |
| — | Close those panels |
| T4 | Live MIDI ports, which is selected, whether SONAR is tuned to it |
| T4 | Set pan (CC10) / volume (CC7) on a channel |
| T4 | Pan and volume for several channels in one round trip |
| — | What a live mixer message can affect, and what is measurable |
| file | Compose notes and CCs into a format-1 .mid, with mixer values baked in |
| file | Parse a .mid — names, channels, notes, CC7/CC10 with pan spelled out |
| — | Registered plugin counts across all three sources, categories, missing files |
| — | Search 1208 plugins by name, with format (VST3/VST2/DX), kind and file presence |
| — | What plugin discovery can do and why insertion cannot be driven |
| — | Instruments grouped by songwriting role |
| T2 | Insert a track (midi / audio / bus / folder / aux) |
| T2 | Insert the tracks a simple arrangement needs |
| — | Every 插入 command with its id |
| — | Measure every capability, grouped by transport |
| — | Per-operation latency profile |
| — | SONAR's enabled MIDI ports, read from TTSSEQ.INI (verifies the receive side) |
| — | Enable a port by writing TTSSEQ.INI — no UI needed, idempotent |
| T4 | Every MIDI device Windows reports |
| T4 | Play one note (pitch / velocity / duration / channel) |
| T4 | Play several notes at once, released together |
| T4 | Control change — 7 volume, 10 pan |
| T4 | Batch of raw |
| T4 | All-notes-off and reset on every channel |
| — | Plan for reading project state via computer-use, per topic |
| — | Cache an observation from a computer-use agent |
| — | Read the observation cache, with staleness |
| — | Which SONAR surface carries which project fact |
| T1 | All tracks in the active project |
| T1 | One track's volume/pan/mute/solo/arm/sends/clips |
| T1 | Volume (0.0–4.0) |
| T1 | Pan (-1.0…+1.0) |
| T5 | Mute / unmute, by clicking the strip's 手动静音 button |
| T5 | Solo / unsolo, by clicking 独奏 |
| T5 | Arm / unarm for record, by clicking 录制 |
| T5 | Read any strip control as SONAR shows it (音量, 声像, 输入, 输出, …) |
| T5 | Rename, by editing the strip's name field (double-click + clipboard paste — handles Chinese) |
| — | The .cwx track templates on disk, with categories (184 on this machine) |
| T5 | Insert a template — instrument + FX chain + routing — and confirm the new track by name |
| T1 | Clips on a track |
| T1 | Notes from a clip (pitch/velocity/time/duration) |
| T1 | play / stop / record / pause |
| T1 | Move the now-time (Bars|Beats) |
The command index
SONAR keeps a SQLite database of every command, view, setting and help topic at
%APPDATA%\Cakewalk\Sonar\cwsearch.dat. It powers the command palette, and
cw_list_commands source="index" reads it: 1315 rows on this machine, each with
a label, the menu path it lives under (e.g. 处理(P)->运行 CakeScript 程序), and
a CMD_ID.
CMD_ID is not a WM_COMMAND id. Posting one is silently dropped. The
index is useful for finding what a build offers and for the human-readable
menu path — not for dispatching. Only ids read from the live menu via
GetMenuItemID are postable, and even then only for main-frame commands.
Which commands respond
Measured on 32.10.0.021; cw_verify_commands re-checks on demand and
cw_command_support reports the split for the current document state.
Always work — app-level commands the main frame owns:
id | command | effect |
| 编辑 > 参数设置 | opens Preferences |
| 帮助 > 关于 Sonar | opens About |
| Cakewalk 助理 | toggles the Assistant / palette panel |
| 工具 > 视频引擎设置 | opens the video engine panel |
| 重置 MIDI 和音频 | opens a confirmation dialog |
| 文件 > 新建 | opens the 新建工程文件 dialog |
| 文件 > 打开 | opens the file dialog |
Additional ones that respond once a project is open — verified against a live 16-track project:
id | command | observed |
| 视图 > 音轨视图 | opens the track view |
| 插入 > MIDI 轨 | inserts a MIDI track (title gains |
| 插入 > 音频轨 | inserts an audio track |
| 视图 > AI Assist | responds (membership panel on a free licence) |
| 处理 > 运行 CakeScript 程序 | responds |
| 视图 > CakeScript View | responds |
| 视图 > 事件列表 / 钢琴卷帘 / 控制台 | open the view |
| 录制 / 播放停止 / 停止 | transport |
| 静音 / 独奏 全部音轨 | track state |
A caution about the verification method. cw_verify_commands diffs the
window list, which cannot see a command that changes state without opening a
window. Transport, mute and solo all appear as unchanged even when they
worked. Read the blind-spot list in lib/commands.js before concluding a
command is dead.
Benchmarks
cw_benchmark runs every capability against the live SONAR and reports each
result with the method used to confirm it, because a PASS from "the window
title changed" and a PASS from "the element value changed" are not equally
strong. cw_latency profiles the individual operations.
Current state on 32.10.0.021 with a project open — 16 of 17 pass; the one failure is the expected absence of the CakeScript transport:
read/static pass 3 plugin inventory, plugin search, MIDI port config
read/win32 pass 4 bridge status, live menu tree, document detect, overlays
write/menu pass 4 assistant toggle, view command, insert command, transport
write/midi pass 4 port resolve, one note, one CC, a batch
read/config pass 1 SONAR tuned to the cable (from TTSSEQ.INI)
transport/T1 fail 1 no XCD*/LLM* window — expected on this buildLatency, median over repeated runs:
Operation | Median |
MIDI: send one message | 18 ms |
Plugins: inventory (warm) | 30 ms |
Bridge: menu tree | 283 ms |
Bridge: status | 362 ms |
Menu: post a command | 2404 ms |
Two notes on the numbers. The menu path is slow by design: cw_run_command
closes modal overlays first and then waits ~1.2 s to observe whether anything
opened, which is what makes none-observed meaningful. And the plugin inventory
was 28 s until the read was changed from reg query /s (which recurses into
all 946 subkeys for their values) to the top-level query (which returns the
subkey names only) — 10 415 ms → 74 ms. CLSIDs are now fetched per-plugin,
on demand, at ~10 ms each.
Project layout
<package>\
├── package.json
├── bin\cakewalk-mcp.js # entry point (starts the shims)
├── bridge\
│ ├── agent.js # PowerShell user32 bridge: status, menu, runmenu, overlays, probe
│ ├── midi.js # PowerShell winmm shim: devices, open, send, panic
│ └── loopback.js # winmm MIDI input capture (for verifying a cable nothing holds)
├── lib\
│ ├── sonar.js # host discovery (Sonar.exe, scripts folder)
│ ├── dispatch.js # transport probing + the "what to use instead" errors
│ ├── menu.js # command index + live menu + WM_COMMAND dispatch
│ ├── commands.js # measured command support + the UI recipe
│ ├── track-ui.js # the track-control contract, read/write split
│ ├── transport.js # transport, tempo, meter, loop — posture over confirmation
│ ├── navigate.js # selection, now-time, markers + the writable-dialog pattern
│ ├── edit.js # editing/processing + the precondition that makes them work
│ ├── note-edit.js # note-level editing: the quantize dialog and the export proof
│ ├── project.js # document lifecycle + the destructive-command guard
│ ├── verify.js # evidence classes: what this process can and cannot confirm
│ ├── mixer.js # volume/pan via CC — the path that works
│ ├── midi-file.js # read/write standard MIDI files (the data level)
│ ├── live.js # real-time MIDI transport (port picking + musical ops)
│ ├── midi-config.js # read/write TTSSEQ.INI — SONAR's enabled MIDI ports
│ ├── plugins.js # plugin detection (registry + menu layout + disk)
│ ├── tracks.js # insert tracks (menu commands + verification)
│ ├── project-state.js # probe plans, operation recipes, observation cache
│ ├── benchmark.js # capability measurement + latency profile
│ ├── convert.js # ticks <-> bar:beat:tick <-> seconds, and the note-value table
│ ├── surface.js # the control-surface bridge client (loopback TCP, JSON lines)
│ ├── jobs.js # background job handles for the slow operations
│ ├── run.js # CakeScript templates over T1
│ ├── cake_templates.js # parameterised CakeScript (Lua) programs
│ └── server.js # MCP tool definitions (89 tools; 97 with CAKEWALK_MCP_SURFACE=1)
├── native\surface\ # the control-surface plugin (C, mingw)
│ ├── cw_surface.c # IControlSurface3 + worker thread + loopback bridge + diagnostics
│ ├── build.cmd # mingw gcc build (no MSVC on this machine)
│ ├── install.ps1 # regsvr32 / folder-copy install, and -Unregister
│ ├── loadprobe2.c # off-line COM contract test: 5 IIDs, slots 10/14/26/43
│ ├── ANALYSIS.md # the full disassembly record: CCtrlSurface's 13 slots,
│ │ # the 3 real IIDs, why SetTargetParam is host->surface
│ └── build\cw_surface.dll # the built plugin
├── node_modules\ # @modelcontextprotocol/sdk + zod + ...
├── test\ # node:test, no new dependencies
│ ├── helpers.mjs # fixtures + shim teardown
│ ├── pure.test.mjs # 25 maths, encodings, coordinate conversion
│ ├── midi-file.test.mjs # 17 .mid write/read round trips
│ ├── parsers.test.mjs # 24 registry, INI, menu layout, document title
│ ├── navigate.test.mjs # 21 selection/marker records and their evidence classes
│ ├── edit.test.mjs # 26 the editing layer and the false-positive fixes
│ ├── note-edit.test.mjs # 50 quantize arithmetic vs a real measured run
│ ├── cal-script.test.mjs # CAL generators, the structural rule, and the write path
│ ├── history.test.mjs # undo/redo records and the rewind-verification trap
│ ├── convert.test.mjs # tick/bar/second conversions and their boundaries
│ ├── surface.test.mjs # the bridge protocol: framing, encoding, error
│ │ # classification, and MIDI-in decoding
│ ├── jobs.test.mjs # job lifecycle, late results, bounded progress trail
│ ├── capability.test.mjs # 23 the guards and the honest-reporting layers [--full]
│ ├── integration.test.mjs # 24 MCP protocol, tool schemas, bridge liveness [--full]
│ └── blackbox.test.mjs # 25 the whole adapter through MCP only, no internal imports [--full]
├── run-tests.mjs # one command, one number; --full for the slow tier
├── mix.mjs # compose the song with its mix baked in
├── song.mjs # perform it over the live MIDI cable
└── README.mdTests
Two tiers, no new dependencies (node:test).
node run-tests.mjs # fast tier — 0.6s, no processes
node run-tests.mjs --full # everything — several minutesThe counts are not written here on purpose. node run-tests.mjs prints a
per-suite block at the end of every run, and that block is the only source:
per-suite (runner counts):
edit.test.mjs 25
midi-file.test.mjs 17
...An earlier version of this file carried the numbers by hand, and an adversarial
audit caught it three separate times — the headline, the per-suite table and
the directory tree each disagreed with the others and with reality, because they
were written at different moments while the suite was still growing. The audit
also showed the "rule" I invented to reconcile them was itself wrong: I claimed
per-suite rows used top-level test() counts, but the gap between that and the
runner's figure varies per file (it depends on how many describe blocks a suite
has), so the rows could not be summed to the total. Both problems have one fix —
stop transcribing, start copying from the run.
The tier split exists because the full run was 7m35s, and almost all of it was waiting on processes. A suite that takes seven minutes to answer "did that edit break anything" stops being run. The tier is an explicit file list, not a timing heuristic — and the runner now refuses to start if a listed suite no longer exists, because renaming a slow suite used to promote it silently into the fast tier.
That split also exposed something the numbers had been hiding. Three suites
called themselves white-box and took 25s, 28s and 46s, because each reached
the PowerShell bridge from inside a unit test. Once the pure parts were extracted
(classifyTitle, classifyEditResult, describeNavigateResult) they run in
~200 ms each — the edit suite went from 46,316 ms to 83 ms. The
behaviour did not change; only which layer owned each assertion.
Reproduce it, per suite, in a shell:
for f in pure midi-file parsers navigate edit note-edit; do
t0=$(date +%s%N); node --test test/$f.test.mjs >/dev/null 2>&1; t1=$(date +%s%N)
printf "%-12s %6d ms\n" "$f" $(( (t1-t0)/1000000 ))
done
# pure 200 · midi-file 229 · parsers 277 · navigate 199 · edit 199 · note-edit 210An adversarial audit flagged the original claim as unverifiable — there was no artifact anywhere in the repo backing "46,316 ms", and no git history to check it against. That is a fair criticism of how the number was recorded, and the command above is the fix: the measurement is now a one-liner anyone can re-run rather than a figure copied out of a session. The old baseline cannot be re-measured (the code that was slow no longer exists in that form), so it is quoted as what it was: a single observation, not a standing guarantee.
Fast tier — the logic, importing the modules
Suite | Tests | What it protects |
pure | 25 | arithmetic with a plausible-but-wrong alternative — a 0-based channel, a 64-centred pan, a bit-shift off-by-one |
midi-file | 17 | the writer and reader are independent implementations of one spec, so a bad byte surfaces as a wrong note, channel or position |
parsers | 24 | external formats that cannot be regenerated — a |
navigate | 21 | selection/marker records and their evidence classes |
edit | 26 | the editing layer, the selection-honesty rule, and the false-positive fixes in |
note-edit | 50 | quantize arithmetic pinned against a real measured run, the half-strength outlier, note-count changes, and the record of how that run was misread twice |
Full tier — the suites that leave this process
Suite | Tests | What it protects |
capability | 23 | that a destructive command refuses, and that "nothing errored" is never reported as success |
integration | 24 | the MCP surface, the documented failure modes, and bridge liveness |
blackbox | 25 | the adapter through MCP only, importing no internal module; and that no tool hangs |
Black-box — the adapter, through MCP only
blackbox.test.mjs (count in the runner's per-suite block, not here) imports
no internal module. It spawns
bin/cakewalk-mcp.js as a client would, speaks JSON-RPC over stdio, and judges
only what comes back on the wire. It holds the adapter to five rules:
every tool is callable and answers within a bounded time
no tool raises an unhandled error at the protocol level
an error is a well-formed result with a readable message, never a timeout
a missing precondition is reported as such, with what to do about it
nothing that discards work happens without an explicit confirmation
This layer caught a defect the white-box suite could not. cw_verify_commands
surveyed 21 commands at roughly 2.5 s each with no cap, so a bare call left a
client waiting a minute. Every unit was fine; the composition was not. It now
takes a budgetMs and returns a partial result naming what it skipped. It is
also the only layer that can catch a wiring mistake — a module that works
perfectly but is never registered as a tool is invisible from inside.
Run everything with node run-tests.mjs, one suite with
node --test test/edit.test.mjs.
Twenty-seven real bugs came out of writing and auditing these, which is the argument for the suite. Eighteen came from auditing rather than from writing:
10–14 from the first adversarial pass (five lenses, each finding re-checked by a separate agent told to falsify it)
15–18 from attacking those fixes
19–24 from attacking the fixes again — the second pass found the most, because that is where the fixes had never been independently examined
25–27 from a third pass aimed at the crash paths and at the measurement habits themselves: the two findings that matter most there are that four tests were green only because they skipped, and that a repair made a test pass by making it unable to fail — caught only by mutating it
Pan was asymmetric.
Math.round(64 + n * 63)put hard-left at 1 instead of 0 (MIDI's halves are 64 and 63 steps, so one multiplier cannot be symmetric) and madedescribePan(0)read102% left. Fixed by scaling each side by its own span.CC.panvsCC.PAN. Three modules, two spellings, and an undefined controller masks to CC0 — so a cross-module call silently wrote a bank-select instead of a pan. Both spellings now resolve, and a non-numeric controller throws.Unterminated notes were dropped. A note-on with no note-off (a trimmed or truncated file) vanished entirely. They are now kept, flagged, and reported.
The test framework itself.
documentState()starts the PowerShell bridge, which is long-lived by design; four orphaned processes from one run slowed the next suite into a 60-second timeout. AddedshutdownShims().riskheld prose, disabling the guard. Three destructive commands hadrisk: 'destructive — the source events are replaced', and the guard compares=== 'destructive'. The confirmation check was silently off for all three. The test that caught it pins the canonical value and runs every destructive command to confirm each actually refuses — checking the field alone would not have.cw_editreported a dialog that had not opened.outcomefell back to the command's description when no window appeared, so a failed run read like a successful one. Measured:newWindowswas empty whileoutcomeclaimed a dialog. Nowoutcomecarries only what was seen andexpectedthe description.A stale modal made a working command look broken. With four leftover modal windows on screen,
cw_edit quantizereportedno-window-change; on a clean state the same call opened its dialog.likelySwallowednow says so and namescw_list_overlays/cw_close_overlays.preconditionSatisfiedclaimed an outcome nothing could observe. It read'selected all first', asserted unconditionally from theselectFirstflag. Select-all is a drawn change — no window, no element, just a highlighted ruler — so a modal that swallowed the menu command (which #7 shows happens) left the field claiming a selection it never made, sitting next to alikelySwallowed: truesaying the command had vanished. NowselectionRequestedreports the attempt,selectionConfirmedis alwaysfalse, andselectionEvidencesays a screenshot is what would settle it. This one is the same defect as #6 in a different field, which is why the fix came with a test asserting the old name is absent from the result.The measured "50%" row was described more confidently than it holds. The prose said 50% strength "moves each note half way to the grid". Recomputing
predictQuantizeagainst the recorded run: seven of eight notes agree to within a tick of rounding, but one (2461 → 2432) is 59 ticks off the linear model. One sample cannot say why, so the claim is now stated as a table with the outlier named, andpredictionConfidenceisexactonly at 100% strength.
The next five came out of an adversarial audit — five independent lenses, every finding re-checked by a separate agent whose instruction was to falsify it. They are listed separately because the failure mode is different: these were not reasoning errors but reporting errors, each of which would have led a reader to the wrong action.
judgeQuantizecould not tell "nothing moved" from "the commit failed". Withstrength: 0the prediction is also "no movement", sobefore == aftermatched the prediction and produced the reassuring "partially moved — this is a fractional strength result, not a failure". A quantize that never applied read exactly like a legitimate no-op. It also explained a changed note count as "the dialog may have applied different settings than were written" — sending a user back to the dialog instead of looking for the missing note. The verdict now branches on the count first, then on whether anything moved at all.describeNavigateResulthad the same false-positive shape as #6, unfixed.confirm === 'dialog'produced "A dialog should be open" while never consultingnewWindows— the evidence was in hand and unused. Worse,nexthad two branches for three evidence classes, soconfirm: 'elements'(onlyshowMarkerView) fell through to the drawn-change wording and emitted a sentence arguing with itself: "drawn, not exposed" followed by "is a TABLE — readable". Each class now has its own branch, and a test walks the real tables so a fourth class cannot be added without wording.Three zero-argument tools hung past a client's patience. Found when the black-box walk timed out at 60 s:
cw_add_song_tracks(six inserts at 2–4 s each),cw_benchmarkandcw_latency. The audit's first guess — the plugin inventory — was only part of it; profiling showed four write cases posting a command and then waiting for the UI account for ~55 s of the benchmark's 70 s. All three now take a budget or default to the cheap stages, and each says what it skipped.cw_latencyalso orders its stages cheapest-first, because the budget is consumed in order and the expensive stages were starving the 22 ms MIDI measurement.eventswas unreachable through MCP, so a guard could never fire.cw_write_midi_filedocumented a channel-mismatch warning, but its zod schema only exposednotes— and zod strips unknown keys, so a client sendingeventshad it silently dropped. The test "the writer warns when a track mixes channels" asserted only!isErrorand could not fail.eventsis now in the schema, and the test drives the path that can actually warn.The marker-removal commands had empty records.
removeProjectStart/End/Rangecarried an id and a name and nothing else — noeffect, noconfirm, noverified— sitting in a table of measured commands. They now state what they do, how they would be confirmed, that they are destructive, and that they were never probed.
Four more came from attacking the fixes themselves, which is the stage that found the most in the end:
judgeQuantizereported a SUCCESS as a suspected failure. "Nothing moved" has reasons that are not failure — the source notes may simply already be on the grid. The rewritten verdict only recognised a zero strength, so quantizing an already-quantized file produced "the commit most likely did not apply". The input decides this, so it is decided:beforeOnGridis computed and the case is labelled a success. (It also explains why quantizing a tidy file proves nothing about the round trip.)A boolean was accepted as a strength.
Number(true)is1andNumber(null)is0, so a bare coercion treatedstrength: trueas a valid 1% and reported no warning. Only a number or a numeric string is a strength now; anything else falls back to 100 and says so.whatToLookvanished on both dialog branches. A command that opens a dialog and names what to look at lost the second half — at exactly the two moments a caller needs it ("a dialog should be open", "no dialog appeared"). Every branch now carries it, and a test sweeps all commands in both window states for unfilled placeholders and doubled punctuation.Three tests that claimed to guard something and did not. The
cw_editwindow-list regression survived two rewrites of its test before the third caught it — see Mutation-test any test that claims to guard something. The one lesson worth repeating here: a test asserting that two values from the same function agree cannot detect an error they agree about.
The second verification pass attacked the fixes above and found six more. Every one is the same species — the record claiming more than was established:
Cost figures I invented. "Each insert costs roughly 2-4s, so six tracks need about 20s" — measured, one insert takes ~19s, so six need ~2 minutes. The same error appeared three times:
cw_latencysaid a menu post costs "~4s" (measured 11s), andcw_verify_commandssaid "~2.5s per command" (measured ~15s). The last one had consequences: the budget default was set from that estimate, so 12s bought one probe and 45s bought three, neither of which is a survey. The comment now carries the measurement and its date.A test that substituted its own arguments. The black-box "no tool hangs" check passed
budgetMs: 3000tocw_verify_commands— a value that existed nowhere in the product. The real default was 45s against a 58.7s workload, so a bare call in the wild blew the client timeout while the test stayed green. It now calls every tool with no arguments, because the defaults are the contract, and tools that are slow by nature get an explicit ceiling instead of an exemption.A fabricated witness. The three
removeProjectStart/End/Rangecommands were marked "not probed" and then givenconfirm: 'screenshot'plus awhatToLooksentence describing what probing would have found. Inventing a plausible witness for an unmeasured command is worse than admitting the gap, because it reads as knowledge. They now carryconfirm: 'unprobed', and the branch that handles it says NOT PROBED.A count change hid a success.
judgeQuantizefired its count-changed branch before any position comparison, so a legitimate count change (SONAR merges same-pitch overlaps on export) reported "not a quantize result" while every surviving note sat exactly on the grid. Both facts are now reported.Clamping was silent.
strength: 150became 100 andstrength: -10became 0, reported as valid with no warning.strengthAdjustedand a message now accompany any value that was not used as given.A whole table was exempt from the rule. The check "every command declares how it can be confirmed" skipped
ARRANGER_COMMANDSwholesale, so a command added there with an empty record would pass. The rule is now per-command:unprobedis a legitimate declaration, silence is not.
A third pass turned on the adapter's own crash path and on the measurement habits used to check it. Three findings, all the same shape — a conclusion that rested on an unverified assumption:
A crash on the most common state, hidden by tests that skipped themselves.
capabilities()returned early when SONAR was not running and lefttransportsan empty object, whilerunCommand()andcakeScriptBlocker()dereferencedtransports[...].availableunconditionally. Starting with SONAR closed — the single most likely way a user meets this adapter — producedCannot read properties of undefined (reading 'available')instead of the documentedCAKESCRIPT_UNAVAILABLEwith its alternatives. Four tests covered this path and all four opened withif (!r.result.isError) return;, so with SONAR running they asserted nothing. They were green because they never ran, not because the code was right. Fixed by populating every transport withavailable: falseand a reason; guarded by a test that asserts the invariant regardless of what SONAR is doing (mutation-checked: bug in → red).A verification that used the wrong command id, and nearly produced a wrong "bug". While checking why an edit test failed, I posted
0x8099to open the quantize dialog and it "worked". It is not 处理 > 量化. The real id is0x8061(lib/edit.jshad it right all along).0x8099happens to open a different#32770, and the resemblance was enough to build a whole chain of wrong conclusions on top of a control experiment that was never valid. The lesson: when a probe succeeds unexpectedly, confirm it is the same operation before using it as a control — a screenshot of the dialog, not just the window class.A test weakened to make it pass, caught by mutating it. The
cw_editend-to-end test asserts a dialog is on screen after a quantize. With an empty project open (tracks, no notes) quantize is legitimately silent, and the test failed on correct code — its third non-bug failure. The first repair relaxed the assertion to "the report should be honest about seeing nothing", which passed even with the plumbing regression injected: the two cases are indistinguishable. Fixed twice over — the regression now has a deterministic guard where it can be told apart (requireWindowList()raisingEDIT_WIRING_FAULTwhen the window list did not survivewithSelection, covered by three process-free tests), and the end-to-end branch ist.todo()rather than a green assertion it cannot earn. A silent pass for an unverifiable state is the same trap as finding 18.
Two conventions the tests pin that are not obvious from the code: parseInventoryKeyNames()
returns an array with a scannedOnly property attached, so deepEqual(result, [])
fails on it; and the pan round trip is asymmetric by one percent near the half
positions because of the 64/63 split — a fact about MIDI, not a bug.
A third is a habit rather than a convention: the note-edit suite runs its
arithmetic against ticks recorded from a real SONAR session, so a change to
the model of how quantize behaves has to argue with an observation rather than
with a plausible-looking formula.
Mutation-test any test that claims to guard something
Writing a regression test is not evidence that it works. The cw_edit window-list
bug is the cautionary case: it was "fixed", a test was written for it, and an audit
later showed the test was vacuous. Two rewrites failed too, and only the third
worked — and the third was believed only because it was checked by injecting the
bug back:
cp lib/edit.js /tmp/bak.js
sed -i 's/const { out: ran } = await withSelection(/const ran = await withSelection(/' lib/edit.js
node --test test/integration.test.mjs # MUST fail
cp /tmp/bak.js lib/edit.js
node --test test/integration.test.mjs # MUST passWhat the three attempts taught, in order:
A test built on the code's own output is a tautology. The first version asserted
outcomematchednewWindows— butoutcomeis computed fromnewWindows, and it has exactly two values. It could not fail.A consistency assertion cannot detect a consistent error. The second version asserted the two agreed. Injecting the bug, they agreed perfectly: both were empty. 24/24 green against broken code.
Assert against a fact from outside the code under test. The third version asks the overlay list whether a dialog is actually on screen. That is not derived from the thing being tested, so it can disagree with it.
Two smaller lessons came from getting even that right. The assertion must match on
the window class (#32770), not the title — SONAR's captions are GBK and
arrive as ��������, so a /量化/ match fails while the dialog sits plainly open.
And a test that drives the live app must reset the screen first and clear up
after, because a modal left by an earlier test swallows menu commands and makes
the next test fail for an inherited reason; integration.test.mjs and
blackbox.test.mjs both do this in test.after.
Registering with ZCode
Already done in C:\Users\molisaa\.zcode\cli\config.json:
"cakewalk": {
"type": "stdio",
"command": "<package>/runtime/node.exe",
"args": ["<package>/bin/cakewalk-mcp.js"],
"env": {}
}Available Tools
89 toolscw_add_song_tracksA
Add the tracks a simple arrangement needs: drums, bass, keys, guitar, strings, synth — in that order, one MIDI track each. Pass roles to add only some. Each track gets SONAR's default instrument; loading a specific plugin is a separate UI step. Cost, measured: one insert takes ~19s (a menu post plus a verification wait), so the full six-track skeleton needs roughly two minutes. Pass roles and a matching budgetMs together rather than asking for all six.
Inputs: roles, budgetMs.
cw_add_trackA
Add a track to the open project via SONAR's 插入 menu. kind: midi | audio | bus | folder | aux. Requires a project to be open — the 插入 menu does not exist without one. Reports whether the project title gained its modified marker, which is the only insert confirmation available without a computer-use runtime.
Inputs: kind, name.
cw_apply_mixB
Set pan and volume for several channels in one round trip. mix is [{ channel, pan?, volume? }] with pan in -1..1 and volume in 0..1.
Inputs: mix (required).
cw_benchmarkA
Measure what this adapter can actually do against the running SONAR, and how fast: every capability grouped by transport, with the confirmation method for each result. Use it after a SONAR update to re-establish the boundaries. Measured: a full sweep takes 70s+, and not only because of the plugin scan — the write cases post a command and then wait for the UI to settle, and four of them account for ~55s of it. So the default answers from the read half (a few seconds) and every expensive stage is opt-in and named in skipped. Pass full: true for everything. The write stages can start playback and send MIDI to the selected destination; they do not insert tracks or buses.
Inputs: full, includeWrites, includeMidiSend, includePluginScan.
cw_cal_cleanupA
Delete the CAL script files cw_cal_run wrote, and their .bak copies. Running CAL leaves a file in the real CAL folder alongside the 37 shipped scripts, so this exists to put the folder back. Only names matching the generated MCP-.CAL pattern are removeable — this will not touch a script you wrote by hand.
Inputs: program.
cw_cal_helpA
CAL is SONAR's legacy macro language and it is NOT behind the membership paywall, unlike CakeScript. It reads and writes note data directly, so on a free licence it is the only way to CREATE, DELETE or READ notes — the dialogs can only transform existing ones. This returns the language reference (fields, operators, builtins), the run procedure, the generated programs, and the traps that cost real time to find.
Inputs: no named parameters.
cw_cal_planA
The exact plan for a CAL run: the script source, the dialog field to write, and how to prove the result from data. Pure — it writes no file and posts no command, so it is safe to call speculatively. Use cw_cal_run to actually do it.
Inputs: program (required), mute, name, port, +8 more.
cw_cal_runA
Write a CAL program into the folder SONAR reads, select everything, and open 处理 > 运行 CAL 程序 (0x806A). CAL needs no licence, so this is how notes get CREATED, DELETED or READ on a free build — the edit dialogs cover only transformation. This process cannot click, so it stops at the open dialog and reports the exact steps an accessibility runtime must take. The script ends with a modal pause that has to be dismissed, and CAL reports only a count — prove the effect by exporting and parsing.
Inputs: program (required), mute, name, port, +12 more.
cw_check_quantizeA
Judge a quantize from actual data instead of guessing. Give it the note ticks before the edit and the ticks the exported file now holds, and it computes what the settings should have produced and says whether they match and whether the notes landed on the grid. Pass before and after as tick arrays, or pass file paths to read them. The judgement is pure arithmetic, so it works without SONAR running.
Inputs: grid, after, swing, before, +3 more.
cw_close_overlaysA
Close transient panels. Standard dialogs, including unsaved-work prompts, are preserved by default. Dismissing them may discard work and requires closeDialogs:true and confirm:"closeDialogs".
Inputs: confirm, closeDialogs.
cw_command_evidenceB
Which commands have been confirmed to work, which are unconfirmed and why. Unconfirmed does NOT mean broken: a toggle or a transport action never opens a window, so a window diff reports nothing. This says which witness would settle each one.
Inputs: no named parameters.
cw_command_supportA
What WM_COMMAND can actually drive in this SONAR build, measured. Working commands are main-frame ones (Preferences, About, Assistant, Video Engine, Reset MIDI/Audio). The 视图 menu, CakeScript and per-track mixer commands are registered but not dispatched, so posting them does nothing — this tool says so up front instead of leaving you to discover it.
Inputs: no named parameters.
cw_convertA
Convert between ticks, bar:beat:tick and seconds. Pure arithmetic — it needs no project and works with SONAR closed, so a measurement already in hand can be converted without waking anything. Pass exactly one of: ticks | time ("1:01:000") | seconds | bar. Note the bases: bare numbers are BARS, and in bar:beat:tick only the final field is 0-based — 1:01:000 is the start of a project, which is what a freshly opened one reads.
Inputs: bar, bpm, time, ticks, +2 more.
cw_convert_helpA
The time units this project uses, the 1-based/0-based trap in bar:beat:tick, the grid note values in ticks, and what the conversions cannot do (tempo changes).
Inputs: no named parameters.
cw_doctorA
Run a health check across every transport channel (host / CakeScript / WM_COMMAND / surface bridge / realtime MIDI / UIA click), each with a verdict and a remedy. THE tool to run first after a SONAR upgrade: it names which paths degraded and what to update.
Inputs: no named parameters.
cw_document_stateA
Whether SONAR has a document open, read from the window title — the one piece of project state this process can see. This gates a lot: with no project the menu bar has only the application-level menus and the track controls do not exist, which makes view and document commands look broken. With a project open the menu tree is 270 entries and the track strips appear.
Inputs: no named parameters.
cw_editB
Run an editing command: quantize | grooveQuantize | transpose | splitClips | splitAtNow | splitMidiNotes | mergeClips | gain | normalize | reverse | removeSilence | fadeEnvelope. Every one needs a selection, which this tool satisfies first — that precondition is the difference between "the command does nothing" and "it opens its dialog".
Inputs: command (required), confirm, selectFirst.
cw_edit_helpC
The editing layer: the commands, their preconditions, the dialogs behind them, and the three-cause taxonomy for "a probe reported nothing happened".
Inputs: no named parameters.
cw_enable_midi_portA
Enable a MIDI port in SONAR by writing TTSSEQ.INI, so the MIDI transport reaches SONAR without touching the UI. Idempotent. SONAR applies it at startup or when its MIDI Devices dialog is applied — not live in the current session.
Inputs: port (required), backup, section.
cw_file_dialogA
How to drive the file dialog a document command opens: the element names, and why this one IS scriptable when SONAR's own controls are not (it is standard MFC, not drawn).
Inputs: no named parameters.
cw_find_pluginB
Search registered plugins by name. Covers effects and instruments; instruments are the ones to load into a track. Each result carries its CLSID, its file path, and whether the file is still present.
Inputs: query (required), kind, limit, presentOnly.
cw_get_clipsB
List clips on a track. NEEDS CakeScript (T1), which this SONAR build cannot dispatch.
Inputs: index (required).
cw_get_notesA
Get the notes of a clip on a track (default clip 1). NEEDS CakeScript (T1), which this SONAR build cannot dispatch. The export route is the verified way to read note data on this build.
Inputs: index (required), clipIndex.
cw_get_stateA
Read the most recent observation for a topic. Reports staleness and why it is empty when nothing has been observed yet.
Inputs: topic.
cw_get_trackA
Get one track's properties. NEEDS CakeScript (T1), which this SONAR build cannot dispatch. cw_get_track_control reads a single strip control and works without it.
Inputs: index (required).
cw_get_track_controlA
Read one track-strip control as SONAR currently shows it — any label, e.g. 音量, 声像, 手动静音, 独奏, 录制, 输入, 输出, 存档. Reading is accurate; writing is only available for the three toggles (cw_set_track_mute / solo / arm).
Inputs: index (required), label (required).
cw_historyA
Open 编辑 > 历史 (0x8044) and report how to read and use the undo stack. The dialog lists every undoable operation as a row, OLDEST FIRST, which makes this the one place in this host where the write history is legible rather than inferred. Reading it changes nothing; choosing an older row and pressing 确定 rewinds TO that point and DISCARDS everything after it — so for a single step use cw_undo instead. Note the stack is depth-limited (measured 128) and old entries are dropped silently.
Inputs: no named parameters.
cw_history_helpA
How undo/redo work here, the undo-stack dialog as measured, why the stack is the backstop for every irreversible write path, and the trap in verifying a rewind (a window diff sees nothing, so "none-observed" reads like failure when it is success).
Inputs: no named parameters.
cw_insert_commandsA
Every 插入 (Insert) command SONAR exposes, with its id. Reference for cw_run_command when you need something cw_add_track does not cover, e.g. a track template.
Inputs: no named parameters.
cw_insert_track_templateA
Insert a track template into the project by name (or full .cwx path), then confirm it by finding the new track in the strip accessibility tree. Needs a project open. Use cw_list_track_templates to see what is available.
Inputs: name (required).
cw_jobA
Read one background job by id: state, elapsed time, progress trail, result or error. Poll this after a slow tool returns a job id.
Inputs: id (required).
cw_job_abandonA
Mark a background job abandoned so its result is discarded. This does NOT stop the work: a menu command already posted to SONAR cannot be recalled. It only stops this adapter from reporting the result.
Inputs: id (required).
cw_job_clearA
Forget finished background jobs. Running jobs are kept so a caller does not lose track of them.
Inputs: no named parameters.
cw_job_helpA
Why background jobs exist here, the states a job moves through, and the one thing the API deliberately cannot do (cancel work already sent to SONAR).
Inputs: no named parameters.
cw_jobsB
List recent background jobs, newest first, without their payloads.
Inputs: limit.
cw_latencyA
Per-operation latency profile: bridge round trips, menu commands, MIDI sends, plugin reads. The plugin-read stage is the slow one, so it is skipped by default for the same reason cw_benchmark is — a bare call must return, not time out.
Inputs: includePluginReads.
cw_list_commandsA
List SONAR commands. source="live" (default) lists ids that cw_run_command can actually post, read from the running build's menu bar. source="index" searches SONAR's command-palette index (broader, but those ids are not postable).
Inputs: limit, query, source.
cw_list_overlaysA
List modal windows (the Assistant / command-palette panel) that block menu commands.
Inputs: no named parameters.
cw_list_stateB
List which project-state topics have been observed, and when.
Inputs: no named parameters.
cw_list_tracksA
List all tracks in the active SONAR project. NEEDS CakeScript (T1), which this SONAR build cannot dispatch — on this build use the export route instead: cw_run_command 0xA659 (文件 > 导出 > 标准 MIDI 文件), then cw_read_midi_file on the result.
Inputs: no named parameters.
cw_list_track_templatesA
List the .cwx track templates SONAR has available, with their category. A template is a whole pre-built strip — instrument, FX chain, sends, routing — and inserting one is the verifiable way this adapter puts a plug-in chain into a project.
Inputs: filter.
cw_locateA
Move the now-time to a Bars/Beats position, e.g. "1:01:000". NEEDS CakeScript (T1), which this SONAR build cannot dispatch, and no menu command performs an absolute jump: cw_navigate moves by whole measures (goToNextMeasure / goToPrevMeasure) only. cw_convert turns a position into ticks if you need the number itself.
Inputs: time (required).
cw_markersC
Everything about markers: the dialog (which IS writable, unlike SONAR's own controls), the commands, and how to read the marker list back. This is the working pattern for a drawn surface that has a command opening an MFC dialog behind it.
Inputs: no named parameters.
cw_midi_ccB
Send a MIDI control change on the live port. cc 7 = channel volume, 10 = pan.
Inputs: value (required), controller (required), channel.
cw_midi_chordB
Play several notes at once on the live MIDI port, released together.
Inputs: pitches (required), channel, velocity, durationMs.
cw_midi_configA
Read SONAR's MIDI port configuration (TTSSEQ.INI): which ports SONAR has enabled as inputs, outputs and echo. Use this to verify the receive side, which a send cannot confirm.
Inputs: no named parameters.
cw_midi_devicesB
List every MIDI device Windows reports, in and out.
Inputs: no named parameters.
cw_midi_noteB
Play a note on the live MIDI port. Use this to audition or to write into a record-armed track. millisecond latency; no CakeScript involved.
Inputs: pitch (required), channel, velocity, durationMs.
cw_midi_panicA
Send all-notes-off and reset controllers on every channel, then reset the port.
Inputs: no named parameters.
cw_midi_sendA
Send a batch of raw MIDI messages in one round trip. Each message is [status, data1, data2]. Use this to lay down a phrase cheaply; pass channel to rewrite the low nibble of each status byte.
Inputs: messages (required), channel.
cw_midi_statusA
Report the real-time MIDI transport: available ports, which one will be used, and the one-time step needed in SONAR (Preferences > MIDI > Inputs) to receive it.
Inputs: no named parameters.
cw_mixer_supportA
What can and cannot set a track's volume or pan on this build, measured, with the survey behind it. Accessibility reads mixer state but does not accept it; MIDI writes do.
Inputs: no named parameters.
cw_mixer_targetsB
What a live MIDI mixer message can affect right now, and why. A CC reaches SONAR but only applies where a track is listening (armed, channel-assigned, or bound to ACT) — without a destination it is delivered and dropped, which is invisible unless you check.
Inputs: no named parameters.
cw_no_effect_causesA
Why a command can report "nothing happened", with how to tell the three causes apart. Only one of them is a limit of this adapter.
Inputs: no named parameters.
cw_note_edit_helpA
How note-level editing actually works: notes cannot be READ through any automation surface, but they can be EDITED through the dialog behind 处理 > 量化, and the exported .mid file is what proves it. Carries the measured field labels, the two mistakes that produced wrong conclusions, and the full verification round trip.
Inputs: no named parameters.
cw_plugin_insert_recipeA
How far plugin insertion can be driven on this build: discovery works (open the browser, list categories, read which plugin is selected), insertion does not (click, double-click and drag all leave the FX bin empty). Read this before promising a plugin can be attached.
Inputs: no named parameters.
cw_pluginsA
Summarise the plugins SONAR has registered: counts, categories, and any registered plugin whose file is missing. Reads SONAR's own scan result, so it works whether or not SONAR is running.
Inputs: no named parameters.
cw_probe_stateA
Get a plan for reading project state on this build. Lists which SONAR surface carries each fact (track list, mixer values, notes) and the steps to capture it. Use when cw_get_* tools report CAKESCRIPT_UNAVAILABLE.
Inputs: topic.
cw_projectA
Run a document command: newProject | open | save | saveAs | close | exportAudio | importMidi | revert. The destructive ones (close, revert) refuse unless confirm is set to the command's own key, because they discard the session with no undo.
Inputs: command (required), confirm.
cw_quantize_dialogA
The 量化 dialog as measured: every field, its accessible label, which element kind to write to, the values it accepts, and the traps. Kept separate from the plan so a caller can see the raw measurement the plan is built from.
Inputs: no named parameters.
cw_quantize_planA
The exact plan for a quantize: which dialog fields to write, with what values, and how to prove afterwards that it landed. This process cannot perform the accessibility writes itself — a computer-use runtime does that — so this states the plan rather than pretending to run it. Pass the settings you want to get the concrete values.
Inputs: grid, swing, offset, strength, +1 more.
cw_read_midi_fileA
Parse a Standard MIDI File: per-track name, channels, note count, and any CC7/CC10 with the pan position spelled out. Use it to check what a file carries before importing it, or to read back a file SONAR exported.
Inputs: path (required), includeNotes.
cw_redoA
Reapply the operation most recently undone. Same silent behaviour as cw_undo — no window, no element change, so the result cannot be confirmed from the screen.
Inputs: no named parameters.
cw_report_stateC
Send back what a computer-use agent observed, so later calls reuse it instead of re-probing. Shape the state like the CakeScript tools did: { tracks: [{index,name,type,volume,pan,mute,solo,arm,clips}], notes: [{track,pitch,velocity,time,duration}], now, tempo, loop, project }.
Inputs: state (required), note, topic, source.
cw_run_commandA
Run a SONAR menu command by numeric id via WM_COMMAND. Version-independent: works on any build whose menu exposes the command. Get ids from cw_list_commands. Returns whether the window list changed, so a registered-but-unhandled command is distinguishable from a working one.
Inputs: cmdId (required), confirm, keepOverlays.
cw_run_command_classifiedB
Run a menu command and report what this process could and could not establish, instead of claiming success from "nothing errored". Returns status confirmed | did-nothing | unconfirmed, with the evidence class behind it.
Inputs: cmdId (required), confirm, keepOverlays.
cw_save_stateA
Whether the open project has unsaved changes, in the terms that matter before closing or opening something else. Read from the title's modified marker.
Inputs: no named parameters.
cw_set_panA
Set a track's pan through the live MIDI cable (CC10). This is the path that actually works: the track strips' pan slider is read-only through accessibility on this build. channel is the MIDI channel the track listens on, not its position — read it from the strip's "MIDI 通道 on Track N" value.
Inputs: value, channel, position.
cw_set_track_armB
Arm or unarm a track for recording, through the track strip's 录制 button. Reports verified from the value read back. Needs a project open and the track visible.
Inputs: arm (required), index (required).
cw_set_track_muteA
Mute or unmute a track. Works by driving the track strip's own 静音 button (a real click — SONAR's accessibility actions are inert), and reports verified from the value read back. Needs a project open and the track visible in the Track view.
Inputs: mute (required), index (required).
cw_set_track_nameA
Rename a track by editing its strip's name field (double-click, paste, Enter), and report verified from the name read back. Handles Chinese, unlike the CakeScript route this replaces. Needs a project open and the track visible in the Track view.
Inputs: name (required), index (required).
cw_set_track_panA
Set a track's stereo pan (-1.0 = full left, 0 = centre, +1.0 = full right). NEEDS CakeScript (T1), which this SONAR build cannot dispatch — same limits as cw_set_track_volume. cw_set_pan sends live CC10 on a MIDI channel instead.
Inputs: pan (required), index (required).
cw_set_track_soloB
Solo or unsolo a track, through the track strip's 独奏 button. Reports verified from the value read back. Needs a project open and the track visible.
Inputs: solo (required), index (required).
cw_set_track_volumeA
Set a track's volume (0.0 to 1.0+; 1.0 = unity). NEEDS CakeScript (T1), which this SONAR build cannot dispatch, and there is no drop-in replacement: SONAR's accessibility actions are inert on the fader (measured) and CAL has no volume builtin. cw_set_volume sends live CC7 on a MIDI channel instead — it reaches the engine but only moves a track that is listening to that channel. See cw_mixer_support for the survey.
Inputs: index (required), volume (required).
cw_set_volumeB
Set a track's volume through the live MIDI cable (CC7). level is 0.0-1.0, or pass a raw CC value.
Inputs: level, value, channel.
cw_song_instrumentsB
Instruments available for songwriting, grouped by the role each suits (drums, bass, keys, guitar, strings, synth), best pick first. Derived from the registered instruments.
Inputs: limitPerRole.
cw_statusA
Check SONAR host, which automation transports this build supports, and what to use. Run this first.
Inputs: refresh.
cw_surfacesB
Every SONAR UI surface that carries project state, and what can be read from each. Reference for writing a probe.
Inputs: no named parameters.
cw_timingB
How to set and read tempo and time signature. Writing them into a .mid and importing is the reliable route; inserting a change at the now-time is a different operation.
Inputs: no named parameters.
cw_track_controlsA
How to read and change tracks through SONAR's accessibility tree, which is the working path on builds with no CakeScript. Gives the element naming ("音量 on Track 17"), which controls each strip type has, and which action each takes. The elements are only reachable from a computer-use runtime — this server ships the contract, it cannot read them itself.
Inputs: no named parameters.
cw_transportA
Send a transport command (play | stop | record | pause). Tries CakeScript first and falls back to SONAR's own menu commands, so it works on builds where T1 cannot be dispatched.
Inputs: cmd (required).
cw_transport_commandB
Send a transport or timing command: play | stop | record | toggleLoop | setLoopSelection | metronomePlayback | metronomeRecord | showTempoView | showMeterView | insertTempoChange | insertMeterChange. Every one of these changes state WITHOUT opening a window, so this tool can post but not confirm — it returns what a computer-use runtime should look at.
Inputs: command (required).
cw_transpose_planA
The exact plan for a transpose: which 移调 dialog fields to write, with what values, and how to prove the commit landed. Transpose is the one note operation that changes PITCH, and it works on a free licence — no CakeScript needed. This process cannot perform the accessibility writes itself (a computer-use runtime does that), so this states the plan rather than pretending to run it.
Inputs: semitones, wholeTones.
cw_ui_recipeA
How to drive SONAR's own UI with a computer-use runtime: which parts are reachable, which are not, and how to recover when a JUCE modal dialog blocks the app. Measured, not guessed — notably, synthetic keystrokes do not reach SONAR and the menu bar is reachable via AXExpand.
Inputs: no named parameters.
cw_undoA
Rewind the most recent operation. Undo opens no window and changes no element, so this process CANNOT confirm it — expect effect "none-observed", which is the SUCCESS case, not a failure. To check it worked, look at the data the operation had changed (a note count, an export), never at the screen. This is the adapter's only rewind, and it is what makes an uncertain write safe.
Inputs: no named parameters.
cw_verify_commandsA
Re-measure which command ids do something on the running SONAR, by posting each and watching the window list. Use after a SONAR update to refresh the working/inert split. Defaults to the two safe view commands when a project is open; nothing without a project. Only a fixed view/dialog allowlist is probed, even for explicit ids. A modal stops the survey and is left open. No insert, recording, mute, solo or document lifecycle probes. Cost, measured: each probe takes about 15s (two bridge round trips plus a settle delay), so the full 21-command survey is roughly five minutes and NO budget makes it quick — a short budget buys one or two probes, which is a much weaker claim than a complete survey. probed says how many were actually measured; give it time if you want the measurement.
Inputs: cmdIds, budgetMs, background.
cw_view_commandsA
Commands that open SONAR views, with the caveat that matters: a view opening inside the existing frame produces NO new window, so cw_run_command reports "none-observed" for all of them even when they worked. Verify a view by reading the accessibility tree or a screenshot.
Inputs: no named parameters.
cw_write_midi_fileA
Generate a Standard MIDI File (format 1) from note and CC events. Each track needs a MIDI channel; CC7/CC10 written at tick 0 become that track's initial volume and pan when SONAR imports the file. This is the reliable way to set mixer values and place notes, because the in-app controls are read-only through automation on this build.
Inputs: path (required), tracks (required), bpm, overwrite.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 89 tools
Many tools have overlapping or closely related purposes: cw_transport vs cw_transport_command, cw_set_volume vs cw_set_track_volume, cw_status/cw_doctor/cw_benchmark/cw_latency, and numerous state/help/plan tools. The descriptions often clarify the distinctions, but an agent must read deeply to avoid choosing a reference/plan tool instead of the actionable one.
All tools share a cw_ snake_case prefix, which is predictable. However, the naming convention is mixed: some are verb_noun (cw_get_track), some are nouns/references (cw_mixer_support, cw_doctor), and near-duplicates like cw_transport vs cw_transport_command and cw_set_volume vs cw_set_track_volume create inconsistency.
89 tools is far beyond a well-scoped set for this purpose, especially because many are help, planning, diagnostic, benchmark, and reference tools rather than distinct operations. The surface is heavy and fragmented, making discovery and selection burdensome.
The surface covers project lifecycle, tracks, MIDI, commands, editing plans, undo/history, jobs, and state reporting, with documented workarounds for CakeScript limitations. But several core operations remain unavailable or indirect on this build—native track listing, note reading, absolute locate, and plugin insertion—so there are notable gaps despite the breadth.
Maintenance
Related MCP Connectors
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Design, build and run teams of AI agents with checked handoffs between them.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- FlicenseAqualityCmaintenanceEnables AI assistants to control a live REAPER DAW session on macOS in real time, including track creation, MIDI writing, FX management, and transport control.20-
- AlicenseBqualityBmaintenanceControl Logic Pro locally on macOS through MCP: transport, tracks, mixer, plug-in parameters, audio analysis, bounce and delivery, with optional gesture and voice control. Uses OSC, CoreMIDI and macOS Accessibility. Actions report confirmed, uncertain or failed outcomes. Actual control requires a local Mac with Logic Pro. Hosted/Linux builds are schema inspection only; all operations are disabled.123MIT
- AlicenseBqualityCmaintenanceEnables MCP-capable AI agents to control REAPER through typed tools and a Lua escape hatch for project creation, track management, recording and editing, MIDI writing, mixing, rendering, and batch operations.501MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLMs to read and control a DAW through typed tools covering session and transport state, tracks, mixer channels, MIDI parts and notes, supported plugin parameters, and finite editing operations, while also offering offline song inspection and WAV analysis.3MIT