Documentation menu
On this page

This guide treats the bridge as an attended performance assistant. It can plan bounded soundscape intent, inspect and shape selected Grid devices, apply revision-guarded graph changes, expose transport/track/mix/device controls, and invoke reviewed native action IDs. The producer still chooses the arrangement and decides when a change is musical.

The source currently registers 57 MCP tools; the running tools/list and native protocol-4 capabilities responses remain authoritative. This page does not add arranger, clip, or project-delivery APIs.

The live-set model

A useful live set has three layers:

  1. Material: kick, bass, percussion, texture, cues, and returns with clear frequency and rhythmic jobs.
  2. Sections: a human-defined energy arc or scene plan.
  3. Agency: a small set of bounded gestures with a known neutral value.

Use grid_soundscape_plan for a non-mutating plan from a brief, then resolve all package/module/port identities against current native reads. A plan is not a project patch and does not create scenes, clips, or instruments.

Example plan request:

{
  "brief": "142 BPM minimal raw techno; stable kick and bass, sparse metallic accents",
  "style": "deep-bed",
  "density": 0.28,
  "motion": 0.38,
  "contrast": 0.55,
  "temperature": 0.35
}

Use grid_list_soundscape_styles for current styles. Planning output is an intent; it contains no durable native instance IDs, package UUIDs, or assumed track indexes.

Start from current state

Before each live pass:

  1. call get_grid_capabilities, get_selected_device_state, and grid_song_state;
  2. call grid_list_tracks when track indexes matter;
  3. call grid_list_devices for a target device chain; and
  4. call get_grid_graph and grid_analyze only when the selected device reports a supported graph.

Record the project token, track index, selection token, mix revision, and graph ID/revision from those reads. A null selection token can support public reads but cannot authorize device insertion/removal. A false graph_available is a hard boundary for graph work, not a reason to guess a module or cable.

Build the material layer

For each role, prefer the smallest operation that produces the intended result:

  • use grid_shape_start/grid_shape_compose for exposed selected-device parameters;
  • use search_grid_modules and search_grid_modulators for current package metadata;
  • use direct guarded graph tools for one insertion, parameter, connection, or movement; and
  • use grid_patch_start/grid_patch_step for a multi-operation topology change that needs preview and per-step read-back.

Read the graph immediately before each operation and again afterward. Keep kick and sub paths centered and mono; place width, feedback, and bright nonlinear detail above the useful bass register. These are producer design guidelines, not additional bridge guarantees.

A practical role order is:

Order Role Musical question
1 Kick Does the downbeat stay stable at the intended level?
2 Bass Does the bass interlock without masking the kick?
3 Percussion/tops Do rests and accents create groove rather than noise?
4 Texture Does motion preserve pulse and tonal center?
5 Returns/cues Does the effect mark a boundary without smearing it?

Design agency as a control contract

For every gesture, record:

Field Requirement
Destination One primary musical job, such as bass bite or transition depth.
Safe range The smallest meaningful range that does not lose the role.
Neutral A known value that restores the accepted groove.
Time scale A phrase, bar, or gesture duration.
Reset A clear action or return ramp to neutral.

Prefer one reviewed modulation route at a time. Use current live parameter metadata and exact graph revisions; historical package names and inventory counts are not substitutes for current catalog reads.

Use host controls safely

For transport, tracks, and mix:

  1. read grid_song_state and (for mix) grid_inspect_mix;
  2. use the fresh project token/mix revision for one guarded write;
  3. read state again; and
  4. continue only when the requested value is observed.

grid_song_transport supports play, continue, restart, stop, seek, tempo, meter, and loop. grid_set_track_state supports arm/mute. grid_set_mix supports gain/volume, pan, and sends. Track indices are 0..63; transport and normalized-value bounds are in the tool schema. Recording and automated targets are guarded.

Native public writes return submitted/immediate proxy observations. A verified: false response is expected and means a fresh read-back is required, not that the producer should immediately retry.

For devices, search with search_grid_devices, inspect the bounded bank with grid_list_devices, and use a fresh non-null selection token for grid_insert_device or grid_remove_device. Re-list after the operation. Positions are before, after, start, end, and replace.

For dynamic application gestures, call grid_list_actions with a focused query, review the exact returned action ID, and invoke it through grid_invoke_action. An action response proves invocation, not the musical result. Do not infer IDs from display labels or another Bitwig version.

Recovery and listening

Before a structural or parameter batch, save a parameter snapshot or preserve the current graph/project copy. Match recovery to the narrowest scope:

  1. grid_shape_undo for a completed shaping session;
  2. apply_parameter_snapshot for exposed controls;
  3. grid_patch_restore for a completed parameter-only patch session; or
  4. grid_project_undo only when the host-wide operation is understood.

After recovery, re-read state. For an ambiguous result, stop and read before retrying. During performance, use the planned neutral values rather than guessing a landing point.

State read-back cannot answer whether the music is compelling. Human listening is separate from bridge acceptance; no native audio capture or rendering tool is available.

Explicit capability boundaries

The bridge does not implement:

  • native arranger note, clip, or automation editing;
  • MIDI import or voice realization;
  • live capture;
  • audio rendering/export; or
  • project save, new, load, or delivery.

An action returned by the native action catalog does not change these declared boundaries. If a desired live-set step is not represented by current capabilities, stop at that boundary rather than claiming it was created.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.