Workflow playbook
On this page
These workflows describe the current bridge contract, not a promise that a
particular Bitwig session is loaded or accepted. Start every live session with
read-only capability and state calls. The running MCP server's tools/list
and the native protocol-4 capabilities response are authoritative.
The bridge deliberately separates:
- native public host operations (song transport, track state, mix, devices, actions);
- private, version-gated Grid graph operations;
- preview-first Grid patch and shaping sessions; and
- offline MIDI and audio-file workflows.
A native write returning submitted is an immediate proxy observation, not a
completion event. Read the corresponding state again before moving to the next
step.
1. Connect without mutating
- Confirm the intended MCP process and checkout.
- Call
get_grid_capabilities,get_selected_device_state, andgrid_song_state. - Call
get_grid_graphonly when the capability response says the selected device has a supported graph. - For native host work, record the current project token, track index, mix revision, and selection token returned by the reads.
- For graph work, record the graph ID, 64-hex native graph revision, native module/instance IDs, package IDs, and exact port names.
A copied extension file or a historical catalog is not activation evidence. After replacing an extension, save work and restart Bitwig; a public ControllerHost restart can retain old loaded definitions in the same session. No throwaway native attach probe is needed.
2. Inspect and analyze a Grid graph
Use the smallest read-only sequence:
get_grid_capabilities {}
get_grid_graph {}
grid_analyze {}
get_grid_graph supplies the current graph identity and revision. grid_analyze
reports topology reachability, disconnected outputs, cycles, lanes, and
uncertainty. It does not prove that a patch produces a desired sound. Stop if
runtime_supported, graph_available, or the relevant catalog/connection
capability is false.
Use search_grid_modules, search_grid_modulators, and
get_grid_host_modulators to obtain current package and semantic-modulation
metadata. Do not infer a package UUID or port from a prose example or an old
inventory.
3. Make one direct graph change
Direct graph edits are appropriate for a small, explicit operation:
- Read
get_grid_graphimmediately before the write. - Confirm the exact package/module/port identities and graph revision.
- Submit one of
grid_insert_module,grid_insert_modulator,grid_set_module_parameter,grid_set_modulator_parameter,grid_connect_modules,grid_connect_modulator, orgrid_disconnect_modulewith thatexpected_revisionandconfirm: true(orcooperative: true). - Read
get_grid_graphand any relevant selected-device state. - Treat the result as complete only when the fresh read reports the expected module, parameter, or connection.
The graph revision is exact and bounded; a stale revision rejects the call. Coordinates are bounded to -4096..4096. Do not retry a timed-out mutation without reading first, because a host operation may have been submitted while its response was lost.
For a module move or destructive clear, use grid_move_module or
grid_clear_graph with the same fresh graph revision and authorization. A
clear is destructive even though the host exposes undo/redo; take a project
copy first.
4. Stage a multi-operation Grid patch
Use a patch session when the change needs a preview, multiple bindings, or controlled read-back:
grid_patch_startwith bounded node/connection intent. Include aliases, current instance IDs for existing nodes, and protected routes where needed.grid_patch_statusto inspectpreview, bindings, remaining steps, and the next action.- For each reviewed operation, call
grid_patch_stepwith the current integer session revision and authorization. The manager performs one operation and read-back at a time. - Re-read status after every step. A failed read-back, stale graph revision, or external graph change freezes the session for review.
- When a parameter-only session is completed, use
grid_patch_controlfor a named control orgrid_patch_restorefor a scoped original-value restore.
A patch session's integer session revision is not the same as the native graph
ID/revision. Keep both. The manager does not auto-replay, auto-rollback, or
silently repair an externally changed graph. grid_analyze can be used before
and after the session, but topology reachability is not an audio assertion.
5. Shape selected-device parameters
For exposed controls rather than graph topology:
- Read
get_selected_device_state. - Start
grid_shape_startwith a brief or one of the supported presets. - Revise with
grid_shape_composeand inspectgrid_shape_status. - Apply the reviewed integer revision using
grid_shape_applywithconfirmorcooperative. - Read selected-device state again.
- Use
grid_shape_undoonly for the parameter values recorded by this completed shaping session.
The MCP-facing selected-device parameter domain is 0–128; the native public
control representation is normalized 0–1. Do not send native normalized values
where the selected-device MCP schema expects 0–128. A snapshot saved by
save_parameter_snapshot is an in-memory process-local snapshot, not a project
backup.
6. Operate transport, tracks, and mix
Start with grid_song_state and grid_inspect_mix for the target track.
Record the fresh project token and mix revision. Then:
- use
grid_song_transportfor play, continue, restart, stop, seek, tempo, meter, or loop; - use
grid_set_track_stateforarmedand/ormuted; and - use
grid_set_mixfor a volume/gain, pan, or send control.
Every write must include the current token/expected value fields from the read. Recording and automated targets are guarded; unsupported combinations are rejected. Some loop-range changes require stopped transport. After each write:
- read
grid_song_stateorgrid_inspect_mix; - compare the observed value with the requested value; and
- only then continue or issue the next guarded write.
A response containing status: submitted or verified: false is expected for
these public calls. It means the request was accepted by the immediate proxy,
not that Bitwig has completed the operation.
7. Inspect and change devices
Use grid_list_devices to read the current device bank, selected device, and
selection token. A bank can be a bounded 16-sibling window; do not assume it
is the complete chain.
For a reviewed insertion or removal:
- obtain a fresh non-null selection token;
- use
search_grid_deviceswhen a UUID is needed; - call
grid_insert_devicewith a UUID and one ofbefore,after,start,end, orreplace, or callgrid_remove_device; - re-list devices and read selected state; and
- continue only when the expected chain is observed.
A stale or null selection token cannot authorize a mutation. Device insertion and removal are submitted public operations, not synchronous completion.
8. Use application actions deliberately
Call grid_list_actions with a narrow query, review the returned action IDs,
and invoke one with grid_invoke_action. The action catalog is not an
arranger, clip, automation, project-save, or delivery API. Do not manufacture
an action ID, and re-read affected state after an action that may mutate host
state.
9. Offline composition and export
Use this path when the desired deliverable is an offline MIDI artifact rather than a native Bitwig project:
grid_track_planwith a bounded brief and musical constraints.grid_track_startto create a process-local session.grid_track_statusto record the current salted 64-hex review revision.grid_track_revisewith that revision and one scope (role,section,phrase, orarrangement); status again after each revision.grid_track_exportwith the latest revision and an allowed output directory.- Verify the returned manifest's artifact SHA-256 and byte count before handing the artifact to another process.
The export is a real Type-1 Standard MIDI File (ppq=480) with a conductor
track and role tracks, plus a manifest.json carrying schema
bitwig-midi-artifact/1, plan metadata, byte count, and artifact digest. A
new revision invalidates older exports. The revision is a review-authority
token, not the MIDI content digest.
This workflow does not import the MIDI into Bitwig, create instruments, realize voices, render audio, or save/load/deliver a project. A later manual import is outside this bridge contract and must be evaluated separately.
10. Audio-file analysis and RMS comparison
Use grid_audio_analyze for one local regular file, with duration/size/channel
bounds appropriate to the task. Use grid_audio_compare for two files and
inspect the reported metrics and differences.
Optional output matching uses whole-file RMS attenuation only: choose the
quieter target and apply min(1, target/rms) to each source. No file is
amplified, and written WAVs are verified after encoding. This is not LUFS
normalization, perceptual approval, live capture, or Bitwig audio rendering.
Recovery and ambiguous results
When any mutation times out, disconnects, or returns an unexpected observation:
- do not retry the same mutation;
- read the relevant current state and token/revision;
- compare the observed state with the intended operation;
- if it was applied, record the new identity/revision and continue only from that state;
- if it was not applied, formulate a new guarded call from the fresh read; or
- if state is contradictory, stop and preserve the project for review.
A stale graph or patch-session revision freezes/rejects instead of permitting a blind replay. A stale project, mix, or selection token has the same purpose. Native global undo/redo is host-wide and can affect work outside the bridge; use it only with a deliberate project-copy and state-read procedure. Shaping session undo and patch scoped restore are narrower, but neither substitutes for a backup.
Unsupported native families
The following are intentionally absent from the current MCP contract:
- arranger note, clip, and automation editing;
- MIDI import or voice realization;
- live capture;
- audio rendering/export; and
- project save, new, load, or delivery.
Do not describe an offline MIDI file as an imported song, a graph analysis as a sound-quality proof, or an immediate host proxy observation as completion.