Quickstart
On this page
Get from an installed extension to a read-only live-device check without setting up MCP. This first check does not change your project or start playback. Already installed? Skip to Verify the connection.
1. Check prerequisites
You need:
- Bitwig Studio 6.1.1 for the version-gated native Grid surface. The public bridge requires Controller API 25; see compatibility.
- Python 3.10 or newer for the verification script. It uses the standard
library; no
uv, Python packages, or MCP client are needed for this check. - The full release bundle, which supplies both the extension and the
examples/automation/grid_bridge_demo.pyscript. - A local account that can write to the Bitwig Studio Extensions directory.
Keep a project copy for experiments. Download the matching
bitwig-grid-bridge-VERSION.zip from GitHub Releases,
replace VERSION with the release number you downloaded, extract it, and open a
terminal in its top-level folder. If the required release is not available, use
the advanced source-build alternative below.
The standalone .bwextension does not include the script. If you installed
that asset, get the matching full bundle or a source checkout before continuing.
2. Install the extension
The commands below assume that your terminal is already in the extracted bundle
folder and that BitwigGridBridge.bwextension is at its top level. Open the
disclosure for your platform; no JavaScript tabs or MCP setup are required.
macOS
mkdir -p "$HOME/Documents/Bitwig Studio/Extensions"
cp BitwigGridBridge.bwextension \
"$HOME/Documents/Bitwig Studio/Extensions/BitwigGridBridge.bwextension"
Linux
mkdir -p "$HOME/Bitwig Studio/Extensions"
cp BitwigGridBridge.bwextension "$HOME/Bitwig Studio/Extensions/"
Windows PowerShell
Run from the extracted bundle folder:
$extensions = Join-Path $HOME 'Documents\Bitwig Studio\Extensions'
New-Item -ItemType Directory -Force $extensions | Out-Null
Copy-Item .\BitwigGridBridge.bwextension (Join-Path $extensions 'BitwigGridBridge.bwextension')
Advanced: build from source
A release bundle is the shortest path. For a source checkout, the direct read-only check still needs only Python; the build itself needs Java 21 or newer and Maven.
On macOS or Linux, make install-extension is the supported build-and-install
path from the checkout root. The Makefile selects
~/Documents/Bitwig Studio/Extensions on macOS and
~/Bitwig Studio/Extensions on Linux:
git clone https://github.com/critx-jt/bitwig-grid-bridge.git
cd bitwig-grid-bridge
make install-extension
For a nonstandard macOS or Linux destination, pass an absolute path:
make install-extension BITWIG_EXTENSIONS_DIR="/absolute/path/to/Extensions"
On Windows PowerShell, use Maven and copy the resulting extension explicitly;
the Unix make install-extension path does not select a Windows directory:
git clone https://github.com/critx-jt/bitwig-grid-bridge.git
Set-Location bitwig-grid-bridge
mvn -B -f extension/pom.xml package
$extensions = Join-Path $HOME 'Documents\Bitwig Studio\Extensions'
New-Item -ItemType Directory -Force $extensions | Out-Null
Copy-Item .\extension\target\BitwigGridBridge.jar (Join-Path $extensions 'BitwigGridBridge.bwextension')
Keep the terminal in the checkout root for the verification command below.
uv is only needed later if you choose the optional MCP server.
After the copy or source build:
- Save your work in Bitwig, then fully restart Bitwig. A public
ControllerHost.restartcan retain an already loaded class definition and is not proof that a replacement was loaded. - Open Settings → Controllers, add Bitwig Grid Bridge if it is not listed, and enable it. Keep only one enabled bridge controller instance.
- Open a project and select the device you want to inspect. A project from
examples/projects/is a useful starting point, but device names vary.
Do not use a mutation or a throwaway native attach probe to test whether the extension loaded. The read-only check is the readiness test.
3. Verify the connection
Run the included client from the bundle folder or checkout root, not from
the Extensions directory. It connects to the local endpoint
127.0.0.1:8765 and makes three read-only requests.
On macOS or Linux:
python3 examples/automation/grid_bridge_demo.py inspect
If python3 is not your Python 3 command, use python instead. In Windows
PowerShell, use the Python launcher or the installed python command:
py -3 examples\automation\grid_bridge_demo.py inspect
What success looks like
The script prints three JSON responses in this order: capabilities, selected
device inspect, and selected-device state. Confirm these schema fields;
the values below are a representative field checklist, not captured output:
| Response | Required fields to inspect |
|---|---|
capabilities |
ok: true, protocol: 4, host_version, host_platform, and graph_available |
inspect |
ok: true, exists: true, name, and device_type |
state |
ok: true, exists: true, name, device_type, selection, and parameters |
Each parameters entry exposes the fields index, exists, name, value,
and display. The selected name and device_type must describe the device
currently selected in Bitwig; do not compare them with a fixed fixture name.
The supported host is Bitwig 6.1.1, while host_version and host_platform
report what the running extension sees.
The connection is successful when all three responses contain ok: true, the
capabilities response reports protocol: 4, and the inspect/state identity
fields match the selected Bitwig device. Stop here if you only need the direct
bridge; no MCP setup or project mutation is necessary.
If any response is missing, has ok: false, reports a protocol other than 4,
or reports exists: false for the device you selected, stop and use If
something fails before doing anything else. A
graph_available: false response is not a failed bridge connection, but it is
a hard stop for graph inspection or graph edits: select a supported Grid or use
only the public controls whose capability flags are true.
If the selected device is a supported Grid, this optional read-only command shows its graph capability and, when available, modules and connections:
On macOS or Linux:
python3 examples/automation/grid_bridge_demo.py graph
In Windows PowerShell:
py -3 examples\automation\grid_bridge_demo.py graph
graph_available: false does not mean the bridge connection failed. Do not
invent graph modules, ports, cables, or revisions when the graph is unavailable.
Optional next musical step: in a project copy, follow the Minimal techno quickstart to build a short loop; it identifies which steps stay in Bitwig and where optional bridge or agent tools can help.
4. Script-based interaction
Use Automation scripts for direct commands, including bounded parameter sweeps. Read each command's effect and recovery behavior before running it on a copy of your project. Treat every later mutation as observe → preview → apply → verify, and read state after an ambiguous result before retrying.
5. MCP-based interaction
MCP is optional. If you want natural-language briefs or MCP workflows, first
read the MCP startup and client configuration guide,
then follow Install the optional MCP server.
The direct inspect check above should already succeed before you attempt live
MCP calls.
After the client starts, call tools/list and begin with the read-only calls
get_grid_capabilities, get_selected_device_state, and grid_song_state. Stop
before any mutation if the intended checkout, tools/list, native capabilities,
or selected state do not match. Only then use the MCP sequences in Producer
workflows.
The adapter can also compose and export MIDI offline. Starting it without Bitwig does not establish a live connection; inspect again before live work. Offline export is an artifact and does not import a project, realize voices, render audio, or save Bitwig.
If something fails
| What you see | Next step |
|---|---|
| Script file not found | Open a terminal in the extracted full bundle or checkout root, not the Extensions directory. |
| Python command not found | Install Python 3.10+ or use your system's python3, python, or Windows py -3 command. |
| Extension cannot be enabled | Confirm the .bwextension is in the platform directory above, keep one bridge controller instance, save work, fully restart Bitwig, and enable it again. |
| Bridge unavailable / connection refused | Confirm Bitwig is running and the extension is enabled. Check that no second instance owns 127.0.0.1:8765, then retry the read-only inspect check. |
ok is false or protocol is not 4 |
Stop. Confirm the running extension and host match the supported installation; do not test with a mutation. |
exists is false or the name/type is wrong |
Select the intended device in Bitwig, then rerun the read-only inspect command. Device names vary. |
| Wrong version or device | Confirm the installed release, supported Bitwig version, and selected device before continuing. |
| Graph unavailable | Select a supported Grid, or use exposed-control commands instead. Do not invent graph identities or revisions. |
For loading errors and adapter problems, see Activation and troubleshooting. If a later mutation times out, stop and observe state; do not repeat it.