osc-bridge

osc-bridge

**Declarative OSC bridge for music hardware *and* software — and an MCP server to drive it from an LLM.**

Hardware synthesizers over MIDI / SysEx, plus DAWs and live-coding environments over OSC (Ableton, Bitwig, Reaper, Sonic Pi, SuperCollider, Pure Data, TouchDesigner, VCV Rack). Every device gets a clean, named OSC surface described by one JSON file, its driver; the catalogue of drivers lives on SynthHub, which hands them out one at a time. Drive it from a live-coding client, a DAW, a script, the CLI — or from Claude via the built-in MCP server (a MIDI MCP *and* OSC MCP).

Install

Hosted MCP server, nothing to install — the SynthHub server, run by the maintainer of osc-bridge, with the catalogue, trust from real use and the relay to your own hardware:

• Claude (web, desktop): Settings → Connectors → *Add custom connector* → https://mcp.synthhub.roomi-fields.com/mcp
• Claude Code: claude mcp add --transport http synthhub https://mcp.synthhub.roomi-fields.com/mcp
• Cursor and other clients: {"mcpServers": {"synthhub": {"url": "https://mcp.synthhub.roomi-fields.com/mcp"}}}

On your machine — the MCP server over stdio, with hardware detection and OSC to a running bridge (each driver fetched from SynthHub when needed and kept in a cache; you choose what it shares):

npx -y @roomi-fields/osc-bridge mcp

As a standalone bridge / CLI:

npm install -g @roomi-fields/osc-bridge      # downloads the prebuilt binary

or grab a binary directly from the Releases page

osc-bridge run --device arturia/minilab3 --out-port 4 # a driver id, or a JSON file of yours

MCP client config and the tools → docs/MCP.md. Full quick-start with MIDI port discovery → § Install & quick start.

Why a bridge?

Modern synths — hardware and software alike — expose themselves over MIDI, SysEx, and OSC with proprietary, scattered protocols. Using them from live-coding environments, a DAW, a script, or an LLM is painful:

• CC / NRPN addresses are cryptic
• SysEx byte formats are hand-rolled per device
• Bidirectional state (what the device CURRENTLY knows) is hard to track

`osc-bridge` gives every supported synth a clean, named OSC surface:

~mb = NetAddr("127.0.0.1", 7777);

~mb.sendMsg("/minilab3/knob/3/cc_number", 64); // reconfigure knob 3 ~mb.sendMsg("/minilab3/pad/0/color", 127, 0, 0); // pad 1 red ~mb.sendMsg("/minilab3/display/text", "Hello", "World");

Each synth is described by one JSON file. No Rust recompile required to add a device.

Where the drivers come from

The catalogue lives on SynthHub, not in this repository: browse and search it at synthhub.roomi-fields.com. osc-bridge asks the SynthHub server for one driver at a time, when it needs it:

