Metadata-Version: 2.4
Name: postfader-fl-studio-mcp
Version: 0.13.0
Summary: Unofficial local MCP bridge for readback-verified FL Studio control
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/synopsys0/postfader-fl-studio-mcp
Project-URL: Repository, https://github.com/synopsys0/postfader-fl-studio-mcp
Project-URL: Issues, https://github.com/synopsys0/postfader-fl-studio-mcp/issues
Project-URL: Documentation, https://github.com/synopsys0/postfader-fl-studio-mcp#readme
Keywords: fl-studio,mcp,model-context-protocol,midi,music-production
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: anyio<5,>=4.5
Requires-Dist: mcp[cli]<3,>=2.0.0
Requires-Dist: jsonschema<5,>=4.20
Requires-Dist: numpy<3,>=1.24
Requires-Dist: scipy<2,>=1.10
Requires-Dist: soundfile<1,>=0.12
Requires-Dist: pyloudnorm<1,>=0.1.1
Requires-Dist: python-rtmidi<2,>=1.5
Requires-Dist: pydantic<3,>=2.12
Provides-Extra: test
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "test"
Provides-Extra: dev
Requires-Dist: fl-studio-api-stubs<38,>=37; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Dynamic: license-file

<div align="center">

# Postfader

### Give your AI assistant eyes and hands inside FL Studio

Explore the project you already have open, make carefully checked changes, and
compare exported mixes—all from an MCP-compatible AI client.

