osc-bridge

osc-bridge started as an OSC driver for the Arturia MatrixBrute, whose patch format was reconstructed from sysex-controls and the community tool MBPV; it became a generic bridge once the Arturia protocol family came into view. It is now the engine of synthhub, which holds the instrument catalogue. Its main limit: an instrument is driven only as its file describes it, and most of these files come from manufacturer documentation or third-party libraries, not from a test on the machine.

One instrument, one file, one named surface

Think of osc-bridge as an interpreter standing in front of each instrument. On the client side, an OSC surface with readable addresses: /minilab3/pad/0/color, /minilab3/display/text. On the instrument side, the bytes the machine expects: CC, NRPN, SysEx frames. In between, one JSON file declares the SysEx framing, the high-level commands (a pad’s colour, a screen’s text, recalling a preset) and the parameter table. Adding an instrument does not require recompiling the program, which is written in Rust.

Software goes through the same mechanism. Ableton Live, Bitwig, Reaper, Sonic Pi, SuperCollider, Pure Data, TouchDesigner and VCV Rack are instruments like any other, reached over OSC instead of a MIDI cable. The full catalogue is searchable on the SynthHub site; the file format is described by open-synth-descriptors.

Getting started

With Node installed, the MCP server starts with nothing else to install:

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

It exposes eight tools to an MCP client (Claude Desktop, Claude Code, Cursor): list_devices, get_device_docs, list_routes, send, get_status, detect_hardware, backup_presets, restore_presets. Client configuration is in the repository’s docs/MCP.md. You then ask, for instance, what the MatrixBrute can do; the model reads its addresses with list_routes, then sends with send. By default, this local copy links to the SynthHub server, which adds its own tools; --offline cuts that link. The hosted server, with nothing to install, is described on the synthhub page.

To list the machine’s MIDI ports:

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

On 28 October 2026, with version 0.16.0, list ran as written, and the MCP server, started with --offline, returned these eight tools. The 0.16.0 npm package contains the catalogue; a connected MiniLab 3 is driven like this (port numbers come from list):

osc-bridge run --device devices/arturia/minilab3.json --out-port 4 --in-port 0 \
  --bind 127.0.0.1:7777 --osc-client 127.0.0.1:8888
osc-bridge osc-send /minilab3/pad/0/color 127 0 0

What it does

• Both directions. What the instrument sends (a knob turned, a SysEx reply) comes back as OSC to one or more clients.
• Several instruments in one process. osc-bridge orchestrate --config bridge.toml gives each its own prefix: two MatrixBrutes live side by side as /matrixbrute-1 and /matrixbrute-2. A [[routes]] section links a source to a target without writing a client, for example a MiniLab knob to the volume of an Ableton track.
• Reconfigurable controllers. For the Electra One MK2, a preset sent as one OSC message reconfigures the device and rebuilds the routing table; /bridge/docs returns the device’s guide, /electra1/routes/list the address table. Checked on firmware 4.1.4 on 14 April 2026.
• Recognising what is plugged in. osc-bridge detect sends the MIDI Identity Request, reads maker, model and firmware, and offers the osc-bridge run line with the right ports.
• Backing up sounds. osc-bridge backup records what the device sends into a .syx file; restore sends it back, overwriting the device’s memory.
• Declared provenance. Each file names its sources in _sources[]: checked on the machine, checked on the software, manufacturer documentation, published OSC API, Electra community preset, import from pencilresearch/midi.
• Lua as a fallback. For a protocol with checksums or state, a Lua 5.4 script runs in a sandbox (1 MiB, 10 ms); osc-bridge lint flags every use.
• Browser. --ws-bind exposes the same surface as OSC over WebSocket, for a web client. Only pages served from the machine itself may connect; --ws-allow-origin adds others.

Common issues

A device does not show up on Windows 11 24H2. Since the March 2026 cumulative update (KB5079473), the USBMidi2-ACX driver makes some devices invisible to the classic MIDI interface; this is confirmed for Polyend devices (Synth, Play, Tracker, Mess, Step). The workaround: force the “USB Audio Device” driver in Device Manager, then unplug and replug. The detailed steps are in the README.

A command does not do what you expect. If the instrument is not marked as checked, its description comes from a spec sheet and may be wrong. The file belongs to the SynthHub catalogue: report the correction there, as the synthhub page describes, or open an issue on the repository.

Where it stands

Version 0.16.0 (24 October 2026) adds sound sharing through SynthHub. The three before it date from 23 October: 0.13.0 brought device detection, SysEx backup and named drum sounds; 0.14.0 moved the code to AGPL-3.0 and took the hosted server out of the repository; 0.15.0 moved the site to SynthHub. Versions 0.11.0 (24 June) and 0.12.0 (20 August, WebSocket transport) are in the changelog with no published package. Binaries for Windows, Linux and macOS.

On the main branch since 27 October 2026, not yet in a published release: the catalogue has left the repository for SynthHub, and osc-bridge fetches each file from there when needed, one at a time, cached on the machine. What is missing: checking most instruments on the machine, which depends on who owns the hardware.

The npm package was downloaded 168 times between 29 August and 27 September 2026, according to npm’s counter.

Repository · synthhub · open-synth-descriptors · the article on osc-bridge · vcv-osc · electra-one

Thanks to sysex-controls (soyersoyer) and the MBPV tool, for the MatrixBrute patch format. The catalogue’s sources are thanked on the synthhub page.