# FL Studio 2025 AI Bridge (fLMCP-2025)

A **Model Context Protocol (MCP) bridge** that lets an AI assistant (Claude, or
any MCP client) **read and control FL Studio** — extended to actually work on
**FL Studio 2025 (build 25.2.5)**, whose locked-down control-script sandbox
breaks every socket-based FL bridge.

> ### Attribution
> This project is a **derivative of [geezoria/FLStudioMCP](https://github.com/geezoria/FLStudioMCP)** (MIT),
> which provides the 159-tool MCP server and the FL-side device script. All
> original credit goes to that project — see [`LICENSE`](LICENSE). This repo adds
> the **FL Studio 2025 compatibility layer** and a few new capabilities (below).

---

## Why this fork exists

On FL Studio 2025 build 25.2.5, control-surface scripts run in a CPython
**sub-interpreter that blocks threads, sockets, and most `os` filesystem calls,
and never calls `OnIdle`** — so the upstream TCP bridge cannot even open its
port. Full diagnosis (with every error, reproduced): [`docs/FL2025_SANDBOX.md`](docs/FL2025_SANDBOX.md).

This fork makes the bridge work anyway, using only the primitives FL 2025
*does* allow:

| Addition | What it does |
|----------|--------------|
| **file-RPC transport** | Request/response over two fixed JSON files (read/write only — no sockets, threads, `mkdir`, `rename`, `unlink`, or `glob`). Enable with `FLMCP_TRANSPORT=file`. |
| **MIDI-wake** | `OnIdle` is dead on this build, so the server sends a tiny MIDI note to the loopback port; FL's `OnMidiIn` (driven by the MIDI engine) fires and pumps the request. |
| **`meta.exec` escape hatch** | Runs arbitrary Python in the live controller interpreter, exposing **all ~250 FL API functions** (not just the ~159 wrapped handlers). Powers the helpers below and the API mapping in the docs. |
| **`pianoroll_apply` (exact note editing)** | FL sandboxes pyscript file I/O, so the notes are **baked into the piano-roll script's source**, deployed, and run via the "run last script" hotkey. Sample-accurate composition — no recording jitter. |
| **`globalTransport` clip placement** | FL exposes no `placePattern`, and `ui.paste` doesn't touch clips — but `transport.globalTransport(FPT_Copy/FPT_Paste)` **does** drive the playlist clipboard. Bridge-only clip placement, playhead-accurate in time. |
| **Note recording** | `channels.triggerNote` while recording writes **pitched notes** into the piano roll/timeline. Good for sparse phrases and song-mode arrangement. |
| **"Ears" (example)** | Play a pattern → capture FL's live output via WASAPI loopback → analyse tempo/key/loudness/brightness with `librosa`. See [`examples/`](examples). |

The high-level helpers live in [`src/fl_studio_mcp/producer.py`](src/fl_studio_mcp/producer.py):
`fl_exec`, `pianoroll_apply`, `record_performance`, `arrange_via_recording`,
`copy_clip_range` / `paste_clips_at` / `duplicate_clip_range`.

Verified end-to-end on FL Studio 2025 build 25.2.5: reads, transport/mixer
control, step-sequencer beats, tempo, **exact piano-roll note editing**, note
recording, **playlist clip placement**, and audio analysis — i.e. the full
compose → arrange → listen loop, plus a complete phonk beat built and arranged
purely through the bridge.

## Quick start (Windows, FL Studio 2025)

```powershell
git clone https://github.com/Boyan253/fl-studio-2025-ai-bridge.git
cd fl-studio-2025-ai-bridge
./scripts/install_windows.ps1
```

Then in FL Studio:
1. Install **[loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)** and create a port (e.g. `loopMIDI Port`).
2. `Options > MIDI settings > Input`: select the loopMIDI port and set **Controller type = `fLMCP Bridge`** (it appears in the **"Scripts"** section near the top — *not* alphabetically).
3. Set **`FLMCP_TRANSPORT=file`** in your MCP client's env for this server (and `FLMCP_MIDI_PORT` if your port name differs from `loopMIDI`).

Smoke test:
```powershell
$env:FLMCP_TRANSPORT="file"
.\.venv\Scripts\python.exe scripts\smoke_test.py
```

## What works vs. doesn't on FL 2025 25.2.5

- ✅ Reads, transport/mixer control, **step-sequencer beats**, tempo, note **recording**, audio analysis
- ✅ **Exact piano-roll note editing** — via the baked-pyscript route (`pianoroll_apply`)
- ✅ **Playlist clip placement** — via `transport.globalTransport(FPT_Copy/FPT_Paste)` (playhead-accurate; track follows FL's paste anchor)
- ✅ **`meta.exec`** — call any of FL's ~250 scripting functions remotely
- ⚠️ Pyscript **file I/O** stays sealed by FL (worked around by baking notes into the script source)

See [`docs/FL2025_SANDBOX.md`](docs/FL2025_SANDBOX.md) for the complete story, the
full enumerated API (proof), and the exact recipes.

## License

MIT — see [`LICENSE`](LICENSE). Original work © the FLStudioMCP authors
([geezoria/FLStudioMCP](https://github.com/geezoria/FLStudioMCP)); FL-2025
additions contributed on top.