Your first device JSON in 30 minutes
This is a hands-on walkthrough: by the end you'll have a working, linted,
tested osc-bridge driver for a CC-based synthesizer, and you'll know how to
extend it.
We'll build the driver step by step. The running example is a small CC-only mono synth with a filter, an envelope, and an LFO — the kind of device whose MIDI implementation fits on one page. The CC numbers below are illustrative. When you follow along with a real device, swap in the values from its MIDI implementation chart.
If you just want the reference (every field, every type), read Open Synth Descriptors. This tutorial is the worked example; that's the dictionary.
Prerequisites (5 min)
git clone https://github.com/roomi-fields/osc-bridge
cd osc-bridge
cargo build --release
./target/release/osc-bridge --help
If cargo build succeeds, you're set. You do not need the physical synth
to write and lint a driver — only to promote it to ✅ later.
Step 1 — Find your source (2 min)
Every driver must cite where its mapping comes from: the catalogue takes no driver without one. Acceptable sources:
- the manufacturer's MIDI implementation chart / programmer's reference,
- a canonical community CSV (e.g. pencilresearch/midi),
- your own reverse-engineering log from the hardware.
For this tutorial, assume we have the synth's one-page MIDI chart in hand.
Step 2 — Create the file (1 min)
In the SynthHub catalogue a driver's id is <vendor>/<slug>: the vendor
folder is the manufacturer in lowercase-kebab, the slug is the model. Write
yours wherever you like, under that name:
Step 3 — The skeleton (3 min)
Every driver starts with a device block. For a CC-only synth, that's almost
all the boilerplate there is:
{
"_sources": [
{
"type": "vendor-doc",
"name": "Acme Bassline MIDI Implementation Chart v1.2",
"url": "https://acme.example/bassline/midi.pdf"
}
],
"device": {
"name": "Acme Bassline",
"vendor": "Acme",
"revision": "firmware 1.2",
"osc_prefix": "/bassline"
}
}
_sources[]— your provenance.typeis one ofvendor-doc,hardware-verified,electra-preset,pencilresearch, … (see the schema doc).osc_prefix— every OSC route this device exposes will be prefixed with it. Keep it short and unambiguous.
A SysEx synth would also declare manufacturer_id / device_id and a sysex
header/footer. A pure-CC synth needs none of that.
Step 4 — Parameters: the cc_params table (8 min)
This is the heart of the driver. Each entry maps one named OSC address to one MIDI Control Change message.
{
"cc_params": {
"channel": 0,
"entries": [
{ "osc": "/filter/cutoff", "cc": 74, "range": [0, 127] },
{ "osc": "/filter/resonance", "cc": 71, "range": [0, 127] },
{ "osc": "/amp/attack", "cc": 73, "range": [0, 127] },
{ "osc": "/amp/release", "cc": 72, "range": [0, 127] },
{ "osc": "/lfo/rate", "cc": 76, "range": [0, 127] },
{ "osc": "/lfo/depth", "cc": 77, "range": [0, 127] }
]
}
}
channel is the default MIDI channel (0–15, i.e. "channel 1"). Sending
/bassline/filter/cutoff 64 now emits B0 4A 40 — a CC message on channel 1.
A few things you'll reach for as your device needs them:
- 14-bit CC — declare an
cc_lsbalongsideccand widen the range:{ "osc": "/osc/pitch", "cc": 3, "cc_lsb": 35, "range": [0, 16383] } - NRPN — declare
nrpn_msb/nrpn_lsbinstead ofcc; the bridge emits the full NRPN sequence for you. - Per-entry channel — add
"channel": 9to one entry to override the default for that parameter only. - Grouping — add a
"section": "Filter"tag; it's free-form and only used for organisation in tooling.
Add one entry per parameter on your synth's chart. This is the bulk of the work and the part worth getting right.
Step 5 — Playing notes: midi_out (4 min)
If your device should also respond to note-on/off, pitch-bend, and friends,
add a midi_out block. Its mere presence switches on a standard set of
performance routes:
With that, the bridge accepts (all prefixed by osc_prefix):
| OSC | sends |
|---|---|
/note/on {note} {vel} |
Note-On |
/note/off {note} |
Note-Off |
/pitchbend {value_u14} |
Pitch-Bend |
/cc/{num} {value} |
raw CC |
/program_change {prog} |
Program Change |
Omit the whole block for a device that should not accept performance routes (a pure effects unit, a controller).
Step 6 — Lint it (2 min)
Expected:
The linter parses the file, counts what it found, and warns on any scripted
fallback (transform / script) — you have none, so it's silent. If the JSON
is malformed or a required field is missing, this is where you find out.
Step 7 — Try it for real (3 min)
Inspect the driver without connecting anything:
If you have the synth on a MIDI port, run the bridge and send it something:
# find your MIDI out port index
./target/release/osc-bridge list
# run the bridge (port 4 is an example)
./target/release/osc-bridge run --device my-drivers/acme/bassline.json --out-port 4 &
# send an OSC message
./target/release/osc-bridge osc-send /bassline/filter/cutoff 100
The filter should move. If it doesn't: double-check the CC number and channel against the chart, and watch the bridge's stderr — it logs every message it dispatches.
Step 8 — Send it to SynthHub (1 min)
The catalogue lives on SynthHub. From an
MCP client linked to it (osc-bridge mcp, or the hosted server), ask your
agent to contribute the driver: the submit_driver tool takes the file and
where its mapping comes from. It is parsed, linted and tested, then added to
the catalogue, where others find it under acme/bassline — and once you
tested it on the synth, report_result records that it works, on which
firmware.
No MCP client at hand? Open a device request with the file attached.
Where to go next
You've covered the 90% case. The remaining 10%, in rough order of how often you'll need it:
- Fixed commands — preset recall, display text, pad colours: the
commands[]block builds a SysEx/OSC frame from a placeholder template. - SysEx parameters — hundreds of params behind one opcode family: the
paramsblock declares the framing once and a flat address table. - Replies — decode device-initiated messages back into OSC: the
replies[]block. - Software targets — driving a DAW or live-coding environment instead of
hardware:
device.transport.kind = "osc". See the schema doc's "Software drivers" section. - Checksums —
twos7,sum7andxor7are declarative: a frame token{checksum:<algorithm>@<from>[+<length>]}, no Lua. - The Lua escape hatch — other checksums, exotic encodings, conditional
transforms:
transform/script. Use sparingly;lintwarns on every use. Seescripting.md.
All of it is in Open Synth Descriptors. And the
contributor checklist — folder conventions, the no-silent-fusion rule, how to
promote a driver to ✅ — is in ../CONTRIBUTING.md.