Home

Awesome

Rust-LV2

Build Status Current Crates.io Version

A safe, fast, and ergonomic framework to create LV2 plugins for audio processing, written in Rust.

This library is a work in progress.

It provides the following features, through the LV2 Core specification:

Through the LV2 official additional specifications, this library also provides many additional features, including:

Note that this library will only provide Rust bindings for the official LV2 specifications, however it is compatible with any other arbitrary or custom specification, and other, external crates are able and welcome to provide Rust bindings to any other specification that will integrate with this library.

Example

This example contains the code of a simple amplification plugin. Please note that this isn't the only thing required to create a plugin, see the documentation below for more details.

// Import everything we need.
use lv2::prelude::*;

// The input and output ports are defined by a struct which implements the `PortCollection` trait.
// In this case, there is an input control port for the gain of the amplification, an input audio
// port and an output audio port.
#[derive(PortCollection)]
struct Ports {
    gain: InputPort<Control>,
    input: InputPort<Audio>,
    output: OutputPort<Audio>,
}

// The plugin struct. In this case, we don't need any data and therefore, this struct is empty.
//
// LV2 uses URIs to identify types. This association is expressed via the `UriBound` trait,
// which tells the framework that the type `Amp` is identified by the given URI. The usual
// way to implement this trait is to use the `uri` attribute.
#[uri("urn:rust-lv2-book:eg-amp-rs")]
struct Amp;

// The implementation of the `Plugin` trait, which turns `Amp` into a plugin.
impl Plugin for Amp {
    // Tell the framework which ports this plugin has.
    type Ports = Ports;

    // We don't need any special host features; We can leave them out.
    type InitFeatures = ();
    type AudioFeatures = ();

    // Create a new instance of the plugin; Trivial in this case.
    fn new(_plugin_info: &PluginInfo, _features: &mut ()) -> Option<Self> {
        Some(Self)
    }

    // Process a chunk of audio. The audio ports are dereferenced to slices, which the plugin
    // iterates over.
    fn run(&mut self, ports: &mut Ports, _features: &mut ()) {
        let coef = if *(ports.gain) > -90.0 {
            10.0_f32.powf(*(ports.gain) * 0.05)
        } else {
            0.0
        };

        for (in_frame, out_frame) in Iterator::zip(ports.input.iter(), ports.output.iter_mut()) {
            *out_frame = in_frame * coef;
        }
    }
}

// Generate the plugin descriptor function which exports the plugin to the outside world.
lv2_descriptors!(Amp);

About this framework

Q&A

Does my host program support it?

Plugins created with rust-lv2 are compatible to all LV2 hosts that comply to the specifications. If your application uses lilv, it's a good sign that it will support your plugin. Some prime examples are Carla and Ardour.

Can I host plugins with rust-lv2?

Currently, hosting plugins is not supported. This project was initialy started to create plugins using safe Rust and therefore, it is very plugin-centric. There are plans for integrated plugin hosting or a spin-off project, but those won't start in the near future.

However, there is a lot of code that can be re-used for a hosting framework. If you want to create such a framework, you should take a look at lv2-sys, urid, and lv2-atom.

A bare hosting framework would require an RDF triple store which can load Turtle files, an internal store for plugin interfaces and their extensions, a centralized URID map store, and a graph based work scheduling system to execute run functions in order.

Documentation

There are multiple valuable sources of documentation:

Features

Internally, this framework is built of several sub-crates which are re-exported by the lv2 crate. All dependencies are optional and can be enabled via features. These are:

Sub-crates with an lv2- prefix implement a certain LV2 specification, which can be looked up in the reference. Enabling a crate only adds new content, it does not remove or break others.

There are also feature sets that account for common scenarios:

Supported targets

Rust-LV2 uses pregenerated C API bindings for different targets in order to increase usability and building speed. Rust has a lot of supported targets, but our maintaining power is limited and therefore, only certain targets can be supported. We've ranked different targets in Tiers, just like rustc does, which gives you a general understanding of what to expect of a target. The tables below list the supported targets, the used binding in the lv2-sys crate, and, if applicable, the maintainer and the last verification of that target.

The bindings itself are generated with the LV2 systool and verified by building the example plugins of the book and testing them with a host of that target.

Tier 1

A Tier 1 target for rust-lv2 also has to be a Tier 1 target of rustc. You can check the platform support page to see which targets are included and what they provide. Additionally, there has to be a maintainer of rust-lv2 who has access to a machine that runs this target and who can generate and verify bindings on this machine. This means that if you have a problem running your code on a Tier 1 target, there will be a maintainer who can help you.

TargetBindingMaintainerLast Verification
x86_64-unknown-linux-gnulinux/x86_64.rs@Janonard10. of May 2020, using Carla v2.1, running on Arch Linux
x86-unknown-linux-gnulinux/x86.rs@Janonard16th of May 2020, using Carla v2.1, running on Linux Mint 19.3 32-bit

Tier 2

A Tier 2 target is a target that is at least in Tier 2 of rustc and has a generated binding. However, it might not work (well) and there might not be a maintainer who has access to a machine that runs this target and who can generate and verify bindings on this machine. This means that if you have a problem running your code on a Tier 2 target, you're stepping into uncharted territory.

TargetBinding
aarch64-unknown-linux-gnuaarch64.rs
arm-unknown-linux-gnueabiarm.rs
arm-unknown-linux-gnueabihfarm.rs
armv5te-unknown-linux-gnueabiarm.rs
armv7-unknown-linux-gnueabiarm.rs
armv7-unknown-linux-gnueabihfarm.rs
thumbv7neon-unknown-linux-gnueabihfarm.rs
x86_64-pc-windows-msvcwindows.rs

License

Licensed under either of

at your option.