Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Add a driver for a new synth

This guide takes a real synth from its first SysEx dump to a driver that the apps list. It assumes that you know Rust and MIDI, and that you did Your first driver or read its code.

Use the Prophet Rev2 driver, crates/drivers/sequential-prophet-rev2, as your model. It is one synth with a published protocol, no shared family crate and no user units. For two synths that share code, see the KORG prologue and the family crate crates/drivers/logue.

1. Learn the synth’s protocol

  1. Collect public documents: the maker’s MIDI implementation chart, the manuals, and open references with a compatible licence.
  2. Record what your synth sends and answers. Compare dumps from before and after one change on the panel.
  3. Send only read requests until you know what a write does.
  4. Note the firmware version that you work with.

Name your sources in the crate’s module docs and in the pull request. Keep your captures and dumps in private/, which git ignores. Never commit vendor firmware, factory programs or files from the internet.

2. Find the synth’s port names

A driver finds its synth by the names of its MIDI ports (port_hint). The same USB port gets a different name on each platform. Oscyl spells the names alike where it can.

PlatformHow the name looksExample
Linux (ALSA)<product> _ <port>, then the client and port numbersminilogue xd:minilogue xd _ SOUND 24:1
Android<product> _ <port>. Android names no port, so Oscyl numbers them: <product> _ MIDI <n>minilogue xd _ MIDI 2
WindowsThe first port has the product name. Windows names later ports MIDIIN2 (<product>) and MIDIOUT2 (<product>), which oscyl_midi::port_label reads as <product> _ MIDI 2minilogue xd _ MIDI 2
macOS, iOSThe names that CoreMIDI reports

To see the names:

  • Linux, macOS and Windows: run oscyl ports.
  • Android: run adb logcat -s OscylMidi while you plug the synth in.
  • iOS: filter Console.app on OscylMidi.

Give port_hint one substring for each name that the synth’s port can have. The minilogue xd driver gives "minilogue xd _ SOUND" and "minilogue xd _ MIDI 2".

3. Make the crate

  1. Make crates/drivers/<vendor>-<model>. The workspace includes every crate under crates/drivers/.
  2. Copy the Rev2’s Cargo.toml, with its path dependencies and its version.workspace = true lines. Change the name and the description. The only dependency is oscyl-driver, and oscyl-conformance is a dev-dependency. Do not add publish = false: only oscyl-tutorial-synth and oscyl-osc-host have it.
  3. Name the crate by the rule: the folder and the driver’s id (in Driver::info) are <vendor>-<model>, and the package is oscyl-<vendor>-<model>. For example, crates/drivers/korg-prologue holds the package oscyl-korg-prologue, whose driver id is korg-prologue. A crate that a family of synths shares is oscyl-<family>, as oscyl-logue. The tutorial’s crate, oscyl-tutorial-synth, is the one exception: no real synth has it.
  4. Split the code into modules as the Rev2 does:
ModuleWhat it holds
msg.rsThe SysEx messages: build them, decode the replies
program.rsThe program bytes, their packing and the name
fields.rsThe parameters, with each field’s offset and range
syx.rsThe synth’s file formats (.syx for the Rev2)
session.rsThe DriverSession: reads, writes and their completion signals
sim.rsThe Simulator, with the faults seen on the hardware
curate.rsThe editor’s pages and sections
generate.rsGenerate’s characters and recipes (optional)
driver.rsimpl Driver and pub static DRIVER

Obey these rules:

  • A write is done only when the synth says so. If the synth sends no completion signal, the session reads the slot back and compares it.
  • The simulator reproduces every fault that you saw on the hardware, so the conformance suite can prove that the session survives it.
  • The simulator offers the fault lose_reply, which loses every reply. The suite switches it on and checks that every operation then fails.
  • Test fixtures are synthetic. You make them; you do not copy them.

The driver contract lists every method and which ones you can leave out.

4. Pass the conformance suite

Add tests/conformance.rs:

#[test]
fn prophet_rev2_conforms() {
    oscyl_conformance::run(&oscyl_sequential_prophet_rev2::DRIVER);
}

Run it until it passes:

cargo test -p oscyl-sequential-prophet-rev2 --test conformance

A failure names the driver, the check and the problem. The driver contract lists the checks.

5. Register the driver

  1. Add the driver to DRIVERS in crates/oscyl-midi/src/device.rs, and as a dependency in crates/oscyl-midi/Cargo.toml. Every app and the command line find drivers there.
  2. Add the package to the conformance matrix in .github/workflows/ci.yml. scripts/ci.sh finds the test on its own.
  3. Name the driver’s maintainer for the crate in .github/CODEOWNERS.
  4. Add a row for the synth to the README’s table of supported synths and to Supported synths, at Tier 2.
  5. Set Driver::tier to 2.

Then try the driver with its simulator:

cargo run -p oscyl-cli -- --simulator --synth sequential-prophet-rev2 info
cargo run -p oscyl-gtk -- --simulator

6. Translate its words (optional)

A driver’s page titles, labels, value names and help can be translated:

  1. Add the driver’s id to TRANSLATED in apps/linux/src/pot.rs.
  2. Regenerate the template, as Translate Oscyl says.

Today only the minilogue xd is translated. The other drivers stay in English.

7. Check it on the synth

If you have the synth, follow Check a driver on hardware before you ask for a review. Tier 2 does not need it, but the real synth can find faults that your simulator does not have.

8. Send it

  1. Open a “Driver submission” issue. It tells the maintainers about the driver.
  2. Open the pull request, and link it from the issue. Its template has a checklist for a new driver.

GOVERNANCE lists what a driver needs before it is accepted.