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

  1. Observe capabilities and current state.
  2. Plan one audible or structural result.
  3. Preview when the tool offers a preview.
  4. Authorize one guarded mutation.
  5. Read back and compare the observed result.
  6. 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:

  1. grid_shape_start with a brief or supported preset;
  2. grid_shape_compose for bounded revisions;
  3. grid_shape_status to review the integer revision;
  4. grid_shape_apply with that revision and confirm or cooperative;
  5. get_selected_device_state for read-back; and
  6. grid_shape_undo only 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:

  1. read get_grid_graph immediately before the operation;
  2. obtain package IDs, module IDs, parameter IDs, and ports from that read;
  3. submit one graph mutation with its exact expected_revision and explicit confirm/cooperative authorization; and
  4. 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:

  1. grid_patch_start with bounded nodes, connections, and protected routes;
  2. grid_patch_status to review preview bindings and remaining steps;
  3. one grid_patch_step at a time with the current session revision;
  4. status/read-back after every step; and
  5. grid_patch_control or grid_patch_restore only 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; and
  • grid_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:

  1. call grid_track_plan with a bounded brief;
  2. call grid_track_start for a process-local review session;
  3. inspect grid_track_status and retain its current 64-hex revision;
  4. use grid_track_revise for one role/section/phrase/arrangement scope at a time, then recheck status; and
  5. call grid_track_export with 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:

  1. stop issuing mutations;
  2. read current state and capability flags;
  3. determine whether the original request was applied;
  4. if applied, continue with the new token/revision; and
  5. 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.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.