# Bitwig Studio Gemini Agent Bridge (MCP)

This project provides a direct integration bridge between **Gemini (via Model Context Protocol - MCP)** and **Bitwig Studio (via Open Sound Control - OSC)**. It allows an AI agent or the Gemini client to manage, control, and monitor your Bitwig Studio projects in real-time.

---

## 🏗️ Architecture

```
┌──────────────────────────┐             ┌─────────────────────────┐             ┌─────────────────────────┐
│                          │  JSON-RPC   │  Node.js MCP Server     │  OSC / UDP  │  Bitwig JS Controller   │
│  Gemini Client / IDE     │ ──────────> │                         │ ──────────> │                         │
│                          │ <────────── │  (mcp-server.js)        │ <────────── │  (AntigravityController)│
└──────────────────────────┘   (Stdio)   └─────────────────────────┘ (Ports 9000/9001) └───────────────────┘
                                                                                              │
                                                                                              │ Bitwig Controller API
                                                                                              ▼
                                                                                  ┌─────────────────────────┐
                                                                                  │  Bitwig Studio DAW      │
                                                                                  └─────────────────────────┘
```

The bridge consists of two main components:
1. **Node.js MCP Server**: Listens to Gemini commands over standard input/output, maps them to OSC messages, and sends them to Bitwig over UDP. It also starts a UDP receiver to get real-time status updates (playback, track volume, solo, mute) from Bitwig.
2. **Bitwig Controller Script**: A JavaScript extension loaded directly inside Bitwig Studio that opens a UDP socket (port `9000`) to receive OSC commands, executes actions natively using the Bitwig Controller API, and pushes state changes back to Node.js (port `9001`).

---

## 📂 Project Structure

```
/home/bedri/Bitwig Studio/Projects/BitWig/
├── package.json                   # Project manifest (dependencies: node-osc)
├── package-lock.json              # Package lockfile
├── mcp-server.js                  # Node.js MCP server (Stdio JSON-RPC bridge)
├── start-mcp.sh                   # Executable launcher script
└── README.md                      # This documentation

/home/bedri/Bitwig Studio/Controller Scripts/
└── AntigravityController.control.js   # Extension script loaded by Bitwig Studio
```

---

## 🚀 Setup & Activation

The project has been automatically deployed, but here are the configuration references:

### 1. Gemini MCP Registration
The server is registered in your local Gemini Configuration file (`~/.gemini/config/mcp_config.json`) under the `bitwig-agent` key:

```json
"bitwig-agent": {
  "command": "node",
  "args": [
    "/home/bedri/Bitwig Studio/Projects/BitWig/mcp-server.js"
  ]
}
```

### 2. Enable in Bitwig Studio
1. Launch **Bitwig Studio**.
2. Open the dashboard (click the Bitwig logo at the top center) and navigate to **Settings > Controllers**.
3. Click **Add Controller**.
4. Set **Vendor** to `Antigravity` and **Model** to `Gemini Controller Bridge`.
5. The extension will automatically bind, starting the UDP servers on ports `9000` (listening) and `9001` (sending).

---

## 🛠️ Supported Tools & Commands

Gemini is equipped with the following tools through this MCP server:

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `get_state` | *None* | Retrieves transport play state, BPM, arranger loop status, and list of existing tracks. |
| `play` | *None* | Starts playback in Bitwig. |
| `stop` | *None* | Stops playback. |
| `record` | *None* | Toggles arranger recording. |
| `toggle_loop` | *None* | Toggles the arranger loop. |
| `set_tempo` | `bpm` (number) | Adjusts the project tempo (e.g. `128.5`). |
| `set_track_volume`| `track_index` (int), `volume` (float 0.0 - 1.0) | Sets the volume level of a track. |
| `set_track_pan` | `track_index` (int), `pan` (float 0.0 - 1.0) | Adjusts the panning of a track (0.5 is center). |
| `set_track_mute` | `track_index` (int), `mute` (bool) | Mutes/unmutes a track. |
| `set_track_solo` | `track_index` (int), `solo` (bool) | Solos/unsolos a track. |
| `set_track_arm` | `track_index` (int), `arm` (bool) | Arms/disarms a track for recording. |
| `launch_scene` | `scene_index` (int) | Launches a scene by index. |
| `undo` | *None* | Executes native Undo. |
| `redo` | *None* | Executes native Redo. |

---

## 💬 Example Prompts

You can now command your DAW in natural language:
* *"Start playback in Bitwig"*
* *"Set the project BPM to 124"*
* *"Mute track 2 and solo track 0"*
* *"Get the current tracks list and their volumes"*
* *"Turn arranger loop on"*
* *"Undo the last action"*

---

## 🔍 Troubleshooting

### Flatpak Network Permissions
Because Bitwig is packaged as a Flatpak on your Linux system, it runs in a sandbox. If the OSC connection fails, grant Bitwig permission to share the host's loopback network interface by running the following command:

```bash
flatpak override --user --share=network com.bitwig.BitwigStudio
```