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

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

CrateUse it to
oscyl-driverUse the contract: Driver, SessionOp, SessionEvent and the other types
oscyl-midiFind and open a synth, and run operations on it. It holds DRIVERS, every driver that Oscyl has
oscyl-coreRead and write .oscyllib library files
oscyl-conformanceTest a driver against its simulator
A driver crate, such as oscyl-korg-minilogue-xdUse 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 .oscyllib format 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.