Workflows
On this page
This page summarizes the current bridge surface for producers. The detailed agent procedures are in Agent workflows; the exact MCP schemas are in the tool reference.
The source currently registers 57 MCP tools. That number describes the source
catalog, not live acceptance. Check the running server's tools/list and the
native protocol-4 capabilities response before relying on a capability.
Use the same loop for every live change:
- Observe capabilities and current state.
- Plan one audible or structural result.
- Preview when the tool offers a preview.
- Authorize one guarded mutation.
- Read back and compare the observed result.
- Recover from any ambiguity before sending another mutation.
A native public write returning submitted is not completion. Save project
work before a deliberate Bitwig restart after extension replacement. A copied
.bwextension or a public ControllerHost restart alone does not prove that the
new class definition is running.
Inspect a live project
Begin with read-only calls:
get_grid_capabilities {}
get_selected_device_state {}
grid_song_state {}
grid_list_devices {}
For a supported Grid device, read get_grid_graph and grid_analyze. Record
project token, selection token, mix revision, graph ID/revision, and exact
native module/port identities. A non-Grid selection or an unsupported private
runtime may report graph_available: false while public selected-device and
host controls remain available.
Shape a selected device
For exposed controls, use the shaping session:
grid_shape_startwith a brief or supported preset;grid_shape_composefor bounded revisions;grid_shape_statusto review the integer revision;grid_shape_applywith that revision andconfirmorcooperative;get_selected_device_statefor read-back; andgrid_shape_undoonly for values recorded by the completed session.
The MCP-facing parameter domain is 0–128. Native normalized controls use 0–1; these domains are not interchangeable. Named snapshots are process-local memory, not project files.
Build or repair a Grid graph
One guarded operation
Use the direct graph tools for one explicit edit:
- read
get_grid_graphimmediately before the operation; - obtain package IDs, module IDs, parameter IDs, and ports from that read;
- submit one graph mutation with its exact
expected_revisionand explicitconfirm/cooperativeauthorization; and - read graph state again before continuing.
The available edits are module/modulator insertion, parameter set, connection,
disconnection, grid_move_module, and grid_clear_graph. Coordinates are
bounded to -4096..4096. A stale revision rejects the write. Treat clear as
destructive and preserve a project copy.
Staged patch session
For a multi-operation change, prefer:
grid_patch_startwith bounded nodes, connections, and protected routes;grid_patch_statusto review preview bindings and remaining steps;- one
grid_patch_stepat a time with the current session revision; - status/read-back after every step; and
grid_patch_controlorgrid_patch_restoreonly after a completed parameter-only session.
The integer patch-session revision and native graph revision are separate. An
external graph change, stale identity, or failed read-back freezes the session;
the manager does not auto-replay or auto-rollback. grid_analyze describes
active topology reachability, not a proof of sound quality.
Transport, tracks, and mix
Read grid_song_state and, for a target track, grid_inspect_mix. Use the
fresh project token and mix revision for:
grid_song_transport: play, continue, restart, stop, seek, tempo, meter, or loop;grid_set_track_state: arm and/or mute; andgrid_set_mix: gain/volume, pan, or send with expected current value.
Track indices are 0..63. Transport bounds include 40..220 BPM, seek 0..24576
beats, and meter numerators 2..12 over denominator 4 or 8. Recording and
automated targets are guarded. After each write, read state again; do not
interpret verified: false as an error or as completion.
Device chain and actions
Use grid_list_devices to inspect the bounded device bank and obtain a fresh
non-null selection token. Search current UUIDs with search_grid_devices, then
use grid_insert_device or grid_remove_device for one reviewed change. The
positions are before, after, start, end, and replace. Re-list devices
and read selected state after a submitted mutation.
Use grid_list_actions to obtain current action IDs and
grid_invoke_action only for a reviewed ID. The action catalog is not a hidden
arranger, clip, automation, project-save, or delivery API.
Offline composition and export
When an offline MIDI artifact is sufficient:
- call
grid_track_planwith a bounded brief; - call
grid_track_startfor a process-local review session; - inspect
grid_track_statusand retain its current 64-hex revision; - use
grid_track_revisefor one role/section/phrase/arrangement scope at a time, then recheck status; and - call
grid_track_exportwith the newest revision.
Export writes a unique private directory containing song.mid and
manifest.json. The MIDI is a real Type-1 SMF with conductor and role tracks
at ppq=480; the manifest schema is bitwig-midi-artifact/1 and carries
metadata, byte count, and artifact SHA-256. A new revision invalidates older
exports.
This path does not import MIDI into Bitwig, create instruments, realize voices, render audio, or save/load/deliver a project. Treat the exported bytes as the artifact under review, not as proof of a live arrangement or sound.
Audio-file analysis and comparison
Use grid_audio_analyze for bounded local files and grid_audio_compare for
two files. Metrics include digest, sample rate, channels, frames, RMS, peak,
clipping/silence, envelope/tail RMS, low-band, and channel data.
The optional matching path is whole-file RMS attenuation only: choose the
quieter target and apply min(1, target/rms). No file is amplified. Verified
output WAVs are still file artifacts, not live capture or Bitwig renders; this
is not LUFS or perceptual approval.
Recovery
For a timeout, disconnect, stale token, stale revision, or unexpected observation:
- stop issuing mutations;
- read current state and capability flags;
- determine whether the original request was applied;
- if applied, continue with the new token/revision; and
- if not applied, formulate one new guarded call from the fresh read.
Never blindly replay a submitted or ambiguous operation. Native global undo and redo are host-wide. Shaping undo and patch restore are narrower, but no undo path replaces a backup.
Explicitly unavailable capabilities
The bridge does not expose:
- native arranger note, clip, or automation editing;
- MIDI import or voice realization;
- live capture;
- audio rendering/export; or
- project save, new, load, or delivery.
These absences are intentional. Bitwig UI actions outside this contract must not be documented as MCP acceptance, and offline artifacts must not be called native project delivery.