[![CI](https://github.com/synopsys0/postfader-fl-studio-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/synopsys0/postfader-fl-studio-mcp/actions/workflows/ci.yml) [![Version](https://img.shields.io/badge/version-0.13.0-blue)](#supported-versions) [![FL Studio](https://img.shields.io/badge/FL%20Studio-2026-orange)](#supported-versions) [![Python](https://img.shields.io/badge/python-3.10--3.14-blue)](https://www.python.org/downloads/) [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey)](#supported-versions) [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

[Features](#what-you-can-do) · [Quick start](#quick-start) · [Supported versions](#supported-versions) · [Safety](#safe-by-default) · [Documentation](#documentation)

</div>

> [!NOTE]
> Postfader is an unofficial community project. It is not made by or affiliated
> with Image-Line.

Postfader connects a local AI client to FL Studio through a small controller
script. You can ask questions about the current project, change supported
controls, audition a note, or measure audio files without building a custom FL
Studio integration.

It includes **37 focused tools**:

- 12 tools for reading the open FL Studio project;
- 19 tools for changing supported project settings and checking the result;
- one session control for enabling or disabling those changes without restarting FL Studio;
- one short live-note audition tool; and
- four tools for analyzing exported audio files.

## What you can do

| 🔎 Understand your project | 🎚️ Shape the mix |
| --- | --- |
| See mixer tracks, effects, routing, channels, transport state, patterns, and plug-in parameters. | Change mixer volume, pan, mute, names, built-in EQ, sends, and send levels. |
| **🎹 Work with channels and patterns** | **📊 Measure exported audio** |
| Route channels, change channel mix and identity, edit step cells, control tempo and playback, or audition a bounded note. | Measure loudness, spectrum, dynamics, stereo image, optional monophonic pitch, masking, and differences between two bounces. |

Postfader can also inspect and control parameters exposed by native FL effects,
VST/VST3/AU effects, and Channel Rack generators. Plug-in support is discovered
from FL Studio at runtime rather than limited to a fixed list.

### Example requests

~~~text
“Show me every used mixer track and where it routes.”

“Which Channel Rack instruments are not assigned to a mixer insert?”

“Rename insert 4 to Lead Vocal, set its pan to 10% left, and confirm both changes.”

“Set the tempo to 128 BPM while the project is stopped.”

“Enable write mode for this session, then rename insert 4 to Lead Vocal.”

“Compare my latest bounce with the reference and summarize the loudness,
stereo, dynamics, and frequency-band differences.”
~~~

## Why use Postfader?

- **Stay in the creative flow.** Ask for project information or routine changes
  without hunting through several FL Studio windows.
- **Know whether a change landed.** Postfader reads supported controls back
  after changing them and reports the before state, after state, and result.
- **Start safely.** Postfader connects in read-only mode. When you are ready,
  ask your AI client to enable writes for the current session—no FL Studio
  restart required.
- **Use the plug-ins you already own.** Postfader discovers the parameter
  surface FL Studio exposes instead of requiring a custom profile for every
  plug-in.
- **Keep it local.** Postfader has no hosted service, account, telemetry, or
  project upload step.

## What “verified” means

For a supported change, Postfader:

1. checks the target, value, current session, and any supplied before-state;
2. asks FL Studio to make the change;
3. waits for a later FL Studio update and reads the control again; and
4. reports whether the requested state was actually observed.

This catches a common automation failure: FL Studio or a plug-in accepting a
command but ignoring the value.

> [!IMPORTANT]
> A verified result means the control was observed at the requested setting. It
> does not mean the musical choice sounds good. Writes affect the open project
> immediately and are not automatically rolled back. Postfader never saves the
> project for you.

## How it works

~~~mermaid
flowchart LR
    A["Your AI client<br/>(MCP)"] --> B["Postfader<br/>runs locally"]
    B -->|"Virtual MIDI"| C["Universal Bridge<br/>inside FL Studio"]
    C --> D["Your open project"]
    B -->|"Files you choose"| E["Exported audio<br/>measurements"]
~~~

MCP is the connection that lets an AI client call Postfader's named tools.
Live FL Studio communication travels over one local virtual MIDI endpoint.
Audio analysis reads exported files from disk because FL Studio's scripting API
does not provide live audio buffers.

## Supported versions

| Component | Support |
| --- | --- |
| Postfader | 0.13.0 |
| FL Studio | FL Studio 2026, version 26.1.3 build 5336 or newer |
| FL MIDI scripting API | Version 44 or newer |
| Python | 3.10 through 3.14 |
| macOS | Supported; v0.13 live-tested on macOS 27.0 arm64 using the built-in IAC bus |
| Windows | Windows 11 x64 implementation, CI, installer, diagnostics, and packaging are complete; supervised FL/virtual-MIDI validation is still pending |
| AI clients | Any MCP-compatible client that can start a local process; configuration helpers are included for Codex and Claude-compatible JSON, plus a Claude Desktop extension |

Python 3.13/3.14 and Windows ARM64 may need a native compiler for
<code>python-rtmidi</code>. Current Windows CI runs on x64.

## Quick start

### 1. Prepare a virtual MIDI endpoint

- **macOS:** enable an IAC bus in **Audio MIDI Setup**.
- **Windows:** create one bidirectional endpoint with the virtual MIDI software
  of your choice.

Postfader does not install or configure virtual MIDI software. You will use the
same endpoint for FL Studio's MIDI input and output.

Launch FL Studio once before installing Postfader so it creates its user-data
folders, then quit FL Studio.

### 2. Install Postfader

**macOS**

~~~bash
git clone https://github.com/synopsys0/postfader-fl-studio-mcp.git
cd postfader-fl-studio-mcp
./scripts/install.sh
~~~

**Windows PowerShell**

~~~powershell
git clone https://github.com/synopsys0/postfader-fl-studio-mcp.git
Set-Location postfader-fl-studio-mcp
.\scripts\install.ps1 -DryRun
.\scripts\install.ps1
~~~

The installers create a local <code>.venv</code>, install Postfader, and copy
<code>Universal Bridge</code> into FL Studio's controller-script folder. They
do not change your AI client's configuration.

You can also install the published Python package:

~~~text
pip install postfader-fl-studio-mcp
postfader-install-bridge
~~~

### 3. Connect FL Studio

Open **Options → MIDI settings** in FL Studio:

1. Enable your virtual endpoint under **Input**.
2. Set its controller type to **Universal Bridge**.
3. Give the input an FL Studio Port number.
4. Enable the same endpoint under **Output** and give it the same Port number.
5. Open **View → Script output** and reload the script.

The script should report <code>ready: MIDI SysEx</code>.

### 4. Check the connection

**macOS**

~~~bash
./.venv/bin/postfader-doctor --midi-port "IAC Driver Bus 1" --json
~~~

**Windows PowerShell**

~~~powershell
.\.venv\Scripts\postfader-doctor.exe --midi-port "Exact Virtual MIDI Endpoint Name" --json
~~~

A healthy connection reports:

- <code>overall: "pass"</code>;
- a live FL Studio connection;
- a controller script that matches the installed Postfader version;
- <code>bridge_mode: "read_only"</code>; and
- <code>verified_writes_enabled: false</code>; and
- <code>runtime_write_mode_control: true</code>.

### 5. Add Postfader to your AI client

Use the included configuration generator so interpreter paths, repository
paths, and endpoint names are explicit:

~~~bash
./.venv/bin/python scripts/generate_mcp_config.py --help
~~~

~~~powershell
.\.venv\Scripts\python.exe scripts\generate_mcp_config.py --help
~~~

It can produce a Codex command, Codex TOML, or Claude-compatible JSON. See the
[client configuration guide](docs/setup.md#4-generate-client-configuration)
for complete macOS and Windows examples.

Claude Desktop users can open the release <code>.mcpb</code>, but the extension
does not install the FL Studio controller script or create the virtual MIDI
endpoint. Complete steps 1–4 first.

## Safe by default

### Read-only mode

A normal FL Studio launch keeps Postfader read-only: project inspection works,
but project-changing tools do not. Audio-file analysis also works without a
live FL Studio connection. This is the recommended mode for exploring a real
session.

### Write mode

When you want Postfader to make changes, ask your connected AI client:

~~~text
“Enable write mode for this session.”
~~~

Your client calls <code>fl_set_write_mode</code> and must carry an explicit
user-present confirmation. Postfader then checks the running controller script,
changes only that live session, and performs a second handshake before reporting
that writes are available. FL Studio does not need to restart.

Ask the client to “disable write mode” when you are done. The setting is never
stored in your project or AI-client configuration, and an ordinary controller
script reload or new FL Studio process starts read-only again. Use a blank or
disposable project the first time you try writes.

Additional safeguards include:

- enabling writes requires an explicit user request and is exposed to MCP
  clients as a destructive capability change;
- writes to the Master track require explicit permission;
- if the installed controller script and Postfader version do not match,
  writes are blocked;
- writes are never automatically repeated after a lost or ambiguous response;
- supplied session and before-state checks can reject stale decisions;
- only one local Postfader connection can use the selected virtual MIDI bus at
  a time; and
- the controller script never calls FL Studio's save-project function.

See [Tool contracts](docs/tool-contracts.md#write-tools) for the exact behavior
of every write.

## Plug-in support

Postfader can work with any mixer effect or Channel Rack generator whose
parameters FL Studio exposes to controller scripts. That includes native
Image-Line plug-ins and many VST, VST3, and AU plug-ins.

Compatibility is intentionally honest:

- an unfamiliar plug-in can be inspected without first adding it to Postfader;
- a parameter that FL does not expose cannot be controlled;
- very large parameter maps are scanned with explicit limits;
- a write that FL accepts but ignores is reported as unverified; and
- named options must use the exact label FL Studio reports, ignoring case.

See [Plug-in support](docs/plugin-support.md) for parameter discovery, option
searches, scan limits, troubleshooting, and the community evidence format.

## Important limitations

Postfader cannot currently:

- add, remove, or reorder plug-ins;
- reliably control an effect slot's bypass or wet/dry mix;
- hear FL Studio's live output;
- render, export, or save a project;
- decide whether a mix sounds good; or
- turn raw Playlist selection endpoints into a safe automatic render range.

Audio tools analyze files you explicitly select or recent bounces found in
bounded FL Studio folders. They return measurements and comparisons, not audio
samples or artistic judgments.

The local virtual MIDI bus is shared and unauthenticated. Use Postfader on a
trusted, single-user workstation.

## Privacy

Postfader itself runs locally and has no telemetry or cloud service. It does
not store your projects, recordings, stems, presets, exports, or live-session
evidence in this repository.

Your AI client is a separate application and may send tool arguments and
results to its model provider. Audio results can include file paths, hashes,
and measurements, but never audio samples. Review your AI client's privacy
policy and Postfader's [security policy](SECURITY.md) before using sensitive
projects.

## Documentation

| Guide | What it covers |
| --- | --- |
| [Setup and troubleshooting](docs/setup.md) | Installation, client configuration, upgrades, diagnostics, write mode, and common errors |
| [Tool reference](docs/tool-contracts.md) | All 37 tools, accepted values, results, refusals, and safety rules |
| [Plug-in support](docs/plugin-support.md) | Effects, generators, parameter scans, option controls, and compatibility evidence |
| [FL Studio constraints](docs/fl-constraints.md) | What FL Studio's scripting API allows and where Postfader deliberately stops |
| [Architecture](docs/architecture.md) | Components, transport, bridge behavior, and trust boundaries |
| [Security](SECURITY.md) | Threat model, privacy boundaries, and vulnerability reporting |
| [Contributing](CONTRIBUTING.md) | Development workflow and contribution guidelines |

## Development

Run the safe, hardware-free test suite from the source checkout:

~~~bash
./.venv/bin/python scripts/run_safe_tests.py
~~~

~~~powershell
.\.venv\Scripts\python.exe scripts\run_safe_tests.py
~~~

The safe suite prevents real MIDI access even when ambient environment
variables request it. Any live hardware test must use a blank, unsaved project,
and its logs, screenshots, and run notes must stay outside the public repository.

## License

Postfader is available under the [Apache License 2.0](LICENSE). See
[NOTICE](NOTICE) for attribution details.

<!-- mcp-name: io.github.synopsys0/postfader-fl-studio-mcp -->
