Documentation menu
On this page

The Java extension exposes a newline-terminated text-command/JSON-response protocol on loopback. Scripts can use it without the Python MCP adapter. The MCP adapter adds JSON schemas, guarded authorization, preview sessions, offline composition, and audio-file analysis.

The native endpoint reports protocol 4. Private graph operations are supported only for the version/signature-checked Bitwig Studio 6.1.1 runtime and remain capability-gated. The source currently registers 57 MCP tools; inspect the running tools/list response rather than relying on a historical count.

Live-script prerequisites

  1. Install the extension and save work before deliberately restarting Bitwig after replacement.
  2. Confirm the local endpoint is the intended 127.0.0.1:8765 service.
  3. Read capabilities, state, and (when applicable) graph-state before mutating anything.
  4. Refresh all project, selection, mix, and graph identities before a guarded write.

A copied JAR/.bwextension is not proof that the running controller loaded the new code. A public ControllerHost restart can retain an old class definition in the same macOS session. Do not use a throwaway native attach probe. Native public writes are submitted/immediate proxy operations and require a fresh read-back before they are treated as complete.

Run the included example

From a source checkout or full release bundle:

python examples/automation/grid_bridge_demo.py inspect
python examples/automation/grid_bridge_demo.py graph

inspect is read-only and works for any selected device. graph is meaningful only for a supported selected Grid. The example also contains bounded, reversible selected-control and device demonstrations:

python examples/automation/grid_bridge_demo.py sweep --index 2 --minimum 0.2 --maximum 0.8 --duration 4
python examples/automation/grid_bridge_demo.py insert-fx-grid --position after --keep

Read the result and verify the current state before another operation.

Protocol shape

Open a TCP connection to 127.0.0.1:8765. Send one UTF-8 command line, not a JSON request, and read one JSON response line. Keep request/response order serialized. Examples:

ping
capabilities
state
inspect
song-state
graph-state

A response with ok: true means the command was accepted at the protocol layer. For public host writes, inspect the operation-specific status and then read song-state, mix-state, or devices again. A response with status: submitted and verified: false is not completion.

Minimal Python client

import json
import socket


def request(command: str):
    if not command or "\n" in command or "\r" in command:
        raise ValueError("Expected one command line")
    encoded = command.encode("utf-8") + b"\n"
    with socket.create_connection(("127.0.0.1", 8765), timeout=65.0) as connection:
        with connection.makefile("rwb") as stream:
            stream.write(encoded)
            stream.flush()
            line = stream.readline(8 * 1024 * 1024 + 1)
    if not line.endswith(b"\n"):
        raise RuntimeError("Missing or incomplete bridge response")
    response = json.loads(line)
    if not isinstance(response, dict) or response.get("ok") is not True:
        raise RuntimeError(f"Bridge request failed: {response!r}")
    return response


capabilities = request("capabilities")
state = request("state")
print(capabilities)
print(state)

A longer script may reuse one connection, but it must preserve order and close the connection on framing or timeout errors. Do not replay a timed-out mutation until a fresh read determines whether it was submitted.

Safe script structure

A mutation script should have explicit phases:

  1. Read capabilities and current state.
  2. Validate selected device, token/revision, IDs, indexes, and ranges.
  3. Record enough state for a deliberate scoped restore or recovery.
  4. Mutate exactly once.
  5. Read back and compare the observable result.

A rejection is a safety result. Do not turn it into a warning and continue.

Public host commands

The direct host forms map to the MCP host tools:

song-state
song-transport PROJECT_TOKEN tempo 120
track-state PROJECT_TOKEN 0 false keep
mix-state 0
mix-set PROJECT_TOKEN 0 MIX_REVISION volume 0.50 0.60
devices
device-catalog synth
device-insert end DEVICE_UUID SELECTION_TOKEN
device-remove SELECTION_TOKEN
actions transport
action ACTION_ID

Use exact values from fresh reads. Track indices are 0..63. Transport supports play/continue/restart/stop, seek 0..24576 beats, tempo 40..220 BPM, meter 2..12 over 4 or 8, and loop with a bounded optional range. Mix values are normalized 0..1 and guard the expected current value. Device insertion/removal requires a fresh non-null selection token; re-list devices after the submitted operation.

Exposed-control automation

The selected-device response contains exposed parameter indexes and values; indexes belong to that snapshot. For a bounded sweep:

  • native set INDEX VALUE uses 0–1; the MCP selected-device interface uses 0–128;
  • use a monotonic clock instead of accumulated sleep durations;
  • limit write frequency so Bitwig's host thread remains responsive;
  • restore the original value in finally unless the caller explicitly asks to keep it; and
  • stop when selection or state no longer matches the initial target.

Revision-guarded graph automation

Graph operations require graph_available: true and data from the latest graph-state/catalog response:

  • package UUIDs from the live catalog;
  • native instance/module IDs from the live graph;
  • exact parameter IDs and types;
  • exact port indexes/names; and
  • the current graph revision.

The native wire forms are:

graph-edit REVISION insert PACKAGE_UUID X Y
graph-edit REVISION insert-modulator PACKAGE_UUID X Y
graph-edit REVISION set MODULE_ID PARAMETER_ID_B64 VALUE
graph-edit REVISION set-modulator MODULE_ID PARAMETER_ID_B64 VALUE
graph-edit REVISION connect SOURCE_ID SOURCE_PORT TARGET_ID TARGET_PORT
graph-edit REVISION connect-modulator SOURCE_ID SOURCE_PORT TARGET_ID TARGET_PORT
graph-edit REVISION disconnect TARGET_ID TARGET_PORT
graph-edit REVISION move MODULE_ID X Y
graph-edit REVISION clear
graph-resolve REVISION MODULE_ID PARAMETER_ID DISPLAY_VALUE_B64

Coordinates are bounded to -4096..4096. Base64url-encode parameter IDs and resolver display text. Resolver display text is read-only and must be 1..256 characters. After insertion, connection, parameter, move, clear, or undo, request graph-state again; never issue dependent writes from the first snapshot.

Offline tools through MCP

The offline path is intentionally separate from the native socket. Use grid_track_plan, grid_track_start, grid_track_revise, grid_track_status, and grid_track_export for a process-local composition review. Export is a real Type-1 MIDI plus digest-bound manifest; it does not import MIDI, realize voices, create instruments, render audio, or save a Bitwig project.

Use grid_audio_analyze and grid_audio_compare for local files. Optional matching is whole-file RMS attenuation only and never amplifies a file. These tools do not capture from Bitwig or export a live render.

Explicit absences

No current native/MCP tool implements arranger note/clip/automation editing, MIDI import or voice realization, live capture, audio rendering/export, or project save/new/load/delivery. Do not recreate those APIs with guessed private calls, UI automation, or synthetic success responses.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.