Documentation menu
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

  1. Confirm the intended MCP process and checkout.
  2. Call get_grid_capabilities, get_selected_device_state, and grid_song_state.
  3. Call get_grid_graph only when the capability response says the selected device has a supported graph.
  4. For native host work, record the current project token, track index, mix revision, and selection token returned by the reads.
  5. 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:

  1. Read get_grid_graph immediately before the write.
  2. Confirm the exact package/module/port identities and graph revision.
  3. Submit one of grid_insert_module, grid_insert_modulator, grid_set_module_parameter, grid_set_modulator_parameter, grid_connect_modules, grid_connect_modulator, or grid_disconnect_module with that expected_revision and confirm: true (or cooperative: true).
  4. Read get_grid_graph and any relevant selected-device state.
  5. 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:

  1. grid_patch_start with bounded node/connection intent. Include aliases, current instance IDs for existing nodes, and protected routes where needed.
  2. grid_patch_status to inspect preview, bindings, remaining steps, and the next action.
  3. For each reviewed operation, call grid_patch_step with the current integer session revision and authorization. The manager performs one operation and read-back at a time.
  4. Re-read status after every step. A failed read-back, stale graph revision, or external graph change freezes the session for review.
  5. When a parameter-only session is completed, use grid_patch_control for a named control or grid_patch_restore for 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:

  1. Read get_selected_device_state.
  2. Start grid_shape_start with a brief or one of the supported presets.
  3. Revise with grid_shape_compose and inspect grid_shape_status.
  4. Apply the reviewed integer revision using grid_shape_apply with confirm or cooperative.
  5. Read selected-device state again.
  6. Use grid_shape_undo only 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_transport for play, continue, restart, stop, seek, tempo, meter, or loop;
  • use grid_set_track_state for armed and/or muted; and
  • use grid_set_mix for 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:

  1. read grid_song_state or grid_inspect_mix;
  2. compare the observed value with the requested value; and
  3. 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:

  1. obtain a fresh non-null selection token;
  2. use search_grid_devices when a UUID is needed;
  3. call grid_insert_device with a UUID and one of before, after, start, end, or replace, or call grid_remove_device;
  4. re-list devices and read selected state; and
  5. 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:

  1. grid_track_plan with a bounded brief and musical constraints.
  2. grid_track_start to create a process-local session.
  3. grid_track_status to record the current salted 64-hex review revision.
  4. grid_track_revise with that revision and one scope (role, section, phrase, or arrangement); status again after each revision.
  5. grid_track_export with the latest revision and an allowed output directory.
  6. 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:

  1. do not retry the same mutation;
  2. read the relevant current state and token/revision;
  3. compare the observed state with the intended operation;
  4. if it was applied, record the new identity/revision and continue only from that state;
  5. if it was not applied, formulate a new guarded call from the fresh read; or
  6. 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.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.