Automation scripts
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
- Install the extension and save work before deliberately restarting Bitwig after replacement.
- Confirm the local endpoint is the intended
127.0.0.1:8765service. - Read
capabilities,state, and (when applicable)graph-statebefore mutating anything. - 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:
- Read capabilities and current state.
- Validate selected device, token/revision, IDs, indexes, and ranges.
- Record enough state for a deliberate scoped restore or recovery.
- Mutate exactly once.
- 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 VALUEuses 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
finallyunless 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.