Oscyl documentation
Oscyl is an open-source librarian and sound editor for hardware synths. It reads the programs on your synth, and lets you organise and edit them on a computer or a phone. Then it writes back only the programs you changed.
New here? Read the four pages of Start here in order, from What Oscyl is, and what it is not.
How this documentation is organised
| Part | Read it when you want to | Start with |
|---|---|---|
| Start here | understand what Oscyl is and how it works | What Oscyl is |
| Tutorials | learn by doing, one lesson at a time | Try Oscyl without a synth |
| How-to guides | finish one real task | Add a driver for a new synth |
| Reference | look up a fact | The driver contract |
| Explanation | understand why Oscyl is made the way it is | Architecture |
Explanation also holds the decision records (ADRs), which record decisions already made, and the RFCs, which propose a change before anyone makes it.
The Rust API reference of the crates that a driver or another project uses is on the website, at oscyl.github.io/oscyl/api.
Outside this book
- README: the project’s front page, with the downloads.
- CONTRIBUTING: how to send a change.
- GOVERNANCE: roles, decisions, driver tiers and driver acceptance.
- CHANGELOG: what each release changed.
What Oscyl is, and what it is not
Oscyl is a librarian and sound editor for hardware synths. It reads the programs on your synth, and lets you organise and edit them on a computer or a phone. Then it writes back only the programs you changed.
What Oscyl does
A synth keeps its sounds as programs in numbered slots. Oscyl does two jobs with them.
- The librarian keeps programs in libraries: files on your computer or phone. You back up a synth, sort and rename programs, copy them between libraries, and send them back to the synth.
- The sound editor shows every parameter of a program on screen. The pages follow the signal: voice, oscillators, mixer, filter, envelopes and effects. Each page has a graph of its stage, and each control shows its saved value next to the new one.
Oscyl also works with the synth unplugged. You open a library, edit it, and sync it to the synth later.
Generate makes new programs. You pick a character, for example “fuzz bass” or “bells”. You set four dials: Bright, Movement, Grit and Ambience. Oscyl then makes six new programs for your synth. You can vary them, cross two of them, keep the one you like, or share it as a short recipe code.
Oscyl runs on Linux, Windows, macOS, Android and iOS, and as a command line
tool, oscyl. Not every platform has run with a real synth yet:
- Checked with a synth: the desktop app and the command line on Linux,
the Android app, and
oscyl infoon Windows. - Built in CI, not yet run with a synth: the desktop app on Windows and macOS, the command line on macOS, and the iOS app. You build the iOS app from source.
Today Oscyl supports the KORG minilogue xd, the KORG prologue and the Sequential Prophet Rev2. Supported synths says what works on each one.
Why it exists
KORG makes librarian software for its synths on Windows and macOS only. Owners on Linux or Android have none, and owners of several synths need one tool for each synth. Oscyl is one librarian and editor for every platform and for synths of different makers.
Oscyl also touches the synth as little as it can. It reads the synth once when the synth connects, and then works from that copy. It writes only the slots you changed, and it backs them up first. What happens when you plug in a synth describes the whole sequence.
The minilogue xd and the prologue run user units: oscillators and effects that anyone can write with KORG’s logue SDK. The synth keeps them in its unit slots. Oscyl lists and loads them. It can also make new user oscillators with its oscillator unit: one prebuilt logue SDK unit whose sound comes from data that Oscyl writes.
What Oscyl is not
- Not a DAW and not a sequencer. Oscyl does not record audio and does not play notes. You play the synth.
- Not a preset converter. A program belongs to one synth model. Oscyl does not convert a minilogue xd program into a Prophet Rev2 program, and it will not.
- Not a synth engine. Oscyl makes no sound of its own. The simulated synth that you can try answers like a real synth, but it is silent.
- Not a platform for synth engines. The oscillator unit is a logue SDK unit for two KORG synths. It is not a third kind of synth and not a target that you write sounds for.
- Not a firmware tool. Oscyl never changes a synth’s firmware.
Next
What happens when you plug in a synth
This page follows a synth from the moment you plug it in to the moment Oscyl writes to it. It also says what Oscyl writes, and when.
plug in
|
v
find the synth -------- device inquiry; the answer names the synth
|
v
read every slot ------- the synth's memory does not change
|
v
edit in Oscyl --------- Oscyl's copy changes
| \
| `-- Live on: the change plays in the edit buffer only
v
Sync ------------------ back up the slots, then write only those slots
Oscyl finds the synth
Each driver knows the names of the MIDI ports its synth shows. When a port with such a name appears, Oscyl sends it the MIDI device inquiry. The synth answers with its identity, and the driver checks that the answer comes from its synth.
On Linux, the desktop app sees a synth when you plug it in. On macOS and Windows, the desktop app connects the synths that are plugged in when it starts. For a synth that you plug in later, choose Connect. On Android, the system offers Oscyl when the synth is plugged in, and Oscyl connects it. The iOS app connects a synth when CoreMIDI reports its port; it has not run with a synth yet.
Oscyl reads the synth
Oscyl then reads every program slot, one slot at a time, in the background. You can work while it reads. On a minilogue xd or a prologue, Oscyl also lists the user units in the synth’s unit slots when a page needs them.
Reading changes nothing on the synth. From now on, Oscyl works from the copy it read.
You edit, and Live plays the edit
An edit changes Oscyl’s copy of the program and nothing else. The program in the list shows that it is edited, and each control shows the value it had before.
When Live is on, every edit also plays on the synth. Oscyl sends the change to the synth’s edit buffer: the working copy of the program that the synth plays now. For most parameters Oscyl sends one MIDI Control Change or NRPN, so held notes keep sounding. For the others, it sends the whole program to the edit buffer. Hold to compare plays the saved program while you hold it.
The edit buffer is not the synth’s memory. The synth forgets the edit buffer when you pick another program on it, and its stored programs do not change.
On a minilogue xd, Live also works the other way. A knob that you turn on the synth moves the same control in Oscyl, as an edit. A program that you pick on the synth opens in Oscyl.
Sync writes, after a backup
Sync is the only action in the apps that writes programs to the synth.
- Sync lists every slot that it will change and asks you to confirm.
- Oscyl saves a backup of those slots as it read them, in its backups
folder. On Linux, the desktop app’s folder is
~/.local/share/oscyl/backups. If the backup fails, Oscyl writes nothing. - Oscyl writes only those slots, one at a time.
- A slot counts as written only when the synth confirms it. When a synth sends no confirmation, the driver reads the slot back and compares it.
No slot that you did not edit changes, and Oscyl never writes a factory slot. One detail: the minilogue xd and the prologue answer a write before they save it to flash memory. A write past the end of the memory group that the synth holds forces the save. So their driver does this:
- It writes the last program of the sync again, with the same bytes, until the synth has saved.
- A sync of the synth’s last slot alone also writes one other slot of the same group. That slot gets the bytes that it already holds.
Then the synth answers only after the save.
When you unplug the synth, your edits that are not synced stay in Oscyl. The phone app keeps them on disk, so they stay even when the app closes.
What can write to the synth
| What you do | What changes on the synth |
|---|---|
| Plug in, read, edit | Nothing |
| Live on, edit or pick a program | The edit buffer only |
| Hold to compare | The edit buffer only |
| Pick a sound in Generate | The edit buffer only |
oscyl audition, oscyl generate --audition | The edit buffer only |
| Sync | The edited slots, after a backup |
| Load a user unit (minilogue xd, prologue) | One empty unit slot |
| Keep a new oscillator | One empty oscillator slot |
| Clear a unit slot | That slot, after a backup of its unit |
oscyl restore | The slots that differ, after a backup of the whole synth |
oscyl units upload, clear, shelf load, make --load | One unit slot; a unit is backed up before it is replaced or cleared |
The apps load a unit only into an empty slot. The command line replaces a
unit only with --force. oscyl backup also reads the global settings and
the tuning of a minilogue xd or a prologue, but no command writes them back.
Where to go next
- Glossary: the words on this page.
- The command line: every command that reads or writes.
- Architecture: how the driver, the session and the apps share this work.
Glossary
The words that Oscyl’s apps, code and documentation use, in alphabetical order. Each entry links to the page that tells more.
Audition
To play a program on the synth without storing it. Oscyl sends the program to the edit buffer. An audition plays one program, for example a sound that you pick in Generate. Live plays each edit as you make it, and Hold to compare plays the saved program while you hold the button. See What happens when you plug in a synth.
Backup
A library file that holds what a synth’s slots held before Oscyl wrote to
them. Sync and oscyl restore make one first and write nothing when they
cannot. See The command line.
Bank
A numbered run of slots on a synth, for example U1 on the Prophet Rev2. A bank is writable, or it is a factory bank that Oscyl never writes. See The driver contract.
Character
A kind of sound that Generate can make, such as “fuzz bass” or “power chord”. Each driver lists its own characters. See What Oscyl is.
Conformance suite
The checks that every driver must pass against its
simulator, in the crate oscyl-conformance. CI runs them on
every commit. See The driver contract.
Driver
The code that teaches Oscyl one synth model: its messages, its program bytes,
its files and its editor pages. A driver is a Rust crate under
crates/drivers/. See Architecture.
Edit buffer
The synth’s working copy of the program that it plays now. Oscyl changes it to audition a program. The synth forgets it when you pick another program, and its stored programs do not change.
Field
One parameter of a program, such as a filter’s cutoff, with its range of raw values. A driver lists its fields in a fixed order. See The driver contract.
Generate
The part of the apps that makes new programs. You pick a
character and set four dials: Bright, Movement, Grit and
Ambience. Oscyl makes six programs, and you can vary them, cross two of
them, or keep one. Each has a recipe code. The command line
does the same with oscyl generate.
Library
A list of programs for one synth model, kept in a file on your computer or
phone. Oscyl’s own format is .oscyllib. Oscyl also reads and writes each
synth’s own file formats. See
The .oscyllib library format.
Live
The switch in the apps that plays every edit on the synth at once, in the edit buffer. On a minilogue xd, Live also follows the synth’s knobs and program changes. See What happens when you plug in a synth.
logue SDK
KORG’s kit for writing user units: oscillators and effects in C. The minilogue xd, the prologue and the other logue synths load them into their unit slots. “logue” is KORG’s name for this family of synths. See User unit.
Oscillator unit
One prebuilt logue SDK unit, made by Oscyl, whose sound comes from data. Oscyl fills it with a new oscillator and loads it into a minilogue xd or a prologue, only when you keep one. It is optional, and it is not a synth engine. See The oscillator unit.
Program
One sound of a synth: all its parameter values and its name, as the synth stores them in one slot. KORG calls it a program. Other makers say patch or preset.
Recipe code
A short text that names a sound from Generate: its character, its four
dials and its seed, for example power-chord-ygy6c734s69jn. The same code
makes the same sound again, on any synth that has that character.
Request engine
The part of oscyl-driver that runs a synth’s protocol. It keeps one
request in flight, matches each reply to it, and fails a request whose reply
does not come. It is sans-IO: it never touches a port or a clock. See
Architecture.
Session
A driver’s protocol for one connected synth, behind the trait
DriverSession. Most sessions use the request engine.
See The driver contract.
Shelf
The unit files that Oscyl keeps for each synth, ready to load into a free unit slot. See The command line.
Simulator
A driver’s model of its synth, in code. It answers messages as the synth does, with no sound. Tests, the conformance suite and the apps’ demo mode use it. See Try Oscyl without a synth.
Slot
One numbered place for a program in the synth’s memory. The apps number slots from 1, the code from 0.
Sync
The action that writes your edited programs to the synth, after a backup. See What happens when you plug in a synth.
Tier
How far Oscyl trusts a driver. Tier 3 compiles, and Tier 2 passes the conformance suite. Tier 1 is also checked on the real synth for each release. See Supported synths.
User unit
A user oscillator or effect, made with KORG’s logue SDK, in one of the unit slots of a minilogue xd or a prologue. Oscyl lists them, loads them and clears them. See Supported synths.
A tour of the code
Oscyl is one Cargo workspace with a few apps around it. This page names each part, follows one program from the synth to the screen, and says where to start reading for each kind of work.
The parts
| Part | What it does |
|---|---|
crates/oscyl-driver | The driver contract: the traits that every driver implements. Also the SysEx helpers and the request engine. |
crates/drivers/ | One crate for each synth model, and logue, the code that the two KORG logue drivers share. |
crates/oscyl-conformance | The checks that every driver passes against its simulator. |
crates/oscyl-core | The .oscyllib library format, and the parts of Generate that no driver owns. |
crates/oscyl-midi | The transport: MIDI ports on the desktop, or bytes that Android and iOS move. It also holds the list of drivers that the apps know, DRIVERS. |
crates/oscyl-app | The app logic that every app shares: documents with undo, libraries, settings, the editor, Generate, and the worker thread that talks to the synths. It has no UI. |
crates/oscyl-cli | The command line tool, oscyl. |
crates/oscyl-ffi | The bindings that give oscyl-app to the mobile apps, through UniFFI. |
crates/oscyl-osc-host | A test crate. It compiles the oscillator unit’s C for the computer, so tests can hear a patch. Nothing ships it. |
apps/linux | The desktop app (GTK 4 and libadwaita), for Linux, Windows and macOS. |
apps/mobile | The Android and iOS apps (Compose Multiplatform). |
units/oscyl-osc | The oscillator unit: its C source and its prebuilt payloads. |
Repository layout lists every top-level folder.
One program, from the synth to the screen
When the desktop app reads slot 5 of a synth, the bytes go through these steps.
- The app asks the worker thread in
oscyl_app::synthto read every slot. - The worker gives the operation to the synth’s
oscyl_midi::Device. The device holds the driver’s session and the MIDI port. - The session turns “read slot 5” into a SysEx request. The request engine sends it and waits for the answer.
- The synth answers with a program dump. The device gives the bytes to the session, which collects one whole SysEx message.
- The session checks that the message answers slot 5. It reports
SessionEvent::Program(5, bytes). - The worker sends the program to the app. The app puts it in the synth’s document, a list of programs with undo.
- The editor reads each value with
Driver::getand its text withDriver::format_value. The driver’scurationsays on which page and in which section each field goes.
A write goes the same way in the other direction. On Android and iOS, step 2
is different. The platform owns the USB port and moves the bytes, and
oscyl-ffi hands them to the same device and session.
Architecture tells why the parts are split this way.
Where to start reading
- A driver for a new synth: the tutorial
Your first driver, then the Prophet Rev2
driver in
crates/drivers/sequential-prophet-rev2. It is the smallest complete driver. - The contract itself:
contract.rsand The driver contract. - The desktop app:
apps/linux/src/app.rs, which holds the app’s state and its answers to the synth’s events. - The mobile apps: the screens under
apps/mobile/shared/src/commonMain, and The mobile bindings. - Generate:
crates/oscyl-app/src/generator.rs, then a driver’s owngenerate.rs. - The library format:
crates/oscyl-core/src/native.rs. - The command line:
crates/oscyl-cli/src/main.rs.
To build and run each app, read Build and run.
Try Oscyl without a synth
In this tutorial you run Oscyl against a simulated minilogue xd. You read its programs, back it up, make new sounds with Generate, and then edit and sync a program in the desktop app. You need no synth: the simulator answers like the real one, with no sound.
It takes about 20 minutes, most of it for the first build.
What you need
- A clone of the repository and Rust 1.92 or newer, through rustup.
- On Linux, the development packages of ALSA (
alsa-lib). For the desktop app in step 6, also GTK 4.20 or newer, libadwaita 1.8 or newer, and gettext.
The command line parts work on Linux, macOS and Windows. The desktop app part uses Linux. Build and run gives the commands for the other systems.
1. Get the code
git clone https://github.com/oscyl/oscyl
cd oscyl
2. See which synths Oscyl knows
cargo run -p oscyl-cli -- ports
The first build takes a few minutes. Then Oscyl lists the MIDI ports of your computer, and after them the synths it supports:
synth: korg-minilogue-xd (KORG minilogue xd)
synth: sequential-prophet-rev2 (Sequential Prophet Rev2)
synth: korg-prologue (KORG prologue)
The first word after synth: is the driver’s id. You use it with --synth.
3. Connect the simulated synth
cargo run -p oscyl-cli -- --simulator info
--simulator connects a simulated synth instead of a MIDI port. The first
driver, the minilogue xd’s, makes it:
synth: KORG minilogue xd
port: simulated minilogue xd
channel: 1
firmware: 2.10
Now ask for the program that the synth plays, its edit buffer:
cargo run -p oscyl-cli -- --simulator current
Oscyl prints the program’s name and then every field with its raw value, the number that the synth stores:
name: Glass Choir
Voice / Octave: 2
Voice / Portamento: 0
Voice / Key Trig: 0
The editor shows some raw values as words or other numbers. For example, it shows Key Trig 0 as Off, and Octave 2 as 0.
4. Back up the synth
cargo run -p oscyl-cli -- --simulator backup my-synth.oscyllib
Oscyl reads all 500 programs, then the synth’s other data, and saves them in one library file:
read everything in 38.4ms
saved my-synth.oscyllib
Compare the file with the synth:
cargo run -p oscyl-cli -- --simulator diff my-synth.oscyllib
Nothing changed since the backup, so Oscyl says:
0 of 500 programs differ
5. Make new sounds
Generate needs no synth. List the characters that the minilogue xd driver can make:
cargo run -p oscyl-cli -- generate --list
Each line is a character’s id, its family and what it sounds like:
power-chord lead Driven fifths for riffs
fuzz-bass bass Low, fuzzy and tight
Deal three fuzz basses from seed 7:
cargo run -p oscyl-cli -- generate --character fuzz-bass --seed 7 --count 3
Each sound has a name and a recipe code:
Deep Thud fuzz-bass-000001v4s69jf
Dirt Growl fuzz-bass-ygy6c734s69jc
Tar Fuzz fuzz-bass-qarjm0k4s69j2
A recipe code makes its sound again. Write the second one to a file:
cargo run -p oscyl-cli -- generate --code fuzz-bass-ygy6c734s69jc --out sounds
Oscyl writes sounds/Dirt Growl.mnlgxdprog, a program file that KORG’s own
software also opens. Play it on the simulated synth:
cargo run -p oscyl-cli -- --simulator audition "sounds/Dirt Growl.mnlgxdprog"
auditioning "Dirt Growl" (366µs)
The simulated synth now holds “Dirt Growl” in its edit buffer. A real synth would play it, and store nothing.
6. Edit and sync in the desktop app
Start the desktop app with simulated synths:
cargo run -p oscyl-gtk -- --simulator
The window opens on the simulated minilogue xd. Under its name, the sidebar says “Simulated, no sound”. The middle column lists its 500 programs, and the editor shows the first one, “Glass Choir”.
- In the row of stages at the top of the editor, click Filter.
- Drag the Cutoff dial up.
- Look at the dial. Under it, Oscyl shows “was” and the value that the synth holds. The Filter stage and the program in the list get a mark.
- Click Sync at the top right. A dialog names the one slot that will change.
- Click Sync in the dialog.
Oscyl backs up the slot and writes it to the simulated synth. The button
then says Synced. The backup is a new file in
~/.local/share/oscyl/backups.
What you did
You connected a synth, read it, backed it up, and compared it with a library. You made sounds with Generate and played one. You edited a program and synced it, and Oscyl backed up the slot before it wrote.
Next:
- What happens when you plug in a synth explains what you saw: reads, the edit buffer, Live and Sync.
- Your first driver adds a synth of your own.
- The command line lists every command.
Your first driver
Read this page in the built book. Its code blocks come from the repository, and GitHub or an editor shows only the lines that include them. Read it on the website, at oscyl.github.io/oscyl/docs/tutorials/first-driver.html, or build the book yourself:
- Install mdBook. On x86_64 Linux,
scripts/docs-tools.sh ~/.local/bindownloads the version that CI uses.- Run
mdbook build docsin the repository.- Open
target/book/tutorials/first-driver.html.
In this tutorial you write a driver for the Tutorial Mono, a small synth that exists only in this tutorial. You build it one file at a time, test each file, and finish when the driver passes Oscyl’s conformance suite.
A driver teaches Oscyl one synth model. When a driver passes the suite, every app can read the synth, edit its programs, play them and write them back.
It takes about an hour.
What you need
- A clone of the repository that builds: Try Oscyl without a synth shows how.
- Some Rust. You copy every line of code from this page, but you read it too.
The Tutorial Mono
A synth maker publishes what its synth sends and answers, in a MIDI implementation chart. This is the chart of the Tutorial Mono.
- It has one bank of 16 program slots, numbered 0 to 15, and an edit buffer.
- A program is 14 bytes: an 8-character name in printable ASCII, padded with spaces, then one byte for each of six parameters.
- Every SysEx message starts with
F0 7D 54.7Dis the manufacturer ID that MIDI keeps for non-commercial use.54is the model.
The six parameters, in the order of their bytes after the name:
| Byte | Parameter | Group | Range | Control Change |
|---|---|---|---|---|
| 8 | Wave | Oscillator | 0 to 3: Saw, Square, Triangle, Noise | 70 |
| 9 | Glide | Oscillator | 0 (off) or 1 (on) | 65, sent as 0 or 127 |
| 10 | Cutoff | Filter | 0 to 127 | 74 |
| 11 | Resonance | Filter | 0 to 127 | 71 |
| 12 | Attack | Envelope | 0 to 127 | 73 |
| 13 | Release | Envelope | 0 to 127 | 72 |
The synth’s messages:
| Message | Bytes | Answer |
|---|---|---|
| Program request | F0 7D 54 01 slot F7 | A program dump of that slot |
| Program dump | F0 7D 54 02 slot program F7 | The synth stores it, then sends an acknowledgement |
| Edit buffer request | F0 7D 54 03 F7 | An edit buffer dump |
| Edit buffer dump | F0 7D 54 04 program F7 | The synth plays it, then sends an acknowledgement |
| Acknowledgement | F0 7D 54 7F slot F7 | Sent by the synth; slot is 7F for the edit buffer |
To the MIDI device inquiry (F0 7E 7F 06 01 F7), the synth answers
F0 7E channel 06 02 7D 54 4D 01 00 01 00 00 00 F7:
06 02: this is an identity reply;7D: the manufacturer;54 4D(“TM”): the family, the Tutorial Mono;01 00: the model in the family;01 00 00 00: the firmware version.
1. Start from an empty crate
The repository holds the finished driver in crates/drivers/tutorial-synth.
Delete it, so that you can rewrite it. Git keeps the finished files:
git restore crates/drivers/tutorial-synth brings them back at any time.
rm -r crates/drivers/tutorial-synth
mkdir -p crates/drivers/tutorial-synth/src crates/drivers/tutorial-synth/tests
The workspace includes every crate under crates/drivers/, so you do not
register the crate anywhere. The crate has three names, each for one use:
- the folder
tutorial-synth; - the package
oscyl-tutorial-synth, which you give to Cargo with-p; - the driver’s id
oscyl-tutorial-mono. The apps and--synthfind a driver by its id once it is inoscyl_midi::DRIVERS. The tutorial’s driver is not, so no app lists it: you run it through its tests. A real driver gets registered, as Add a driver for a new synth says.
Create crates/drivers/tutorial-synth/Cargo.toml:
[package]
name = "oscyl-tutorial-synth"
description = "The Tutorial Mono, an invented synth, and the driver that Oscyl's first-driver tutorial builds"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish = false
[dependencies]
oscyl-driver = { path = "../../oscyl-driver" }
[dev-dependencies]
oscyl-conformance = { path = "../../oscyl-conformance" }
The driver depends only on oscyl-driver, the contract. The conformance
suite is a dev-dependency: only the tests use it.
Create src/lib.rs. It names the six files that you write in the next
steps:
//! The Tutorial Mono, a small invented synth, and its Oscyl driver.
//!
//! The tutorial "Your first driver" (docs/tutorials/first-driver.md) builds
//! this crate one file at a time. No app lists the Tutorial Mono, because
//! the crate is not in `oscyl_midi::DRIVERS`.
pub mod driver;
pub mod files;
pub mod msg;
pub mod program;
pub mod session;
pub mod sim;
Create the six files, empty for now, and build:
cd crates/drivers/tutorial-synth
touch src/driver.rs src/files.rs src/msg.rs src/program.rs src/session.rs src/sim.rs
cd ../../..
cargo build -p oscyl-tutorial-synth
Cargo builds the crate and prints Finished. The crate is empty, but it
compiles: Rust accepts an empty module. Each file stays empty until its
step.
2. The program
Oscyl treats a program as bytes that only the driver understands. The apps
read and change a program only through the driver. Open src/program.rs.
First, the fields. A FieldInfo gives a parameter’s name, the group that it
belongs to, and its smallest and largest raw value:
//! The Tutorial Mono's program: an 8-character name, then one byte for
//! each field. Every byte is 7-bit, so a SysEx dump carries the program
//! as it is.
use oscyl_driver::{DriverError, FieldInfo};
/// The program's parameters, in the order of their bytes after the name.
pub const FIELDS: [FieldInfo; 6] = [
field("Wave", "Oscillator", 3),
field("Glide", "Oscillator", 1),
field("Cutoff", "Filter", 127),
field("Resonance", "Filter", 127),
field("Attack", "Envelope", 127),
field("Release", "Envelope", 127),
];
/// The names of the values of field 0, Wave.
pub const WAVES: [&str; 4] = ["Saw", "Square", "Triangle", "Noise"];
/// The name's length in bytes: ASCII, padded with spaces.
pub const NAME_LEN: usize = 8;
/// A program's length in bytes.
pub const LEN: usize = NAME_LEN + FIELDS.len();
const fn field(name: &'static str, group: &'static str, max: u16) -> FieldInfo {
FieldInfo {
name,
group,
min: 0,
max,
}
}
Next, a check that refuses bytes that are not a whole program. Every other function calls it first, so bad bytes never go further:
/// Whether `c` can be part of a name: printable ASCII.
pub fn allowed(c: char) -> bool {
(' '..='~').contains(&c)
}
/// Refuses bytes that are not a whole program: a wrong length, a name
/// character that is not printable ASCII, or a field out of its range.
pub fn check(bytes: &[u8]) -> Result<(), DriverError> {
if bytes.len() != LEN {
return Err(DriverError(format!(
"a program has {LEN} bytes, not {}",
bytes.len()
)));
}
let (name, values) = bytes.split_at(NAME_LEN);
if !name.iter().all(|&b| allowed(char::from(b))) {
return Err(DriverError("the name is not printable ASCII".into()));
}
for (f, &v) in FIELDS.iter().zip(values) {
if u16::from(v) > f.max {
return Err(DriverError(format!("{} = {v} is out of range", f.name)));
}
}
Ok(())
}
Then the functions that make a program and read or change one field:
/// The new program: "Init", a saw with the filter open.
pub fn init() -> Vec<u8> {
let mut bytes = b"Init ".to_vec();
bytes.extend([0, 0, 127, 0, 0, 20]);
bytes
}
/// The value of field `i` in `bytes`.
pub fn get(bytes: &[u8], i: usize) -> Result<u16, DriverError> {
check(bytes)?;
let at = NAME_LEN + index(i)?;
Ok(u16::from(bytes[at]))
}
/// Sets field `i` in `bytes` to `value`, which must be in its range.
pub fn set(bytes: &mut [u8], i: usize, value: u16) -> Result<(), DriverError> {
check(bytes)?;
let f = &FIELDS[index(i)?];
if value > f.max {
return Err(DriverError(format!("{} = {value} is out of range", f.name)));
}
// The range check above keeps `value` at 127 or less.
bytes[NAME_LEN + i] = value as u8;
Ok(())
}
fn index(i: usize) -> Result<usize, DriverError> {
if i < FIELDS.len() {
Ok(i)
} else {
Err(DriverError(format!("no field {i}")))
}
}
Then the name:
/// The program's name, without the padding.
pub fn name(bytes: &[u8]) -> Result<String, DriverError> {
check(bytes)?;
let name = String::from_utf8_lossy(&bytes[..NAME_LEN]);
Ok(name.trim_end().to_string())
}
/// Sets the name: at most 8 printable ASCII characters.
pub fn set_name(bytes: &mut [u8], name: &str) -> Result<(), DriverError> {
check(bytes)?;
if name.len() > NAME_LEN || !name.chars().all(allowed) {
return Err(DriverError(format!(
"a name has at most {NAME_LEN} printable ASCII characters"
)));
}
let padded = format!("{name:<NAME_LEN$}");
bytes[..NAME_LEN].copy_from_slice(padded.as_bytes());
Ok(())
}
Last, a test at the end of the file:
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_field_and_the_name_read_back() {
let mut p = init();
set(&mut p, 2, 64).unwrap();
set_name(&mut p, "Bass").unwrap();
assert_eq!(get(&p, 2), Ok(64));
assert_eq!(name(&p).as_deref(), Ok("Bass"));
assert!(set(&mut p, 0, 4).is_err(), "Wave has four values");
assert!(check(&p[1..]).is_err(), "a program has 14 bytes");
}
}
Run it:
cargo test -p oscyl-tutorial-synth program
test program::tests::a_field_and_the_name_read_back ... ok
3. The messages
Open src/msg.rs. One enum holds every message from the chart:
//! The Tutorial Mono's SysEx messages.
//!
//! Every message starts with `F0 7D 54`: `7D` is the manufacturer ID that
//! MIDI keeps for non-commercial use, and `54` is the model. The synth
//! answers a dump with an acknowledgement after it stores the dump.
use crate::program;
/// The number of program slots: 0 to 15.
pub const SLOTS: u16 = 16;
const HEADER: [u8; 3] = [0xF0, 0x7D, 0x54];
const PROGRAM_REQUEST: u8 = 0x01;
const PROGRAM_DUMP: u8 = 0x02;
const EDIT_REQUEST: u8 = 0x03;
const EDIT_DUMP: u8 = 0x04;
const ACK: u8 = 0x7F;
/// The slot byte of an acknowledgement for the edit buffer.
const EDIT_BUFFER: u8 = 0x7F;
/// One message to or from the synth.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Msg {
/// Asks for the program in a slot.
ProgramRequest(u16),
/// The program in a slot: to store it, or as an answer.
ProgramDump(u16, Vec<u8>),
/// Asks for the edit buffer: the program the synth plays now.
EditRequest,
/// The edit buffer: to play it, or as an answer.
EditDump(Vec<u8>),
/// The synth stored a dump: in slot `Some(n)`, or in the edit buffer.
Ack(Option<u16>),
}
encode turns a message into bytes. decode does the opposite, and gives
None for any message that is not one of the Tutorial Mono’s:
impl Msg {
/// The message as bytes, from `F0` to `F7`.
pub fn encode(&self) -> Vec<u8> {
let body = match self {
Msg::ProgramRequest(n) => vec![PROGRAM_REQUEST, slot_byte(*n)],
Msg::ProgramDump(n, p) => [&[PROGRAM_DUMP, slot_byte(*n)][..], p].concat(),
Msg::EditRequest => vec![EDIT_REQUEST],
Msg::EditDump(p) => [&[EDIT_DUMP][..], p].concat(),
Msg::Ack(Some(n)) => vec![ACK, slot_byte(*n)],
Msg::Ack(None) => vec![ACK, EDIT_BUFFER],
};
[&HEADER[..], &body, &[0xF7]].concat()
}
/// The message in `bytes`, or `None` when it is not one of ours.
pub fn decode(bytes: &[u8]) -> Option<Msg> {
let body = bytes.strip_prefix(&HEADER[..])?.strip_suffix(&[0xF7])?;
let slot = |b: u8| (u16::from(b) < SLOTS).then_some(u16::from(b));
let program = |p: &[u8]| (p.len() == program::LEN).then(|| p.to_vec());
match body {
[PROGRAM_REQUEST, n] => Some(Msg::ProgramRequest(slot(*n)?)),
[PROGRAM_DUMP, n, p @ ..] => Some(Msg::ProgramDump(slot(*n)?, program(p)?)),
[EDIT_REQUEST] => Some(Msg::EditRequest),
[EDIT_DUMP, p @ ..] => Some(Msg::EditDump(program(p)?)),
[ACK, EDIT_BUFFER] => Some(Msg::Ack(None)),
[ACK, n] => Some(Msg::Ack(Some(slot(*n)?))),
_ => None,
}
}
}
/// A slot as one 7-bit byte. Callers keep `n` below [`SLOTS`].
fn slot_byte(n: u16) -> u8 {
(n & 0x7F) as u8
}
Oscyl knows a synth by its answer to the device inquiry. Add the answer and a function that recognises it from any channel:
/// The start of the synth's answer to the MIDI device inquiry, after the
/// channel byte: manufacturer `7D`, family `54 4D`, member `01 00`. Four
/// version bytes and `F7` follow.
const IDENTITY: [u8; 7] = [0x06, 0x02, 0x7D, 0x54, 0x4D, 0x01, 0x00];
/// The synth's answer to the device inquiry, from channel `channel`.
pub fn identity_reply(channel: u8) -> Vec<u8> {
[&[0xF0, 0x7E, channel][..], &IDENTITY, &[1, 0, 0, 0, 0xF7]].concat()
}
/// Whether `bytes` is the Tutorial Mono's answer to the device inquiry,
/// from any channel.
pub fn is_identity(bytes: &[u8]) -> bool {
bytes.len() == 15 && bytes[..2] == [0xF0, 0x7E] && bytes[3..10] == IDENTITY
}
Add the test and run it:
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn messages_round_trip() {
let p = program::init();
for m in [
Msg::ProgramRequest(15),
Msg::ProgramDump(3, p.clone()),
Msg::EditRequest,
Msg::EditDump(p),
Msg::Ack(Some(0)),
Msg::Ack(None),
] {
assert_eq!(Msg::decode(&m.encode()), Some(m));
}
assert_eq!(
Msg::ProgramRequest(2).encode(),
[0xF0, 0x7D, 0x54, 0x01, 0x02, 0xF7]
);
assert!(is_identity(&identity_reply(0x7F)));
}
}
cargo test -p oscyl-tutorial-synth msg
test msg::tests::messages_round_trip ... ok
4. The simulator
A simulator is the synth in code. The conformance suite talks to it, and so
does the apps’ demo mode. Open src/sim.rs. The synth’s memory is 16
programs and an edit buffer:
//! A simulated Tutorial Mono. It answers every message as the synth
//! would, with no sound and no MIDI port: the conformance suite and demo
//! mode talk to it.
use oscyl_driver::Simulator;
use oscyl_driver::sysex::DEVICE_INQUIRY;
use crate::msg::{Msg, SLOTS, identity_reply};
use crate::program;
/// The synth's memory: one program per slot, and the edit buffer.
pub struct Sim {
programs: Vec<Vec<u8>>,
edit: Vec<u8>,
/// The fault `lose_reply`: the synth answers nothing.
lose_reply: bool,
}
impl Default for Sim {
fn default() -> Sim {
Sim {
programs: vec![program::init(); usize::from(SLOTS)],
edit: program::init(),
lose_reply: false,
}
}
}
The synth’s answer to each message follows the chart. A dump that holds a bad program gets no answer, as on a real synth:
impl Sim {
/// The synth's answer to one of its own messages, if it answers.
fn answer(&mut self, bytes: &[u8]) -> Option<Msg> {
match Msg::decode(bytes)? {
Msg::ProgramRequest(n) => {
let p = self.programs[usize::from(n)].clone();
Some(Msg::ProgramDump(n, p))
}
Msg::EditRequest => Some(Msg::EditDump(self.edit.clone())),
Msg::ProgramDump(n, p) if program::check(&p).is_ok() => {
self.programs[usize::from(n)] = p;
Some(Msg::Ack(Some(n)))
}
Msg::EditDump(p) if program::check(&p).is_ok() => {
self.edit = p;
Some(Msg::Ack(None))
}
// A bad program, or a message only the synth sends.
_ => None,
}
}
}
The Simulator trait is what Oscyl sees. The fault lose_reply makes the
synth silent. The suite switches it on to check that a lost reply never
counts as success:
impl Simulator for Sim {
fn handle(&mut self, msg: &[u8]) -> Vec<Vec<u8>> {
let reply = if msg == DEVICE_INQUIRY {
Some(identity_reply(0x7F))
} else {
self.answer(msg).map(|m| m.encode())
};
if self.lose_reply {
return vec![];
}
reply.into_iter().collect()
}
/// The Tutorial Mono stores a dump at once: no work waits for idle time.
fn idle_tick(&mut self) {}
fn program(&self, slot: u16) -> Option<Vec<u8>> {
self.programs.get(usize::from(slot)).cloned()
}
fn edit_buffer(&self) -> Vec<u8> {
self.edit.clone()
}
fn is_settled(&self) -> bool {
true
}
fn faults(&self) -> &'static [&'static str] {
&["lose_reply"]
}
fn inject(&mut self, fault: &str) {
match fault {
"lose_reply" => self.lose_reply = true,
_ => panic!("unknown fault {fault:?}"),
}
}
}
Add the test and run it:
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_dump_is_stored_and_acknowledged() {
let mut sim = Sim::default();
let mut p = program::init();
program::set_name(&mut p, "Stored").unwrap();
let reply = sim.handle(&Msg::ProgramDump(5, p.clone()).encode());
assert_eq!(reply, [Msg::Ack(Some(5)).encode()]);
assert_eq!(sim.program(5), Some(p));
}
}
cargo test -p oscyl-tutorial-synth sim
test sim::tests::a_dump_is_stored_and_acknowledged ... ok
5. The session
The session is the protocol. It decides what to send for each operation and which answer finishes it. It never touches a port or a clock: Oscyl gives it the bytes and the time. This is sans-IO. The same session runs on every platform and in tests.
The request engine in oscyl_driver::engine does the hard part. It keeps
one request in flight, times out a request whose reply does not come, and
reports progress. You describe the synth’s protocol to it with the trait
Protocol:
| Item | What it is |
|---|---|
expand(op) | Turns one operation, such as “read slots 3 and 4”, into its requests, in order. |
on_message(bytes, expect, what, index) | Says what one message from the synth means for the request in flight. |
Step | One request: msg, the bytes to send; expect, what completes it; timeout; what, its name in error messages (“program write”); index, its slot, also for error messages. |
Outcome::Done | The message completes the request, with an event for the apps or none. |
Outcome::Unrelated | The message does not answer the request. The engine keeps waiting. |
Outcome::Failed | The message fails the request, and the engine drops the rest of the operation. |
progress, done, failed | Make the events that the engine reports. |
Open src/session.rs. First, write the requests that make up each
operation:
//! The session: the Tutorial Mono's protocol, sans IO.
//!
//! The request engine of `oscyl_driver::engine` keeps one request in
//! flight and times it out. This file says what to send for each
//! operation and which reply completes each request. A write is done only
//! when the synth acknowledges it, so a lost reply is a failure.
use std::time::{Duration, Instant};
use oscyl_driver::engine::{Engine, OpError, Outcome, Protocol, Step};
use oscyl_driver::{DriverError, DriverSession, SessionEvent, SessionOp};
use crate::msg::{Msg, SLOTS};
use crate::program;
/// The reply that completes a request.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Expect {
Program(u16),
EditBuffer,
Ack(Option<u16>),
}
/// How long to wait for a reply. It finds a dead link; it does not pace
/// the messages.
const TIMEOUT: Duration = Duration::from_secs(2);
/// The Tutorial Mono's rules for the request engine.
pub struct Mono;
impl Protocol for Mono {
type Op = SessionOp;
type Event = SessionEvent;
type Expect = Expect;
/// The requests that make up `op`, in order.
fn expand(&self, op: SessionOp) -> Vec<Step<Expect>> {
let step = |msg: Msg, expect, what, index| Step {
msg: msg.encode(),
expect,
timeout: TIMEOUT,
what,
index,
};
match op {
SessionOp::ReadCurrent => {
vec![step(
Msg::EditRequest,
Expect::EditBuffer,
"edit buffer read",
None,
)]
}
SessionOp::ReadPrograms(slots) => slots
.into_iter()
.map(|n| {
step(
Msg::ProgramRequest(n),
Expect::Program(n),
"program read",
Some(n),
)
})
.collect(),
SessionOp::WritePrograms(batch) => batch
.into_iter()
.map(|(n, p)| {
let expect = Expect::Ack(Some(n));
step(Msg::ProgramDump(n, p), expect, "program write", Some(n))
})
.collect(),
SessionOp::Audition(p) => {
vec![step(Msg::EditDump(p), Expect::Ack(None), "audition", None)]
}
}
}
Notice that a write waits for the acknowledgement. The program dump alone does not finish it.
Second, write what each message from the synth means for the request in
flight. on_message gets what and index so that an error can name
them. This driver’s one error names the step only, so it ignores index.
Add the rest of the impl block, and a helper after it:
/// What one message from the synth means for the request in flight.
fn on_message(
&self,
bytes: &[u8],
expect: Expect,
what: &'static str,
_index: Option<u16>,
) -> Outcome<SessionEvent> {
match (Msg::decode(bytes), expect) {
(Some(Msg::ProgramDump(n, p)), Expect::Program(m)) if n == m => {
whole(p, what, |p| SessionEvent::Program(n, p))
}
(Some(Msg::EditDump(p)), Expect::EditBuffer) => whole(p, what, SessionEvent::Current),
(Some(Msg::Ack(s)), Expect::Ack(t)) if s == t => Outcome::Done(None),
// Another message: an echo of our own, or a dump sent by hand.
_ => Outcome::Unrelated,
}
}
fn progress(done: usize, total: usize) -> SessionEvent {
SessionEvent::Progress { done, total }
}
fn done() -> SessionEvent {
SessionEvent::Done
}
fn failed(e: OpError) -> SessionEvent {
SessionEvent::Failed(e)
}
}
/// The request is done with the event `event(p)` when `p` is a whole
/// program. Bad bytes never reach the apps: the request fails.
fn whole(
p: Vec<u8>,
what: &'static str,
event: impl FnOnce(Vec<u8>) -> SessionEvent,
) -> Outcome<SessionEvent> {
match program::check(&p) {
Ok(()) => Outcome::Done(Some(event(p))),
Err(e) => Outcome::Failed(OpError::BadData { what, error: e.0 }),
}
}
A message that does not answer the request is Unrelated, and the engine
keeps waiting. If no answer comes, the request times out and fails.
The DriverSession trait is what Oscyl calls. The session checks every slot
and program before it queues anything, then passes each call to the engine:
/// A session with one Tutorial Mono.
pub struct Session(Engine<Mono>);
impl Default for Session {
fn default() -> Session {
Session(Engine::new(Mono))
}
}
/// Refuses a slot past the last one.
fn slot(n: u16) -> Result<(), DriverError> {
if n < SLOTS {
Ok(())
} else {
Err(DriverError(format!("the Tutorial Mono has no slot {n}")))
}
}
impl DriverSession for Session {
/// Checks every slot and program first: a bad operation sends nothing.
fn submit(&mut self, op: SessionOp) -> Result<(), DriverError> {
match &op {
SessionOp::ReadCurrent => {}
SessionOp::ReadPrograms(slots) => slots.iter().try_for_each(|&n| slot(n))?,
SessionOp::WritePrograms(batch) => batch
.iter()
.try_for_each(|(n, p)| slot(*n).and_then(|()| program::check(p)))?,
SessionOp::Audition(p) => program::check(p)?,
}
self.0.submit(op);
Ok(())
}
fn is_idle(&self) -> bool {
self.0.is_idle()
}
fn poll_transmit(&mut self, now: Instant) -> Option<Vec<u8>> {
self.0.poll_transmit(now)
}
fn next_deadline(&self) -> Option<Instant> {
self.0.next_deadline()
}
fn handle_timeout(&mut self, now: Instant) {
self.0.handle_timeout(now)
}
fn handle_input(&mut self, bytes: &[u8]) {
self.0.handle_input(bytes)
}
fn poll_event(&mut self) -> Option<SessionEvent> {
self.0.poll_event()
}
}
Add the test and run it:
#[cfg(test)]
mod tests {
use super::*;
use crate::sim::Sim;
use oscyl_driver::Simulator;
#[test]
fn a_write_ends_when_the_synth_acknowledges_it() {
let (mut s, mut sim) = (Session::default(), Sim::default());
s.submit(SessionOp::WritePrograms(vec![(4, program::init())]))
.unwrap();
let now = Instant::now();
let request = s.poll_transmit(now).unwrap();
assert!(s.poll_transmit(now).is_none(), "one request at a time");
for reply in sim.handle(&request) {
s.handle_input(&reply);
}
let events: Vec<_> = std::iter::from_fn(|| s.poll_event()).collect();
assert_eq!(events.last(), Some(&SessionEvent::Done));
assert!(s.submit(SessionOp::ReadPrograms(vec![16])).is_err());
}
}
cargo test -p oscyl-tutorial-synth session
test session::tests::a_write_ends_when_the_synth_acknowledges_it ... ok
6. Files
A driver reads and writes the synth’s own file formats, so that you can open
a file from the maker’s software. The Tutorial Mono’s .syx file is
program dumps, one after the other. Write src/files.rs:
//! `.syx` files: program dumps one after the other, as the synth sends
//! them. The format has no place for a program's author or comment.
use oscyl_driver::sysex::Framer;
use oscyl_driver::{DriverError, LibProgram, LibraryData};
use crate::msg::{Msg, SLOTS};
use crate::program;
/// Every program dump in `bytes`, in file order.
pub fn import(bytes: &[u8]) -> Result<LibraryData, DriverError> {
let mut programs = vec![];
for m in Framer::new().push(bytes) {
let Some(Msg::ProgramDump(_, data)) = Msg::decode(&m) else {
return Err(DriverError(
"the file holds a message that is not a program dump".into(),
));
};
program::check(&data)?;
programs.push(LibProgram {
data,
..LibProgram::default()
});
}
if programs.is_empty() {
return Err(DriverError(
"the file holds no Tutorial Mono programs".into(),
));
}
Ok(LibraryData {
programs,
extras: Default::default(),
})
}
/// The programs of `lib` as dumps for slots 0, 1, 2 and on.
pub fn export(lib: &LibraryData) -> Result<Vec<u8>, DriverError> {
if lib.programs.len() > usize::from(SLOTS) {
return Err(DriverError(format!(
"a file holds at most {SLOTS} programs"
)));
}
let mut out = vec![];
for (n, p) in (0..).zip(&lib.programs) {
program::check(&p.data)?;
out.extend(Msg::ProgramDump(n, p.data.clone()).encode());
}
Ok(out)
}
cargo build -p oscyl-tutorial-synth
7. The driver
The Driver trait is all that the apps see of a synth. Open
src/driver.rs. First, the facts: the synth’s identity, what it can do, and
its file format:
//! The Tutorial Mono behind the driver contract: what the apps see.
use oscyl_driver::{
Bank, Capabilities, Control, Curation, Driver, DriverError, DriverSession, FieldInfo,
FileFormat, Info, LibraryData, NameRules, Simulator, curation_by_group, format_raw_default,
};
use crate::msg::{SLOTS, is_identity};
use crate::program::{self, FIELDS, WAVES};
use crate::{files, session, sim};
/// The Tutorial Mono's driver. Apps see it as `&dyn Driver`.
pub struct TutorialMono;
pub static DRIVER: TutorialMono = TutorialMono;
static INFO: Info = Info {
id: "oscyl-tutorial-mono",
vendor: "Oscyl",
model: "Tutorial Mono",
};
/// One bank of 16 slots, all of them writable, and an edit buffer.
static CAPABILITIES: Capabilities = Capabilities {
banks: &[Bank {
name: "User",
first: 0,
len: SLOTS,
writable: true,
}],
edit_buffer: true,
live_changes: true,
units: &[],
};
const SYX: FileFormat = FileFormat {
ext: "syx",
name: "Tutorial Mono program dumps",
keeps_metadata: false,
};
Start the impl block. These methods hand the program work to
program.rs:
impl Driver for TutorialMono {
fn info(&self) -> &'static Info {
&INFO
}
fn capabilities(&self) -> &'static Capabilities {
&CAPABILITIES
}
fn fields(&self) -> &'static [FieldInfo] {
&FIELDS
}
fn name_rules(&self) -> NameRules {
NameRules {
max_len: program::NAME_LEN,
allowed: program::allowed,
}
}
fn init_program(&self) -> Vec<u8> {
program::init()
}
fn check_program(&self, bytes: &[u8]) -> Result<(), DriverError> {
program::check(bytes)
}
fn get(&self, bytes: &[u8], field: usize) -> Result<u16, DriverError> {
program::get(bytes, field)
}
fn set(&self, bytes: &mut [u8], field: usize, value: u16) -> Result<(), DriverError> {
program::set(bytes, field, value)
}
fn name(&self, bytes: &[u8]) -> Result<String, DriverError> {
program::name(bytes)
}
fn set_name(&self, bytes: &mut [u8], name: &str) -> Result<(), DriverError> {
program::set_name(bytes, name)
}
Add the file format:
fn file_formats(&self) -> &'static [FileFormat] {
&[SYX]
}
fn import(&self, ext: &str, bytes: &[u8]) -> Result<LibraryData, DriverError> {
syx(ext)?;
files::import(bytes)
}
fn export(&self, ext: &str, lib: &LibraryData) -> Result<Vec<u8>, DriverError> {
syx(ext)?;
files::export(lib)
}
Add the editor. curation puts the fields on pages. Here
curation_by_group makes one page for each group: Oscillator, Filter and
Envelope. control and format_raw give Wave its four names:
/// One editor page for each group of fields.
fn curation(&self) -> Curation {
curation_by_group(self.fields())
}
/// Wave picks one of four names. Glide is a switch.
fn control(&self, _bytes: &[u8], field: usize) -> Control {
match field {
0 => Control::Choice(&WAVES),
1 => Control::Toggle,
_ => Control::Continuous,
}
}
fn format_raw(&self, field: usize, raw: u16) -> String {
match (field, FIELDS.get(field)) {
(0, _) => WAVES.get(usize::from(raw)).copied().unwrap_or("?").into(),
(_, Some(f)) => format_raw_default(f, raw),
(_, None) => String::new(),
}
}
Add live edits. With Live on, an app sends this Control Change for each edit, so the change plays at once:
/// One Control Change for each field, so a change sounds at once on
/// the notes that play.
fn live_messages(&self, bytes: &[u8], field: usize, channel: u8) -> Option<Vec<Vec<u8>>> {
const CC: [u8; 6] = [70, 65, 74, 71, 73, 72];
let value = program::get(bytes, field).ok()?;
// Glide is a switch: MIDI reads 64 or more as on.
let value = if field == 1 { value * 127 } else { value };
Some(vec![vec![0xB0 | (channel & 0x0F), CC[field], value as u8]])
}
Last, the link to the synth: the session, the simulator, the port name and
the identity. Close the impl block:
/// The Tutorial Mono's SysEx has no channel byte, so `channel` is unused.
fn session(&self, _channel: u8) -> Box<dyn DriverSession> {
Box::new(session::Session::default())
}
fn simulator(&self) -> Box<dyn Simulator> {
Box::new(sim::Sim::default())
}
fn port_hint(&self) -> &'static [&'static str] {
&["Tutorial Mono"]
}
fn recognize(&self, identity_reply: &[u8]) -> bool {
is_identity(identity_reply)
}
}
/// Refuses every file extension but `syx`.
fn syx(ext: &str) -> Result<(), DriverError> {
if ext == SYX.ext {
Ok(())
} else {
Err(DriverError(format!(
"the Tutorial Mono has no .{ext} files"
)))
}
}
cargo build -p oscyl-tutorial-synth
8. Pass the conformance suite
Create tests/conformance.rs:
//! The checks every driver passes against its simulator.
#[test]
fn tutorial_mono_conforms() {
oscyl_conformance::run(&oscyl_tutorial_synth::driver::DRIVER);
}
Run it:
cargo test -p oscyl-tutorial-synth --test conformance
test tutorial_mono_conforms ... ok
The suite wrote programs to your simulator and read them back. It played a program in the edit buffer, lost every reply on purpose, and checked that nothing reported a false success. It also checked every field, every name, the file format, the editor pages and the live messages.
When a check fails, its message names the driver, the check and the
problem, for example oscyl-tutorial-mono: fields: Wave reads back wrong.
What you built
You wrote a complete driver:
- a program model;
- the synth’s messages;
- a simulator;
- a sans-IO session on the request engine;
- a file format;
- the
Driverthat the apps see.
It passes the same suite as every driver of a real synth.
To put the repository’s own copy back, run:
git restore crates/drivers/tutorial-synth
Next:
- Add a driver for a new synth: from the first SysEx dump of a real synth to its hardware check.
- The driver contract: every method, and the optional ones that this driver leaves out, such as graphs, help and Generate.
- Architecture: why drivers are sans-IO and compiled in.
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.
Check a driver on hardware
This guide checks a driver on the real synth. You need the synth, a USB
cable, and the command line tool oscyl (from a release, or
cargo run -p oscyl-cli --).
When the check is needed:
- Tier 2 needs no hardware check. The conformance suite against the simulator is enough for a driver to be accepted.
- Tier 1 needs this check for each release, by the driver’s named maintainer. A Tier 1 failure blocks the release.
- A new driver gains from one check before its first review, if you have the synth. Its simulator copies only the faults that you saw, so the real synth can find more.
Supported synths lists each driver’s tier.
Before you start
- Find the synth’s firmware version.
oscyl infoshows it for a driver that reads it. - Choose a few scratch slots: slots whose programs you can lose.
Check the driver
-
Connect the synth, and check that Oscyl finds it:
oscyl ports oscyl info -
Back up the whole synth before any write:
oscyl backup before.oscyllibKeep this file until the check is done. It is your way back.
-
Read the program that the synth plays:
oscyl current -
Make a library with new programs in your scratch slots only. For example, open
before.oscyllibin the desktop app, change the scratch slots, and save it asscratch.oscyllib. -
List the programs that the write will change:
oscyl diff scratch.oscyllibIt prints one line for each program that differs, its position from 0 and its name, then
N of M programs differ. Check that it lists only your scratch slots. If it lists any other slot, stop. -
Write it. Oscyl backs up the whole synth first, then writes only the programs that differ:
oscyl restore scratch.oscyllibIt prints
backup of the synth saved to <path>, the progress, andwrote and saved N programs in <time>. Check that N is the number of programs that the diff listed. -
Compare the synth with the library again. Expect
0 of M programs differ:oscyl diff scratch.oscyllib -
Play a program without storing it, and listen to the synth:
oscyl audition scratch.oscyllib --index 3 -
Put the scratch slots back:
oscyl restore before.oscyllib oscyl diff before.oscyllibThe diff must say that no program differs.
-
In the desktop app, connect the synth and check that it reads every slot. Turn on Live, edit a value, and listen to the change.
Record the result
Write down in the pull request, or in the release’s notes:
- the synth and its firmware version;
- the platform and the app or command that you used;
- which steps passed, and the output of each step that failed.
Never commit the captures or the backups. Keep them in private/, which
git ignores.
A Tier 1 failure blocks the release. Cut a release says where the check fits.
Use Oscyl’s crates in your own project
This guide adds Oscyl’s crates to another Rust project, from Git. Use it for a tool that reads a synth or a library file with Oscyl’s drivers.
Oscyl’s crates are not on crates.io yet. A driver for a new synth goes in this repository: see Add a driver for a new synth.
Choose the crates
| Crate | Use it to |
|---|---|
oscyl-driver | Use the contract: Driver, SessionOp, SessionEvent and the other types |
oscyl-midi | Find and open a synth, and run operations on it. It holds DRIVERS, every driver that Oscyl has |
oscyl-core | Read and write .oscyllib library files |
oscyl-conformance | Test a driver against its simulator |
A driver crate, such as oscyl-korg-minilogue-xd | Use one synth’s own types directly |
The driver packages are named oscyl-<vendor>-<model> from Oscyl 0.6.0.
Up to the tag v0.5.0, two of them have older names: oscyl-minilogue-xd
and oscyl-prophet-rev2.
oscyl-midi depends on every driver crate. Cargo clones the whole
repository once, then builds only the crates that you name and their
dependencies. On Linux, the default feature midir of oscyl-midi needs
the ALSA development package (alsa-lib).
Add the dependencies
Name the same tag for every Oscyl crate. A tag is a release, and its crates are tested together. This guide uses the newest release:
[dependencies]
oscyl-driver = { git = "https://github.com/oscyl/oscyl", tag = "v0.6.0" }
oscyl-midi = { git = "https://github.com/oscyl/oscyl", tag = "v0.6.0" }
Read a program
This main.rs connects a simulated minilogue xd, reads the program that it
plays, and prints its name and four fields:
//! Read the program that a synth plays, and print its first fields.
use oscyl_driver::{SessionEvent, SessionOp};
use oscyl_midi::Device;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let driver = oscyl_midi::driver("korg-minilogue-xd").ok_or("no such driver")?;
// A simulated synth. For a real one: oscyl_midi::scan() and Device::open.
let mut synth = Device::demo(driver)?;
let mut program = None;
synth.run(SessionOp::ReadCurrent, |event| {
if let SessionEvent::Current(bytes) = event {
program = Some(bytes.clone());
}
})?;
let program = program.ok_or("the synth sent no program")?;
println!("{}", driver.name(&program)?);
for (i, field) in driver.fields().iter().enumerate().take(4) {
let value = driver.format_value(&program, i);
println!("{} / {}: {value}", field.group, field.name);
}
Ok(())
}
cargo run prints the program’s name, then one line for each field. This
is the output with that tag:
Glass Choir
Voice / Octave: 0
Voice / Portamento: 0
Voice / Key Trig: Off
Voice / Voice Mode Depth: Off
format_value gives each value as the editor shows it. Driver::get gives
the raw number that the synth stores, as oscyl current prints it: Octave
2, Key Trig 0.
Open a real synth
oscyl_midi::scan() lists the MIDI ports that a driver claims, each with
its driver. Device::open connects one. It sends the device inquiry, and
fails unless the driver’s synth answers:
let found = oscyl_midi::scan()?;
let candidate = found.first().ok_or("no synth found")?;
let mut synth = Device::open(candidate)?;
println!("{} on {}", synth.driver().info().model, synth.port_name());
Then run operations on synth as above. A scan needs the feature midir,
which is on by default.
What may change
Oscyl is before version 1.0. Any release can change any public item of any crate. A change to the driver contract needs an RFC first (GOVERNANCE), and the changelog names each release’s changes.
- Name a tag, never a branch, so that your build does not change under you.
- Read the changelog before you move to a new tag.
- The
.oscyllibformat has a version number, and new readers keep reading old files. See The .oscyllib library format.
The API reference of the crates is at oscyl.github.io/oscyl/api.
Build and run Oscyl
This guide builds and runs the desktop app and the command line tool on each system. For the Android and iOS apps, see Build, run and test the mobile apps.
Every system needs Rust 1.92 or newer, through rustup.
Linux: the desktop app and the command line
-
Install the development packages of GTK 4.20 or newer, libadwaita 1.8 or newer, ALSA (
alsa-lib) and gettext. -
Run the app or the command line:
cargo run -p oscyl-gtk # the desktop app cargo run -p oscyl-gtk -- --simulator # with simulated synths cargo run -p oscyl-cli -- --help # the command line tool cargo run -p oscyl-cli -- --simulator info # try it without a synth -
Connect the synth over USB. Oscyl finds its port by name.
To build the Flatpak, see packaging/flatpak.
macOS and Windows: the command line
Rust is all that you need:
cargo run -p oscyl-cli -- --help
macOS: the desktop app
-
Install the libraries with Homebrew:
brew install pkgconf gtk4 libadwaita gettext adwaita-icon-theme -
Run the app:
GETTEXT_DIR="$(brew --prefix gettext)" cargo run -p oscyl-gtk -- --simulator
To make Oscyl.app, also install dylibbundler and librsvg, then run:
GETTEXT_DIR="$(brew --prefix gettext)" cargo build --release -p oscyl-gtk
packaging/desktop/bundle-macos.sh target/release/oscyl-gtk 0.0.0 dist
The release’s Oscyl.app is signed ad hoc but not notarised, so macOS
refuses to open it the first time. Do one of these:
- In Finder, Control-click the app, choose Open, then choose Open in the dialog.
- On macOS 15 and later, try to open the app. Then go to System Settings, Privacy & Security, and choose Open Anyway.
- Clear the quarantine flag:
xattr -dr com.apple.quarantine Oscyl.app.
macOS has no hotplug yet. If you plug the synth in after Oscyl starts, choose Connect.
Windows: the desktop app
-
In an MSYS2 UCRT64 shell, install the toolchain and the libraries:
pacman -S --needed mingw-w64-ucrt-x86_64-{toolchain,rust,pkgconf,gtk4,libadwaita,gettext-tools} -
Run the app:
cargo run -p oscyl-gtk -- --simulator
To make the folder that a release ships (bin/Oscyl.exe runs it):
cargo build --release -p oscyl-gtk
packaging/desktop/bundle-windows.sh target/release/oscyl-gtk.exe "$MSYSTEM_PREFIX" dist/Oscyl
To make the installer from that folder, install
mingw-w64-ucrt-x86_64-nsis, then run:
eval "$(scripts/version.sh)"
makensis -DVERSION="$version" -DNUMERIC="$marketing" -DSRC="$(cygpath -w "$PWD/dist/Oscyl")" \
-DOUT="$(cygpath -w "$PWD/dist/oscyl-setup.exe")" packaging/desktop/oscyl.nsi
The installer is for the current user only, and needs no admin rights. It
puts Oscyl in %LOCALAPPDATA%\Programs\Oscyl and adds it to the Start
menu. To remove Oscyl, open Settings > Apps > Installed apps, choose Oscyl,
then choose Uninstall. Your settings and libraries stay.
You can also build the Windows app on Linux:
- Install
mingw-w64-gcc. - Unpack the same MSYS2 packages into a directory.
- Point
PKG_CONFIG_SYSROOT_DIR,PKG_CONFIG_LIBDIRandMSYSTEM_PREFIXinto it, and setPKG_CONFIG_ALLOW_CROSS=1. - Run
cargo build -p oscyl-gtk --target x86_64-pc-windows-gnu.
The installer and the app are not signed, so SmartScreen can warn the first time you run one of them. Choose More info, then Run anyway. As on macOS, if you plug the synth in after Oscyl starts, choose Connect.
To try the app on a Windows PC with a synth, from Linux, see Test on Windows hardware from Linux.
The optional tools of the checks
scripts/ci.sh uses these tools when they are installed, and skips their
stages when they are not. Run the checks says what
each stage does.
- actionlint and zizmor: the workflows.
- Ruby: the issue forms.
- typos: spelling.
- cargo-deny: the licences
and advisories of the dependencies (
cargo install cargo-deny --locked). - mdBook, Vale and lychee: the book, its prose and its links.
scripts/docs-tools.sh DIRdownloads the versions that CI uses, for x86_64 Linux.
Build, run and test the mobile apps
This guide builds, runs and tests the Android and iOS apps. They are in
apps/mobile (Compose Multiplatform) and use the same Rust core as the
desktop app, through crates/oscyl-ffi. Gradle builds the Rust core
itself. Repository layout names the app’s
modules, and The mobile bindings lists
what the Rust core gives the app.
What you need for Android
- A JDK 21.
- The Android SDK, with
ANDROID_HOMEset. - The NDK r30 (
ndk;30.0.16248370). Oscyl finds it throughANDROID_NDK_HOME, or takes the newest one under$ANDROID_HOME/ndkor~/Android/Sdk/ndk. - cargo-ndk:
cargo install cargo-ndk. - The Rust targets:
rustup target add aarch64-linux-android x86_64-linux-android.
Run the Android app on the emulator
Use any x86_64 virtual device:
emulator -avd <name> -no-window & # or with a window
cd apps/mobile && ./gradlew :androidApp:installDebug
adb shell am start -n io.github.oscyl/.android.MainActivity
The emulator has no USB. Pick a simulated synth on the welcome screen, or later choose “Try the demo” on the Synth page.
Run the Android app on a phone
-
Turn on USB debugging on the phone, and connect it.
-
Install the app:
cd apps/mobile && ./gradlew :androidApp:installDebug -
Plug the synth into the phone’s USB-C port, through an OTG adapter or a USB-C to USB-B cable. The phone powers the synth’s USB port.
-
Android offers Oscyl for the synth. Oscyl connects it.
adb logcat -s OscylMidi shows the port names that Android reports. The
app finds a minilogue xd on a Pixel 7 Pro. Testers with other phones and
synths are welcome.
To make an APK file instead, run ./gradlew :androidApp:assembleDebug in
apps/mobile. The APK is
androidApp/build/outputs/apk/debug/androidApp-debug.apk.
Run the iOS app
You need a Mac with Xcode and a JDK 21. The build finds the JDK with
/usr/libexec/java_home, or uses JAVA_HOME. Add the Rust targets:
rustup target add aarch64-apple-ios aarch64-apple-ios-sim
- Open
apps/mobile/iosApp/iosApp.xcodeproj. - Pick a simulator, then choose Run.
Xcode’s “Compile Kotlin” phase runs
./gradlew :shared:embedAndSignAppleFrameworkForXcode. That builds the
Rust core for the target and the Shared framework. The simulator has no
USB: open Synth and choose “Try the demo”. The project builds arm64 only.
The iOS app has not run on an iPhone yet. To try it on one:
- Set your Apple developer team in
Configuration/Config.xcconfig(TEAM_ID=). The bundle ID becomesio.github.oscyl<TEAM_ID>, so a free personal team can sign it. - Plug the synth into the iPhone: USB-C directly, or Apple’s Lightning to USB 3 Camera Adapter on an iPhone with Lightning.
- In Console.app, filter on
OscylMidito see the port names that CoreMIDI reports.
For an App Store build, set the bundle ID without the team suffix, and an App Store provisioning profile. The version numbers follow the release: Cut a release sets them.
When you add or remove a source file
The “Compile Kotlin” phase lists its inputs in
Configuration/KotlinInputs.xcfilelist, so Xcode skips the phase when no
Kotlin or Rust source changed. When you add or remove a source file, run:
scripts/mobile-assets.sh --inputs
scripts/ci.sh fails when the list is out of date.
The icon and the launch screen
scripts/mobile-assets.sh makes the iOS icon from the desktop app’s SVG,
the launch colours from design/tokens.json, and the input list again. It
needs rsvg-convert and ImageMagick. scripts/mobile-assets.sh --check
checks the committed files: the plists, the project file, the asset catalogs,
the icon, the launch colour and the input list.
The privacy manifest
iosApp/PrivacyInfo.xcprivacy declares no tracking and no collected data.
It also gives a reason for each required-reason API that the app uses:
- File timestamps, C617.1: the Rust core reads the modification times
of files in its own folders, for example to list backups newest first.
llvm-nmon the iOS static library findsstd::fs::metadataandMetadata::modified. - System boot time, 35F9.1: to measure elapsed time. This covers Rust’s
Instantand the clocks of the Kotlin/Native and Compose runtimes. Those runtimes cannot be inspected on Linux.
App Store Connect checks the manifest when you upload a build. If it names
another API, for example UserDefaults, add that API’s reason.
Test the apps
| What | Command, in apps/mobile |
|---|---|
| Behaviour tests (Robolectric, with the real Rust core built for this computer) | ./gradlew :shared:check :androidApp:testDebugUnitTest |
| Screenshot goldens | ./gradlew :androidApp:verifyRoborazziDebug (see Update screenshots and goldens) |
| Accessibility checks (ATF), on an emulator that Gradle manages | ./gradlew :androidApp:pixel6Api34DebugAndroidTest (needs KVM) |
| iOS tests, on macOS | ./gradlew :shared:iosSimulatorArm64Test :iosPlatform:iosSimulatorArm64Test |
If the emulator’s software GPU crashes (emulator 36.6 on Linux), put
android.testoptions.manageddevices.emulator.gpu=host in
~/.gradle/gradle.properties.
scripts/ci.sh runs the Android tests when ANDROID_HOME is set, and the
accessibility checks only when /dev/kvm is usable. On Linux it also checks
what it can for iOS: clippy of the Rust core for both iOS targets, the
:iosPlatform klibs and the files above. The iOS workflow
(.github/workflows/ios.yml) builds the app on macOS, starts it in a
simulator and keeps a screenshot.
Fast loops
From fastest to slowest. Use the first loop that can prove the change.
| Loop | Command (in apps/mobile) | Time |
|---|---|---|
| One test class | ./gradlew :androidApp:testDebugUnitTest -Poscyl.goldens=false --tests '*EditorBehaviourTest' | 25 s |
| Every behaviour test | ./gradlew :androidApp:testDebugUnitTest -Poscyl.goldens=false | 50 s |
| On the phones | scripts/mobile-phone.sh frames graph (from the repository root) | 1 min |
| Screenshots too | ./gradlew :androidApp:verifyRoborazziDebug (recordRoborazziDebug after a change that you want) | 2 min |
| What changed | scripts/ci.sh | depends on the change |
| Numbers of record | the Macrobenchmark, 5 iterations | 10 min for each phone |
The preview screenshots take nine tenths of the time of the unit tests.
scripts/ci.sh runs them only when a file under apps/mobile, design or
po changed.
Judge smoothness
Judge smoothness on the release-like build only. installDebug runs Compose
without optimisation, several times slower, so it says nothing about what a
user gets.
scripts/mobile-phone.sh # R8 build on every attached phone, profile compiled, started
scripts/mobile-frames.py -s <serial> # frame numbers of every journey, about a minute
scripts/mobile-frames.py -s <serial> graph rail # only these journeys
mobile-frames.py drives the installed app with adb and reads gfxinfo and
SurfaceFlinger. It needs no Gradle and no instrumentation. Its last column
is the one that the eye sees: the refreshes that the display missed, out of
the frames that it showed.
The column “late” is something else. On Android 11, one slow frame queues
every later frame of the gesture one refresh behind. The screen still gets
one frame for each refresh. While you tune, use mobile-frames.py. For
numbers of record, use the Macrobenchmark:
cd apps/mobile
ANDROID_SERIAL=<serial> ./gradlew -PreleaseBuild=true :androidApp:generateBaselineProfile
ANDROID_SERIAL=<serial> ./gradlew -PreleaseBuild=true :baselineprofile:connectedBenchmarkReleaseAndroidTest \
-Pandroid.testInstrumentationRunnerArguments.class=io.github.oscyl.baselineprofile.FrameBenchmarks#knobDrag \
-Pandroid.testInstrumentationRunnerArguments.iterations=2
The benchmark build (R8, with the shipped Baseline Profile) installs as
io.github.oscyl.bench. To install a debug build beside your own Oscyl,
add -Poscyl.idSuffix=.redesign (or another suffix) to the Gradle command.
Mobile smoothness records what was slow, why, and the numbers before and after.
Build the Rust libraries by hand
Gradle builds the Rust core itself. scripts/mobile-rust.sh builds the same
libraries and bindings alone. scripts/ci.sh runs it in the stage “ffi
bindings”.
scripts/mobile-rust.sh # output in target/mobile
scripts/mobile-rust.sh some/dir # or elsewhere
It makes:
jniLibs/arm64-v8a/liboscyl_ffi.soandjniLibs/x86_64/liboscyl_ffi.so(phone and emulator), as Android’sjniLibsexpects them;kotlin/io/github/oscyl/core/oscyl_ffi.kt, the stock UniFFI Kotlin bindings.
The stock bindings only check that the library’s metadata generates. The
app takes its bindings from the Kotlin Multiplatform plugin
ch.ubique.uniffi.plugin 1.3.x, which needs UniFFI 0.32.0 exactly. So
Cargo.toml pins uniffi = "=0.32.0". The Kotlin package is set in
crates/oscyl-ffi/uniffi.toml.
Without cargo-ndk or an NDK, the script builds the bindings only, and says that it skipped the Android libraries.
Run the checks
This guide runs the checks that CI runs, on your own machine, before you send a change. Checks and workflows says what each check proves.
Check a change
Run the script from the repository’s root:
scripts/ci.sh
It runs only the stages that your change reaches, since its last green run
or since your branch left main. It stops at the first failure. A stage
whose tool is not installed says so and is skipped.
- To run every stage, for a release:
scripts/ci.sh --all. - To skip the mobile app on purpose:
env -u ANDROID_HOME scripts/ci.sh.
Build and run lists the optional tools.
Check one part while you work
Run the smallest check that can fail for your change, for example:
- one crate:
cargo test -p oscyl-appandcargo clippy -p oscyl-app; - one driver’s conformance:
cargo test -p oscyl-sequential-prophet-rev2 --test conformance; - one mobile test class: see Fast loops;
- the book:
mdbook build docs, then opentarget/book/index.html.
Run the hardware tests
Tests that need a synth are marked #[ignore]. Connect the synth, then run
them:
cargo test -- --ignored
Fuzz a parser
The parsers that read synth replies and files have fuzz targets, in
fuzz/. They use cargo-fuzz
with nightly Rust:
cd fuzz && cargo +nightly fuzz run sysex # or: program, files
A new parser gets a fuzz target, or a line in one.
After you change a dependency
The About pages of both apps list the licences of the Rust crates. Write them again:
scripts/licences.sh
It uses cargo-about. scripts/ci.sh runs scripts/licences.sh --check.
The Kotlin and Android libraries’ notices come from the AboutLibraries
Gradle plugin, on every build.
Check the book’s prose and links
scripts/ci.sh runs three stages for the documentation: “book”, “prose”
and “links”. To run them alone:
mdbook build docs
git ls-files -z '*.md' | xargs -0 vale --minAlertLevel=warning
git ls-files -z '*.md' | xargs -0 lychee --no-progress --config lychee.toml
lychee --no-progress --config lychee.toml target/book
Vale applies the house style of .vale.ini. A page must have no errors and
no warnings. lychee checks every link and anchor offline. scripts/ci.sh
also checks the links to this repository on GitHub, against your work tree.
When you write a link:
- Link a page of the book with a relative
.mdlink. - Link a folder’s
README.mdby its folder, for example../adr/. The book renames that file toindex.html. - Link a file outside
docs/with its full GitHub address, because the book does not copy it.
Test on Windows hardware from Linux
This guide lets you run Oscyl on a Windows PC that has a synth plugged in,
from a Linux machine on the same network. The script
scripts/windows-test-host.ps1
opens a locked SSH door into the PC. The door stays closed until you open
it, and it closes itself after a few hours.
What the door allows
- One standard Windows user,
oscyl-test, with no administrator rights. It does not show on the sign-in screen. - A login only with one SSH key, and only from one address: your Linux machine’s.
- No password login, and no forwarding of ports, agents or X11.
- A firewall rule for port 22 from that address only, on private networks. The rule stays off while the door is closed.
Make a key on Linux
ssh-keygen -t ed25519 -f ~/.ssh/id_oscyl_windows
Install the door on the PC, once
-
Copy
scripts/windows-test-host.ps1to the PC. -
Open PowerShell as administrator, in the folder of the script.
-
Run the script. Replace
<linux-address>with your Linux machine’s address, and<public key>with the line in~/.ssh/id_oscyl_windows.pub:powershell -ExecutionPolicy Bypass -File .\windows-test-host.ps1 -Install -LinuxIp <linux-address> -PublicKey '<public key>'
The script installs OpenSSH Server, set to start only by hand. It makes the
user, the key file and the firewall rule. It keeps a copy of the old
sshd_config as sshd_config.before-oscyl. Then it closes the door and
says “Installed and closed. Open with -On.”
Add the PC to your SSH configuration
On Linux, add a host entry to ~/.ssh/config. Replace <pc-address> with
the PC’s address:
Host oscyl-win
HostName <pc-address>
User oscyl-test
IdentityFile ~/.ssh/id_oscyl_windows
IdentitiesOnly yes
StrictHostKeyChecking accept-new
Open the door, test, close it
-
On the PC, in an administrator PowerShell, open the door:
powershell -ExecutionPolicy Bypass -File .\windows-test-host.ps1 -On -Hours 3The door stays open for three hours unless you give another
-Hours. A scheduled task closes it then. -
On Linux, build the command line tool for Windows and copy it to the PC. The build needs
mingw-w64-gccand the Rust targetx86_64-pc-windows-gnu:cargo build --release -p oscyl-cli --target x86_64-pc-windows-gnu scp target/x86_64-pc-windows-gnu/release/oscyl.exe oscyl-win: -
Run it on the PC, against the synth:
ssh oscyl-win oscyl.exe ports ssh oscyl-win oscyl.exe info -
Close the door when you are done. On the PC, run the script with
-Off, or with no argument:powershell -ExecutionPolicy Bypass -File .\windows-test-host.ps1 -Off-Offstops the SSH server, ends every session ofoscyl-testand turns the firewall rule off.
For the checks to run on the synth, see Check a driver on hardware.
Remove the door
powershell -ExecutionPolicy Bypass -File .\windows-test-host.ps1 -Uninstall
-Uninstall closes the door, then removes the user and its profile, the
key, the firewall rule and OpenSSH Server. It puts back the sshd_config
from before -Install.
Translate Oscyl
Oscyl keeps its words in two places:
- gettext catalogs in
po/, for the desktop app, the drivers’ labels, value names and help, and the core’s messages. The mobile apps show the core’s messages too. - Compose resources, for the mobile app’s own words, in
apps/mobile/shared/src/commonMain/composeResources/values*/strings.xml.
English is the source. Italian is the second language, and every new string needs it. If you are not sure of a translation, ask someone who reads the language to review it, and say so in the pull request.
Translate the desktop app and the core
The domain is oscyl. In po/:
oscyl.potis the template;<lang>.pois one language, for exampleit.po;LINGUASlists the languages that ship.
-
Regenerate the template after a change to the words:
cargo run -p oscyl-gtk -- --write-pot po/oscyl.potA test fails when the template is out of date.
-
Start a new language, or update one:
msginit -i po/oscyl.pot -l <lang> -o po/<lang>.po # a new language msgmerge -U po/<lang>.po po/oscyl.pot # an existing one -
For a new language, add it to
po/LINGUAS. -
Translate the strings in
po/<lang>.po. Keep labels short: the label under a dial has room for about 12 characters. -
Try the translation from a source checkout:
mkdir -p /tmp/oscyl-locale/it/LC_MESSAGES msgfmt po/it.po -o /tmp/oscyl-locale/it/LC_MESSAGES/oscyl.mo OSCYL_LOCALEDIR=/tmp/oscyl-locale LANGUAGE=it cargo run -p oscyl-gtk
The strings come from the app and from the drivers that have translations. Today that is the minilogue xd: its parameter names, value names and help. The other drivers stay in English. To translate a driver’s words, see Add a driver for a new synth.
Translate the mobile app
- Add each English string to
values/strings.xml. - Add the same key to
values-<lang>/strings.xmlfor every language.StringsCompleteTestfails when a language misses a key. - Use positional arguments (
%1$s) and plurals for counts. - Put a comment above a string whose context is not clear.
Only the launcher label is in
apps/mobile/androidApp/src/main/res/values/strings.xml. It is the brand
name and has no translation. The MIDI errors that Android and iOS share are
Compose resources too.
Debug and test builds carry a generated pseudo-locale, en-XA. Its text is
accented, about 40% longer, and in brackets, so clipping and joined strings
show. Pick “English (XA)” in the phone’s developer options, or look at the
pseudoLocale_xa screenshot goldens. Release builds (-PreleaseBuild=true)
leave it out.
Never translate the names and texts of the licences on the About page.
Update screenshots and goldens
Oscyl’s pictures come from the apps themselves. This guide updates the mobile app’s screenshot goldens, a screenshot of the desktop app, and the pictures that the README and the website show.
Update the mobile goldens
Every @Preview in the mobile app is a screenshot golden, under
apps/mobile/androidApp/src/test/snapshots/. The previews are the only
source of the app’s screenshots.
-
Change the UI and its previews.
-
Record the goldens:
cd apps/mobile && ./gradlew :androidApp:recordRoborazziDebug -
Look at every golden that changed (
git status). Look at each theme, size and font scale, and at the mirrored and pseudo-locale versions. A golden that nobody looked at hides a bug. -
Check them as CI does:
./gradlew :androidApp:verifyRoborazziDebugWhen the check fails, the comparison images are in
apps/mobile/androidApp/build/outputs/roborazzi/.
Take a screenshot of the desktop app
The desktop app draws a scripted state and saves its window as a PNG:
cargo run -p oscyl-gtk -- --demo demo:filter:edited --screenshot shot.png
The function run_demo in
apps/linux/src/onboarding.rs
lists the other states. --theme light, --theme dark and
--size 1600x1000 set the theme and the window’s size.
Update the README’s and the website’s pictures
scripts/readme-images.sh makes every picture in docs/images/ again: the
desktop app’s windows from its demo states, and the phone’s screens from
the goldens.
-
Record the mobile goldens first, if the phone’s screens changed.
-
Build the desktop app:
cargo build -p oscyl-gtk. -
Run the script. It needs a display and ImageMagick 7:
scripts/readme-images.sh -
Look at each picture that changed in
docs/images/.
Cut a release
This guide makes a release. A release is a signed tag vX.Y.Z on main.
When you push the tag, .github/workflows/release.yml builds every
artifact, writes SHA256SUMS, attests the build provenance, and opens a
draft GitHub Release. Its notes are the version’s section of
CHANGELOG.md. Nothing is public until a maintainer publishes the draft.
Release artifacts lists what the workflow builds and what it refuses.
Make the release
-
Check the hardware. Each Tier 1 driver’s maintainer checks the driver on the real synth for this release (Check a driver on hardware). Name any driver that missed the check in the changelog.
-
Change the version in a release pull request:
- In
Cargo.toml, set[workspace.package] version. Then runcargo checkto updateCargo.lock. The version isX.Y.ZorX.Y.Z-rc.N, with Y and Z under 100 and N from 1 to 98. - In
apps/mobile/iosApp/Configuration/Config.xcconfig, setMARKETING_VERSIONto themarketingline ofscripts/version.sh, andCURRENT_PROJECT_VERSIONto itscodeline. - In
apps/linux/data/io.github.oscyl.Oscyl.metainfo.xml, add a new<release>as the first one in<releases>. - For a final release, in
docs/how-to/use-the-crates.md, set the dependencies’tagtovX.Y.Z. That guide names the newest release.
- In
-
Edit the changelog.
- Rename
## [Unreleased]to## [X.Y.Z] - YYYY-MM-DD. - Add a new, empty
## [Unreleased]above it. - At the bottom, make
[Unreleased]comparevX.Y.Z...HEAD, and add[X.Y.Z]: …/compare/vPREV...vX.Y.Z. - Write the section for users. It is the release note.
- Rename
-
Check the pull request.
scripts/release-check.sh X.Y.Zchecks that the versions agree and that the section exists.scripts/release-notes.sh X.Y.Zprints what the release will say. Merge the pull request when CI passes. -
Do a dry run (optional). In GitHub, choose Actions, Release, Run workflow, on
main. The run builds and attests everything and publishes nothing. The artifacts are on the run. -
Tag the merge commit, sign the tag, check the signature, and push it:
git switch main && git pull --ff-only git tag -s vX.Y.Z -m "Oscyl X.Y.Z" git tag -v vX.Y.Z git push origin vX.Y.ZA version with a pre-release suffix, such as
v1.0.0-rc.1, becomes a pre-release. -
Approve the
releaseenvironment when the workflow asks. The Android signing and the publish job wait for it. -
Review the draft: its notes, its assets and
SHA256SUMS. Then publish it.
How the version numbers work
scripts/version.sh is the one parser of the version. It prints the
version, iOS’s numeric marketing version, and the build code:
- for a release candidate,
codeis ((X×100 + Y)×100 + Z)×100 + N; - for a final release, it is ((X×100 + Y)×100 + Z)×100 + 99.
So 0.4.0-rc.1 is 40001, and 0.4.0 is 40099. Every release candidate gets
its own store build, below its final release. The Android app takes its
versionName and versionCode from the script when it builds.
scripts/release-check.sh checks the iOS numbers.
Set up the release, once
- The environment
release(Settings, Environments): the maintainers as required reviewers. Limit its deployment refs to the tagsv*.*.*and to the branchmain, for dry runs. - The Android signing secrets, as secrets of the
releaseenvironment:ANDROID_KEYSTORE_BASE64: the output ofbase64 -w0 release.jks;ANDROID_KEYSTORE_PASSWORD,ANDROID_KEY_ALIASandANDROID_KEY_PASSWORD.
Keep the keystore and its passwords offline as well. A lost upload key needs a reset from Google Play, and installed APKs update only from the same key.
The driver contract
The traits that a driver implements, in
crates/oscyl-driver/src/contract.rs.
Each method links to its documentation in the
API reference.
ADR 0002 records why the contract is
made this way.
A driver is a crate under crates/drivers/ that exposes one
pub static DRIVER. Its folder and its driver id (Info::id) are
<vendor>-<model>, and its package is oscyl-<vendor>-<model>, for
example oscyl-korg-minilogue-xd. A crate that a family of synths shares
is oscyl-<family>, as oscyl-logue. The tutorial’s oscyl-tutorial-synth
is the one exception. Of the 53 methods of Driver, 18 are required, and the
other 35 have defaults. The apps use it only as &dyn Driver. A required
method has no default. An optional method has a default that suits a
driver which does not use it.
Driver
One synth model: everything that the apps know about it.
Identity
| Method | Required | What it gives |
|---|---|---|
info | Yes | The driver’s id, the maker and the model. |
recognize | Yes | Whether an answer to the MIDI device inquiry comes from this synth. |
port_hint | Yes | Substrings of the names of the MIDI ports that the synth shows. |
firmware | No | The firmware version that an identity reply names. Default: none. |
setup_hint | No | What to check on the synth when it does not answer the inquiry. Default: empty. |
tier | No | The driver’s support tier. Default: 3. |
voices | No | The polyphony of the models that it covers. Default: unknown. |
What the synth has
| Method | Required | What it gives |
|---|---|---|
capabilities | Yes | The banks and their slots, which banks are writable, the edit buffer, live changes and unit slots. |
The program
| Method | Required | What it gives |
|---|---|---|
fields | Yes | The parameters: name, group and range. |
init_program | Yes | A new, valid program. |
check_program | Yes | Refuses bytes that are not a whole program. |
get | Yes | A field’s raw value. |
set | Yes | Sets one field, and no other. |
name | Yes | The program’s name. |
set_name | Yes | Sets the name. |
name_rules | Yes | The longest name and the characters that a name can hold. |
Files
| Method | Required | What it gives |
|---|---|---|
file_formats | Yes | The synth’s own file formats. Can be empty. |
import | Yes | Reads a file of one of those formats. |
export | Yes | Writes a file. Importing it gives back the same library. |
The editor
| Method | Required | What it gives |
|---|---|---|
curation | Yes | The editor’s pages and sections. A simple driver can return curation_by_group(self.fields()). |
control | No | The control for a field: a dial, a switch, named choices or named bands. Default: a switch for a two-value field, else a dial. |
short_label | No | A short label inside a titled section. Default: the field’s name. |
label_in | No | The label when a field’s job depends on another field. Default: the short label. |
emphasized | No | Whether a field is a main control, which apps draw larger. Default: no. |
format_value | No | A field’s value as text, in the context of the program. Default: format_raw of the value. |
format_raw | No | A raw value as text, with no program. Default: the number, or Off and On for a two-value field. |
page_summary | No | One line on a page’s state. Default: empty. |
page_summary_in | No | The page summary, short or translated, for an app. Default: page_summary. |
graphs | No | Pictures of a page. Default: none. |
handles | No | Draggable points on a page’s first graph. Default: none. |
drag | No | The field values for a handle at a point. Default: none. |
relevant | No | Whether a field does anything with the other settings. Default: yes. |
help | No | What a field does. Default: empty. |
category | No | What kind of sound a program is. Default: unknown. |
categories | No | Every category, for filters. Default: none. |
list_facet | No | A choice field that program lists can filter by. Default: none. |
Generate
| Method | Required | What it gives |
|---|---|---|
characters | No | The kinds of sound that Generate makes. Default: none, so the driver does not generate. |
macro_info | No | The titles and help of the four dials. Default: Bright, Movement, Grit and Ambience. |
mutability | No | What generation may do to a field. Default: keep it. |
generate | No | A new program from a recipe. |
vary | No | A variation of a program. |
breed | No | A child of two programs. |
morph | No | A step between two programs. Default: morph_fields. |
generated_name | No | A name for a generated program. Default: the character’s title and a number. |
needs | No | The user unit slots that a program relies on. Default: none. |
unit_param | No | Which user unit parameter a field is. Default: none. |
Live and the panel
| Method | Required | What it gives |
|---|---|---|
live_messages | No | The MIDI messages that set one field on the sounding voices. Default: none, so apps send the whole program. |
program_slot | No | The slot that the synth’s panel picked, from Bank Select and Program Change. Default: unknown. |
panel_listener | No | A decoder for the Control Changes that the panel sends. Default: none. |
Sessions and demo
| Method | Required | What it gives |
|---|---|---|
session | Yes | A new session for one synth. |
simulator | Yes | A new simulated synth. |
demo_library | No | A library to explore without a synth. Default: one generated program for each character. |
demo_simulator | No | The simulated synth of demo mode. Default: simulator. |
DriverSession
The synth’s protocol for one connected synth, sans IO: it never touches a
port or a clock. Oscyl gives it the bytes and the time. Most sessions keep
an Engine, the request engine,
which keeps one request in flight. Every method is required.
| Method | What it does |
|---|---|
submit | Plans an operation. A bad slot, a write to a factory slot or a bad program fails here, and nothing is sent. |
is_idle | True when nothing is queued or in flight. |
poll_transmit | The next bytes to send, if the session sends now. |
next_deadline | When a request in flight times out. |
handle_timeout | Time passed: a request whose reply did not come fails. |
handle_input | Bytes from the synth, in fragments of any size. |
poll_event | The next result, in order. |
An operation is a SessionOp:
ReadCurrent, ReadPrograms, WritePrograms or Audition. Its results
are SessionEvents: Current,
Program, Progress, then Done or Failed.
Simulator
The synth itself, in code, sans IO. The conformance suite and demo mode talk to it. Every method is required.
| Method | What it does |
|---|---|
handle | One message in, the synth’s replies out. |
idle_tick | One pass of the firmware’s main loop, with no MIDI traffic. |
program | The program in a slot. |
edit_buffer | The edit buffer’s program. |
is_settled | No save is pending and no reply state is corrupt. |
faults | The faults seen on the hardware that inject can switch on. It must include lose_reply. |
inject | Switches a fault on. |
PanelListener
An optional decoder of the Control Changes that a synth’s panel sends,
from Driver::panel_listener. Its one method,
control, gives the field and the value that a
Control Change sets, once the value is complete.
What the conformance suite checks
oscyl_conformance::run(&DRIVER) runs these checks in order, against the
driver’s simulator. A failure panics with <driver id>: <check>: <what>.
| Check | What it proves |
|---|---|
init_program | The init program is valid, and its name is not empty and uses allowed characters. |
fields | Every field takes its minimum and its maximum, reads them back, and changes no other field. One step outside the range is refused. |
names | A name of the longest length reads back. One character more is refused. |
wrong_length_programs | A program one byte short or one byte long is refused by every method that takes a program. |
rejects_bad_targets | A write to a factory slot or past the last slot, and a read past the last slot, fail at submit and send nothing. |
file_formats_round_trip | Every file format gives back the programs, and the author and comment when it keeps them. A second round trip changes nothing. An unknown format is refused. |
write_then_read_back | A write to the first, second and last slot of each writable bank ends Done. The simulator then holds the programs and is settled, and a read gives them back. |
audition | With an edit buffer: an audition ends Done, the edit buffer holds the program, and ReadCurrent gives it back. |
progress | Reads and writes report progress that rises to the total, and Done comes last. |
faults_never_report_false_success | With each fault: a write that ends Done stored every program, and a read returns only what the synth holds. |
lost_replies_fail | The simulator has lose_reply. With it, every operation ends Failed. |
curation_covers_every_field | Every field is in exactly one section or excluded, and at least one is shown. Every shown field has a label and a control that fits it. |
formats_every_value | Every field’s minimum and maximum format as text that is not empty. |
generation_is_deterministic_and_valid | For each character, the same recipe gives the same bytes, and every value is in range. Kept fields and pages stay, and vary, breed and morph behave. |
live_messages_are_well_formed | Live messages exist only with live_changes, and each one is one complete channel message on the channel asked for. |
presentation_is_consistent | Emphasized fields are shown, labels exist, categories are listed, and graphs, handles and drags stay within the pages and fields. |
recognizes_its_simulator | Port hints exist. The driver recognises its simulator’s identity reply from any channel, but not the inquiry itself and not another maker’s reply. |
app_hooks | The demo library is valid and fits the writable slots, the demo simulator is recognised, and the list facet is an in-range choice field. |
Supported synths
The synths that Oscyl has a driver for, and what Oscyl does with each one.
What works on each synth
| KORG minilogue xd | KORG prologue (8 and 16) | Sequential Prophet Rev2 | |
|---|---|---|---|
| Librarian: read, organise, write programs | Yes | Yes | Yes |
| Editor, with a graph for each stage | Yes | Yes | Yes |
Backup and oscyl restore | Yes | Yes | Yes |
| Live: edits play at once | Yes | Yes | Yes |
| Live: the synth’s knobs and program changes move the app | Yes | No | No |
| Generate | Yes | Yes | Yes |
| User units: list, load, clear, shelf | Yes | Yes | No |
| The oscillator unit | Yes | Yes | No |
| The driver’s own words in Italian | Yes | No | No |
The drivers
| KORG minilogue xd | KORG prologue | Sequential Prophet Rev2 | |
|---|---|---|---|
| Driver id | korg-minilogue-xd | korg-prologue | sequential-prophet-rev2 |
| Crate | oscyl-korg-minilogue-xd | oscyl-korg-prologue | oscyl-sequential-prophet-rev2 |
| Tier | 1 | 2 | 2 |
| Program slots | 500, all writable | 500, all writable | U1 to U4 (512, writable); F1 to F4 (512, factory, never written) |
| User unit slots | Oscillators 16, modulation effects 16, delays 8, reverbs 8 | Oscillators 16, modulation effects 16, delays 8, reverbs 8 | None |
| File formats | .mnlgxdlib, .mnlgxdpreset, .mnlgxdprog | .prlglib | .syx |
| Unit files | .mnlgxdunit | .prlgunit | None |
| Port name hints | minilogue xd _ SOUND, minilogue xd _ MIDI 2 | prologue _ SOUND, prologue _ MIDI 2 | Prophet Rev2 |
Every format above keeps each program’s author and comment, except .syx.
Oscyl also reads and writes every synth’s programs as .oscyllib.
What was checked on hardware
- minilogue xd: checked on the synth, firmware 2.10, with the desktop
app and the command line on Linux. The Android app finds it on a Pixel 7
Pro. On Windows 11,
oscyl infofinds it. - prologue and Prophet Rev2: tested against their simulators only, not yet on the synths. Hardware testers are welcome.
- The oscillator unit: not yet heard on a synth.
The desktop app on macOS and Windows, and the iOS app, have not run with a synth yet.
Tiers
GOVERNANCE
defines the tiers. A driver reports its tier with Driver::tier.
The minilogue xd is Tier 1: its maintainer, named in .github/CODEOWNERS,
checks it on the synth for each release. The prologue and the Prophet Rev2
are Tier 2: no named maintainer checks them on hardware yet.
| Tier | What it takes |
|---|---|
| Tier 3 (community) | It compiles. |
| Tier 2 (conformance-proven) | It passes the conformance suite against its simulator on every commit. |
| Tier 1 (hardware-validated) | Tier 2, and a named maintainer checks it on the real synth for each release. A Tier 1 failure blocks the release. |
To add a synth, see Add a driver for a new synth.
The command line
oscyl is Oscyl’s command line tool, for every desktop system. It comes
with each release, or runs from the source as cargo run -p oscyl-cli --.
This page lists every command and option, as oscyl --help and each
command’s --help give them.
oscyl [OPTIONS] <COMMAND>
Global options
| Option | What it does |
|---|---|
--port <PORT> | Only consider MIDI ports whose name contains this text. |
--synth <SYNTH> | Which kind of synth, by driver id, when no file says. oscyl ports lists the ids. |
--simulator | Use a simulated synth, with its demo programs, instead of MIDI hardware. The environment variable OSCYL_SIMULATOR does the same. |
-h, --help | Print the help. |
-V, --version | Print the version. |
A command that needs a synth looks for exactly one synth on the ports that
a driver claims. When it finds more than one, give --synth or a more
exact --port.
Files that Oscyl keeps
Oscyl keeps its files in $XDG_DATA_HOME/oscyl, or in
~/.local/share/oscyl when XDG_DATA_HOME is not set:
backups/: the automatic backups ofrestore, and the unit backups ofunits upload --forceandunits clear;units/: the shelf.
Commands that read
oscyl ports
List the MIDI input and output ports, then the synths that Oscyl supports. Needs no synth.
oscyl ports
oscyl info
Show the connected synth’s model, port, MIDI channel and firmware.
oscyl info
oscyl current
Print the edit buffer: the program that the synth plays now, which can be unsaved. It prints the name, then one line for each field.
| Option | What it does |
|---|---|
--raw | Print the program’s bytes as hex instead. |
oscyl current --raw
oscyl backup <OUT>
Read every program and save them to a library: .oscyllib, or one of the
synth’s own formats, by the extension of OUT. On a synth with user units
(minilogue xd, prologue), the backup also holds the global settings, the
tuning and the units.
oscyl backup my-xd.oscyllib
oscyl diff <LIBRARY>
List the programs that differ between a library and the synth.
oscyl diff my-xd.oscyllib
Commands that write to the synth
oscyl restore <LIBRARY>
Write a library to the synth. Oscyl reads the synth, saves an automatic backup of it, then writes only the programs that differ. It writes nothing when the backup fails. It never writes a factory slot.
| Option | What it does |
|---|---|
--all | Write every program, also the unchanged ones. |
oscyl restore my-xd.oscyllib
oscyl audition <FILE>
Play a program from a file, in the edit buffer, without storing it.
| Option | What it does |
|---|---|
--index <INDEX> | Which program of a library, from 0. Default: 0. |
oscyl audition my-xd.oscyllib --index 12
Generate
oscyl generate
Deal new sounds, each with a recipe code that makes it again. Needs no
synth, except for --audition and --units. Give one of --character,
--code, --vary or --breed.
| Option | What it does |
|---|---|
--list | List the characters that the synth (--synth) can generate. |
--character <CHARACTER> | The character, by id (see --list). |
--bright <BRIGHT> | Filter openness, 0 to 100. Default: 50. |
--movement <MOVEMENT> | Modulation, 0 to 100. Default: 50. |
--grit <GRIT> | Drive, noise and other dirt, 0 to 100. Default: 50. |
--space <SPACE> | Delay, reverb and other ambience, 0 to 100. Default: 50. |
--seed <SEED> | The first sound’s seed. The others follow from it. Random when left out. |
--code <CODE> | Deal the sound that a recipe code names, first. |
--count <COUNT> | How many sounds. Default: 6, or 1 with --code. |
--out <OUT> | Write each sound into this folder as a program file. |
--audition | Play the first sound on the synth, without storing it. |
--units | Let the sounds use the user units that the synth holds (about one sound in three). Needs the synth, or --simulator. |
--vary <FILE> | Deal variations of the program in a file instead. |
--breed <A> <B> | Deal children of the programs in two files instead. |
oscyl generate --character fuzz-bass --seed 7 --count 3
User units
oscyl units
Manage the logue SDK user oscillators and effects of a minilogue xd or a
prologue. Without --synth, the commands work on the first driver with user
units, the minilogue xd. Slot numbers start at 1.
| Command | What it does | Writes |
|---|---|---|
units list | Show what each user slot holds. | Nothing |
units upload <FILE> --slot <SLOT> | Load a unit file into a slot. --force replaces a unit already there, after a backup of it. | One slot |
units clear --module <MODULE> --slot <SLOT> | Empty a slot, after a backup of its unit. MODULE is osc, modfx, delfx or revfx. | One slot |
units info <FILE> | Show what a unit file says about itself: section, name and parameters. Needs no synth. | Nothing |
units shelf add <FILES>... | Copy unit files onto the shelf. | Nothing |
units shelf list | List the shelf, each unit with its parameters. | Nothing |
units shelf remove <NAME> | Take a unit off the shelf, by name. | Nothing |
units shelf load <NAME> | Load a unit from the shelf into the first free slot of its section. | One empty slot |
units make | Make a new oscillator with Oscyl’s oscillator unit and show it. Needs no synth, except for --load. | With --load, one empty slot |
units make takes these options:
| Option | What it does |
|---|---|
--family <FAMILY> | What the oscillator is built around: wavetable, fm, fold, formant, noise or hybrid. Default: any, by the seed. |
--seed <SEED> | The same seed and family make the same oscillator. Random when left out. |
--load | Put the oscillator on the shelf and load it into the first free oscillator slot. |
--out <OUT> | Write it as a unit file. |
oscyl units make --family fm --seed 3 --out fm3.mnlgxdunit
oscyl --synth korg-prologue units list
The .oscyllib library format
Oscyl keeps each library in its own file, which no synth’s software owns.
The code is
crates/oscyl-core/src/native.rs.
A .oscyllib file is a ZIP archive with these members, in this order:
| Member | Content |
|---|---|
oscyl.json | The manifest (below). |
programs/0000.bin, programs/0001.bin, … | One program for each member, in library order, as raw bytes in the driver’s own layout. The index has four digits and starts at 0. |
extras/<name> | Members that the driver owns, kept byte for byte: vendor entries that Oscyl does not edit. For the minilogue xd: favourites, tuning tables, preset information, unknown members, and FileInformation.xml, which lists those entries. They let a later export to the vendor’s format lose nothing. |
Manifest
{
"format": 1,
"driver": "korg-minilogue-xd",
"programs": [
{ "author": "…", "comment": "…" }
]
}
format: the version of the format.driver: the id of the driver that owns the program bytes and the extras (Driver::info().id).programs: one object for each program, in order.programs[i]describesprograms/<i>.bin. Every program in the list has its member.
Versioning
- A reader refuses a file whose
formatis higher than the newest that it knows. It says that a newer version of Oscyl made the library. - A new version can add optional fields without a new
format. Readers ignore fields that they do not know, and a missing optional field takes its default. - A change that an older reader would misread raises
format.
Migration from .mnlgxdlib
Before this format, the Linux app kept its libraries as minilogue xd
.mnlgxdlib files, listed in index.json. The index is now
libraries.json. When it does not exist yet, Oscyl starts it from
index.json, and leaves index.json in place for an older build.
When the library folder opens, Oscyl takes each old file through these steps:
- It converts the file to
.oscyllib. - It reads the new file back and compares it with the conversion.
- It moves the original into
before-oscyllib/, with a copy of the originalindex.json.
If a step fails:
- Oscyl cannot read the original: the original moves into the backup folder as it is.
- Oscyl cannot write the new file, or it does not read back equal: the original stays, with its entry in the index. The next open tries again.
- A backup with the same name exists: Oscyl keeps the original as
<id>.<n>.mnlgxdlibinstead.
Oscyl never deletes or overwrites an original.
The mobile bindings
What crates/oscyl-ffi gives the Android and iOS apps, through UniFFI. The
logic lives in oscyl-app, and the bindings carry it across. The same calls
serve both platforms. The names below are the Kotlin names.
Transport
oscyl-midi’s ALSA code (midir, hotplug and port scanning) is behind its
default feature midir, and oscyl-ffi builds without it. On mobile, the
platform owns the USB MIDI ports (Android’s MidiManager, iOS’s CoreMIDI)
and moves the bytes.
| Call | What it does |
|---|---|
candidates(portNames) | Which drivers can answer on these ports. The platform finds the ports and asks. |
Synth.openLink(driverId, port, out) | Opens one port. Rust sends through the platform’s MidiOut.send(bytes). The returned MidiInputSink takes what the synth sends. |
MidiOut.send(bytes) | The platform sends bytes. An exception here disconnects the synth. |
MidiInputSink.push(bytes) | The platform pushes received bytes, in fragments of any size. Rust frames the SysEx. |
MidiInputSink.disconnect() | The port went away. A second call does nothing, and a later push is ignored. |
Synth.gone(port) | Drops the synth on that port, on unplug. |
Synth.openDemo | Connects a driver’s simulated synth. |
Synth.quit() | Ends the work and stops the threads. Call it when done (ViewModel.onCleared, close). After it, every call does nothing. |
Rules:
portnames one physical port, and it must be unique among the open ports. On Android, include theMidiDeviceInfoid, for example"42:minilogue xd". A secondopenLinkon a port that is open or opening ends inConnectFailed, and its sink is never read.- The device inquiry confirms the synth, as on Linux. Releasing a
MidiInputSinkwithoutdisconnect()also disconnects it. MidiInputSink.close()is UniFFI’sAutoCloseable.close(). It releases the object, and every later call throws. Call it only when no receiver can push any more.- Events (
SynthEvent) reach the app’sSynthListenerin order, on a Rust thread of their own. Move to the main dispatcher there. - On unplug, the closed input can end the synth before
gone(port)comes. Then anErrorfor that id, which says that the synth disconnected, comes just before itsDisconnected. Treat that pair as status, not as an error dialog. - Dropping the
Synthalso quits, but only as a fallback. The event thread holds the listener and the worker holds eachMidiOut. If either refers back to theSynth, the drop never comes. Onlyquit()then stops the threads and releases the device.
On Android, AndroidMidi names each port as ALSA does: <product> _ <port name>, or the product alone when the port has no name. A device with
several unnamed ports numbers them: <product> _ MIDI 2. So the drivers’
hints, such as minilogue xd _ SOUND, match. It logs the raw values with
the tag OscylMidi.
Libraries and documents
| Call | What it does |
|---|---|
Libraries.open(dir) | Opens Oscyl’s libraries folder, and makes it if needed (on Android, filesDir/libraries). It converts old .mnlgxdlib libraries once, keeps the originals in before-oscyllib/, and empties the last run’s trash. |
Libraries.outline() | The tree, depth first: folders and libraries, whether each one shows, a library’s synth and program count, or why it cannot be read. |
create, add, newFolder, rename, duplicate, place, step, setOpen | Change the tree. |
delete | Returns a Trashed, for restore (Undo) or purge (the Undo is gone). |
newLibraryName(), newFolderName() | “Library 1”, “Folder 1” and so on, a name that is not taken. |
Libraries.read(id) | A Document to edit. save(id, doc) writes it back. The app saves after every change. |
Document.synth(driverId, title) | A synth’s slots. Give it each SynthEvent.Program with receive(slot, data). |
Document.rows() | The whole list in one call: slot, name, edited, read-only factory slot, read yet. Document.row(i) gives one row. |
setName, newProgram, remove, reorder, copy, paste, pasteOver, revertProgram, clearProgram, undo, redo | Change a document. Each change is one undo step. copy gives a Clip. revision() changes with every edit. |
Document.put(index, data) | Puts a program over a slot, or at the end of a library. Refused when the document is read-only or full. |
programMenu(doc, index, libraries, libraryId, clipboard) | What a program’s menu holds, in order, which items are on, and which libraries “Copy to Library” offers. |
importFile(fileName, bytes) | Reads an Oscyl library or a synth’s own file (by extension, else by contents). Refuses more programs than a library holds. |
exportFormats(driverId) | The formats that a library exports to: the synth’s usual format first, .oscyllib last. |
exportFile(doc, ext) | Writes one file. |
- Every
Librariesmethod reads or writes the folder: call it onDispatchers.IO. ADocumentis cheap to call from the main thread. - Files cross as bytes; the platform owns pickers and URIs.
importFileandexportFileparse or build the whole file: call them off the main thread. - Errors are
FfiError.Failedis a file or the folder, with the reason.Refusedis a factory slot, or a name that the synth cannot hold. The core’s own reasons go through its translation hook. File system reasons keep the system’s words.
On Android, AndroidFiles (in androidApp) opens and creates documents
through the Storage Access Framework. It shares through the share sheet,
with a FileProvider over one file in the app’s cache. The shared Files
interface takes it. On the emulator, run
adb push some.mnlgxdlib /sdcard/Download/, then choose Import file in
Library.
Preferences and language
| Call | What it does |
|---|---|
Settings.load(path) | Reads the preferences: the oscyl-app settings file that the desktop uses too, here filesDir/settings.json. They hold the theme, the app’s own animation switch, haptics, demo mode’s driver and the first-run answer. Setters change them, and save() writes them (blocking). |
Settings.onboarded, role | Keep the welcome’s answer. role picks the start page: Library for Organise, the editor for the others. |
setLocale(tag) | Makes the core’s and the drivers’ words follow the app’s language: page and field names, values, summaries, refusals and worker errors. They come from the po/*.po catalogs, built into the library (oscyl-app catalog). Call it at start and when the language changes. The app’s own words stay Compose resources. |
Synth work
| Call | What it does |
|---|---|
Synth.readAll, cancelRead | Read a synth again, or stop. |
Synth.readCurrent | Read the program that the synth plays (a Current event). |
readUnit(driverId, module, bytes) | Checks a unit file for a section (logue synths). |
Synth.uploadUnit | Loads a unit into a slot. |
Synth.clearSlot | Backs the slot’s unit up to a file (unitBackupPath), then clears the slot. It never clears without the backup. |
unitExt, unitSection | A synth’s unit file extension, and a section’s name. |
backups(dir) | The backups folder, newest first. readFile reads one backup. |
keepUnsynced, unsynced, forgetUnsynced | Keep a connected synth’s unsynced edits on disk between runs. |
newLibraryDriver | Picks a new library’s synth, as on the desktop. |
ProgramEditor.update(pages, points), facts() | What an edit changed, and the state of the top row, in one call each. |
Generate and the welcome
| Call | What it does |
|---|---|
Generator(driverId, seed) | Holds the core’s hands (oscyl-app generator, shared with the desktop): characters, macros, pages, deal, vary, breed, step, select, markKept, selectedProgram. The same seed deals the same bytes. |
Generator.hand(points) | The tiles with their pictures. Each tile is drawn from the page whose pictures differ most across the hand, so the tiles tell the sounds apart. |
CharacterInfo.family | “keys”, “bass”, “lead”, “pad”, “rhythm” or “effect”. The page’s family row filters the characters by it. |
Generator.surprise(), dealCode(code) | Deal, and return what they chose (Dealt: the character and the dials), for the page to show. |
Generator.morph(other) | Deals six steps between two sounds. |
Generator.code() | The recipe code of the picked sound. A variation, a child or a morph step has none. Files.shareText offers the code to another app. |
keepPalettes(path) | Where each synth’s user units are remembered, beside the preferences. The worker fills them in from every slot listing. |
Generator.units(), setUnitOn | Generate’s “My units”. setUnitOn leaves one out for the session. A SoundTile names the units that it uses. |
keepWarning(onSynth) | The warning to say once when a sound that uses a unit is kept. |
Shelf(dir) | Keeps unit files: list, add, remove. Synth.loadFromShelf puts one into its section’s first free slot. |
SlotInfo, ShelfUnitInfo | Carry a unit’s params, each with its range in words. In the editor, a known unit’s Param 1 to 6 arrive named and ranged (FieldState). |
ProgramEditor.startPage(role) | The page that a program opens at: the oscillators for sound design, the voice for a performance. |
Document.demo(driverId, title) | A synth’s demo library. The driver makes the sounds, so Oscyl ships no vendor data. The welcome keeps it as a library. |
On iOS, Files.opened carries the files that other apps open in Oscyl
(onOpenURL). Oscyl owns .oscyllib, and the synths’ library files open in
Oscyl as an alternate handler.
The editor and the review
The editor’s logic lives in oscyl-app (editor, review), and the
desktop app uses it too.
| Call | What it does |
|---|---|
Document.editor(index) | Opens program index as a ProgramEditor. Open a new one after the document reorders or removes programs. |
pages() | The stages: title, the desktop app’s icon id, intro, and sections with their fields. |
fields(page), field(f) | Each field as the program shows it now. A field has: label, ControlKind (dial, segments, menu, Off/On), raw and saved raw, option and saved option, value texts, relevant, edited, help. Ask again after an edit, because the control and the label can change with other fields. |
stages() | Every stage’s summary, edit count and which sections apply. |
graphs(page, points) | The stage’s picture as plain marks (GraphShape), now and, when it differs, as saved. |
handles(page) | The picture’s draggable points. |
set(field, raw), choose(field, option), revertField(field) | Edits. choose is for segments, menus and Off/On. Each is one undo step of the document until seal(). Call seal() when a gesture ends. |
dragTo(page, handle, x, y) | Sets every field that a handle moves. The whole drag is one undo step until seal(). drag only says which fields it would set. |
setComparing(true) | Shows the saved program everywhere and ignores edits. program() is the program that shows, to audition. |
Document.review() | Each edited program’s changes, in words. |
markSaved() | Keeps a library’s edits: nothing shows as edited. |
syncPlan() | What a sync writes. It is refused until every edited slot has been read. |
writeBackup(dir, doc, indices) | Backs up what those slots hold (blocking). Then call Synth.write. |
auditionTarget(synths, active, driverId) | The synth that plays a program. |
- An edit is refused (
FfiError.Refused) on a factory slot, or on a slot that is not read yet. - An edit returns what to play:
Audition.Live(send it withSynth.live) orAudition.Program(send it withSynth.audition). - On
Written, give each written program back withdoc.receive(slot, data). It becomes the slot’s saved version, so an edit made while the write ran stays edited.
iOS platform
:iosPlatform holds the iOS code that needs no Rust core:
- CoreMIDI (
CoreMidi): one client. Its setup-changed notification lists the ports again. Each source pairs with a destination of the same entity. Bytes go out withMIDISend, and come in through an input port’s block. - Files (
Documents): the document picker opens a file and exports one. Export asks for the place first, then writes the bytes. The share sheet is a popover on iPad. - Haptics: UIKit’s selection, impact and notification generators.
- Storage and language: Application Support for storage, and
NSLocale.preferredLanguagesfor the language.
:iosPlatform has no cinterop, so scripts/ci.sh compiles its klibs on
Linux (kotlin.native.enableKlibsCrossCompilation). The UniFFI bindings of
:shared use cinterop, so :shared builds for iOS on macOS only.
shared/src/iosMain adapts the platform code to the shared contracts
(IosPlatform).
On the Rust side, the transport stays the platform’s, as on Android: the
same Synth.openLink, MidiOut and MidiInputSink carry the bytes. Oscyl
does not use midir’s CoreMIDI backend because it gives no hotplug
notifications, so the port list would need polling.
MidiLink (early bytes, then the rules for the close order),
midiPortName, AppStorage and the MIDI error words are in commonMain,
for both platforms.
Checks and workflows
What scripts/ci.sh checks on your machine, and what each GitHub workflow
checks. Run the checks says how to run them.
The stages of scripts/ci.sh
The script runs these stages in order and stops at the first failure. A
stage runs only when a file that it checks changed since the last green
run. The last green run is the tree in target/ci-green-tree; without it,
the script compares with the branch’s merge base with main. --all runs
every stage.
| Stage | What it checks | When it runs |
|---|---|---|
| workflows | actionlint (with shellcheck) and zizmor, pedantic, over .github/ | .github/ changed |
| issue forms | Every field of every issue form is valid (Ruby’s YAML) | An issue form changed |
| spelling | typos, over the changed files | Always |
| release scripts | The release notes test, every changelog section and its compare link, and the version parser’s test | CHANGELOG.md or a release script changed |
| book | mdbook build docs | A Markdown file, the style rules or the tutorial’s driver changed |
| prose | Vale, over every Markdown file, with warnings shown | As “book” |
| links | lychee, over every Markdown file and over the built book | As “book” |
| fmt | cargo fmt --all --check | A Rust crate changed |
| clippy | Clippy, with warnings as errors, over the crates that the change reaches | As “fmt” |
| tests | The tests of those crates | As “fmt” |
| without midir | Clippy and the tests of oscyl-midi and oscyl-app without their feature midir, as the mobile apps build them | The change reaches oscyl-midi or oscyl-app |
| conformance | Each driver’s tests/conformance.rs. A driver crate without one fails | The change reaches that driver |
| docs | cargo doc, with warnings as errors | As “fmt” |
| ffi bindings | scripts/mobile-rust.sh: the Kotlin bindings, and the Android libraries when cargo-ndk and an NDK exist | The change reaches oscyl-ffi |
| ios | Clippy of oscyl-ffi for both iOS targets, when they are installed | As “ffi bindings” |
| (Xcode files) | scripts/mobile-assets.sh --check | The mobile app, the design tokens, the icons, the fonts or a licence text changed |
| licences | scripts/licences.sh --check: the About pages list the crates of Cargo.lock | Cargo.lock or the licence script changed |
| mobile app | The common Kotlin, :shared:check, the behaviour tests, the screenshot goldens, the debug build and the iOS platform klibs | The mobile app or the design tokens changed, or the change reaches oscyl-ffi. Needs ANDROID_HOME |
| accessibility | The accessibility checks, on a running emulator or on one that Gradle manages | A UI source of the mobile app changed. Needs /dev/kvm |
| cargo deny | Licences, advisories, bans and sources of the dependencies | A manifest, Cargo.lock or deny.toml changed |
The screenshot goldens run only when a file under apps/mobile, design
or po changed. For a change to the Rust core alone, the mobile stage runs
the behaviour tests without them.
The GitHub workflows
| Workflow | Jobs and what they check | When it runs |
|---|---|---|
CI (ci.yml) | rust: fmt, clippy and the tests of the workspace, and the build without midir. desktop: the tests and the command line on macOS and Windows. conformance: each driver’s conformance test. msrv: the build with Rust 1.92. deny: cargo-deny. docs: rustdoc with warnings as errors. book: the book, its prose and its links. licences, typos. flatpak-sources and gtk: the desktop app, built and tested in the GNOME runtime. | Every push to main and every pull request |
Android (android.yml) | android: :shared:check, the behaviour tests, the screenshot goldens and the debug build. accessibility: the accessibility checks on an emulator | A change to the mobile app, the crates, the manifests or the design |
iOS (ios.yml) | The iOS tests, then the iOS app: built on macOS and started in a simulator, with a screenshot | A change to the mobile app, the crates, the manifests or the design tokens |
Desktop apps (desktop-apps.yml) | The desktop app built and bundled for Windows and macOS, as a release does, then opened once with a simulated synth for a screenshot | A change to the desktop app, the crates, the design, the translations or the bundle scripts |
Fuzz (fuzz.yml) | A short run of every fuzz target | A change to the crates or to fuzz/, and once a week |
CodeQL (codeql.yml) | Code scanning | Every push to main, every pull request, and once a week |
Dependency review (dependency-review.yml) | The dependencies that a pull request adds | Every pull request |
Changelog (changelog.yml) | A pull request that changes what users get also changes CHANGELOG.md, or has the label no-changelog. Docs, workflows, tests and Markdown are exempt. | Every pull request |
Lint workflows (lint-workflows.yml) | actionlint and zizmor | A change to .github/ |
Scorecard (scorecard.yml) | The OpenSSF Scorecard | Every push to main, and once a week |
Site (pages.yml) | Publishes the website, the book and the API reference to GitHub Pages | A change to the site, the book or the crates of the API reference |
Release (release.yml) | Builds, checks and attests every artifact; opens a draft release. See Release artifacts. | A pushed tag vX.Y.Z, or by hand |
Release artifacts
What the release workflow, .github/workflows/release.yml, builds and
checks. Cut a release says how to start it.
What a release holds
| Artifact | Notes |
|---|---|
oscyl-X.Y.Z-{x86_64,aarch64}-unknown-linux-gnu.tar.gz | The oscyl command line for Linux (ALSA). Built on Ubuntu 24.04, so it needs glibc 2.39 or newer. There is no musl build: it would need a static libasound. |
oscyl-X.Y.Z-{aarch64,x86_64}-apple-darwin.tar.gz | The oscyl command line for macOS (CoreMIDI). Not signed or notarised. |
oscyl-X.Y.Z-x86_64-pc-windows-msvc.zip | The oscyl command line for Windows (WinMM). Not signed. |
oscyl-X.Y.Z-desktop-windows-x86_64.zip | The desktop app for Windows: a folder with bin\Oscyl.exe, and the MSYS2 UCRT64 DLLs, data and licence texts that it needs. Not signed. |
oscyl-X.Y.Z-windows-x86_64-setup.exe | The same desktop app as an installer for the current user (NSIS, packaging/desktop/oscyl.nsi). It installs to %LOCALAPPDATA%\Programs\Oscyl, and Settings > Apps uninstalls it. Not signed. |
oscyl-X.Y.Z-desktop-macos-{aarch64,x86_64}.zip | The desktop app for macOS: Oscyl.app, with Homebrew’s libraries inside. Signed ad hoc, not notarised. It needs the macOS version of the runner that built it, or newer. |
oscyl-X.Y.Z-x86_64.flatpak | The GNOME app on the GNOME 49 runtime, which installs from Flathub. |
oscyl-X.Y.Z.apk, .aab | The Android app, signed when the keystore secrets exist. Otherwise -unsigned is in the name. |
oscyl-X.Y.Z.tar.gz | The source (git archive of the tag). |
SHA256SUMS | The checksums of all of the above. |
Each artifact has a SLSA build-provenance attestation. To check a file and the sums:
gh attestation verify <file> --repo oscyl/oscyl
sha256sum -c SHA256SUMS --ignore-missing
What the workflow refuses
The workflow refuses a tag when:
- the tag is not on
main; - its version differs from the one in
Cargo.toml, in the Android app or in the metainfo; CHANGELOG.mdhas no dated section for the version.
Last dry run
0.4.0, 2026-11-13, on an x86_64 Linux workstation. Every Linux release build ran by hand, as the workflow runs it. Nothing was tagged, signed or published.
| Artifact | Result |
|---|---|
oscyl-0.4.0-x86_64-unknown-linux-gnu.tar.gz | cargo build --release --locked -p oscyl-cli, 12 s warm. The binary reports oscyl-cli 0.4.0. |
oscyl-0.4.0-x86_64.flatpak | scripts/flatpak-sources.sh, then flatpak-builder (the org.flatpak.Builder app) on GNOME 49 with rust-stable 25.08, and flatpak build-bundle. 1 min 22 s with warm sources. |
oscyl-0.4.0-unsigned.apk, .aab | ./gradlew -PreleaseBuild=true :androidApp:assembleRelease :androidApp:bundleRelease, 1 min 7 s. aapt2 reads versionName='0.4.0'. After the version scheme was settled, a rebuild reads versionCode='40099'. There is no en-XA pseudo-locale. |
oscyl-0.4.0.tar.gz | git archive --prefix=oscyl-0.4.0/. Its Cargo.toml says 0.4.0. |
SHA256SUMS | sha256sum -- * over the five files. sha256sum -c passes. |
The checks passed: scripts/release-check.sh 0.4.0 says that the versions
and the changelog agree, scripts/release-notes.sh 0.4.0 prints the
section, and appstreamcli validate --no-net passes the metainfo.
The dry run did not cover:
- the
aarch64-unknown-linux-gnucommand line, which the workflow builds on an ARM runner; - Android signing, because it used no keystore;
- the attestations;
- the draft release itself.
Only the release workflow runs those.
Repository layout
The top-level folders and files of the repository, and what each one holds. A tour of the code says how the crates work together.
Crates
| Path | What it holds |
|---|---|
crates/oscyl-driver | The driver contract, the shared SysEx helpers and the request engine. |
crates/drivers/ | One crate for each synth model: its protocol, program model, files and simulator. Also logue, which the KORG logue drivers share, and tutorial-synth, the driver of the tutorial “Your first driver”. |
crates/oscyl-conformance | The checks that every driver must pass. |
crates/oscyl-core | The .oscyllib library format, and the parts of Generate that no driver owns. |
crates/oscyl-midi | The transports (midir on the desktop, or bytes that the platform moves) and DRIVERS, the drivers that the apps know. |
crates/oscyl-app | The app logic that every app shares: documents, libraries, settings, the synth worker, the editor, Generate, translations. |
crates/oscyl-ffi | The UniFFI bindings over oscyl-app, for the mobile apps. |
crates/oscyl-cli | The command line tool, oscyl. |
crates/oscyl-osc-host | Tests of the oscillator unit: its C, compiled for the computer. |
Apps
| Path | What it holds |
|---|---|
apps/linux | The desktop app (oscyl-gtk), for Linux, Windows and macOS. Its desktop entry, AppStream metadata, icons and fonts are in apps/linux/data/. |
apps/mobile/shared | The mobile apps’ UI and the bindings, in common Kotlin. |
apps/mobile/androidApp | The Android entry, USB-MIDI and the manifest. |
apps/mobile/iosApp | The Xcode project of the iOS app. |
apps/mobile/iosPlatform | The iOS platform code that needs no Rust core: CoreMIDI, files, haptics, storage and language. |
apps/mobile/baselineprofile | The Baseline Profile generator and the frame benchmarks. |
Everything else
| Path | What it holds |
|---|---|
units/oscyl-osc | The oscillator unit: its C source, KORG’s logue SDK files and the prebuilt payloads. |
docs/ | This book. docs/images/ holds the pictures of the README and the website. |
site/ | The website’s landing page. |
design/tokens.json | The design tokens: every colour, shape, spacing and motion value of both apps. |
DESIGN.md | The design system. |
po/ | The gettext translations. |
packaging/ | The Flatpak manifest, the bundle scripts for Windows and macOS, and the install notes. |
scripts/ | The local checks (ci.sh) and the build, release and asset scripts. |
fuzz/ | The fuzz targets of the parsers. |
.github/ | The workflows, the issue forms, the pull request template and the Vale styles. |
.vale.ini, lychee.toml | The settings of the prose check and of the link check. |
_typos.toml, deny.toml, about.toml | The settings of the spelling check, of cargo-deny and of cargo-about. |
Architecture
Oscyl is a set of Rust crates with thin apps around them. This page explains how the parts divide the work, and why. A tour of the code names the parts, and Repository layout lists the folders.
Generic code and synth code
Oscyl splits its code in two: what is the same for every synth, and what belongs to one synth.
- The same for every synth: the library, sync, auditions, the editor’s
drawing, Generate’s hands, the files on disk. This code is in
oscyl-core,oscyl-appand the apps. - One synth’s: its protocol, the meaning of its program bytes, its file formats, its quirks, and how its editor pages look. This code is in its driver.
The two meet in the driver contract, the traits of oscyl-driver. Generic
code sees a driver only as &dyn Driver. It never asks which synth it has:
a driver declares what its synth can do (Capabilities), and the apps show
only that. So a new driver gets every feature of every app, and no app
changes for it.
Why drivers are compiled in
A driver is a crate in this repository, compiled into each app. Oscyl has no plugins that load at run time. ADR 0002 records the decision. These are the reasons:
- A driver writes to a synth’s memory. Oscyl must trust it, and CI tests every driver on every commit.
- iOS does not let an app load code at run time, and every app shares the same drivers.
- The contract is young. When it changes, every driver changes in the same
commit, so
mainalways builds (ADR 0001).
A driver outside this repository is not supported yet. That can change when the contract crate is published and stable.
Sans IO
A driver’s session and simulator never touch a port, a thread or a clock. The session takes bytes and the time from its caller, and gives back bytes to send and events. This is sans-IO code.
Sans IO has three uses:
- The same session runs on Linux, macOS and Windows (through midir), on Android and iOS (where the platform moves the bytes), and in tests.
- A test runs a session against its simulator on a virtual clock. Time jumps to the next deadline, so a lost reply times out at once, and no test sleeps.
- The conformance suite can run every driver through the same checks, faults and all, in milliseconds.
Nothing in Oscyl waits for a fixed time. A step ends on the synth’s reply,
or on a timeout that only finds a dead link. The worker thread of
oscyl-app sleeps until a synth sends bytes, a command comes, or the
earliest deadline of a session passes.
The request engine
Most synths answer one request at a time, and their replies often do not
say which request they answer. So oscyl_driver::engine runs a protocol
with one request in flight:
- A driver’s
Protocolexpands each operation into steps. A step is a message to send and the reply that completes it. - The engine sends one step, and waits.
- Each complete SysEx message from the synth goes to the protocol, which says whether it completes the step, fails it, or is unrelated.
- The first failure, or a timeout, ends the operation. The engine does not send the rest of its steps.
- The engine reports progress after each step, then
DoneorFailed.
An unrelated message is common: a port that echoes Oscyl’s own output, or a dump that someone sends from the synth’s panel. The engine ignores it and keeps waiting, so neither can complete a write by accident.
Safe writes
A write changes the only copy of someone’s sounds. These rules keep it safe:
- A write is done only when the synth says so. If the synth sends no completion signal, the driver reads the slot back and compares it. The conformance suite checks, with every known fault, that no write reports a false success.
- A backup comes first. Sync backs up the slots that it will change, and
writes nothing if the backup fails.
oscyl restorebacks up the whole synth first. - Factory slots are never written. A bank says whether it is writable, and a session refuses a write to a factory slot before it sends anything.
- The driver plans the commit. A KORG logue synth saves its flash memory later than it answers. Its driver pads each batch so that the last write forces the save before the synth answers. Then the next read is safe at once, with no timing involved.
What runs where
| Platform | App | Synth link |
|---|---|---|
| Linux | The GTK app (apps/linux) on oscyl-app | oscyl-midi with midir on ALSA, with hotplug |
| macOS | The same GTK app | midir on CoreMIDI; synths plugged in at start connect, later ones need Connect |
| Windows | The same GTK app | midir on WinMM; synths plugged in at start connect, later ones need Connect |
| Android | The Compose app (apps/mobile), on oscyl-app through oscyl-ffi | Android’s MidiManager moves the bytes |
| iOS | The same Compose app | CoreMIDI, in the app’s own code, moves the bytes |
| Every desktop | The command line, oscyl-cli | oscyl-midi with midir, one operation at a time |
On every platform, the same oscyl_midi::Device holds a driver’s session
and a link. Only the link differs: a midir port, bytes that the platform
pushes, or a simulator.
Further reading
- What happens when you plug in a synth: the same design, from the user’s side.
- The driver contract: every method.
- Decision records: the decisions behind this page.
The oscillator unit
The KORG minilogue xd and prologue load user oscillators: small programs, made with KORG’s logue SDK, that the synth plays in its Multi Engine. A user oscillator is normally C code, built with an ARM compiler for one synth. Oscyl makes new user oscillators on a phone, with no compiler. This page explains how, and why the oscillator unit lives in this repository.
One prebuilt unit, many oscillators
Oscyl has one logue SDK oscillator of its own, the oscillator unit, in
units/oscyl-osc.
Its C holds a fixed set of DSP blocks. Some make a sound: wavetables, FM,
a supersaw, a sub oscillator and noise. Others shape it: phase distortion,
sync, a wavefolder, a bit crusher, a low-pass filter and formant filters.
The unit is built once for each synth. The builds are in the repository, as
payload/minilogue-xd.bin and payload/prologue.bin.
The blocks do nothing on their own. A patch wires them up. A patch is data, and it says:
- which blocks run, in what order, and with which constants;
- what Shape, Shift-Shape, an LFO, an envelope and the six parameters move;
- up to eight single-cycle tables.
The unit keeps a marked region of 4,608 bytes for the patch. It reads the patch from there when the synth starts the unit. As built, the region holds only its marker, and the unit plays a plain saw.
To make a new oscillator, Oscyl writes a patch into a copy of the payload.
Then it adds a manifest: the oscillator’s name, its parameters and an id of
its own. The result is an ordinary unit file, .mnlgxdunit or
.prlgunit. The synth loads it like any other user oscillator, into a free
oscillator slot.
So the sound is data, and every app can make it. The desktop app, the
phone apps and oscyl units make all use the same Rust code,
oscyl_logue::osc.
It makes patches in six families: wavetable, FM, fold, formant, noise and
hybrid. It varies and crosses them as Generate does with programs.
An extra, not a requirement
The oscillator unit is optional. Oscyl puts one on the synth only when you keep a new oscillator, and only into an empty oscillator slot. The librarian, the editor and Generate’s sounds all work without it, and the Prophet Rev2 has no user units at all.
How Oscyl knows what a patch sounds like
Oscyl draws one cycle of each new oscillator’s wave, and checks that no
patch is silent or too loud. For this, oscyl_logue::osc::render runs the
unit’s DSP in Rust, operation for operation.
A Rust copy of C code can drift from the C. So the test crate
oscyl-osc-host compiles the unit’s C for the computer, and its tests hold
the two together:
- every family’s oscillators make a sound, do not clip, and carry no DC offset (a constant shift of the whole wave);
- the Rust port plays what the C plays;
- a bad or empty patch plays a plain saw;
- the committed payloads come from the sources as they are. The file
payload/SOURCEholds the checksum of the sources and ofscripts/build-units.sh, and a test compares it.
Why it lives in this repository
The unit, its patch format and its Rust code change together. A new block needs C, a Rust port, a patch field and new tests, in one commit. The KORG drivers load the unit’s payloads, so the unit stays beside them. ADR 0001 gives the same reason for the whole repository: a change and everything that it affects land together.
scripts/build-units.sh rebuilds the payloads, with
arm-none-eabi-gcc. A new payload must be checked on the synths before a
release, so nobody builds them again without a reason.
What it is not
- Not a synth engine on your computer. The unit runs on the synth. Oscyl’s apps make no sound.
- Not a target platform. It is one oscillator for two KORG synths. It is not a third kind of synth next to them, and not a place to run other engines.
- Not a converter. It does not turn a program of one synth into a sound of another.
The oscillator unit has not yet been heard on a real synth. Testers with a minilogue xd or a prologue are welcome.
Mobile smoothness
The mobile app must feel smooth on a phone: a drag follows the finger, and a page change never stutters. This page records what was measured, what was slow, and what changed, in order. To measure, follow Judge smoothness.
The rules that came out of it
- Judge smoothness only on the release-like build. A debug build runs Compose without optimisation and is several times slower.
- Never use
Modifier.dropShadoworinnerShadow: they blur on the CPU for each new size. UsesoftShadow. - Nothing that animates changes a layout size in each frame. Move or scale a layer instead.
- What a transition shows stays composed under it, so a transition composes nothing new.
- A control that becomes edited moves nothing: it keeps its space, or draws in place.
- A fade of a large part fades stroke by stroke
(
CompositingStrategy.ModulateAlpha), not through an offscreen copy. - A class that every item of a list gets must compare by value.
Editor drag performance (2026-11-13)
The plan’s target was an editor drag at p90 16 ms or less, on a release build. The measurement used:
dumpsys gfxinfo;- a release build (
-PreleaseBuild=true) on the Pixel_10_b emulator (gfxstream, host GPU); - a drag of Cutoff in its middle range, so the filter graph drew again in every frame.
Three runs of about 220 frames each gave:
- p50 21 to 22 ms, p90 27 ms, p95 27 to 28 ms;
- GPU p90 23 ms;
- 0 to 2 slow frames on the UI thread in each run.
The UI thread’s work was done. The graph keeps its paths, dashes and strokes from frame to frame, and an edit asks the core once.
Smoothness run (2026-11-13)
A release build on the same emulator, with the frame statistics of dumpsys gfxinfo for each gesture, warm (after the first pass):
| Gesture | p50 | p90 | p95 | Slow UI-thread frames | GPU p90 |
|---|---|---|---|---|---|
| 500-slot list, flings both ways | 16 ms | 16 ms | 16 ms | 0 of 118 to 294 | 14 ms |
| Editor drag (Cutoff, middle range) | 22 to 24 ms | 27 to 28 ms | 27 to 30 ms | 0 to 1 of about 220 | 23 ms |
| Stage-rail scrub (hold, then drag through every stage and back) | 21 ms | 25 to 31 ms | 32 ms | 3 to 4 of about 410 | 19 to 21 ms |
- The list was smooth. Its first, cold pass composed new rows and was slower: 20 slow UI frames of 75. So each row’s words are now looked up once for the list, not once for each row.
- The editor’s drag and scrub were bound by the GPU. The p90 was above the target because the GPU took the rest of the frame. This was the emulator’s GPU, so the numbers do not stand for a phone. The owner decides on any new target, after a measurement on a real device.
The redesign, on real phones (2026-11-13)
The owner measured the phone-first redesign on a Pixel 7 Pro (120 Hz) and a
Pixel 2 XL (60 Hz). The tool was dumpsys gfxinfo over adb, for each
journey.
These were debug builds: debuggable, no R8 and no Baseline Profile. They
were installed beside the owner’s own Oscyl, as io.github.oscyl.redesign.
Debug Compose runs several times slower than release, so these numbers are
an upper bound.
| Journey | Pixel 7 Pro p50 / p90 / p95 | Pixel 2 XL p50 / p90 / p95 |
|---|---|---|
| Editor scroll (6 flings) | 10 / 22 / 26 ms | 12 / 36 / 109 ms |
| Knob drag (slow and fast, up and down) | 9 / 13 / 14 ms | 24 / 34 / 40 ms |
| Destination switch (5 switches) | 6 / 11 / 17 ms | 8 / 21 / 30 ms |
| Graph grow and Back (3 times) | 10 / 25 / 40 ms | 32 / 53 / 73 ms |
The design’s targets are p95 8.3 ms on the 7 Pro and 16.7 ms on the 2 XL. They are for a release build with R8 full mode and Baseline Profiles. On the debug build, the slowest spots were the knob drag on the 2 XL and the graph’s first growth. During a knob drag, each value composed the field and its section again. At the graph’s first growth, the full-screen page composed its pager and its controls sheet.
A screen recording of the destination switch (adb shell screenrecord),
read frame by frame, showed this. The old page fades out, the ground shows
for a few frames, and the new page fades in. No frame mixes the two pages
or flashes.
The redesign, release-like (2026-11-13)
The benchmark build (R8, with the shipped Baseline Profile) installs as
io.github.oscyl.bench. The :baselineprofile module holds the profile
generator and the frame benchmarks. FrameTimingMetric,
frameDurationCpuMs p50 / p90 / p95 in ms, 5 iterations; the 2 XL’s knob,
graph and scroll rows are later runs of 2 iterations:
| Journey | Pixel 7 Pro (120 Hz, target p95 8.3) | Pixel 2 XL (60 Hz, target p95 16.7) |
|---|---|---|
| Editor scroll | 4.4 / 6.0 / 6.7 | 7.7 / 27.6 / 28.2 |
| Program list scroll | – | 4.4 / 8.8 / 9.5 |
| Knob drag | 6.2 / 9.9 / 10.7 | 12.7 / 27.3 / 27.8 |
| Graph grow and back | 7.3 / 14.4 / 15.4 | 26.0 / 62.4 / 73.3 |
| Destination switch | 2.6 / 6.7 / 11.2 | 7.9 / 17.1 / 20.7 |
| Synth sheet | 4.9 / 6.2 / 6.9 | 11.0 / 12.5 / 14.0 |
On the 7 Pro, the frame overrun’s p95 was negative (on time) for the scroll, the knob and the sheet. On the 2 XL the render thread set the pace. It spent 9 to 13 ms of GPU command flush on each full-screen frame of its QHD+ panel. Still above the target: the graph’s growth and return, the 2 XL’s knob and scroll, and the destination switch.
Smoothness pass
atrace and simpleperf record --app on the 2 XL found what was slow:
- Blurred shadows on the UI thread.
Modifier.dropShadowblurs a mask on the CPU again for every new size. A growing rail, a dragged sheet or a sliding plate cost 35 to 57 ms a frame. Every shadow is nowsoftShadow(ui/parts/SoftShadow.kt): gradients that the GPU shades at any size. - Panels composed inside a frame. A fling, a rail jump or the way back
from the full-screen graph composed whole sections of knobs, for 15 to
190 ms. The editor’s list now keeps the program composed around the page
(
LazyLayoutCacheWindow), and fills it in idle time. The list stays composed under the full-screen graph, and the graph’s page stays composed (hidden) under the list. - The graph’s growth measured and drew the picture again at every size.
It is now a transform of the page’s picture on its layer (
PortraitinEditorScreen.kt). The page’s ground and header fade, and its sheet rises. - The controls sheet changed its height in each frame. It now slides by translation. It rises under a drag anywhere on it, before its list scrolls. It lowers from the list’s top, on a tap on the picture, or on Back.
- Each knob step asked the core for the head and for five written values. Now the head is asked once for each gesture, and a turning knob’s values are written once for each turn.
- Layout jumps. “was N” is now in the foot of the knob’s scale. A selector’s “was X” is at the end of its legend’s row. Nothing moves when a control becomes edited, and no empty line waits under a selector.
Refreshes missed, out of frames shown, on the Pixel 2 XL (60 Hz), on the same journeys, before and after. The graph journey opens and closes the full-screen graph three times.
| Journey | Before | After |
|---|---|---|
| Graph grow and back | 30 / 102 | 1 to 4 / 99 |
| Editor scroll | 2 to 7 / 127 | 1 to 3 / 127 |
| Knob drag | 0 to 5 / 127 | 0 to 2 / 127 |
| Stage rail, held and scrubbed | 4 to 6 / 127 | 0 to 1 / 127 |
On the Pixel 7 Pro (120 Hz), the graph journey had frames of up to 83 ms before. After, it missed 1 or 2 refreshes of 58. The knob and the rail missed none. Its scroll figure does not compare: the panel changes its refresh rate while the page moves.
Second pass (2026-11-14)
This pass used simpleperf record --app ... -g --trace-offcpu --clockid monotonic, with the samples cut to the slow frames of dumpsys gfxinfo framestats, so blocked time counts too.
- The profile was never compiled in.
cmd package compile -m speed-profileonly uses a profile that the app’s installer wrote. Just afteradb installthere is none, so the app ran interpreted.scripts/mobile-phone.shnow broadcastsandroidx.profileinstaller.action.INSTALL_PROFILEfirst, and fails if the app refuses it. Numbers from before this date are of an interpreted app. - The Baseline Profile is older than the redesign. It has no rule for
ScrollPeek,DockedSheet,SoftShadoworSheetLayer, so that code runs interpreted until the JIT compiles it. Generate the profile again before a release. - A fade through an offscreen copy.
graphicsLayer { alpha }below 1 makes a copy as large as what fades, in the first frame of the motion. That cost the render thread 30 ms or more in three places. One was the start of a scroll (the island’s dim). One was each destination switch (two whole screens). One was the graph page’s entry. Those layers now fade stroke by stroke (CompositingStrategy.ModulateAlpha). - A synth’s read in one go. The demo synth answers 500 slots at once, and the model took them all in one turn of the main loop. It now takes them in slices of 4 ms.
- Work for a list that nobody looked at. Each knob release changed the document’s revision. Then every row of the program list, composed under the editor, asked the core for its picture again. The list’s menu asked for the whole history. Now the pictures of untouched rows stay across an editor change, and the menu reads the history when it opens.
RowWordshad noequals. So every recomposition of the program list composed every row again.- The graph page’s sheet now composes its neighbours’ knobs one section for each frame while the pager rests, and keeps them measured. A swipe’s change at the halfway point composes nothing.
Refreshes missed, out of frames shown, on the Pixel 2 XL, with the profile compiled in both runs and the app warm:
| Journey | Before | After |
|---|---|---|
| Program list fling | 4 to 7 / 127 | 0 to 3 / 127 |
| Editor scroll | 3 to 5 / 127 | 0 to 1 / 127 (one pass of 4 and 5 just after an install) |
| Knob drag | 4 to 6 / 127 | 0 to 3 / 127 |
| Destination switch | 2 / 121 warm, 5 to 12 from a fresh start | 2 / 120 warm, 4 to 5 from a fresh start |
| Graph grow and back | 5 / 68 | 4 to 5 / 93 (the render thread’s first frame of each growth) |
Passes differ by a few refreshes on this phone, but the slow frames named above are gone in every pass. Two remain. One render-thread frame of 20 to 30 ms comes as the graph’s page first draws. Two frames of 20 to 40 ms come as a destination comes back, because its tree is placed and drawn again. The motion waits for them, so nothing stutters, but the tap answers late.
The design system
Oscyl’s apps share one look, which the design system calls “Ulm Hi-Fi”.
The apps look like 1960s audio equipment from the Ulm school of design. The
full design system is
DESIGN.md, at the
root of the repository. This page explains its main ideas, and where its
values come from.
The ideas
- Less, but every widget exact. Grey or anthracite enamel, fine printed legends, 1 px rules and small soft corners. Colour only ever means a function.
- Two function colours. Green means connected, synced or live. Orange means edited, or waiting to be written. Everything else is grey, and every coloured mark also has a shape and a word.
- Selection is a plate. A selected segment, stage tab or tile becomes a solid plate, in the opposite tone of the ground, with its own text colour.
- The editor is a compare bench. Every control keeps the saved sound on its face, so an edit reads as a distance from the saved value. Hold to compare plays the saved program, on the screen and on the synth.
- One design language. The desktop app and the phone apps use the same parts for the same jobs: the same dials, stage tabs, graphs and review of changes.
Where the values come from
Every colour, shape, spacing and motion value is in one file,
design/tokens.json.
- The desktop app’s build (
apps/linux/build.rs) makes its light, dark and AMOLED stylesheets from the tokens, as--oscyl-<role>custom properties. - The mobile apps generate their colours, shapes and motion from the same
file, as
OscylTokens.kt. - The iOS launch colours come from it too, through
scripts/mobile-assets.sh.
When DESIGN.md and tokens.json disagree, tokens.json wins. Change a
value in the tokens, never in a stylesheet.
Why one system
A user moves between the phone and the computer. When the same control looks and acts the same on both, nothing must be learned twice. And a contributor who changes a part on one app knows what the other app must match.
Architecture decision records
An ADR records one architecture decision that has been made: the context, the decision, and its consequences. Unlike an RFC, which proposes a change, an ADR is the short record left after the decision.
Files are numbered in order (0001-short-title.md) and are not edited
afterwards except to mark them Superseded by a later ADR.
| ADR | Decision |
|---|---|
| 0001 | One repository for the core, every driver and every app |
| 0002 | Drivers are compiled-in crates behind an object-safe contract, proven by conformance against simulators, with a native library format |
ADR 0001: Monorepo
- Status: Accepted
- Date: 2026-11-12
Context
Oscyl is growing from a minilogue xd tool into a companion for several synths. Each synth gets a driver; the core, the conformance suite, the transports, the CLI and the apps all depend on the driver contract. The contract will change often while the second and third drivers are written.
Decision
Keep everything in one repository and one Cargo workspace: the contract
(crates/oscyl-driver), the core, the conformance suite, the transports,
the CLI, every driver under crates/drivers/, and the apps under apps/.
Consequences
- A contract change and the fixes in every driver land in one commit, so
mainalways builds and passes conformance. - CI runs the conformance suite for every driver on every commit.
- Driver maintainers own their paths through
CODEOWNERSinstead of owning separate repositories. - Third-party drivers outside the repository are not supported for now; they can come later, once the contract crate is published and stable.
ADR 0002: Driver contract, conformance and native library format
- Status: Accepted
- Date: 2026-11-12
Context
Supporting several synths needs a clear line between what is generic (the library, sync, audition, the editor’s rendering) and what is specific to one synth (protocol, program bytes, quirks). It also needs a way to trust a driver without owning the hardware, and a library file that is not tied to one vendor’s format.
Decision
- Drivers are compiled-in crates behind an object-safe contract. Each
driver is a crate under
crates/drivers/that implements the traits inoscyl-driverand exposes a staticDRIVER. Apps and the core use drivers only as&dyn Driver, so they can pick one at run time (from a connected synth’s identity, or from a library’s driver id) with no synth-specific code. There are no dynamic plugins. - Capabilities are declared, not assumed. A driver describes its identity, capabilities, field schema, curation, protocol, commit planning and file formats as data; the apps read capabilities and assume nothing else.
- Drivers are proven against simulators. Every driver ships a sans-IO
simulator, with fault injection for faults known on the hardware. The
oscyl-conformancesuite runs the same checks against every driver’s simulator in CI. Hardware tests stay#[ignore]d and back the Tier 1 release validation (see GOVERNANCE.md). - Libraries use a native format,
.oscyllib. It records which driver a library belongs to and stores programs as the driver’s own bytes. Vendor library and program files are import and export formats handled losslessly by each driver. The format is described in oscyllib-format.md.
Consequences
- Any change to the contract needs an RFC and updates every driver in the same change.
- A driver without a simulator, or one that fails conformance, is not accepted.
- Libraries written by older versions are migrated to
.oscyllibautomatically, keeping the originals. - The contract crate is versioned with SemVer and will be published to crates.io once the project is public.
RFCs
An RFC (request for comments) is a short design document for a change that affects more than one part of Oscyl. GOVERNANCE.md says when one is required: any change to the driver contract, any change that touches more than one driver or what every driver must provide, and any change to the native library format.
Process
- Copy
0000-template.mdto0000-short-title.mdand fill it in. - Open a pull request that adds only the RFC. Discussion happens there.
- When the pull request is opened, rename the file to use the pull request
number, for example
0042-patch-kinds.md. - A core maintainer accepts the RFC by merging it with its status set to Accepted, or closes the pull request with the reasons written down. Driver maintainers of affected drivers are asked to review first.
- Implementation follows in separate pull requests that link the RFC. A
contract change and the fixes in every driver land together, in one pull
request, so
mainalways passes conformance.
An accepted RFC that turns out to be wrong is changed by a new RFC, which marks the old one Superseded.
RFC 0000: Title
- Status: Draft (Draft, Accepted, Rejected, Superseded by RFC NNNN)
- Author:
- Pull request:
- Affected drivers: all / list
Summary
One paragraph: what changes.
Motivation
What problem this solves, and for which synths or users.
Design
The change in enough detail to implement it: new or changed contract types and methods, format changes, conformance checks. Show the API shape.
Impact on drivers
What every existing driver must change, and how the conformance suite checks the new behaviour.
Compatibility
Is this a breaking change to the contract crate (a SemVer major bump)? Does
it change the .oscyllib format, and how do existing libraries migrate?
Alternatives
Other designs considered and why they were not chosen.
Open questions
What is still undecided.