Data and safety
On this page
The bridge is a guarded adapter, not a project database. Values returned by a read describe one current native/session observation. Preserve the identity and revision that came with a value; do not combine fields from older reads.
Authority and capability layers
The native extension reports protocol 4 and version-gated capability flags.
Its direct endpoint is local (127.0.0.1:8765) and uses a newline-delimited
request/one-JSON-response protocol. The private Grid graph layer is checked
against Bitwig 6.1.1 class and method signatures and fails closed on an
unsupported runtime. Public host controls can be available while the private
grid_graph is unavailable.
A capability response can distinguish:
- native host scheduling and application actions;
- song state and transport;
- track state, mix controls, and device inventory/mutations;
- Grid graph inspection, catalogs, insertion, parameters, connections, revision guards, display-value resolution, and native undo; and
- runtime support for the selected device.
graph_available is selection- and runtime-dependent. It is not implied by a
package version or by a historical catalog count. tools/list is the
MCP-layer authority for the running server; native capabilities is the
extension-layer authority.
Non-interchangeable identities
The following values have different scopes and must never be substituted:
| Identity | Scope | Use |
|---|---|---|
| Project token | Current native song/project process | Guards transport, track, mix, and related public host operations. |
| Selection token | Current device-bank/selection observation | Guards device insertion/removal. A null token cannot authorize a write. |
| Mix revision | Current target-track mix observation | Guards gain/pan/send writes together with expected control value. |
| Graph ID | Current selected Grid document/graph | Identifies the graph from which module and port identities were read. |
| Graph revision | Current native graph topology/parameter revision | Guards graph edits, move, clear, and display-value resolution. |
| Native module ID / instance ID | One current graph node | Identifies an existing node; it is not a catalog package ID. |
| Shaping revision | One process-local shaping session | Guards grid_shape_apply and session status/undo. |
| Patch session revision | One process-local patch session | Guards grid_patch_step, control, and restore. |
| Composition revision | One process-local offline composition review | Guards revise/status/export; it is salted review authority, not content hash. |
| Artifact SHA-256 | One exported MIDI or audio artifact | Binds verification to exact bytes; it is not a session revision. |
| Action ID | One current native action catalog entry | Identifies an action returned by grid_list_actions. |
Most guarded tokens are lower-case 64-hex strings, but their meaning remains scope-specific. Tokens are process-local or observation-local unless the response explicitly says otherwise; they are not durable project IDs.
Read-before-write contract
A guarded operation follows this sequence:
- read current state and capabilities;
- retain the relevant token/revision and expected current value;
- submit one authorized operation;
- read state again; and
- continue only if the fresh read verifies the intended result.
Graph writes also require exact current native module/port identities and a
fresh graph revision. Graph coordinates are bounded to -4096..4096. Host writes
require confirm: true or cooperative: true at the MCP layer in addition to
the operation-specific token fields.
Public native host writes use a submitted/immediate-proxy contract. A normal response can contain:
{
"status": "submitted",
"verified": false,
"observation": "immediate_proxy_read_not_completion"
}
The observation can be useful for diagnosing a request, but it is not a completion event. This applies to transport, track arm/mute, mix, and device writes. The next read is the authority. A lost response must not trigger a blind retry.
Native host domains and guards
Song and transport
grid_song_state reports the project token, transport, recording state, track
state, and public capabilities. grid_song_transport accepts play,
continue, restart, stop, seek, tempo, meter, and loop with the
current project token. Bounds are:
- seek position: 0..24576 beats;
- tempo: 40..220 BPM;
- meter numerator: 2..12; and
- meter denominator: 4 or 8.
Loop range fields must describe a valid current range; changing some loop ranges requires stopped transport. Playback, seek, tempo, meter, and loop operations reject unsupported recording conditions instead of guessing.
Tracks and mix
Track indices are 0..63. grid_set_track_state changes muted and/or
armed using the current project token. grid_inspect_mix reports a target
track's mix revision, controls, and capabilities. grid_set_mix guards the
project token, mix revision, control ID, expected normalized value, and new
normalized value. Current controls include gain/volume, pan, and sends;
automated targets are rejected. Native normalized values are 0..1.
The selected-device shaping interface is separate: its MCP-facing exposed parameter domain is 0..128, while its native control representation is 0..1. Do not transfer a value between those APIs without the documented conversion.
Devices and actions
grid_list_devices returns a bounded device bank, selected device, and a
selection token. The bank can be a 16-sibling window and may not be the entire
chain. grid_insert_device uses a catalog UUID and a position (before,
after, start, end, or replace); grid_remove_device removes the
selected device. Both require a fresh non-null selection token and are
submitted operations. Re-list and inspect state after the write.
grid_list_actions returns current native application action IDs. An action ID
is valid only for the catalog observation that returned it. Review the ID and
re-read any affected state after grid_invoke_action. Actions do not add
arranger, automation, or project-delivery capabilities.
Graph model
The graph response includes a graph ID, 64-hex native graph revision, native module/instance IDs, package metadata, coordinates, typed parameters, ports, and current connections. Catalog package IDs describe insertable definitions; native instance IDs describe nodes already in the graph. Port names and parameter IDs come from the current graph/catalog response.
The graph mutation set is:
- insert module or modulator;
- set module or modulator parameter;
- connect module or modulator;
- disconnect a target module port;
- move one module; and
- clear the graph.
Every mutation checks the exact expected revision at submission. A stale
revision rejects the operation. grid_resolve_parameter_value is read-only:
it resolves a user-facing display value through the current native parameter
definition and does not itself mutate a parameter. Native graph capability
flags include revision guards and display-value resolution when supported.
grid_analyze describes active topology reachability, cycles, disconnected
outputs, lanes, and uncertainty. It is not a waveform, mix, or perceptual
sound-quality measurement.
Session models
Shaping sessions
A shaping session has a process-local ID and integer revision. Start and compose produce a preview; apply requires the current revision and explicit authorization. Session undo restores only parameter values recorded by that session. Named parameter snapshots are process-local memory, not project files.
Patch sessions
A patch session has a process-local session ID and integer session revision,
plus the native graph ID/revision observed for each operation. The manager
limits nodes and operations, performs one step with read-back, and reports
preview, completed, or frozen. An external graph change, stale revision,
or failed verification freezes the session. It does not auto-replay or
rollback. Control staging and restore are allowed only for a completed
parameter-only session; restore is scoped to recorded parameters.
Composition sessions
Composition sessions are offline and do not mutate Bitwig. Plan/start/revise
accept bounded musical intent. Revise requires a current 64-hex review
revision and a scope (role, section, phrase, or arrangement); each new
revision invalidates previous exports.
Export writes a private unique directory containing a real Type-1 Standard
MIDI File (ppq=480) and manifest.json. The manifest schema is
bitwig-midi-artifact/1 and includes plan metadata, byte count, and the
artifact SHA-256. The export has no instrument definitions, native voice
realization, audio, or project-save semantics.
Audio observations
Audio analysis is offline and file-based. Inputs must be local regular files within configured size, duration, and channel bounds. The returned metrics include digest, sample rate, channels, frames, RMS, peak, clipping/silence, envelope/tail RMS, low-band information, and channel metrics.
Comparison's optional match operation is whole-file RMS attenuation only. It
chooses the quieter target and applies min(1, target/rms) to each file; no
file is amplified. Output WAVs are checked after writing. These metrics do not
claim LUFS normalization, perceptual approval, live capture, or Bitwig audio
rendering.
Revisions, failure, and recovery
A stale token or revision is a safety signal. On rejection, timeout, or an unexpected observation:
- stop issuing mutations;
- read the relevant current state and capability response;
- determine whether the original operation was applied;
- if applied, continue from the new identity/revision; and
- if not applied, formulate one new guarded operation from the fresh read.
Native global undo/redo is host-wide and may affect work outside the bridge. Shaping undo and patch scoped restore are narrower. Neither is a substitute for a backup or project copy.
Deliberate absences
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 offline MIDI artifact is not an imported song. A successful graph mutation is not a sound-quality proof. A submitted host observation is not completion.