Changelog
All notable changes to osc-bridge. Format loosely follows
Keep a Changelog. Version numbers follow
Semantic Versioning: MAJOR.MINOR.PATCH.
Until 1.0.0 the schema and runtime are still stabilising — expect
additive minor bumps every time a new device class surfaces something
the JSON can't yet express. Backwards-compat of existing device JSONs
is tracked explicitly under each release.
[Unreleased]
Added — a learn mode of the detection
detect_hardware(learn,listen_ms) andosc-bridge detect --learn --listen-mslisten for 1000-30000 ms (default 5000) on each port while the person moves the controls, sending nothing but the universal Identity Request, and return per port an OSD 0.6 fingerprint (usb,ports,identity_reply,sends, up to 32controls; absent fields are never guessed) with the measured delays beside it inmeasured. So a device that does not say who it is still gives what is needed to learn it. Withoutlearn, the report is unchanged.
Added — the detection reads the USB ids of a device (Linux)
detect_hardwareandosc-bridge detectgive, per device,usbwithvendor_idandproduct_idwhen its port belongs to a USB card (read from/proc/asound); the key is absent for a virtual or DIN port, and on a platform that does not read them yet.- The local ranking favours a driver whose
identity.usbholds the pair (80 points, above the port name's 60), and recognises it without a SysEx reply or a matching port name (recognised_bysaysusb). The request sent to the SynthHub service does not carry the pair.
Changed (breaking) — the local MCP tools name a device by device, and slug is gone
get_device_docsandlist_routestakedevice(a catalogue id or an OSC prefix), as the other tools do. A call that passesslug, alone or besidedevice, is refused with an error that says to name the device bydevice; a call with neither saysdeviceis missing.- In a
list_devicesentry and adetect_hardwarecandidate,deviceis the catalogue id (it replacesidandslug) and the OSC prefix isosc_prefix.get_device_docsreturnsdeviceas the caller passed it. - The unknown-device message and the
match:line of the command-line detection saydevice.
[0.23.1] — 2026-11-20
Fixed — the OSCQuery export keeps a command whose address takes a number
osdandosd-formatsare pinned to commit9fd94ecof Open Synth Descriptors (wasbc6afe9). The OSCQuery export of a 0.5 descriptor no longer drops the commands with a number captured in their address ("volume of track 3"): forableton/live.third-party-osc.fw-12.2it writes its numbered commands instead of 12 nodes out of 20. The same bump lets a descriptor drop a key its maker profile gives (null, OSD-b91.8) and lets osc-bridge read it; nothing changes in what osc-bridge publishes.
[0.23.0] — 2026-11-20
Added — an export put on a recognised device in one gesture
export_deviceandosc-bridge export --formatoffer every format ofosd-formats(delugeamong them: a Deluge definition file); the names, media types and extensions come fromosd-formats, and an unknown name is refused with the list. TheFormattype ofosc_bridge::exportnow wraps theosd-formatsone (no case per format).- New MCP tool
install_export(device,on,confirm_overwrite) and CLI formosc-bridge export --device <device> --on <target> [--yes]: the export of a device is put on a plugged target, the format, the path and the way (a file written by SysEx) being read in the target's own descriptor (resources), so no command or tool is specific to a device. Without consent nothing is sent and the preview (format, way, path, size, losses) is returned; a target that declares nothing it receives, a target not plugged in and a source whose export cannot be built are refused before any message; a send that fails on the way says the step reached and the messages already sent, with no retry.export_devicestays read-only. osdandosd-formatsare pinned at the OSD commit that holdsresourcesand the formats'media_type()andextension().
Removed — breaking: the browser relay script
docs/assets/connect.js, the browser side of the relay door, is gone from this repository: it lives in SyntHub, behind its page https://synthhub.roomi-fields.com/connect/.osc-bridge connectis unchanged; its relay frames are now built and read byosc_bridge::relay_protocol.
Changed — breaking: restore_presets and backup_presets name a device
deviceis required on the MCP toolsrestore_presetsandbackup_presetsand on the CLI wordsrestoreandbackup(--device); the mode without a device is gone. A command that does not know which device it talks to cannot respect its banks, pauses or sounds, as every send and receive of KnobKraft Orm goes through a named device's adaptation. A device the catalogue does not know is refused with an invitation to describe it.restore_presetstakesbankandnumber(optional, for a sound that carries no place) and uses the driver: a bank it says cannot be written is refused before any message, the pauses (delay_ms) are kept, the channel and device number are written as configured.gap_msis removed: the pause comes from the driver.backup_presetstakes the sounds the driver recognises on any channel or device number;request_hexis removed: the request comes from the driver (out_portsends it). The CLI losesrestore --gap-msandbackup --request.
Changed
/program/recallwaits the pause a driver declares (programs.delay_ms) between the messages of a recall; a driver declaring none waits nothing. So a device that needs time between a bank select and a program change gets it, as KnobKraft Orm's adaptations give it.osdandosd-formatsmove to the revision that readsdelay_ms,reply_timeout_ms,writableand the sound-transfer elements (OSD 0.6).- The reply bound of a read-back (
dump_paced) is inprograms; no tool, address or CLI word exposes it yet.
[0.22.0] — 2026-11-20
Changed
- The MIDNAM and OSCQuery documents are now written by the shared
osd-formatspackage; osc-bridge keeps only its own addresses (/bridge/*,/identity,/program/*,/raw/syx,/sysex/raw), added to the same namespace for the export and for the running bridge's answer. - Named values of a control are read from its
valuesfield (descriptor 0.6), no longer from the free text_usage. - A device with no
_sourcesentry is refused by the export with the package's fault; the running bridge reports that fault at load and does not serve that device's OSCQuery namespace (the rest of the device works as before). - Accepted differences from the former documents (no OVERLOADS, credit on the
device node, no empty PatchBank) are written in
docs/EXPORT.md.
Added
- An agent sets a sound by the role of a control, on any loaded device, without
knowing its numbers: the MCP tools
list_roles(roles of a device, most important first),set_by_role(value normalised 0 to 1, scaled on the range and steps of the device's control) andget_by_role(current value, when the device declares a read request). Described indocs/MCP.md. - What a format could not carry is shown: the
exportcommand prints the lost elements on the error output (never inside the document), and the MCP toolexport_devicereturns them in alostfield beside the document.
[0.21.1] — 2026-11-18
Changed
- The date library
chrono(declared unmaintained, RUSTSEC-2026-0543) is replaced byjiff; the time printed before a logged message keeps its form (HH:MM:SS.mmm, local time).
[0.21.0] — 2026-11-17
Added
- Links between two devices can be made while the bridge runs, by an agent:
the MCP tools
add_link,remove_linkandlist_linksreach the running bridge through the control addresses/bridge/link/add,/bridge/link/removeand/bridge/link/list(answered to every client, UDP and WebSocket). A link is effective at the next message, with no restart. One table holds the links of the configuration file and the live ones; the list gives each link's origin, source, target and scaling. A link naming an address its driver does not have, a loop, or more than four hops is refused with an error that names it, and the table does not change.
Fixed
printof a script engine built without a driver (identity detection, programs) now writes to the log, not to standard output, where a local MCP session speaks. Every script engine is built by the same constructor.- The MCP tool
submit_driverdescribes the driver format as Open Synth Descriptors and points to its page (https://synthhub.roomi-fields.com/osd/); the SynthHub pageDEVICE_JSON_SCHEMAit cited no longer exists.
[0.20.0] — 2026-11-16
Changed — osc-bridge reads its drivers through osd
- The engine reads every driver with the
osdcrate (Open Synth Descriptors), git dependency pinned to a commit: its own driver structures and the resolution of shared MIDI (midi_of) and maker profiles are removed, the callers read the types ofosd. A driverosdrefuses (a field it does not know, a missing profile or shared file, a cycle) fails to load withosd's fault. Rules that belong to the engine (identity.request,identity.firmware,programsframes) are still refused by the engine, naming the defect. docs/DEVICE_JSON_SCHEMA.mdis removed: the format is the OSD's (https://github.com/roomi-fields/open-synth-descriptors); the documents that cited it point there. The test drivers are the converter's 0.5 output.- A driver's
identity.sendsandidentity.usbare read and kept as written; they are signs of recognition, never messages the engine sends, and recognition itself does not change. - The client downloads a driver with the files
osdsays it is built from (shared MIDI, profiles), asking the server asosdreclaims them; nothing reaches the cache until the resolution succeeded, and a driverosdrefuses fails the download withosd's fault, the cached copy left as it is.
Changed — every request to SynthHub presents this machine's anonymous account
- The server issues the anonymous account before a copy's first request to it,
no longer at the first report or contribution; it is kept in
<config>/osc-bridge/useras before. Detection, driver downloads and the catalogue tools present it on each request.PRIVACY.mdsays so. Offline, nothing is sent.
[0.19.1] — 2026-10-31
Fixed — a command's checksums are computed after its script
- When a command has a
script, every{checksum:...}of its frame is computed after the script has run, over the bytes the script leaves: a function byte the script writes before a checksum is covered. The script sees 0x00 where a checksum goes, and the engine overwrites what it writes there. A script that changes the frame's length on a command holding a checksum is refused (nothing is sent, the error names the driver and the command). Commands without a script build as in 0.19.0.
[0.19.0] — 2026-10-31
Fixed — a driver with a checksum the engine cannot compute loads again
- A driver holding a checksum token the engine cannot compute (
{checksum}without an algorithm, an unknown algorithm, an offset at or past the token, a length past the bytes) loads again, as in 0.17.0; its other commands, parameters and CC work. The commands holding such a token fail at build, naming the driver, the command and the token, and send nothing.lintandinspectprint aWARNline for each such token, andlintcounts them in itsN warning(s).
Added — a driver's Lua reads Electra One's parameterMap.get and the device channel
- A command
scriptcallsparameterMap.get(deviceId, PT_<TYPE>, number)anddevices.get(id):getChannel()(1..16), as an Electra One preset's functions do (https://docs.electra.one/developers/luaext.html);printgoes to the log. - A command carries Electra's parameter number under the annotation key
_electra:{"_electra": {"parameter": {"type": "sysex", "number": 1}}}.
[0.18.0] — 2026-10-31
Changed — the engine computes three checksum algorithms in every frame
{checksum:<algorithm>@<from>[+<length>]}works in command, parameter,programsandidentity.requestframes, withtwos7(Roland),sum7(Waldorf) andxor7(Fractal), as the Electra One preset format defines them; F0 is offset 0. An unknown algorithm or an offset past the bytes written is a load error naming the driver and the token. The former{checksum:twos@N}is removed: write{checksum:twos7@N}.
Changed — PRIVACY.md says what the service keeps of a call
- PRIVACY.md now says that the service keeps each forwarded tool call with its outcome, a shortened error message and its duration, and each search with its words and filters, with or without an account, tied to the visitor and never to the address; it keeps this detail 6 months, then deletes it, and only each day's totals remain, with no visitor and no account.
Changed — tests leave no temporary file behind
- The tests make their temporary folders and files with
tempfile, removed when dropped, a failed test included; CI runs them in a temporary folder of their own and fails on anything they leave there. take_soundwithoutfilesaves the sound in the system's temporary folder under a name of its own (<synth>-<sound>-<random>.syx), so a second take no longer overwrites the first. On Linux and macOS that file is readable by its owner only.
[0.17.0] — 2026-10-29
Added — how a device is recognised, and how its programs are recalled
- Drivers may carry an
identityblock (the request a device answers, universal or the maker's own, the start of its reply, where the firmware version is in it and how to read it, its USB port names) and aprogramsblock (what a program change selects, the banks with their bank select and numbering, settings to switch on, messages around the program change, how a stored sound is read back). A firmware file sharing another's MIDI may hold its own. The OSD format describes both (docs/DEVICE_JSON_SCHEMA.md, since removed, is replaced by it). - Detection sends, after the Universal Identity Request, the makers' requests
the identity blocks name, keeps every SysEx answer per port, and puts first
the driver whose identity recognises it, the variant for the firmware read
from the reply above the others.
GET /v1/detectlists the requests;POST /v1/detecttakes each port's answers asreplies_hex(in place ofidentity_hex); candidates carryrecognised_byandfirmware. When several drivers match the replies equally, the one the others share their MIDI with (midi_of) comes first, and each lists the others inequally_matching. - Maker profiles: what a maker's models share (identity request, reply
pattern with
{family}/{member}, firmware rule, banks, dump request pattern) is written once in<maker>/_profile[.<name>].json; a block names it ("profile": "roland") and gives what differs. Profiles are fetched and cached with the driver that names them. - Lua where no rule fits: an identity
script(is this reply the device's?),firmware.decode: "lua",programs.recall_scriptanddump.script;{checksum:twos@N}in frames. - The same addresses on every device:
/identity(and/identity/reply),/program/recall,/program/dump. /<prefix>/program/recall <bank> <number> [channel]recalls a stored program by bank (name or place) and number as the device shows it. OSCQuery lists it; MIDNAM writes each bank with its bank select and programs.
Changed — the catalogue lives on SynthHub
- The driver catalogue (
devices/, its listings and import scripts) left this repository: it lives on the SynthHub server, which hands drivers out one at a time.--device,inspect,exportand the orchestrator'sspectake a driver file, or a catalogue id (korg/minilogue) or slug (minilogue, the best variant), fetched with its notes and the drivers it shares its MIDI with into<cache>/osc-bridge/drivers; offline, the cached copy. osc-bridge mcp: without--devices-dir,list_devicessearches the catalogue on the server,detect_hardwareandosc-bridge detecthave the server match the MIDI ports found here (POST /v1/detect), and a tool that needs a driver fetches it once per session; offline, only cached drivers.--devices-dir(no default any more) serves a folder of drivers as it is.- Removed: the whole-catalogue mirror (
GET /v1/catalogue,POST /v1/catalogue/files), the catalogue bundled with the npm package, and the lookup ofdevices/next to the executable (OSC_BRIDGE_HOME). - The tests read a few drivers kept in
tests/fixtures/devices/.
Changed — a kept driver is checked for freshness
- A driver, maker profile or notes file fetched from SynthHub is kept in
the cache with the ETag the server gave (
<file>.etagbeside it). The next fetch sends it inIf-None-Match: on304 Not Modifiedthe kept file is used without being downloaded again; on200the file and its ETag are replaced; when the server cannot be reached the kept file is used, as before. osc-bridge never asks for the whole catalogue, only for the drivers a session uses. - When a reply of the server marks this osc-bridge as deprecated
(
DeprecationwithLink: <url>; rel="deprecation", RFC 9745), osc-bridge says once per run, on standard error and in the result of the next MCP tool call, that a newer osc-bridge exists and where. mcp::serveruns one MCP session over any reader and writer, linked to a given server and cache;mcp::runis it over stdio.
Added — OSCQuery and MIDNAM
osc-bridge export --device <file> --format oscquery|midnamand the MCP toolexport_device(shared with the hosted server) write a driver as an OSCQuery namespace (every OSC route with types, ranges, access) or a MIDI Name Document (controllers incl. NRPN/RPN, named values, drum notes per channel), with its sources' credit and licence. Seedocs/EXPORT.md.osc-bridge run --oscquery-bind <addr>(oscquery_bindunderorchestrate) serves the namespace over HTTP, with?HOST_INFO.- A loaded
midi_offile keeps the shared file's sources as_midi_of_sources, so what is written from it credits both.
Changed — a Cargo workspace
- The root
Cargo.tomldeclares a workspace whose root package is the application; version, edition, licence, lints and dependencies come from[workspace.package],[workspace.lints]and[workspace.dependencies], and unsafe code is denied. The released binary is unchanged. scripts/sync_version.pyreads the version from[workspace.package].
Changed — clippy with warnings denied
- CI runs
cargo clippy --workspace --all-targets -- -D warnings, so a new lint fails the build; the code is clean of them, with no behaviour change.
[0.16.0] — 2026-10-24
Added — shared presets
- Tools forwarded to the SynthHub server, for what users make on their
devices, shared under CC BY-SA 4.0:
share_preset(a sound, sequence, kit, project, bank or MIDI clip: device data as hex or a.syxfile, settings by driver address, a MIDI file; category, genres, tags, tempo, key, playing tips;derived_fromfor a remix; an audio preview, uploaded from this machine),update_preset(new versions with a change note),find_presets,get_preset,report_preset,withdraw_preset,comment_preset,favorite_preset,preset_collection,follow_author,set_profile; andload_preset, which fetches a shared preset and plays it into a local device (device data only withconfirm_overwrite). A private device's sounds are refused before anything is sent. take_sound: takes the sound a synth is playing (or a stored program) straight from the synth, with its name, through SynthHub's librarian (the KnobKraft Orm adaptations run on the server; this copy carries the MIDI): the synth is found on its ports, asked for its sound, and the sound saved as a.syxforshare_preset, which takes thelibrarianit returns.load_presetplays the messages the server gives for a preset: a sound the librarian took is fitted to the receiving synth (its MIDI channel, its edit buffer), found by the same detect messages.link_account: links this machine's SynthHub account to the user's account on the site (a one-time address to open and sign in), so what this copy shared appears under their profile.- The test synth keeps one sound: it dumps it on
F0 7D 01 10 F7and takes a patch (F0 7D 01 20+ five values), inosc-bridge connect --test-synthand on the connect page.
Added — catalogue
- 22 synths from KnobKraft Orm adaptations (
knobkraftsource tier, 💾: sound exchange only, no control mapped), for the synths SynthHub's librarian can take sounds from and no other source covers (scripts/import_knobkraft.py): 986 devices. - One count of the catalogue, written everywhere it appears and checked by CI.
[0.15.0] — 2026-10-23
Changed — the site moves to synthhub.roomi-fields.com
- The documentation site and the device catalogue's pages are now built and
served by SynthHub, at https://synthhub.roomi-fields.com/; osc-bridge keeps
its engine docs under
docs/(also published there).mkdocs.yml, the site's own pages and its build hooks leave this repository; GitHub Pages only publishes a page pointing to the new address.
Changed — the server is SynthHub, at mcp.synthhub.roomi-fields.com
- The hosted MCP server, the relay and the link of local copies now use
mcp.synthhub.roomi-fields.com(online::SERVER,connect's default relay, the /connect page,server.json's remote). The server introduces itself as SynthHub. Copies already installed keep working: the old address still serves. - README, the npm README and the MCP guide lead with the hosted server; the
local copy (
npx) comes second.
[0.14.0] — 2026-10-23
Removed — the hosted server's code
osc-bridge mcp --http,--behind-proxy,--data-dirand--relay-bindare gone, with the server side of the relay, the ledger of accounts and reports, the merge job of agent contributions and the container image: the hosted server atmcp.osc-bridge.roomi-fields.comis now a separate program built on this crate.osc-bridge mcpis the local server on stdio; everything that talks to the hosted server stays here (the link of a local copy,osc-bridge connect, the/connectpage). The relay protocol is documented insrc/relay_protocol.rs.
Added — privacy choices, sharing on by default
- A commented settings file,
<config>/osc-bridge/settings.toml, created at first start and editable by hand:offline = truecuts the link to the server,private = [...]lists devices (catalogue id, slug, orvendor/*) about which nothing is sent —report_result,report_mapping,submit_fixandsubmit_driverare refused locally, andget_trustis answered from the trust fetched at startup.osc-bridge privacyshows the settings and changes them (--offline on|off,--private,--public);mcp --offlineandOSC_BRIDGE_OFFLINEstill apply to one run. - Relay: one device can be kept private — a private box per device on the
/connectpage (remembered by the browser),osc-bridge connect --private-port <name>— and its identity is never recorded;relay_detectsays so. Theshareframe gainsprivate: [port names].
Added — every copy linked to the osc-bridge server
osc-bridge mcpon your machine now stays up to date with what the community builds on the hosted server: at startup it mirrors the server's catalogue in the background (only the files that changed, into<cache>/osc-bridge/catalogue), shows each driver's trust inlist_devices(usage_status), and offersreport_result,report_mapping,get_trust,submit_driver,submit_fixandget_contribution, run on the server under an anonymous account kept on the machine (the oneosc-bridge connectuses). MIDI ports never leave the machine.--offlineorOSC_BRIDGE_OFFLINE=1cuts the link.- Hosted server:
GET /v1/catalogue(every driver file with its SHA-256) andPOST /v1/catalogue/files(their contents, 100 per request).
Added — the person at the relay confirms memory writes
- A message sent through the relay that may overwrite the device's memory —
every SysEx but the Identity Request: patch dumps, stores, settings — goes
out only once the person at the door accepts it. The
/connectpage shows what the agent wants to send with Accept / Refuse (and an option to accept the rest of the session);osc-bridge connectasks in the terminal.relay_sendwaits for the answer (two minutes at most) and reports it;gap_msspaces the messages of a dump. Protocol:confirm,confirm_reply,confirm_cancelframes; doors drop any such message that comes as a plainmidi_out.
Changed — licence
- The code is now AGPL-3.0-or-later (was GPL-3.0-or-later): a modified
version run as a network service must offer its source to its users. The
hosted server links its source from
GET /. Driver files are unchanged.
[0.13.0] — 2026-10-23
The catalogue catches up with MIDI Guide — 132 new drivers, drum machines addressable by sound name — and its community data is now properly licensed.
Added — named drum sounds (triggers)
- New optional
triggersblock in device JSONs: each note-triggered sound (drum voice, sample slot) gets an OSC address, e.g./drm1_mkiv/drum/kick.<address> [velocity] [note] [channel]sends the documented Note On; the note is range-checked, velocity defaults to 100. list_routes(MCP) returns the triggers of a device.- 15 drivers ship with a drum map (476 named sounds): Roland TR-8S, TR-1000, T-8; Elektron Analog Rytm MKII, Digitakt II, Syntakt, Model:Samples; KORG drumlogue; Behringer LM Drum; Vermona DRM1 MKIV; Alesis SR-16; Novation DrumStation; and more, plus the General MIDI percussion map.
Added — catalogue API for agents
list_devices(MCP) takes optionalquery,vendor,kindandlimit, and reports the firmware version a driver's source documents.osc-bridge mcp --http <host:port>: MCP over HTTP (endpoint/mcp, JSON responses), offering the catalogue tools plusreport_resultandget_trust, 120 requests per minute per client. No sign-up: the server issues each client an account (Mcp-Session-Id, kept across sessions through a personal endpoint/u/<id>/mcpor auser_idargument) and refuses ids it did not issue; each tool call is logged with that id only.- Usage reports and trust (
report_result,get_trust,GET /v1/trust): works / fails / partial per driver or OSC address, with firmware and the device's Identity Reply. Trust is counted per firmware by concordance of distinct users (3 agreeing, one identified device →usage-verified); a failure on another firmware givesfirmware-dependent, not a demotion; a contrary report without firmware givesdisputedwithneeds_firmware, asking reporters to identify their device. - Automatic rollback: a report that 3 other accounts or more contradict on
the same firmware is rolled back, its account becomes suspect and its
other and new reports wait for approval.
/admin/pendingand/admin/decide(tokenOSC_BRIDGE_ADMIN_TOKEN) approve, reject, suspect or clear. --data-dirkeeps usage records (usage.jsonl) and the ledger of accounts, reports and decisions (ledger.jsonl) on disk.list_devicesreturns each driver'sid(its path in the catalogue) and, on the hosted server, itsusage_status.- Relay (
--relay-bind,relay_status,relay_detect,relay_send,relay_listen): a door — the site's/connectpage with Web MIDI, or any program speaking the WebSocket protocol — pairs the user's MIDI ports with a code; agents detect, play and listen to that hardware through the hosted server, which encodes driver addresses into MIDI itself.osc-bridge connectis the command-line door (all ports, rescanned every 3 s, account kept in~/.config/osc-bridge/user). The first agent account to use a code owns the door; 64 doors at most, 4 per address. - Learned mappings (
report_mapping,GET /v1/learned,mappingsinget_trust): which CC / NRPN / note a control really sends, observed while the user moves it; learned per control and firmware when 3 accounts agree, compared with the driver. - Contributions (
submit_driver,submit_fix,get_contribution): agents submit a driver file, or a corrected variant built from learned mappings; a merge job (.github/workflows/contributions.yml,scripts/apply_contributions.py) checks each one (parse, lint, catalogue regenerated, library tests, nothing else touched) and merges it as a pull request. New source tieragent-contributed(🤖), ranked last. - Test Synth (
devices/examples/test_synth.json, tiertest-fixture🧪): a virtual synth simulated byosc-bridge connect --test-synthand the connect page's checkbox — answers the Identity Request as manufacturer 7D, echoes what it receives — to test the whole chain without hardware. - Hosted instance: https://mcp.osc-bridge.roomi-fields.com/mcp.
- The site publishes a static JSON API:
/api/v1/index.json(every driver with source, firmware and coverage) and each driver file under/api/v1/devices/.
Added — hardware detection
osc-bridge detectand thedetect_hardwareMCP tool: list MIDI ports, send the standard Identity Request, read manufacturer / model / firmware, match the catalogue (port name, manufacturer ID, driver slug) and return a ready-to-runosc-bridge runcommand with the right port numbers.
Added — SysEx librarian
osc-bridge backup/restoreand thebackup_presets/restore_presetsMCP tools: record a device's dump to a.syxfile and send it back, paced. Ports by index or name fragment.restore_presetsrefuses unlessconfirm_overwrite: true(destructive hint set).- The MCP server now exposes eight tools.
Changed — catalogue
- Resynchronised with MIDI Guide (pencilresearch/midi @ 91299d6): 244
drivers refreshed, 132 devices added as
<slug>.pencilresearch.fw-unknown.json(one source per file). Catalogue: 963 devices, 212 vendors, 981 driver files. scripts/import_pencilresearch.py --syncreplaces--bulk, which overwrote existing files. The sync refreshes MIDI Guide-only drivers in place (following upstream renames), keeps hand-added fields such asexpects, never touches the data of drivers mixing several sources, and applies the catalogue's structuralexpectsrule to new entries.- MCP: when several driver files share a slug, the most trustworthy source now wins (verified, then vendor doc, then OSC API, then Electra, then MIDI Guide) instead of whichever file was read first.
- Modbap Trinity moved from
devices/unknown/todevices/modbap/.
Fixed — MCP through npm
- The npm package now ships the device catalogue, and the binary finds it
next to itself (
src/catalogue.rs: current directory,$OSC_BRIDGE_HOME, then beside the executable). Before,npx @roomi-fields/osc-bridge mcpstarted from a client's working directory saw an empty catalogue, and--device devices/…only worked from a checkout. /bridge/statusand/bridge/docsare answered straight to the sender, not only to the configured--osc-clients — the MCPget_statustool asks from its own port and never got a reply.
Security — WebSocket origin check
- The WebSocket transport (0.12.0) accepted any browser page: a website open
in the same browser could drive your synths while
--ws-bindwas on. The handshake now refuses (403) origins other than pages served from this machine; non-browser clients are unaffected.--ws-allow-origin/ws_allow_originsadd trusted origins (nullforfile://,*for any).
Changed — MCP
- A tool that fails now answers with
isError: trueand the reason in its content, as the MCP spec asks, so the model can read it and react; only an unknown tool name is a protocol error. - A
Dockerfile(andglama.json) runs the MCP server in a container with the catalogue, for directories that evaluate servers by running them.
Fixed — licensing
- MIDI Guide data is CC BY-SA 4.0 (it was declared MIT in
sources.toml). Every MIDI Guide source entry now recordslicenseandattribution, and the README credits MIDI Guide and documents the adaptation.
Compatibility
- Device JSONs: additive (
triggersis optional). Existing driver paths are unchanged except Modbap Trinity.
[0.12.0] — 2026-08-20
Browser clients join the bridge: a WebSocket transport carries OSC to and from web pages, which cannot speak UDP.
Added — WebSocket transport
run --ws-bind <ADDR:PORT>and, for the orchestrator,ws_bindin the[osc]section ofbridge.toml: an optional WebSocket listener, disabled by default.- Binary WS frames are raw OSC packets — byte-identical to the UDP transport (rosc encoding), no JSON envelope, so one OSC codec serves both transports. Text frames are ignored with a warning.
- A connected WS client is equivalent to a dynamic
--osc-client: it receives every outbound message (decoded MIDI-in, SysEx replies,/bridge/statusresponses) and its frames go through the exact same dispatch as OSC over UDP — on all three loops (runfor MIDI devices,runfor OSC-transport devices,orchestrateincl. inter-device routes). - Synchronous
tungstenite(one accept thread, one thread per connection) — no async runtime, matching the existing thread-based architecture. A slow client drops frames past a 256-message backlog instead of stalling the bridge; disconnected clients are pruned silently. - First consumer: browser-based Web Audio instruments driven by hardware controllers through the bridge (#1).
Compatibility
- Device JSONs: unchanged — every
0.11.xdriver loads and emits identically; the catalogue is untouched. - CLI / config: purely additive. Without
--ws-bind/ws_bind, behaviour is byte-for-byte identical to0.11.0.
[0.11.0] — 2026-06-24
Adds a control-nature hint to the device surface, so a caller can tell what each control expects without guessing from the range alone.
Added — surface schema
- Every surface entry (
cc_params.entries[]and SysExparams.entries[]) may carry anexpectsfield describing the device-side nature of the control:continuous(default),switch,momentary,trigger,clock,discrete. - It is purely informative: osc-bridge emits the exact same bytes regardless
and adds no runtime behaviour. The signal realization (CV / Gate / Trig /
Clock) is the caller's concern — osc-bridge stays universal and only states the
device-side expectation. The field is open (any string is accepted) and the
recommended vocabulary is documented in the OSD format (
DEVICE_JSON_SCHEMA.md, since removed). list_routes(MCP) now returnsexpectson every cc/sysex entry; the livedevices.jsonindex carries per-nature counts.- Catalogue-wide structural pass: 1363 entries across 96 drivers annotated from
unambiguous structure — binary
[0,1]controls →switch(564), small-range NRPN/SysEx steppers →discrete(799). Hand-annotated Subsequent 37 (switches, stepped selectors, arpeggiator/panic triggers) and Osmose (pedals → momentary). momentary/trigger/clockare not auto-detected (name-based guessing mislabels envelope sustain as a pedal, etc.) — they staycontinuousuntil a driver is reviewed by hand.
Compatibility
- Device JSONs: unchanged behaviour — every unannotated entry is
continuous, so all0.10.xdrivers load and emit identically. The 849-driver catalogue is byte-compatible at runtime.
[0.10.1] — 2026-05-14
A polish release for the MCP server. No device-JSON or runtime changes.
Changed — MCP server
- All five tools now declare an
outputSchemaandannotations(title + read-only / idempotent / open-world hints). Tool results carrystructuredContentalongside the text block, so MCP clients get a typed, machine-readable payload — not just prose to re-parse. - Protocol version advertised at
initializebumped to2025-06-18(the revision that introducedoutputSchema/structuredContent).
Compatibility
- Device JSONs: unchanged — every
0.10.0driver loads as-is. - MCP clients on the older
2025-03-26revision still work; the text block in every tool result is unchanged.
[0.10.0] — 2026-05-14
osc-bridge stops being a hardware-only tool. A new OSC transport lets a driver target a software endpoint — a DAW or a live-coding environment — behind the same named OSC surface as a synth. Eight software targets ship in this release. The multi-device orchestrator gains full dispatch and declarative inter-device routing. And the whole 849-device catalogue is now reachable from an LLM through a built-in MCP server.
Added — OSC transport (software targets)
device.transportblock:kind = "osc"routes a driver to a UDP/OSC endpoint instead of a MIDI port (host/port/reply_port).Command.forward— emit a templated OSC message (typed args,{name}placeholders) to the target; the OSC-mode counterpart offrame.subscriptions[]— one-shot OSC emitted at startup, e.g. to subscribe to a DAW's state changes.replies[]extended withmatch_osc+match_args— decode an incoming OSC message from the target back into the device's named surface.transport.passthrough_prefix— passthrough mode for environments with a user-defined OSC surface: forward everything under/<prefix>/...verbatim, no per-command modelling.- New source tiers:
📡 vendor-osc-api,📡 third-party-osc, and✅ software-verified(tested end-to-end against a running instance of the host software).
Added — software drivers
- Ableton Live via AbletonOSC — ✅ software-verified on Live 12.2.7.
- Bitwig Studio (DrivenByMoss) and Reaper (native OSC) — declarative.
- Sonic Pi, SuperCollider, Pure Data, TouchDesigner, VCV Rack — passthrough.
- Each ships a companion
.mddocumenting host-side setup, ports, conventions.
Added — orchestrator
- Full dispatch:
osc-bridge orchestratenow runs the same command / param / cc_param / midi_out pipeline as single-device mode, not just perf-MIDI. - Loads OSC-transport (software) devices alongside hardware MIDI devices in
a single
bridge.toml. [[routes]]— declarative inter-device routing with optional linear value remap (map.from/map.to). Routes fire on any event the bridge emits, including MIDI-in knob turns and software replies./bridge/docsserved in orchestrator mode (was single-device only).bridge.tomldevice entries can override an OSC driver'shost/port/reply_port.
Added — MCP server
osc-bridge mcp— a Model Context Protocol server (JSON-RPC over stdio). Five tools:list_devices,get_device_docs,list_routes,send,get_status. Both a MIDI MCP (hardware over MIDI/SysEx) and an OSC MCP (DAWs and live-coding environments).- Catalogue index built once at startup — device tools don't re-walk the
devices/tree on every call.
Added — distribution
@roomi-fields/osc-bridgenpm wrapper:npm installdownloads the prebuilt native binary for the platform from the matching GitHub release.server.json(Official MCP Registry) and.claude-plugin/plugin.json.scripts/sync_version.py—Cargo.tomlis the single version source of truth, propagated to every manifest mirror; CI gate fails on drift.
Added — devices & docs
- Arturia MatrixBrute promoted to hardware-verified-partial (fw
2.0.3.1411): 78 hierarchically-named CC params, 39 global options as a
paramsblock (0x42/0x43), 2 SysEx preset commands, 2 reply patterns. - Ableton Push 3 hardware-verified driver (Control Mode, USB-C).
docs/TUTORIAL_FIRST_DEVICE.md— a 30-minute hands-on "first device JSON".- Pages site: Author column added,
📡 OSC-APIfilter chip.
Changed
- Per-variant driver convention — one source per JSON file, never
silently fused. Variants named
<device>.<source-tier>.fw-<version>.json;regen_supported_devices.pygroups them under one catalogue entry. Beetlecrab Tempera rewritten from the vendor doc (fw 2.2) as the reference. _sources[].type "electra-preset-private"normalised toelectra-presetacross 191 devices — a single Electra-preset tier; provenance still carried per entry byurl/preset_id.
Backwards compat
All existing device JSONs load unchanged — every new field is optional
(device.kind, transport, forward, subscriptions, match_osc,
passthrough_prefix). The hardware MIDI drivers are byte-for-byte unaffected.
Test suite: 131 passing.
[0.9.0] — 2026-04-14
Reconfigurable controllers become first-class citizens, driven by the Electra One MK2 as the hardware-verified reference. The Lua scripting subsystem grows from a narrow escape hatch (per-field transforms) into a full device-driver substrate — persistent state, native JSON, dynamic routing, multi-block SysEx emission, outbound OSC — all proven end-to-end against real hardware (firmware 4.1.4).
Added
src/routing.rs—DynamicRouteswith page-aware CC↔OSC lookup, mutable at runtime underArc<Mutex<_>>.- Scripting extensions (
src/scripting.rs): - Persistent per-device state (
ob.state). - Native JSON codec (
ob.json_decode/ob.json_encode). - Execution profiles (
Default10 ms / 1 MiB vsPresetIngest500 ms / 4 MiB). - Dynamic route registration (
ob.register_cc_route,clear_routes,set_current_page,get_current_page,list_routes). - Multi-block SysEx emission (
ob.emit_sysex). - Outbound OSC emission (
ob.emit_osc) for introspection. log_warn/log_error.- Device schema:
custom_commands(scripted OSC endpoints with no declarative frame), auto-loaded companion<stem>.mdserved via/bridge/docs. - Runtime:
try_dynamic_cc_in/try_dynamic_osc_outhelpers consulted ahead of the declarative pipeline;reply.scriptwired through withctx.bindings;/bridge/docsendpoint. - Electra One MK2 driver (
devices/electra-one/): /preset/uploadcustom_command — parses an Electra preset, rebuilds CC routes, sets current page, emits the SysEx data block (0x01 0x01) to the device./routes/list,/preset/current,/page/currentintrospection.- Reply script on
/page/switchedkeepingcurrent_pagein sync. electra-one.mdintegration guide served over/bridge/docs— hardware-verified against firmware 4.1.4.- CLI:
osc-send --from-file <path>for loading large string args (preset JSON) without shell quoting hell. - Tests:
routing(6),dynamic_routing(7),custom_commands(3),electra_one_driver(12), plus expandedscripting(27). Total 100.
Hardware-verified
- Electra One MK2 (firmware 4.1.4, serial EO2-4312746f, hw rev 3.0) — upload round-trip, route registration, pot mapping, SysEx ACK/NACK flow, all introspection endpoints, and rendering of all control types (fader, list, pad, adsr, adr, dx7envelope). Bumped from 📘 vendor-doc to ✅.
Known caveats (documented in the companion guide)
- Midir/Windows truncates incoming SysEx at 1024 bytes, affecting
/preset/geton large presets (the device side is fine). inputs: [{potId, valueId}]mandatory on every Electra control.- Colors must be hex 6-char (no palette names).
- Upload targets the currently-selected slot — pair with
arm_upload. - Envelope segments cycle via a touch-and-hold gesture, not multi-pot binding.
[0.8.0] — 2026-04-13
Massive library expansion via Electra One community presets — and a generic multi-source ingest pipeline.
Added
sources.toml— central declaration of every bulk-import source the project knows about. Currently:pencilresearch(git) andelectra-one-public(Firestore).scripts/sync_sources.py— generic driver that dispatches each source to the right module underscripts/sources/(git, firestore, …).scripts/sources/firestore.py— Firebase login + Firestore listing/fetch with predicate filtering and incremental skip.scripts/import_electra_preset.py— converts an Electra One preset (schemaVersion 2/3 — Editor "tiles" layout) into an osc-bridge device JSON. Handles cc7 / cc14 / nrpn / sysex inline message types. Auto-merges into existing devices when vendor + name match strictly; otherwise creates a new entry. SysEx common-prefix factored into the device'ssysex.header.scripts/enrich_electra_authors.py— second pass that resolves each imported preset'suserId→ display name and writes it into_sources[].authorfor credit.- New status marker 🎛️ electra-preset in
regen_supported_devices.pyto distinguish community Electra presets from manufacturer docs.
Imported
- +464 new devices, +95 enriched existing pencilresearch devices, from the 636 public Electra One presets. 71 skipped (Lua-only utilities with no MIDI bindings).
- Library size: 331 → 795 devices across 117 vendors.
- Notable additions: every Sequential Prophet (incl. Prophet-5/10 Rev4, Prophet 6, OB-6, OB-X8), MatrixBrute, Hydrasynth, Access Virus A/TI, Waldorf Iridium / Blofeld, Korg Wavestate, Elektron Digitone / Syntakt / Octatrack, Dreadbox Nymphes (+SysEx layer), and ~450 more.
Schema
_sources[]entries gain an optionalauthorfield when the source istype: "electra-preset". Each Electra import cites the preset URL, ID, revision, and the author's display name (credit only — no internal account identifier is stored).
Backwards compat
All previously-shipped devices continue to load. Existing pencilresearch
JSONs that gained an Electra layer keep their original _sources[] entry
(pencilresearch reference now appears alongside the Electra one).
[0.7.0] — 2026-04-13
Mass device library: 331 devices across 102 vendors.
Added
- Bulk import of pencilresearch/midi —
326 new devices generated from the canonical community CSV collection
(commit
deb41f2). Moog (13), Roland (37), Elektron (16), DSI (9), Sequential (7), Yamaha (7), Waldorf (8), Novation (8), Behringer (6), Dreadbox (3), and ~80 more vendors. 7 empty-skeleton CSVs skipped. scripts/import_pencilresearch.py— single-CSV, bulk, and--updatemodes. Records the upstream commit SHA in_sources[0].commitso re-imports can diff against a precise baseline. Preserves custom extensions (SysEx layer, replies, custom commands) across re-imports.scripts/regen_supported_devices.py— rebuildsdocs/SUPPORTED_DEVICES.mdfrom everydevices/**/*.json, grouped by vendor alphabetically. Single source of truth = the JSONs.- Schema:
_source(string) deprecated in favour of_sources(array of{type, url, commit?, imported_at}). Multiple sources can coexist (e.g. pencilresearch CC/NRPN baseline + vendor-doc SysEx layer). The legacy_sourcefield is still read for backwards-compat. - CI step: regenerates
SUPPORTED_DEVICES.mdand fails on diff — contributors must keep the catalogue in sync. - GitHub topics added for discoverability: osc, midi, sysex, hardware-synth, moog, arturia, novation, sequential, korg, roland, yamaha, elektron, dave-smith-instruments, waldorf, dreadbox, erica-synths, polyend.
- README compacted: a 3-row summary instead of an unbounded table.
Full catalogue lives in
docs/SUPPORTED_DEVICES.md.
Known limitations
Pencilresearch-imported devices are CC/NRPN only. SysEx (preset
management, display control, vendor-proprietary opcodes) is NOT
covered for those 326 devices — the _limitations field spells it out.
Extending a device with SysEx on top of the imported base is a
first-class contribution path; see CONTRIBUTING.md and the
update_device.md PR template.
[0.6.0] — 2026-04-13
Kanopi integration: N/N bridge — performance MIDI + multi-client + multi-device.
Added
midi_outoptional section on every device. When present, activates standard OSC performance routes automatically:/note/on,/note/off,/pitchbend,/aftertouch,/poly_aftertouch,/cc/{num},/program_change. Supportsdefault_channelandnote_offset(drum-machine mappings)./bridge/statusRPC endpoint — emits one/bridge/status/device <slug> okOSC message per active device to every configured client. Lets Kanopi verify the setup at boot.--osc-clientis now repeatable. Every listed client receives a copy of each outbound event.RuntimeOptions.osc_client: Option<...>→RuntimeOptions.osc_clients: Vec<SocketAddr>.- New subcommand:
osc-bridge orchestrate --config bridge.toml. Drives N devices in one process, dispatched byosc_prefix. Each entry can override the device's defaultosc_prefix(useful when two instances of the same model are wired up — e.g./matrixbrute-1//matrixbrute-2). Rate-limited per device, MIDI-in events emitted with the right prefix. docs/CR-kanopi-gaps.md— design rationale.examples/bridge.toml— sample orchestrator config.- Added
toml = "0.8"dependency.
Backwards compat
All existing device JSONs load unchanged. Zero regression on prior tests
(24 → 42 passing). CLI breaking change on --osc-client: the flag is
now a Vec, so passing it once still works as before; passing it
multiple times is the new feature.
[0.5.0] — 2026-04-13
Architecture: Lua scripting escape hatch.
Added
mlua(Lua 5.4 vendored) as an optional runtime dependency.src/scripting.rs— sandboxedScriptEnginewith 1 MiB memory cap, 10 ms deadline via instruction hook,ob.*helper library (u7_clamp,u14_lsb/msb,checksum_xor/sum,log). Loaders,os,io,debug,package,requireare stripped.- Schema: optional
transform/transform_reverseonParamEntryandCcParamEntry; optionalscriptonCommandandReplyPattern(the latter reserved). - Runtime wiring:
transformapplied pre-clamp on CC + SysEx param paths;scriptrun post-build on commands. Engine is lazy-init — devices without scripts pay zero overhead. osc-bridge lint <device.json>— validates schema, warns on every use oftransform/scriptper the design CR.devices/examples/scripted-example.jsonwith 3 integration tests.docs/scripting.mduser guide.
Backwards compat
All existing device JSONs load unchanged. 24 pre-existing tests green.
[0.4.0] — 2026-04-13
Novation Launch Control XL 3 (doc-derived).
Added
devices/novation/launch-control-xl-3.json— 6 SysEx commands (DAW mode on/off, RGB LED per control, display configure/text/bitmap)- 69 CC entries (12 feature controls + 57 palette-index LED setters)
- bitmap-ack reply. CC numbers cross-checked against Novation's published surface diagram PNG.
tests/launch_control_xl_3.rs— 8 integration tests verifying SysEx bytes against the reference guide.- README: Novation row added with source + entry count.
[0.3.0] — 2026-04-13
Electra One MK2 (doc-derived).
Added
devices/electra-one/electra-one.json— 31 SysEx commands (query preset/runtime/config, preset/page/control-set switch, display text, Lua eval via/lua, reboot, destructive ops) + 12 inbound events decoded viareplies(ACK/NACK, switch events, pot touch, list-change notifications).tests/electra_one.rs— 9 integration tests.- README: Electra One row + updated "Source" column distinguishing hardware-verified from doc-derived.
[0.2.1] — 2026-04-13
Honesty pass: exhaustive doc-derived maps, explicit source tracking.
Changed
- Polyend Synth: 110 → 195 CC entries (previously 85 silently skipped). Parsed via fixed-column layout from the official PDF. All 8 engines fully covered.
- Moog Subsequent 37: cleaner OSC naming (dropped redundant section prefix from param names).
- README: added explicit
Sourcecolumn (hardware-verified vs doc-derived) and per-device entry counts.
[0.2.0] — 2026-04-13
Schema extension: 14-bit CC pairs + NRPN addressing.
Added
- Moog Subsequent 37 (131 params: 89 CC, 98 NRPN, 31 as 14-bit CC pairs).
CcParamEntrygains optionalcc_lsb,nrpn_msb,nrpn_lsbfields. Runtime emits the correct MIDI sequence per entry: single CC, 14-bit CC pair, or full NRPN (CC 99/98/6 + CC 38 when 14-bit).
Backwards compat
Existing devices with single-CC entries continue to work unchanged;
the new fields are all Option<u8> with #[serde(default)].
[0.1.1] — 2026-04-13
Added
- Polyend Synth device (110 CC-mapped params across 8 engines,
program-change command). First CC-only device —
cc_paramssection introduced in the schema.
[0.1.0] — 2026-04-12
Initial public release.
Added
- Skeleton declarative bridge: OSC ↔ MIDI/SysEx driven by
devices/<vendor>/<name>.json. - Hardware-verified Arturia MiniLab 3 (264 SysEx params + 6 commands
- MIDI-in feedback, Ghidra static + empirical fuzz).
- CLI:
list,inspect,run,osc-send,osc-listen. - GPL-3.0 licence (inherits from the
sysex-controlsreverse engineering that seeded the MiniLab 3 parameter table).
The extracts of the service are compressed
The audio the service plays on the virtual FM-1 or DX7 for a sound without a recording from its author is kept as Opus at about 64 kbit/s in an MP4 file, served as audio/mp4, instead of a 350 kB WAV (audio/wav). Where an audio comes from is no longer read from its type: audio_source (virtual-instrument or author) is kept with the media and unchanged in form. The extracts already kept as WAV are converted once, in the background, after the service starts; an author's recording is never converted.
Breaking: a sound's sheet no longer carries audio, image or midi
The sheet of a sound (GET /v1/presets/<id>, the get_preset tool) drops the direct addresses audio, image and midi, which the service refused without a signed link. It gains has_audio and has_image (booleans); the only addresses of a sound's files are those of links. midi_base64 is unchanged. The .osd.json export of a sound no longer carries content.midi or preview.