Bitwig Grid Bridge Documentation
Documentation menu

Installation

On this page

For your first connection, follow Quickstart. This page covers installation choices, optional MCP setup, upgrades, and troubleshooting.

Requirements

  • Bitwig Studio 6.1.1 for native Grid, note, device and arranger operations
  • A local account able to write to the Bitwig Extensions directory
  • Python 3.10 or newer for the read-only verification script; it needs no extra packages
  • uv only for the optional Python MCP adapter
  • Java 21 and Maven only when building the extension from source

The runtime bridge binds to loopback only at 127.0.0.1:8765. It claims no MIDI ports and requires no external hardware.

0.2.0 is the extension/Python package version. Its private Grid, device, note and arranger bindings require exactly Bitwig Studio 6.1.1. Controller API 25 is the public minimum and compile-time dependency, not a promise of private compatibility with other Bitwig versions. Unknown private runtimes fail closed. See compatibility boundaries.

Install from a release bundle

For published versions, download the matching bitwig-grid-bridge-VERSION.zip full bundle from GitHub Releases. It includes the extension, verification script and deliberate public fixtures. If the required version is not available there, build from source.

Full bundle

Extract the ZIP and open a terminal in its top-level folder, alongside BitwigGridBridge.bwextension and INSTALL.txt. On Linux:

mkdir -p "$HOME/Bitwig Studio/Extensions"
cp BitwigGridBridge.bwextension "$HOME/Bitwig Studio/Extensions/"

On Windows, copy the extension into the Bitwig Studio Extensions folder under the current user's Documents directory instead.

Restart Bitwig, open Settings → Controllers, add Bitwig Grid Bridge, and enable it. Keep the extracted bundle: its examples/ folder supplies the verification script and sample projects.

Continue with Verify the extension. You do not need to install Python packages or start MCP for this check.

The bundle also includes the optional adapter, locked environment, Python distributions under python/, documentation, and source. Those are for later use; see Install the optional MCP adapter.

Standalone extension

If you only need the extension, download BitwigGridBridge.bwextension from the same release and copy it into your Extensions directory as above. Restart Bitwig and enable it in Settings → Controllers.

The standalone asset does not include the verification script. Get the matching full bundle or source checkout before following the command below.

Build from source

You need Git, Java 21, and Maven. Clone the repository and build from its root:

git clone https://github.com/critx-jt/bitwig-grid-bridge.git
cd bitwig-grid-bridge
mvn -f extension/pom.xml package

On Linux, install the built extension:

mkdir -p "$HOME/Bitwig Studio/Extensions"
cp extension/target/BitwigGridBridge.jar \
  "$HOME/Bitwig Studio/Extensions/BitwigGridBridge.bwextension"

With make available, the equivalent build-and-install command on Linux is:

make install-extension

Restart Bitwig, add and enable Bitwig Grid Bridge in Settings → Controllers, then continue below from the checkout root. The checkout already contains the verification script; uv sync is not required for it.

Verify the extension

Open a project and select a device. From the extracted full bundle folder or source checkout root — not the Extensions directory — run:

python examples/automation/grid_bridge_demo.py inspect

Use python3 if that is your Python 3 command. The script prints capabilities, selected-device inspection, and exposed controls as three JSON responses. Each successful response contains "ok": true. Confirm the extension/host/API match your installation and the inspected device matches the selection in Bitwig.

Reload is asynchronous: copying the extension is not a readiness check. Use this read-only result before any mutation. For help interpreting it, see Quickstart or Troubleshooting.

For a supported selected Grid:

python examples/automation/grid_bridge_demo.py graph

If graph_available: false, the connection can still work for exposed controls, but graph operations are unavailable for that selection. Select a supported Grid or stay with exposed-control commands. A successful inspection is a complete first check; there is no need to change your project.

Install the optional MCP adapter

Add MCP only when you want an agent or client to call the tools. For live work, verify the direct bridge first. Offline composition and artifact export can run without Bitwig.

Install the adapter and extension from the same release. With Python 3.10+ and uv installed, run from the matching checkout or full bundle:

uv sync --frozen

Start the adapter for either offline composition or live work:

BITWIG_MCP_GRID_BRIDGE_ENABLED=true uv run bitwig-mcp