• osc-bridge run --device korg/minilogue (a driver id) or --device minilogue (a slug: the device's best variant) fetches that driver and keeps it in the cache (~/.cache/osc-bridge/drivers/, or $XDG_CACHE_HOME, %LOCALAPPDATA%), then downloads it again only when the server's copy changed;
• osc-bridge detect and the MCP tool detect_hardware ask the server which makers' identity requests to send, then send it the names of the MIDI ports found here and what the devices answered, and it names the matching drivers and firmware; list_devices searches the catalogue there;
• offline (osc-bridge privacy --offline on, OSC_BRIDGE_OFFLINE=1), only the drivers already cached are used and nothing is sent.

These requests present the anonymous account of this machine. A JSON file on your machine is used as it is (--device my-synth.json, osc-bridge mcp --devices-dir my-drivers/).

What makes it different

• One JSON = one driver. Adding a synth is ~30 lines of declarative JSON — CC numbers, SysEx frame templates, optional parameter tables. No Rust, no bindings, no build step. Ship a PR, osc-bridge run picks it up.
• A shared catalogue. Prophets, Oberheims, the Yamaha DX family, MatrixBrute, Hydrasynth, Virus TI, Digitone, Matrix-1000… the SynthHub catalogue covers most synths, drum machines and DAWs, and grows with what users and agents contribute. Searchable at synthhub.roomi-fields.com.
• **Hardware *and* software.** The same named OSC surface drives a hardware synth over MIDI/SysEx *or* a DAW / live-coding environment over OSC — Ableton, Bitwig, Reaper, Sonic Pi, SuperCollider, Pure Data, TouchDesigner, VCV Rack. See § Software targets.
• An MCP server built in. osc-bridge mcp exposes the SynthHub catalogue to Claude (or any MCP client) — a MIDI MCP *and* OSC MCP. Discover devices, read a device's OSC surface, send OSC to synths and DAWs. See docs/MCP.md.
• Honest provenance. Each device declares its source in _sources[]: ✅ hardware-verified, ✅ software-verified, 📘 vendor-doc, 📡 vendor-osc-api / 📡 third-party-osc, 🎛️ electra-preset, 📦 pencilresearch. You always know whether a mapping was tested on the device or lifted from a spec sheet.
• Bidirectional out of the box. Incoming MIDI (knob turns, SysEx replies, NRPN) is decoded and re-emitted as OSC. Multi-client fan-out is a --osc-client flag.
• N-to-N orchestration. One process can drive several synths at once (osc-bridge orchestrate --config bridge.toml), each reachable under its own OSC prefix — so two MatrixBrutes live side-by-side as /matrixbrute-1 and /matrixbrute-2.
• First-class reconfigurable controllers (Electra One MK2). Upload a generated preset as one OSC call; the bridge parses the JSON, reconfigures the device over SysEx, and *dynamically* rewires its own CC↔OSC routing so each knob on the new layout is reachable by name. Self-describing over OSC: /bridge/docs returns the integration guide, /electra1/routes/list returns the authoritative address table, so clients (or LLM-driven integrators) never hardcode slugification or protocol details. See § Reconfigurable controllers below.
• Escape hatch when JSON isn't enough. For devices with checksums, quirky scaling, or stateful protocols, an optional per-parameter transform / per-command script runs Lua 5.4 sandboxed (1 MiB / 10 ms caps, no os/io/loaders). Used sparingly — osc-bridge lint warns on every script use — but it lets the declarative core stay small without giving up on edge cases. See docs/scripting.md.
• Runtime you can trust. Rate-limiting per device, backpressure-aware, zero-alloc hot path, no GC. Single static binary on Windows / Linux / macOS.

Supported devices

The catalogue — synths, drum machines, controllers, DAWs and live-coding environments, with each driver's source and how far users confirmed it — is on SynthHub:

• 🔎 Interactive browser → [https://synthhub.roomi-fields.com/](https://synthhub.roomi-fields.com/) (live search by vendor / model / author / source).
• 🤖 For scripts and AI agents → JSON API at https://synthhub.roomi-fields.com/api/v1/index.json (each driver at /api/v1/devices/ / .json), or the hosted MCP server at https://mcp.synthhub.roomi-fields.com/mcp — see API for agents.

Each driver declares its source in _sources[]: ✅ hardware-verified, ✅ software-verified, 📘 vendor-doc, 📡 vendor-osc-api / 📡 third-party-osc, 🎛️ electra-preset, 📦 pencilresearch.

Share your own device

New here? The 30-minute tutorial builds a working driver end to end. Otherwise — three common cases, pick yours:

Your synth isn't listed → write its driver and send it to SynthHub.

1. Find a source: vendor programmer's reference, MIDI implementation PDF, or a canonical CSV.
2. Follow docs/DEVICE_JSON_SCHEMA.md; the driver of a similar device (/api/v1/devices/ .json on SynthHub, or the copy in your cache) is a good template.
3. Check it: osc-bridge lint my-synth.json, then osc-bridge run --device my-synth.json on the device.
4. Contribute it: from an MCP client, the submit_driver tool (it is checked, then added to the catalogue); or open an issue here with the file.

A driver is wrong, or you tested it on the hardware → tell SynthHub: report_result and report_mapping (MCP) record what works on which firmware, and submit_fix turns learned mappings into a corrected driver.

Full contributor guide (schema extensions, bug reports, Lua escape hatch) → CONTRIBUTING.md. For devices whose protocol can't be expressed declaratively, see docs/scripting.md — use sparingly; osc-bridge lint warns on every use.

Reconfigurable controllers (Electra One MK2) — the scripts stress-test

Most synths have a fixed set of controls — MiniLab 3's knobs always mean the same thing. The Electra One MK2 is different: its 216 controls are defined by a preset that you upload to the device, and the meaning of every CC changes when the preset changes. A static JSON spec can't describe that; the bridge treats it as a first-class case.

This integration is what validates the whole Lua scripting subsystem in anger. The MK2 driver exercises every feature of the scripting.rs layer on real hardware (firmware 4.1.4, verified 2026-04-14):

• Native JSON codec (ob.json_decode / ob.json_encode) — parses a full Electra preset (up to 100 KB of nested pages/devices/groups/controls/overlays) in a single Lua block, under the 500 ms preset_ingest profile.
• Persistent per-device state (ob.state) — the driver stores the active preset name so /electra1/preset/current can report it on demand.
• Dynamic CC↔OSC route registration (ob.register_cc_route / ob.clear_routes / ob.set_current_page) — every preset upload rebuilds the bridge's routing table from scratch, zero restart.
• Multi-block SysEx emission (ob.emit_sysex) — the upload script emits the wrapped SysEx preset data block directly from Lua.
• Outbound OSC emission (ob.emit_osc) — powers the introspection endpoints: /routes/list, /preset/current, /page/current.
• Reply scripts with matched bindings (ctx.bindings) — when the device reports a page switch over SysEx, a reply script updates the bridge's active page so CC routing tracks the hardware UI automatically.
• Companion markdown auto-load — the driver's notes (electra-one.md, next to its JSON) are loaded at startup and served over /bridge/docs, so LLM-driven integrators read the device-specific quirks (hex-color requirement, inputs[{potId}] mandatory, envelope-segment cycling gesture, MIDI port selection, etc.) without any code-side knowledge.

Every item above has a unit test, an end-to-end test against the real .json driver, and a hardware-verified green light. If you're building a driver for another reconfigurable cont