Skip to content
SynthHub

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) and osc-bridge detect --learn --listen-ms listen 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 32 controls; absent fields are never guessed) with the measured delays beside it in measured. So a device that does not say who it is still gives what is needed to learn it. Without learn, the report is unchanged.

Added — the detection reads the USB ids of a device (Linux)

  • detect_hardware and osc-bridge detect give, per device, usb with vendor_id and product_id when 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.usb holds the pair (80 points, above the port name's 60), and recognises it without a SysEx reply or a matching port name (recognised_by says usb). 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_docs and list_routes take device (a catalogue id or an OSC prefix), as the other tools do. A call that passes slug, alone or beside device, is refused with an error that says to name the device by device; a call with neither says device is missing.
  • In a list_devices entry and a detect_hardware candidate, device is the catalogue id (it replaces id and slug) and the OSC prefix is osc_prefix. get_device_docs returns device as the caller passed it.
  • The unknown-device message and the match: line of the command-line detection say device.

[0.23.1] — 2026-11-20

Fixed — the OSCQuery export keeps a command whose address takes a number

  • osd and osd-formats are pinned to commit 9fd94ec of Open Synth Descriptors (was bc6afe9). The OSCQuery export of a 0.5 descriptor no longer drops the commands with a number captured in their address ("volume of track 3"): for ableton/live.third-party-osc.fw-12.2 it 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_device and osc-bridge export --format offer every format of osd-formats (deluge among them: a Deluge definition file); the names, media types and extensions come from osd-formats, and an unknown name is refused with the list. The Format type of osc_bridge::export now wraps the osd-formats one (no case per format).
  • New MCP tool install_export (device, on, confirm_overwrite) and CLI form osc-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_device stays read-only.
  • osd and osd-formats are pinned at the OSD commit that holds resources and the formats' media_type() and extension().

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 connect is unchanged; its relay frames are now built and read by osc_bridge::relay_protocol.

Changed — breaking: restore_presets and backup_presets name a device

  • device is required on the MCP tools restore_presets and backup_presets and on the CLI words restore and backup (--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_presets takes bank and number (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_ms is removed: the pause comes from the driver.
  • backup_presets takes the sounds the driver recognises on any channel or device number; request_hex is removed: the request comes from the driver (out_port sends it). The CLI loses restore --gap-ms and backup --request.

Changed

  • /program/recall waits 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.
  • osd and osd-formats move to the revision that reads delay_ms, reply_timeout_ms, writable and the sound-transfer elements (OSD 0.6).
  • The reply bound of a read-back (dump_paced) is in programs; 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-formats package; 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 values field (descriptor 0.6), no longer from the free text _usage.
  • A device with no _sources entry 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) and get_by_role (current value, when the device declares a read request). Described in docs/MCP.md.
  • What a format could not carry is shown: the export command prints the lost elements on the error output (never inside the document), and the MCP tool export_device returns them in a lost field beside the document.

[0.21.1] — 2026-11-18

Changed

  • The date library chrono (declared unmaintained, RUSTSEC-2026-0543) is replaced by jiff; 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_link and list_links reach the running bridge through the control addresses /bridge/link/add, /bridge/link/remove and /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

  • print of 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_driver describes the driver format as Open Synth Descriptors and points to its page (https://synthhub.roomi-fields.com/osd/); the SynthHub page DEVICE_JSON_SCHEMA it 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 osd crate (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 of osd. A driver osd refuses (a field it does not know, a missing profile or shared file, a cycle) fails to load with osd's fault. Rules that belong to the engine (identity.request, identity.firmware, programs frames) are still refused by the engine, naming the defect.
  • docs/DEVICE_JSON_SCHEMA.md is 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.sends and identity.usb are 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 osd says it is built from (shared MIDI, profiles), asking the server as osd reclaims them; nothing reaches the cache until the resolution succeeded, and a driver osd refuses fails the download with osd'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/user as before. Detection, driver downloads and the catalogue tools present it on each request. PRIVACY.md says 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. lint and inspect print a WARN line for each such token, and lint counts them in its N warning(s).

Added — a driver's Lua reads Electra One's parameterMap.get and the device channel

  • A command script calls parameterMap.get(deviceId, PT_<TYPE>, number) and devices.get(id):getChannel() (1..16), as an Electra One preset's functions do (https://docs.electra.one/developers/luaext.html); print goes 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, programs and identity.request frames, with twos7 (Roland), sum7 (Waldorf) and xor7 (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_sound without file saves 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 identity block (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 a programs block (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/detect lists the requests; POST /v1/detect takes each port's answers as replies_hex (in place of identity_hex); candidates carry recognised_by and firmware. When several drivers match the replies equally, the one the others share their MIDI with (midi_of) comes first, and each lists the others in equally_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_script and dump.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, export and the orchestrator's spec take 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_devices searches the catalogue on the server, detect_hardware and osc-bridge detect have 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 of devices/ 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>.etag beside it). The next fetch sends it in If-None-Match: on 304 Not Modified the kept file is used without being downloaded again; on 200 the 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 (Deprecation with Link: <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::serve runs one MCP session over any reader and writer, linked to a given server and cache; mcp::run is it over stdio.

Added — OSCQuery and MIDNAM

  • osc-bridge export --device <file> --format oscquery|midnam and the MCP tool export_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. See docs/EXPORT.md.
  • osc-bridge run --oscquery-bind <addr> (oscquery_bind under orchestrate) serves the namespace over HTTP, with ?HOST_INFO.
  • A loaded midi_of file 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.toml declares 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.py reads 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 .syx file, settings by driver address, a MIDI file; category, genres, tags, tempo, key, playing tips; derived_from for 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; and load_preset, which fetches a shared preset and plays it into a local device (device data only with confirm_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 .syx for share_preset, which takes the librarian it returns.
  • load_preset plays 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 F7 and takes a patch (F0 7D 01 20 + five values), in osc-bridge connect --test-synth and on the connect page.

Added — catalogue

  • 22 synths from KnobKraft Orm adaptations (knobkraft source 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-dir and --relay-bind are 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 at mcp.osc-bridge.roomi-fields.com is now a separate program built on this crate. osc-bridge mcp is the local server on stdio; everything that talks to the hosted server stays here (the link of a local copy, osc-bridge connect, the /connect page). The relay protocol is documented in src/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 = true cuts the link to the server, private = [...] lists devices (catalogue id, slug, or vendor/*) about which nothing is sent — report_result, report_mapping, submit_fix and submit_driver are refused locally, and get_trust is answered from the trust fetched at startup. osc-bridge privacy shows the settings and changes them (--offline on|off, --private, --public); mcp --offline and OSC_BRIDGE_OFFLINE still apply to one run.
  • Relay: one device can be kept private — a private box per device on the /connect page (remembered by the browser), osc-bridge connect --private-port <name> — and its identity is never recorded; relay_detect says so. The share frame gains private: [port names].

Added — every copy linked to the osc-bridge server

  • osc-bridge mcp on 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 in list_devices (usage_status), and offers report_result, report_mapping, get_trust, submit_driver, submit_fix and get_contribution, run on the server under an anonymous account kept on the machine (the one osc-bridge connect uses). MIDI ports never leave the machine. --offline or OSC_BRIDGE_OFFLINE=1 cuts the link.
  • Hosted server: GET /v1/catalogue (every driver file with its SHA-256) and POST /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 /connect page shows what the agent wants to send with Accept / Refuse (and an option to accept the rest of the session); osc-bridge connect asks in the terminal. relay_send waits for the answer (two minutes at most) and reports it; gap_ms spaces the messages of a dump. Protocol: confirm, confirm_reply, confirm_cancel frames; doors drop any such message that comes as a plain midi_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 triggers block 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 optional query, vendor, kind and limit, 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 plus report_result and get_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>/mcp or a user_id argument) 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 gives firmware-dependent, not a demotion; a contrary report without firmware gives disputed with needs_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/pending and /admin/decide (token OSC_BRIDGE_ADMIN_TOKEN) approve, reject, suspect or clear.
  • --data-dir keeps usage records (usage.jsonl) and the ledger of accounts, reports and decisions (ledger.jsonl) on disk.
  • list_devices returns each driver's id (its path in the catalogue) and, on the hosted server, its usage_status.
  • Relay (--relay-bind, relay_status, relay_detect, relay_send, relay_listen): a door — the site's /connect page 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 connect is 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, mappings in get_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 tier agent-contributed (🤖), ranked last.
  • Test Synth (devices/examples/test_synth.json, tier test-fixture 🧪): a virtual synth simulated by osc-bridge connect --test-synth and 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 detect and the detect_hardware MCP 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-run osc-bridge run command with the right port numbers.

Added — SysEx librarian

  • osc-bridge backup / restore and the backup_presets / restore_presets MCP tools: record a device's dump to a .syx file and send it back, paced. Ports by index or name fragment. restore_presets refuses unless confirm_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 --sync replaces --bulk, which overwrote existing files. The sync refreshes MIDI Guide-only drivers in place (following upstream renames), keeps hand-added fields such as expects, never touches the data of drivers mixing several sources, and applies the catalogue's structural expects rule 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/ to devices/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 mcp started from a client's working directory saw an empty catalogue, and --device devices/… only worked from a checkout.
  • /bridge/status and /bridge/docs are answered straight to the sender, not only to the configured --osc-clients — the MCP get_status tool 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-bind was on. The handshake now refuses (403) origins other than pages served from this machine; non-browser clients are unaffected. --ws-allow-origin / ws_allow_origins add trusted origins (null for file://, * for any).

Changed — MCP

  • A tool that fails now answers with isError: true and 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 (and glama.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 records license and attribution, and the README credits MIDI Guide and documents the adaptation.

Compatibility

  • Device JSONs: additive (triggers is 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_bind in the [osc] section of bridge.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/status responses) and its frames go through the exact same dispatch as OSC over UDP — on all three loops (run for MIDI devices, run for OSC-transport devices, orchestrate incl. 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.x driver loads and emits identically; the catalogue is untouched.
  • CLI / config: purely additive. Without --ws-bind / ws_bind, behaviour is byte-for-byte identical to 0.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 SysEx params.entries[]) may carry an expects field 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 returns expects on every cc/sysex entry; the live devices.json index 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 / clock are not auto-detected (name-based guessing mislabels envelope sustain as a pedal, etc.) — they stay continuous until a driver is reviewed by hand.

Compatibility

  • Device JSONs: unchanged behaviour — every unannotated entry is continuous, so all 0.10.x drivers 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 outputSchema and annotations (title + read-only / idempotent / open-world hints). Tool results carry structuredContent alongside the text block, so MCP clients get a typed, machine-readable payload — not just prose to re-parse.
  • Protocol version advertised at initialize bumped to 2025-06-18 (the revision that introduced outputSchema / structuredContent).

Compatibility

  • Device JSONs: unchanged — every 0.10.0 driver loads as-is.
  • MCP clients on the older 2025-03-26 revision 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.transport block: 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 of frame.
  • subscriptions[] — one-shot OSC emitted at startup, e.g. to subscribe to a DAW's state changes.
  • replies[] extended with match_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 .md documenting host-side setup, ports, conventions.

Added — orchestrator

  • Full dispatch: osc-bridge orchestrate now 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/docs served in orchestrator mode (was single-device only).
  • bridge.toml device entries can override an OSC driver's host / 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-bridge npm wrapper: npm install downloads 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.toml is 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 params block (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-API filter 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.py groups them under one catalogue entry. Beetlecrab Tempera rewritten from the vendor doc (fw 2.2) as the reference.
  • _sources[].type "electra-preset-private" normalised to electra-preset across 191 devices — a single Electra-preset tier; provenance still carried per entry by url / 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 — DynamicRoutes with page-aware CC↔OSC lookup, mutable at runtime under Arc<Mutex<_>>.
  • Scripting extensions (src/scripting.rs):
  • Persistent per-device state (ob.state).
  • Native JSON codec (ob.json_decode / ob.json_encode).
  • Execution profiles (Default 10 ms / 1 MiB vs PresetIngest 500 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>.md served via /bridge/docs.
  • Runtime: try_dynamic_cc_in / try_dynamic_osc_out helpers consulted ahead of the declarative pipeline; reply.script wired through with ctx.bindings; /bridge/docs endpoint.
  • Electra One MK2 driver (devices/electra-one/):
  • /preset/upload custom_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/current introspection.
  • Reply script on /page/switched keeping current_page in sync.
  • electra-one.md integration 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 expanded scripting (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/get on 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) and electra-one-public (Firestore).
  • scripts/sync_sources.py — generic driver that dispatches each source to the right module under scripts/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's sysex.header.
  • scripts/enrich_electra_authors.py — second pass that resolves each imported preset's userId → display name and writes it into _sources[].author for credit.
  • New status marker 🎛️ electra-preset in regen_supported_devices.py to 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 optional author field when the source is type: "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 --update modes. Records the upstream commit SHA in _sources[0].commit so re-imports can diff against a precise baseline. Preserves custom extensions (SysEx layer, replies, custom commands) across re-imports.
  • scripts/regen_supported_devices.py — rebuilds docs/SUPPORTED_DEVICES.md from every devices/**/*.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 _source field is still read for backwards-compat.
  • CI step: regenerates SUPPORTED_DEVICES.md and 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_out optional section on every device. When present, activates standard OSC performance routes automatically: /note/on, /note/off, /pitchbend, /aftertouch, /poly_aftertouch, /cc/{num}, /program_change. Supports default_channel and note_offset (drum-machine mappings).
  • /bridge/status RPC endpoint — emits one /bridge/status/device <slug> ok OSC message per active device to every configured client. Lets Kanopi verify the setup at boot.
  • --osc-client is 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 by osc_prefix. Each entry can override the device's default osc_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 — sandboxed ScriptEngine with 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, require are stripped.
  • Schema: optional transform / transform_reverse on ParamEntry and CcParamEntry; optional script on Command and ReplyPattern (the latter reserved).
  • Runtime wiring: transform applied pre-clamp on CC + SysEx param paths; script run 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 of transform / script per the design CR.
  • devices/examples/scripted-example.json with 3 integration tests.
  • docs/scripting.md user 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 via replies (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 Source column (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).
  • CcParamEntry gains optional cc_lsb, nrpn_msb, nrpn_lsb fields. 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_params section 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-controls reverse 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.