Skip to content

Getting started

Five minutes from download to a synth answering your first OSC message.

1. Install

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

Or download a binary from the releases page, or build from source:

git clone https://github.com/roomi-fields/osc-bridge
cd osc-bridge && cargo build --release      # binary in target/release/

Newest features from source

Hardware detection, preset backup, drum sounds by name and WebSocket clients arrived in v0.13.0. Until the next release is published, build from source to get them.

2. Find your device and its ports

osc-bridge detect

It lists MIDI ports, asks each device who it is (the standard MIDI Identity Request — it changes nothing on the device) and prints the matching driver and a ready-to-run line. Search the catalogue if your device does not answer.

3. Start the bridge

osc-bridge run --device devices/arturia/minilab3.json --out-port 4 --in-port 0 \
  --osc-client 127.0.0.1:8888

The bridge listens for OSC on 127.0.0.1:7777. With --in-port, everything the device sends (knobs, pads, SysEx replies) goes out as OSC to each --osc-client. Add --ws-bind 127.0.0.1:7890 for browser clients.

4. Send OSC

osc-bridge osc-send /minilab3/display/text "Hello" "World"
osc-bridge osc-listen --bind 127.0.0.1:8888    # watch what the device sends

Every device page lists its addresses; so does osc-bridge inspect <json>.

5. Or let Claude drive it

Add the MCP server to Claude Desktop, Claude Code or Cursor:

{ "mcpServers": { "osc-bridge": { "command": "npx", "args": ["-y", "@roomi-fields/osc-bridge", "mcp"] } } }

Then ask: “What synth is plugged in, and what can it do?” — see the MCP guide.

Next