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.