uv run python -m bitwig_mcp_server remains equivalent. The bitwig-mcp console command is included in built Python distributions.

Example MCP client configuration:

{
  "mcpServers": {
    "bitwig-grid-bridge": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/bitwig-grid-bridge", "bitwig-mcp"],
      "cwd": "/absolute/path/to/bitwig-grid-bridge",
      "env": {
        "BITWIG_MCP_GRID_BRIDGE_ENABLED": "true",
        "BITWIG_MCP_LOG_LEVEL": "WARNING"
      },
      "timeout": 120000
    }
  }
}

Use an absolute path. The default bridge-only adapter tolerates an unavailable Bitwig connection at startup; it does not fabricate live state or silently fall back to OSC. Device/Grid catalogs served by the extension still need Bitwig. Offline style catalogs and the installed Nitro archive are separate sources.

After this launch check, stop the terminal process with Ctrl+C and let your MCP client launch it using the configuration above. Continue with the Agent integration reference before following MCP tool sequences in producer workflows.

Optional read-only Nitro evidence

Install the pinned extra only when local DSP research is needed:

uv sync --frozen --extra nitro

The extra pins bitwig-nitro-tools at a34c1d61c7e48b1531fb3fba5e4c06d9e1e0cf16. grid_nitro_status reports readiness; search_grid_nitro can list the installed ZIP catalog without the extra or keys. BITWIG_NITRO_IMAGE can select a local nitro-image.

inspect_grid_nitro requires the extra and already obtained, authorized local keys: BITWIG_NITRO_KEYS points to upstream-format keys.json containing nitro_image_key, or BITWIG_NITRO_IMAGE_KEY supplies its hex value. Do not put keys in prompts, tracked files, or logs. This adapter never extracts keys, installs an extraction controller, executes DSP, or modifies Bitwig. See Nitro evidence for discovery order and limits.

Upgrade

  1. Stop the MCP adapter if you use it.
  2. Replace BitwigGridBridge.bwextension with the new release asset.
  3. Restart Bitwig, then run the read-only inspect check from the matching bundle or checkout.
  4. If you use MCP, update its checkout or bundle to the same release, run uv sync --frozen, and reconnect the client so its tool catalog and schemas refresh from the new adapter. Version 0.2.0 exposes 90 tools.
  5. Read capabilities again before any live change.

Copying the JAR/.bwextension is not a readiness signal: Java extension reload is asynchronous. Wait for read-only capabilities from the expected extension, exact Bitwig 6.1.1 and API 25 before mutation. A successful adapter startup is not proof that the new native extension is active. Never probe readiness with a write or retry an ambiguous mutation after timeout.

Do not carry graph revisions, native device/clip IDs, selection/project tokens, snapshot names, shaping/patch sessions, song revisions or import receipt authority across an upgrade. Keep exported files as artifacts, not as permission to replay an earlier import.

Troubleshooting

Extension does not appear

  • Confirm the filename ends in .bwextension.
  • Confirm it is in the current user's Bitwig Extensions directory.
  • Restart Bitwig after copying it.
  • Inspect Bitwig's controller-extension log for Java loading errors.
  • Confirm the release targets Controller API 25 and the installed Bitwig version supports it.

Bridge unavailable at startup

  • Confirm Bitwig is running and Bitwig Grid Bridge is enabled.
  • Run the direct inspect command before starting MCP.
  • Confirm no second Bitwig instance or stale process owns port 8765.
  • Keep host and port at the defaults unless the extension and adapter are changed together.

MCP client times out

Run the adapter manually from a terminal and inspect stderr. A healthy stdio process stays open, including in offline planning mode; stdout is reserved for MCP messages. A live tool's “bridge unavailable” error is not an MCP initialization failure. Fix the extension or port before live calls rather than repeatedly issuing mutations.

OSC controller is installed but MCP still fails

OSC is not the supported MCP transport. Install and enable Bitwig Grid Bridge for live tools. Legacy OSC compatibility is explicitly opt-in, never an automatic fallback; enabling it changes startup behavior and does not provide the native Grid or song contracts.

Search docs

All words must match. Enter opens the first result.

Type a tool, argument, or guard to begin.