rust-lv2

The lv2-atom crate is a library designed for reading and writing the LV2 Atom type system. This type system is used by the rust-lv2 framework to facilitate versatile and portable data exchange between plugins.

Supported data types include:

• Basic integer types
• Basic float types
• Vectors
• Event sequences
• URID -> Atom maps

The lv2-midi crate is a MIDI processing library for the rust-lv2 framework. It acts as an addon to lv2-atom by introducing the MidiEvent atom type.

If you enable the wmidi feature, the library also introduces the WMidiEvent atom type, which allows you to directly read and write MIDI events using the types defined by the wmidi crate.

The lv2-state crate provides a Rust wrapper for the LV2 State API. It allows LV2 plugins to implement functionality for saving and restoring their internal state (e.g., presets or configuration). This library is part of the broader rust-lv2 framework.

For detailed guidance on how to properly implement state management in Rust, refer to the rust-lv2 book.

The lv2-sys crate provides low-level Rust bindings to the official LV2 C API headers. It is primarily used as a dependency by the higher-level rust-lv2 framework to provide safe, ergonomic interfaces for creating LV2 audio plugins.

Key details:

• Specification Version: It implements version 1.18.0 of the LV2 specification.
• Relationship: While lv2-sys provides the raw bindings, developers looking to build plugins should use the rust-lv2 crate for a safe and idiomatic Rust experience.

The worker library is a work scheduling library designed to allow real-time capable LV2 plugins to execute non-real-time actions safely. It is a component of the rust-lv2 framework, which provides a safe and ergonomic way to create LV2 plugins in Rust.

For detailed guidance on using the framework and understanding the underlying LV2 concepts, refer to the Rust translation of "the LV2 book": https://janonard.github.io/rust-lv2-book/

The Metro plugin serves as an example of how to implement several advanced LV2 features in Rust:

1. Note Synthesis: Uses a sampled sine wave combined with an envelope to generate notes.
2. Host Synchronization: Synchronizes synthesized notes to the host's transport using the LV2 time extension.
3. Pipeline Architecture: Uses the pipes library to structure the audio processing flow.

The lv2-core-derive crate provides procedural macros specifically designed for use with the lv2-core crate. These macros assist in implementing the LV2 plugin interface in Rust by automating boilerplate code required by the LV2 specification.

For detailed guidance on how to use these macros and the underlying LV2 concepts, refer to the rust-lv2 book.

In the LV2 ecosystem, many entities are identified by URIs. To optimize performance, hosts map these URIs to numbers called URIDs (URI Identifiers).

Using URIDs instead of full URI strings provides several benefits:

• Speed: Comparing numbers is significantly faster than comparing long URI strings.
• Efficiency: URIDs save space in memory and during communication.
• Consistency: The host manages the mapping, ensuring that URIDs are consistent for host-plugin or plugin-plugin communication.

When developing plugins, you will use URIDs for efficient identification and communication within the host environment.

The Metro plugin demonstrates a modular approach to audio synthesis using the pipes library. Instead of a manual processing loop, the plugin expresses its internal processing pipeline as a chain of individual 'pipes'.

Key Concepts:

• Pipe Mechanism: A pipe is similar to an iterator but includes a next method that takes an input item to produce an output item. This allows pipes to be chained into larger, complete pipelines.
• Advantages: Slices the algorithm into well-defined, understandable pieces; provides a testable interface for individual parts of the algorithm; improves code reusability.
• Trade-offs: Requires more boilerplate code (each pipe is its own type) and may introduce function call overhead or make it harder for the compiler to apply SIMD optimizations compared to a manual implementation.

The Plugin trait is the core abstraction for defining an LV2 plugin. It requires specifying the types for ports and features, and implementing the lifecycle methods.

• type Ports: The struct defining the plugin's input/output ports.
• type InitFeatures: Defines host/plugin extensions required during initialization.
• type AudioFeatures: Defines extensions required during the audio processing loop.
• fn new(&PluginInfo, &mut Features) -> Option<Self>: The constructor for the plugin instance.
• fn run(&mut Ports, &mut Features): The real-time audio processing callback. Ports are provided as mutable references, allowing direct access to audio and control data.

In RDF-based systems, resources are identified by URIs. Because comparing strings (URIs) is slow, this library introduces the URID: a u32 that represents a URI.

Key components of the URID model include:

• UriBound trait: A trait used to associate a Rust type with a specific URI.
• Map trait: Responsible for assigning u32 URIDs to URIs.
• Unmap trait: Responsible for "dereferencing" a URID back into its original URI.
• URID<T>: A type-safe wrapper that connects a URID to its UriBound type T. This allows the compiler to prevent misuse (e.g., passing a URID for Type A into a function expecting a URID for Type B).