Writing a driver in other formats — every format of osd-formats
A driver file can be written in every format the osd-formats package offers
(oscquery, midnam, deluge, and the others it lists), which other tools
read. Two are detailed here:
- OSCQuery — the OSC addresses of the device, with their types, ranges and access, as the JSON namespace of the OSCQuery proposal. OSC controllers and browsers build their controls from it.
- MIDNAM — the device's MIDI names as a MIDI Name Document 1.0: its controllers and drum notes, by name, for DAWs (Ardour, Logic, Digital Performer…).
Every format is written by the osd-formats package, the one everyone uses: a format
corrected there is corrected here. What each element of a descriptor becomes in
each format is in its documents (osd-formats/docs/oscquery.md,
osd-formats/docs/midnam.md).
The same text comes from three places:
| Where | How |
|---|---|
| Command line | osc-bridge export --device korg/minilogue --format oscquery (any format of osd-formats, for example midnam or deluge; an unknown name lists them): the document on the standard output, what the format could not carry on the error output, one line each (not carried: <place>: <reason>) |
| MCP server | tool export_device with device (id or slug) and format; the document is the text content, the list lost (place, reason) is beside it in the structured result |
| Running bridge | osc-bridge run … --oscquery-bind 127.0.0.1:7891, or oscquery_bind in the [osc] section of bridge.toml |
Putting an export on a device
An export can be put on a recognised device, in one gesture that is the same
for every target: what the target receives is said in its own descriptor
(resources: the format it exports, the path of the file, the steps of a file
written by SysEx), so osc-bridge holds no command per device. A target that
declares nothing it receives is refused.
| Where | How |
|---|---|
| Command line | osc-bridge export --device korg/minilogue --on synthstrom/deluge [--yes] (no --format: the target gives it) |
| MCP server | tool install_export with device, on and confirm_overwrite |
A write may overwrite a file on the device, which is not read first: without
--yes (confirm_overwrite: true) nothing is sent, and the format, the way,
the path, the size and what the format could not carry are shown. A target that
is not plugged in is refused before any message. A send that fails on the way
says the step reached and the messages already sent; nothing is retried or
undone. The library function is osc_bridge::install::install.
The library function is osc_bridge::export::export(&device, format): it
returns the document with the list of what the format could not carry. The
hosted server serves the same tool, so the site and the API give the same
output.
Credit and licence
Both documents carry the credit and licence of the driver's _sources. A
driver with no source is not written (NoSources): its credit cannot be.
- OSCQuery: in the
DESCRIPTIONof the device's node. - MIDNAM: in the
<Author>element.
Errors
- A device that speaks OSC only has no MIDNAM: the export fails with
«
speaks OSC, not MIDI: it has no MIDI names ». - An unknown format name fails with « unknown format '
' (one of: oscquery, midnam) ».
The running bridge
The listener stays in osc-bridge: it answers GET / (whole namespace),
GET /<path> (that node and what is under it), GET /<path>?ATTRIBUTE (one
attribute, 204 when the node has none, 400 for an attribute it does not know)
and ?HOST_INFO (OSC_IP, OSC_PORT, OSC_TRANSPORT UDP, and
WS_IP/WS_PORT when --ws-bind is on). The namespace it answers is the
export document; under orchestrate the documents of every device are merged
under one root.
Left out: VALUE (the bridge keeps no state), LISTEN and the other
WebSocket commands, and Zeroconf advertising (_oscjson._tcp): give clients
the address by hand.
What osc-bridge adds to the namespace
osd-formats writes the namespace of the device. The addresses that are
osc-bridge's own conventions, not the device's, are added by one module of
osc-bridge (bridge_routes), for the export and for the running bridge alike:
/bridge/*, and for each MIDI device /identity, /identity/reply,
/program/recall, /program/dump, /raw/syx, /sysex/raw. They keep the
types, ranges, VALS of the bank names and OVERLOADS they had.
A driver with no source
No source is made up. The export of a driver with no _sources is refused with
the fault of osd-formats (NoSources). The running bridge names that fault at
start-up and does not serve that driver's OSCQuery namespace; the rest of the
driver works as before, and a link under its prefix is not judged against a
namespace it does not have.
Differences from the former exporters
Measured by crates/osc-bridge/tests/it/export_documents.rs against facts
frozen from the exporters osc-bridge held before (tests/fixtures/exports/).
These differences are accepted:
- OSCQuery: no
OVERLOADSon the routes of the descriptor's controls and commands (the descriptor has no field for another argument list), and noEXTENDED_TYPEfor a control's value (the descriptor names no argument of a controller); - OSCQuery: the credit is on the device's node, not on the root;
- OSCQuery: no
/param/get, no MIDI performance routes (/note/on,/cc/<n>…), no route a script adds, and no address the bridge sends (midi_in,replies): the package writes the routes of the controls, commands and triggers (what it does not carry is in the list of what is lost); - MIDNAM: a driver without banks has no empty
PatchBank; - MIDNAM: the named values of a control come from its
valuesfield; the free text_usageis no longer read.
What osd-formats could not carry is shown to the person who exports.