Skip to main content
Glama

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-midi

Two 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 DllImport that takes a string is declared CharSet.Unicode. PowerShell 5.1's Add-Type defaults to ANSI, and without the attribute FindWindowW("Sonar", "Cakewalk Sonar") silently returns 0.

  • GetMenuTree reads 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, probe and msgids — there is no init/toolcall operation, so the write_cakescript / run_cakescript IPC is not wired. On a host that exposes the Assistant, runTemplate fails with T1_CHAIN_UNIMPLEMENTED rather 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_COMMAND posts are dropped. The bridge closes those panels first (cw_close_overlays, or automatically inside cw_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_command therefore diffs the window list before and after and reports none-observed when 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 ................. unchanged

That 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:

  1. Locate by name through accessibility — 手动静音 on Track 3.

  2. Act with a genuine click at the element's BoundingRectangle centre.

  3. 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 to unavailable after 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 through CW_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_doctor reports sonarMinimized: true and says to restore the window, instead of leaving every write mysteriously verified: 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-SonarMain now refuses to fall back to HUD windows, and cw_doctor reports frameGhost: true with 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=1

So 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

Cakewalk Sonar

Cakewalk Sonar - [name.cwp*] for a .cwp, or name.mid - Cakewalk Sonar for imported MIDI. The * dirty marker is drawn on the document tab, reported as documentTab; the frame caption does not always carry it.

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 (cw_track_controls)

accurate snapshots

change volume / pan

cw_set_volume / cw_set_pan (MIDI CC7/CC10), or a .mid file

reaches the engine, not the UI

change project structure

cw_add_track

insert commands are dispatched

write notes

cw_write_midi_file + import

no note-level element exists

edit existing notes

cw_quantize_plan → dialog → cw_check_quantize

the dialog accepts writes; the export proves it

create / delete notes

cw_cal_run (addNotes, deleteNotes)

CAL is a note-level API and is not paywalled

read notes

cw_project export → cw_read_midi_file

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% 右    音量=86

Channel, 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

cw_write_midi_file

compose notes and CCs, write a format-1 file, import it

cw_read_midi_file

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 as outside 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

AXExpand a top-level item, then click the entry by index

Standard MFC dialogs (Preferences, any #32770)

yes

read elements by index; AXToggle / AXPress

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_COMMAND to 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

"<dll path>*<index> <name>" + clsidPlug

Registry inventory, scanned but unnamed

293

real and loadable — Battery 4, BBC Symphony Orchestra, Melodyne, Boost11

Menu layout only

262

the DX-era effects (Compressor/Gate), not in the VST inventory

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 (查看插件, 0x8A59)

works — a JUCE panel docks on the right with a category tree

Expand a category

works — Dynamics lists Archetype Mateus Asato, BL 1176, Boost11, Curves Resolve, Gater, …

See each plugin's format

works — rows are tagged VST3 / VST2 / BandLab / DX

Read which plugin is selected

works — the status bar reports Neural DSP, VST3, 64 Bit, In: 2, Out: 2

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:

  1. Insert the plugin by hand — fastest and most reliable.

  2. cw_add_track — inserts a track with SONAR's default instrument attached, which is enough to hear a MIDI part.

  3. 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 (cw_set_volume / cw_set_pan)

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

drawn-not-exposed

it is a toggle, transport action, selection or fader

it worked; the result is pixels

confirm with a screenshot

precondition-missing

it is an edit, an export, or acts on a selection

the command is fine, the state was not

satisfy the precondition and retry

gated-by-licence

a PaywallWindow appears

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 back

The 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

0x8072 视图 > 速度

no change

a tempo track appeared (TEMPOTRACKVIEW in the tree)

0x82CE 显示/隐藏总线区域

no change

the track view repainted

0x80B9 循环开关

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

window

this process

编辑 > 历史 opens a #32770 dialog

elements

computer-use runtime

视图 > 速度 adds TEMPOTRACKVIEW

screenshot

computer-use runtime

循环开关 flips a button

accepted

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

播放/停止 / 停止 / 录制

0x801D 0x801F 0x801C

循环开关 / 设置循环选区

0x80B9 0x80FE

节拍器(回放 / 录制)

0x8171 0x8172

视图 > 速度 / 拍号调号

0x8072 0x8073

插入速度变更 / 拍号变更

0x807D 0x807E

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 refused

A 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

WM_GETTEXT on every window SONAR owns

empty string — no track, clip or mixer text anywhere

UIA TreeScope::Descendants on the main window

19 elements, all containers (MDIClient, AfxControlBar140u, CCtrlBar*, the JUCE shell)

MSAA AccessibleObjectFromWindow

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

cw_probe_state

A plan for a topic (overview/tracks/mixer/notes/selection/all): which SONAR surface carries each fact, and the steps to capture it. Notes go through the Event List view because tabular text survives reading far better than a piano-roll render.

cw_report_state

Accepts what a computer-use agent observed and caches it, in the same shape the CakeScript tools returned (tracks[], notes[], now, tempo, loop).

cw_get_state / cw_list_state

Read the cache back, with staleness (30 min) and an explanation when empty.

cw_surfaces

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:

  1. The 助理 (Assistant) menu entry opens the command palette, not an AI chat panel. XCDLLMSERVER is never created, so the write_cakescript / run_cakescript IPC has nowhere to land. The T1 transport is gone.

  2. 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) and CakeScript (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 an Anthropic API 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 / IClipboard symbols, plus the literal Lua 5.4.

  • XCDLLMSERVER still appears once as a string, but no such window is ever created, and LLM_INIT / LLM_TOOL_CALL do not appear as literals at all — they are RegisterWindowMessage ids, 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 0xA78D with a project open raises a JUCE_1a13a4b5ecf window titled PaywallWindow, 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

0x8061

start times → grid

round trip verified

移调 Transpose

0x8066

pitch by an interval (signed)

round trip verified

力度 Scale Velocity

0x8067

velocities, as a percentage ramp

round trip verified

音长 Length

0x8064

durations and/or start times, scaled

round trip verified

倒置 Retrograde

0x8065

mirrors the pitch contour in place

round trip verified

时间匹配 Fit to Time

0x8068

stretches the selection to a target end time

fields

律动量化 Groove Quantize

0x8062

timing/duration/velocity against a groove

fields

移动 Slide

0x8043

shifts events by a signed amount in a chosen unit

fields

轻移 Nudge ×8

0x846F…0x8531

pitch (up/down) and time (left/right)

no dialog; step sizes measured

查找/更改 Find/Change

0x8063

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 3404 at 100% became 0 480 960 1440 1920 2520 2880 3360; a no-edit control export showed zero drift.

  • 移调 — wrote 3 into 数量(A) (element 25), pressed 确定, exported: 63,65,67,68,70,72,74,75 — every note +3 semitones, control unchanged.

  • 力度 — wrote 50 into both 开始(B) (element 9) and 结束(E) (element 7), pressed 确定, exported: every velocity 100 → 50.

  • 音长 — wrote 50 into 按照(B) (element 24) and pressed 确定: every duration 400 → 200 and every start tick 0,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,63 at 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 (cw_list_tracks …)

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 (cw_edit findChange)

a project open; it changes no data

cw_run_command (menu commands)

a project open, for the view/document commands

cw_midi_*

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 (0x809F, 0x80E2) — no licence

Undo / redo / inspect the undo stack

0xE12B / 0xE12C / 0x8044 — no licence, no dialog for the first two

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

(= Note.Vel 64)

8 notes, every velocity 100 → 64

create

(insert t ch NOTE (+ k 12) v d) ×3

8 → 32 notes; each new pitch exactly source+12/+16/+19, each at its source tick

delete

(if (>= Note.Key 80) (delete))

32 → 16; exactly the 16 above the threshold, none left

read

summary written into the track name

Q:n16,lo60,hi79,v64-64,d6400,t0-3360 — matches the project exactly

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 / epilog split 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.CAL proves the body slot is a slot — it puts NIL there with a comment saying this makes the routine run once instead of per event. (forEachEvent expr) is the explicit form; LEGATO.CAL uses both.

  • Variables. (int name init), (dword …), (word …), (string …). A prolog variable persists across the walk — that is the only cross-event state, and SINGLE.CAL uses it (with a -1 sentinel) 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.Kind and Event.Chan are read-only in every shipped usage; Event.Time, Note.Key, Note.Vel, Note.Dur and Control.Val are written. Observed kinds: NOTE, CONTROL, WHEEL, CHANAFT; KEYAFT and PATCH are 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) and pause (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:

  1. Export and parse — 0xA659 then cw_read_midi_file. No side effect, already verified, and it returns every field of every note. This is the answer for reading note data.

  2. queryNotes — encodes a fixed-format summary into the track name, which is readable from an export. It works, but it renames the track, so cw_cal_run refuses it without allowRename: true.

  3. 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_ID was a misgeneralisation. The index has 481 rows with ACTION_TYPE_ID = 1 (Execute Command), and all 481 carry a real CMD_ID that matches the live menu exactly — verified against ids this adapter already posts (0x82A6 insert MIDI track, 0x806A run CAL, 0x804C select all, 0xE101 open…). What produced the "index ids are not WM_COMMAND ids" warning was a different set of rows: the view-menu mirrors (音轨视图->音轨->…, 控制台视图->…) are ACTION_TYPE 6/7/8 with CMD_ID = 0 and the real id in ACTION_ID. Posting their CMD_ID posts 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 / DecrementPluginPreset have no id. CakeScript's Plugins:InsertAt is the only in-process route. Two alternatives exist and neither is a scripting path: a control-surface plugin (the interface is real — IControlSurface/2/3 in D:\CAKEWALK\Shared Surfaces\GenericSurface.dll, discovered through HKCR\CakewalkControlSurfaces — note that this is not HKLM\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 .cwx track 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

HKCR\CakewalkControlSurfaces\{CLSID} with a Description value. Five shipped GUIDs live there; nothing reads HKLM\SOFTWARE\Classes\...

Register a sixth entry

works, no elevation — writing through HKCR lands in HKCU\SOFTWARE\Classes, part of the merged view SONAR reads

Build a COM object of the right shape

works — 44-slot vtable (IUnknown 3 + IDispatch 4 + 9 + 10 + 18); DllGetClassObject, CreateInstance and all five QueryInterface calls succeed

Survive the deepest slot

works — slot 43 (OnContextSwitch), which is what a short vtable gets wrong

Appear in the picker

works — Cakewalk MCP Surface Bridge appears in 参数设置 > MIDI > 控制界面 alongside the five shipped surfaces

Get instantiated by SONAR

works — Connect() is called, and RefreshSurface() ticks at the configured 75 ms (158 calls in ~13 s)

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.exe exports CCtrlSurface::PersistSurfaces — the function that writes ctrlsurface.dat — and contains no LoadSurfaces, RestoreSurfaces or InitSurfaces symbol anywhere. It persists the list and never reads it back at startup.

  • Measured consequence: ctrlsurface.dat held the bridge's CLSID (written 00:09), SONAR started at 00:16, and the resulting process module list did not contain cw_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 plugin

No 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 -> 0x80004002

For 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:

  1. The log file gave absolute addresses, and the module base made the vtable RVA exact: 0x1433505D8 - 0x140000000 = 0x33505D8.

  2. On disk that RVA lands in .rdata, and [vtable-8] is an MSVC RTTICompleteObjectLocator. Following it to the TypeDescriptor gave the class name: .?AVCCtrlSurface@@.

  3. Its ClassHierarchyDescriptor listed 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.

  4. Disassembling its slot 0 showed it is QueryInterface — the code does mov rax,[rdx] and compares against IID pointers. That also explains the crash of the earlier blind probe: passing (1, 2) made the function dereference 1 as an IID.

  5. 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=8

So 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

SetTargetParam

reads this+0xF0 — its OWN state

SONAR notifies the surface that a value changed, so it can move its fader

SetParamMidiMsg

mov eax,0x80004001; ret = E_NOTIMPL

the surface does not declare a MIDI mapping

GetTargetParam

reads this+0xF0

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 On

11 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":

  1. Recover the interface from the binary. GenericSurface.dll does 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 parameter mixerParam and dwParamNum from the callee side. Nothing there reveals what SONAR passes in, and the referenced typelib (SURFACEFRAMELib) has no resource table in the DLL and no .tlb anywhere on disk.

  2. Recover the class from RTTI. The vtable was attributed to Sonar.exe and the first twelve slots all resolve into it, so the object is a real C++ class in the host. But the MSVC RTTICompleteObjectLocator read back empty, and Sonar.exe is stripped — 7 symbols — so the class name could not be recovered that way.

  3. 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 IUnknown prefix (slot 1 = 6, slot 2 = 5 — reference counts; slot 3 = a heap pointer), and the bridge answered ping afterwards.

      And SONAR then raised its own crash dialog: C0000005, access violation, dumped to MiniDumps\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 separates not-installed from needs-user-setup from ready, and the diagnostics are what produced the measurement above. Anyone re-attempting this on a future build should start from cw_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:

  1. RefreshSurface is a real, configurable heartbeat — 75 ms default, set in ‎参数设置 > MIDI > 控制界面 → 刷新频率(毫秒). A surface that only needed to read or tick could use it.

  2. The accessibility path already covers what the surface was meant to give. The track strips expose 手动静音, 独奏, 录制, 输出, 输入, 音色, 音色库 and MIDI 通道 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 through 0x806A and the exported .mid came 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:40 reads ; Un-mute the track directly above (TrackActive TRUE nTrk), so TRUE is audible and FALSE is muted.

  • Mute, solo and arm also have postable menu commands after all: MuteSelectedTracks 0x80E1 (32993), SoloAllSelectedTracks 0x809F (32927), ArmSelectedTracks 0x80E2 (32994), plus the Toggle*AllTracks family at 0x8202–0x8204, two of which commands.js already 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 /cakeScript and /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 Lua io.open and cakeapp.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. .lua has no assoc/ftype entry 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 from RootElement (it is a child of the SONAR frame, not a desktop top-level), but it can be bound — enumerate the process's #32770 windows, then AutomationElement.FromHandle. That yields the real HWND of every control: 331254|Edit (the 数量 field), 2624150|Button|确定, 7210576|Button|取消, and 723106|CC:SpinCtrl. The catch is what those controls are: SONAR's number fields are CC:SpinCtrl, a custom control, and the Edit beside it is a shadow. WM_SETTEXT "7" on that Edit reads straight back as '7' — and a fresh GetWindowText on 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_SETTEXT is 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

  1. 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.

  2. Accessibility for reads. With a project open, cw_track_controls gives 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).

  3. Menu commands for navigation. cw_run_command opens views, inserts tracks and drives transport once a document exists.

  4. 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 history_edit

Closed — cw_undo, cw_redo, cw_history, cw_history_help. Measured: rewinding to an older stack entry took a project from 16 notes to 8.

Clip CRUD

ACE clip_edit (18 verbs)

Partial — split and merge exist as dialogs (cw_edit); create/delete/move/resize have no surface on this build.

Plugin insert → params → presets → editor UI

ACE (the richest surface of the three)

Blocked — no insertion path exists; cw_plugin_insert_recipe records why. The only non-scripting routes are a control-surface COM plugin or a .cwx template.

Automation envelopes, sends/buses

ACE midiparam_*, vocalparam_*

Blocked — drawn, not writable, and CAL has no envelope builtin.

Async job handles

ACE job_*

Open — this adapter blocks and pushes budget management onto the caller (cw_add_song_tracks(budgetMs)). A server-side wrapper would close it cheaply.

Tick/time/bar conversion

ACE convert_edit

Open — pure arithmetic, no host involvement needed.

One docs index

ACE get_docs

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_classified returns confirmed / did-nothing / unconfirmed with 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

  1. 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.

  2. 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_clear now 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

cw_doctor

—

Health check across all five transports with verdicts and remedies — run first after a SONAR upgrade

cw_status

—

Host, version, transports, real-time MIDI state, recommended path

cw_save_state

—

Whether the open project has unsaved changes

cw_project

T2

newProject / open / save / saveAs / close / exportAudio / importMidi / revert

cw_file_dialog

—

How to drive the file dialog, and why it IS scriptable

cw_transport_command

T2

play / stop / record / loop / metronome / tempo & meter views

cw_timing

—

How to set and read tempo and time signature

cw_navigate

T2

Selection, now-time movement, and markers

cw_edit

T2

quantize / transpose / split / merge / gain / normalize / reverse / fade

cw_edit_help

—

The editing layer, its preconditions and its dialogs

cw_note_edit_help

—

How notes are edited: the dialog route, the export check, and the two mistakes behind it

cw_quantize_plan

—

The exact dialog writes for a given quantize, and how to prove it landed

cw_check_quantize

—

Judge a quantize from two tick lists — pure arithmetic, no SONAR needed

cw_quantize_dialog

—

The 量化 dialog as measured: fields, element kinds, traps

cw_cal_help

—

The CAL language: fields, operators, builtins, the run procedure, and the traps

cw_cal_plan

—

The exact plan for a CAL run — source, dialog write, verification. Pure

cw_cal_run

T2

Write a CAL program, post 0x806A, and report the dialog steps. No licence needed — notes and track properties

cw_cal_cleanup

—

Delete the CAL scripts cw_cal_run wrote, and their .bak copies

cw_undo

T2

Rewind the last operation. Silent — it cannot be confirmed from the screen

cw_redo

T2

Reapply the last undone operation

cw_history

T2

Open the undo stack (0x8044) and report how to read and rewind it

cw_history_help

—

How undo works here, and the trap in verifying a rewind

cw_convert

—

Convert between ticks, bar:beat:tick and seconds. Pure arithmetic

cw_convert_help

—

The time units, the 1-based/0-based trap, and what conversions cannot do

cw_surface_status

socket

Opt-in (CAKEWALK_MCP_SURFACE=1). Is the plugin loaded, has SONAR called Connect, what is still needed

cw_surface_diag

socket

Opt-in. The plugin's log, counters, and the interface sweep that established what the host object is

cw_surface_params

socket

Opt-in. The parameter vocabulary the plugin accepts, with each kind

cw_surface_set

socket

Opt-in. Set a mixer parameter. Refuses on this build — the host object has no IDispatch; use the .mid / CAL / click paths instead

cw_surface_midi_in

socket

Opt-in. MIDI that SONAR forwarded to the surface, decoded — needs the input port assigned

cw_surface_help

—

Opt-in. How the bridge works, how SONAR discovers a surface, and what it cannot do

cw_job

—

Read one background job: state, elapsed, progress trail, result or error

cw_jobs

—

List recent jobs, newest first, without payloads

cw_job_abandon

—

Discard a job's result. Does not stop work already posted to SONAR

cw_job_clear

—

Forget finished jobs; running ones are kept

cw_job_help

—

Why background jobs exist, and the one thing the API cannot do

cw_no_effect_causes

—

Why a command can report nothing happened — three causes

cw_markers

—

The marker dialog (writable), its commands, and the readback path

cw_command_evidence

—

Which commands are confirmed, which are unconfirmed and why

cw_run_command_classified

T2

Run a command and report what could and could not be established

cw_command_support

—

Which commands WM_COMMAND actually drives, measured, plus the UI recipe

cw_verify_commands

—

Re-measure command ids against the running SONAR after an update

cw_ui_recipe

—

How to drive the UI, what is unreachable, and how to recover a lockup

cw_list_commands

T2

source="live" lists postable ids; source="index" searches SONAR's command index

cw_run_command

T2

Run a menu command by id; reports whether the window list changed

cw_list_overlays

—

Modal panels currently blocking menu commands

cw_close_overlays

—

Close those panels

cw_midi_status

T4

Live MIDI ports, which is selected, whether SONAR is tuned to it

cw_set_pan / cw_set_volume

T4

Set pan (CC10) / volume (CC7) on a channel

cw_apply_mix

T4

Pan and volume for several channels in one round trip

cw_mixer_targets / cw_mixer_support

—

What a live mixer message can affect, and what is measurable

cw_write_midi_file

file

Compose notes and CCs into a format-1 .mid, with mixer values baked in

cw_read_midi_file

file

Parse a .mid — names, channels, notes, CC7/CC10 with pan spelled out

cw_plugins

—

Registered plugin counts across all three sources, categories, missing files

cw_find_plugin

—

Search 1208 plugins by name, with format (VST3/VST2/DX), kind and file presence

cw_plugin_insert_recipe

—

What plugin discovery can do and why insertion cannot be driven

cw_song_instruments

—

Instruments grouped by songwriting role

cw_add_track

T2

Insert a track (midi / audio / bus / folder / aux)

cw_add_song_tracks

T2

Insert the tracks a simple arrangement needs

cw_insert_commands

—

Every 插入 command with its id

cw_benchmark

—

Measure every capability, grouped by transport

cw_latency

—

Per-operation latency profile

cw_midi_config

—

SONAR's enabled MIDI ports, read from TTSSEQ.INI (verifies the receive side)

cw_enable_midi_port

—

Enable a port by writing TTSSEQ.INI — no UI needed, idempotent

cw_midi_devices

T4

Every MIDI device Windows reports

cw_midi_note

T4

Play one note (pitch / velocity / duration / channel)

cw_midi_chord

T4

Play several notes at once, released together

cw_midi_cc

T4

Control change — 7 volume, 10 pan

cw_midi_send

T4

Batch of raw [status, data1, data2] messages in one round trip

cw_midi_panic

T4

All-notes-off and reset on every channel

cw_probe_state

—

Plan for reading project state via computer-use, per topic

cw_report_state

—

Cache an observation from a computer-use agent

cw_get_state / cw_list_state

—

Read the observation cache, with staleness

cw_surfaces

—

Which SONAR surface carries which project fact

cw_list_tracks

T1

All tracks in the active project

cw_get_track

T1

One track's volume/pan/mute/solo/arm/sends/clips

cw_set_track_volume

T1

Volume (0.0–4.0)

cw_set_track_pan

T1

Pan (-1.0…+1.0)

cw_set_track_mute

T5

Mute / unmute, by clicking the strip's 手动静音 button

cw_set_track_solo

T5

Solo / unsolo, by clicking 独奏

cw_set_track_arm

T5

Arm / unarm for record, by clicking 录制

cw_get_track_control

T5

Read any strip control as SONAR shows it (音量, 声像, 输入, 输出, …)

cw_set_track_name

T5

Rename, by editing the strip's name field (double-click + clipboard paste — handles Chinese)

cw_list_track_templates

—

The .cwx track templates on disk, with categories (184 on this machine)

cw_insert_track_template

T5

Insert a template — instrument + FX chain + routing — and confirm the new track by name

cw_get_clips

T1

Clips on a track

cw_get_notes

T1

Notes from a clip (pitch/velocity/time/duration)

cw_transport

T1

play / stop / record / pause

cw_locate

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

0x882D

编辑 > 参数设置

opens Preferences

0xE140

帮助 > 关于 Sonar

opens About

0xA783

Cakewalk 助理

toggles the Assistant / palette panel

0xA798

工具 > 视频引擎设置

opens the video engine panel

0x8036

重置 MIDI 和音频

opens a confirmation dialog

0x80B3

文件 > 新建

opens the 新建工程文件 dialog

0xE101

文件 > 打开

opens the file dialog

Additional ones that respond once a project is open — verified against a live 16-track project:

id

command

observed

0x8294

视图 > 音轨视图

opens the track view

0x82A6

插入 > MIDI 轨

inserts a MIDI track (title gains *)

0x82A5

插入 > 音频轨

inserts an audio track

0x8105

视图 > AI Assist

responds (membership panel on a free licence)

0xA78D

处理 > 运行 CakeScript 程序

responds

0xA797

视图 > CakeScript View

responds

0x8021 0x8023 0x8029

视图 > 事件列表 / 钢琴卷帘 / 控制台

open the view

0x801C 0x801D 0x801F

录制 / 播放停止 / 停止

transport

0x8202 0x8203

静音 / 独奏 全部音轨

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 build

Latency, 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.md

Tests

Two tiers, no new dependencies (node:test).

node run-tests.mjs            # fast tier — 0.6s, no processes
node run-tests.mjs --full     # everything — several minutes

The 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 210

An 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 reg query dump, an INI, an XML layout

navigate

21

selection/marker records and their evidence classes

edit

26

the editing layer, the selection-honesty rule, and the false-positive fixes in outcome

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:

  1. every tool is callable and answers within a bounded time

  2. no tool raises an unhandled error at the protocol level

  3. an error is a well-formed result with a readable message, never a timeout

  4. a missing precondition is reported as such, with what to do about it

  5. 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

  1. 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 made describePan(0) read 102% left. Fixed by scaling each side by its own span.

  2. CC.pan vs CC.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.

  3. 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.

  4. 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. Added shutdownShims().

  5. risk held prose, disabling the guard. Three destructive commands had risk: '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.

  6. cw_edit reported a dialog that had not opened. outcome fell back to the command's description when no window appeared, so a failed run read like a successful one. Measured: newWindows was empty while outcome claimed a dialog. Now outcome carries only what was seen and expected the description.

  7. A stale modal made a working command look broken. With four leftover modal windows on screen, cw_edit quantize reported no-window-change; on a clean state the same call opened its dialog. likelySwallowed now says so and names cw_list_overlays / cw_close_overlays.

  8. preconditionSatisfied claimed an outcome nothing could observe. It read 'selected all first', asserted unconditionally from the selectFirst flag. 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 a likelySwallowed: true saying the command had vanished. Now selectionRequested reports the attempt, selectionConfirmed is always false, and selectionEvidence says 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.

  9. 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 predictQuantize against 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, and predictionConfidence is exact only 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.

  1. judgeQuantize could not tell "nothing moved" from "the commit failed". With strength: 0 the prediction is also "no movement", so before == after matched 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.

  2. describeNavigateResult had the same false-positive shape as #6, unfixed. confirm === 'dialog' produced "A dialog should be open" while never consulting newWindows — the evidence was in hand and unused. Worse, next had two branches for three evidence classes, so confirm: 'elements' (only showMarkerView) 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.

  3. 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_benchmark and cw_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_latency also orders its stages cheapest-first, because the budget is consumed in order and the expensive stages were starving the 22 ms MIDI measurement.

  4. events was unreachable through MCP, so a guard could never fire. cw_write_midi_file documented a channel-mismatch warning, but its zod schema only exposed notes — and zod strips unknown keys, so a client sending events had it silently dropped. The test "the writer warns when a track mixes channels" asserted only !isError and could not fail. events is now in the schema, and the test drives the path that can actually warn.

  5. The marker-removal commands had empty records. removeProjectStart/End/Range carried an id and a name and nothing else — no effect, no confirm, no verified — 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:

  1. judgeQuantize reported 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: beforeOnGrid is computed and the case is labelled a success. (It also explains why quantizing a tidy file proves nothing about the round trip.)

  2. A boolean was accepted as a strength. Number(true) is 1 and Number(null) is 0, so a bare coercion treated strength: true as 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.

  3. whatToLook vanished 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.

  4. Three tests that claimed to guard something and did not. The cw_edit window-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:

  1. 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_latency said a menu post costs "~4s" (measured 11s), and cw_verify_commands said "~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.

  2. A test that substituted its own arguments. The black-box "no tool hangs" check passed budgetMs: 3000 to cw_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.

  3. A fabricated witness. The three removeProjectStart/End/Range commands were marked "not probed" and then given confirm: 'screenshot' plus a whatToLook sentence 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 carry confirm: 'unprobed', and the branch that handles it says NOT PROBED.

  4. A count change hid a success. judgeQuantize fired 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.

  5. Clamping was silent. strength: 150 became 100 and strength: -10 became 0, reported as valid with no warning. strengthAdjusted and a message now accompany any value that was not used as given.

  6. A whole table was exempt from the rule. The check "every command declares how it can be confirmed" skipped ARRANGER_COMMANDS wholesale, so a command added there with an empty record would pass. The rule is now per-command: unprobed is 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:

  1. A crash on the most common state, hidden by tests that skipped themselves. capabilities() returned early when SONAR was not running and left transports an empty object, while runCommand() and cakeScriptBlocker() dereferenced transports[...].available unconditionally. Starting with SONAR closed — the single most likely way a user meets this adapter — produced Cannot read properties of undefined (reading 'available') instead of the documented CAKESCRIPT_UNAVAILABLE with its alternatives. Four tests covered this path and all four opened with if (!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 with available: false and a reason; guarded by a test that asserts the invariant regardless of what SONAR is doing (mutation-checked: bug in → red).

  2. A verification that used the wrong command id, and nearly produced a wrong "bug". While checking why an edit test failed, I posted 0x8099 to open the quantize dialog and it "worked". It is not 处理 > 量化. The real id is 0x8061 (lib/edit.js had it right all along). 0x8099 happens 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.

  3. A test weakened to make it pass, caught by mutating it. The cw_edit end-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() raising EDIT_WIRING_FAULT when the window list did not survive withSelection, covered by three process-free tests), and the end-to-end branch is t.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 pass

What the three attempts taught, in order:

  1. A test built on the code's own output is a tautology. The first version asserted outcome matched newWindows — but outcome is computed from newWindows, and it has exactly two values. It could not fail.

  2. 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.

  3. 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 tools
cw_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_navigateC

Selection, navigation and marker commands: selectAll | selectNone | selectByTime | selectFromNow | selectToNow | selectToEnd | goToNextMeasure | goToPrevMeasure | goToPrevMarker | goToNextMarker | insertMarker | setProjectStart | setProjectEnd | setProjectRange | toggleProjectMarkers | removeProjectStart | removeProjectEnd | removeProjectRange | showMarkerView. Reports whether the result is a readable dialog or a drawn change this process cannot confirm.

Inputs: command (required), confirm.

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

    C2.9/5.0

    Scored across 89 tools

    Disambiguation2/5

    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.

    Naming Consistency3/5

    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.

    Tool Count1/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Control 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.
      12
      3
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      50
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      3
      MIT