Open Synth Descriptors (OSD)

OSD is the open format in which MIDI devices, their sounds and their firmwares are described; osc-bridge makes them talk, and synthhub holds their catalogue. It grew out of that catalogue on 27 October 2026, split off into a specification of its own and dedicated to the public domain. Its main limit: it is a draft, at version 0.4; until 1.0, a new version may rename or remove fields.

A format cannot be heard: the example in the next section stands in for a demo.

What MIDI leaves out

OSD complements the MIDI standards; it does not replace them. MIDI says how messages travel, and MIDI 2.0 Property Exchange lets a recent device describe part of itself. OSD covers the rest: the thousands of devices that never will, each maker’s own SysEx, which holds most of a synth, and the sounds and firmwares people share. Where a MIDI standard already names something, OSD aims for the same name, so that exporting stays a translation.

A sound descriptor, as it stands in the repository (examples/warm-pad.sound.json):

{
  "$schema": "https://synthhub.roomi-fields.com/osd/0.4/sound.schema.json",
  "name": "Warm pad",
  "kind": "sound",
  "device": { "descriptor": "korg/minilogue", "vendor": "KORG", "model": "minilogue" },
  "content": {
    "settings": { "/amp/attack": [90], "/amp/release": [100], "/filter/cutoff": [64] }
  },
  "author": { "name": "Example Author", "url": "https://example.org" },
  "license": "CC0-1.0",
  "category": "pad",
  "genres": ["ambient"],
  "tips": "Hold chords; the mod wheel opens the filter.",
  "version": 1,
  "published": "2026-10-27T12:00:00Z"
}

Settings are given by readable address (/filter/cutoff); the device descriptor turns each one into a CC, NRPN, note or SysEx.

Getting started

From a clone of the repository:

pip install jsonschema
python3 tools/validate.py sound examples/warm-pad.sound.json

The second command answers 1/1 valid sound descriptors. Run as written on 28 October 2026, at commit 2f0f8c0, with jsonschema 4.19.2. The first argument names the descriptor type; a folder is checked file by file. The schemas are also served online, at https://synthhub.roomi-fields.com/osd/<version>/<name>.schema.json.

What it describes

Five things, each with its JSON schema:

• Device: its identity and how to recognise it (identity reply, port names, USB ids, what it sends by itself); its controls as CC, 14-bit CC, NRPN, RPN and SysEx parameters; its named messages and checksums; its programs and banks; its drum sounds; what it sends back.
• Maker profile: what a maker’s or a family’s devices share, extended by each device.
• Sound: a sound, kit, pattern, project, bank or MIDI clip; its data, its device and firmware, its author, its licence, its origin.
• Fingerprint: what a detection observed of a device plugged in, and the model the person confirmed; it recognises devices that do not identify themselves.
• Firmware: a firmware or mod, its author, its repository, its licence, what it changes to the MIDI, how to install it and revert it. It points to the author’s release without carrying it.

Each descriptor says where its data comes from and how far it was checked (_sources). Fields starting with _ are notes for people; a program never needs them.

Who uses it

The synthhub catalogue: every driver in it is a valid OSD descriptor, checked by the catalogue’s tests; shared sounds export as .osd.json; recognition fingerprints are stored in the OSD format.

Common issues

An older file no longer passes. The tool checks against the newest version; another is chosen with the OSD_VERSION variable: OSD_VERSION=0.1 python3 tools/validate.py device old.json.

A file in a folder is checked as a profile. In a folder, a file whose name starts with _ is read as a maker profile or a note, never as a device.

Fields in Lua. Fields marked x-osd-extension in the schemas, a few Lua expressions and scripts, belong to osc-bridge; another program may ignore them.

Where it stands

A draft, at version 0.4 (28 October 2026, commit 2f0f8c0): the rule that reads the firmware from the identity reply can read a JSON reply, as the Electra One sends. Versions 0.1 to 0.3, all from 27 October 2026, remain published. Version 0.1 sets out the device, the maker profile, the sound and the firmware; 0.2 creates the fingerprint and adds the USB ids and what the device sends by itself to its identity; 0.3 lets a fingerprint name a device no descriptor describes yet. A published version never changes; a new one is added beside it.

Since 29 October 2026, OSD has a permanent address, w3id.org/osd, which leads to the repository. w3id.org is the permanent identifier service of the W3C Permanent Identifier Community Group; it accepted the OSD entry (request 7015). A file that cites this address stays valid if the repository or the site moves.

Contributions go through an issue or a pull request on the repository, with an example descriptor that shows the need.

Repository · Permanent address · Format page · synthhub · osc-bridge