Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

PartWhat it does
crates/oscyl-driverThe 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-conformanceThe checks that every driver passes against its simulator.
crates/oscyl-coreThe .oscyllib library format, and the parts of Generate that no driver owns.
crates/oscyl-midiThe 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-appThe 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-cliThe command line tool, oscyl.
crates/oscyl-ffiThe bindings that give oscyl-app to the mobile apps, through UniFFI.
crates/oscyl-osc-hostA test crate. It compiles the oscillator unit’s C for the computer, so tests can hear a patch. Nothing ships it.
apps/linuxThe desktop app (GTK 4 and libadwaita), for Linux, Windows and macOS.
apps/mobileThe Android and iOS apps (Compose Multiplatform).
units/oscyl-oscThe 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.

  1. The app asks the worker thread in oscyl_app::synth to read every slot.
  2. The worker gives the operation to the synth’s oscyl_midi::Device. The device holds the driver’s session and the MIDI port.
  3. The session turns “read slot 5” into a SysEx request. The request engine sends it and waits for the answer.
  4. The synth answers with a program dump. The device gives the bytes to the session, which collects one whole SysEx message.
  5. The session checks that the message answers slot 5. It reports SessionEvent::Program(5, bytes).
  6. The worker sends the program to the app. The app puts it in the synth’s document, a list of programs with undo.
  7. The editor reads each value with Driver::get and its text with Driver::format_value. The driver’s curation says 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

To build and run each app, read Build and run.