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
- Collect public documents: the maker’s MIDI implementation chart, the manuals, and open references with a compatible licence.
- Record what your synth sends and answers. Compare dumps from before and after one change on the panel.
- Send only read requests until you know what a write does.
- 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.
| Platform | How the name looks | Example |
|---|---|---|
| Linux (ALSA) | <product> _ <port>, then the client and port numbers | minilogue xd:minilogue xd _ SOUND 24:1 |
| Android | <product> _ <port>. Android names no port, so Oscyl numbers them: <product> _ MIDI <n> | minilogue xd _ MIDI 2 |
| Windows | The first port has the product name. Windows names later ports MIDIIN2 (<product>) and MIDIOUT2 (<product>), which oscyl_midi::port_label reads as <product> _ MIDI 2 | minilogue xd _ MIDI 2 |
| macOS, iOS | The names that CoreMIDI reports |
To see the names:
- Linux, macOS and Windows: run
oscyl ports. - Android: run
adb logcat -s OscylMidiwhile 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
- Make
crates/drivers/<vendor>-<model>. The workspace includes every crate undercrates/drivers/. - Copy the Rev2’s
Cargo.toml, with its path dependencies and itsversion.workspace = truelines. Change the name and the description. The only dependency isoscyl-driver, andoscyl-conformanceis a dev-dependency. Do not addpublish = false: onlyoscyl-tutorial-synthandoscyl-osc-hosthave it. - Name the crate by the rule: the folder and the driver’s id (in
Driver::info) are<vendor>-<model>, and the package isoscyl-<vendor>-<model>. For example,crates/drivers/korg-prologueholds the packageoscyl-korg-prologue, whose driver id iskorg-prologue. A crate that a family of synths shares isoscyl-<family>, asoscyl-logue. The tutorial’s crate,oscyl-tutorial-synth, is the one exception: no real synth has it. - Split the code into modules as the Rev2 does:
| Module | What it holds |
|---|---|
msg.rs | The SysEx messages: build them, decode the replies |
program.rs | The program bytes, their packing and the name |
fields.rs | The parameters, with each field’s offset and range |
syx.rs | The synth’s file formats (.syx for the Rev2) |
session.rs | The DriverSession: reads, writes and their completion signals |
sim.rs | The Simulator, with the faults seen on the hardware |
curate.rs | The editor’s pages and sections |
generate.rs | Generate’s characters and recipes (optional) |
driver.rs | impl 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
- Add the driver to
DRIVERSincrates/oscyl-midi/src/device.rs, and as a dependency incrates/oscyl-midi/Cargo.toml. Every app and the command line find drivers there. - Add the package to the
conformancematrix in.github/workflows/ci.yml.scripts/ci.shfinds the test on its own. - Name the driver’s maintainer for the crate in
.github/CODEOWNERS. - Add a row for the synth to the README’s table of supported synths and to Supported synths, at Tier 2.
- Set
Driver::tierto 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:
- Add the driver’s id to
TRANSLATEDinapps/linux/src/pot.rs. - 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
- Open a “Driver submission” issue. It tells the maintainers about the driver.
- 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.