1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
//! A safe, fast, and ergonomic Rust framework to create [LV2 plugins](http://lv2plug.in/) for audio processing or synthesis.
//!
//! **This library is a work in progress.**
//!
//! It provides the following features, through the [LV2 Core specification](http://lv2plug.in/ns/lv2core/lv2core.html):
//!
//! * Lightweight, realtime non-blocking and allocation-free audio processing.
//! * Generates all the boilerplate to make a LV2 plugin binary, usable by any LV2 host.
//! * Any number of ports / Any channel mapping, which can be different for input and output.
//! This obviously includes Mono, Stereo, Surround, etc., anything your CPU can handle.
//! * Can be extended to support any additional features, extensions and port types.
//! They can be official, unofficial or completely custom.
//!
//! Through the [LV2 official additional specifications](http://lv2plug.in/ns/), this library also provide many
//! additional features, including:
//!
//! * MIDI processing
//! * Serialization of custom data structures, and plugin-plugin or plugin-GUI communication and property manipulation
//! * State management
//! * Asynchronous work processing
//! * Custom Graphical User Interfaces, both in a toolkit-agnostic and in a platform-agnostic way **(Not yet implemented)**
//! * Presets handling **(Not yet implemented)**
//! * ... and more! (Not yet implemented either)
//!
//! 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
//!
//! A simple amplification plugin would like this:
//!
//! ```
//! // 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 (), _: u32) {
//! 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;
//! }
//! }
//! }
//! ```
//!
//! # Using this framework
//!
//! ## Documentation
//!
//! There are multiple valuable sources of documentation:
//! * ["The Rust-LV2 book"](https://rustaudio.github.io/rust-lv2/) describes how to use Rust-LV2 in general, broad terms. It's the ideal point to get started and is updated with every new version of Rust-LV2.
//! * [The API documentation](https://docs.rs/lv2).
//! * [The LV2 specification reference](https://lv2plug.in/ns/).
//!
//! ## 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:
//!
//! * `lv2-atom`: General data IO.
//! * `lv2-core`: Implementation of the core LV2 specification.
//! * `lv2-midi`: MIDI message extension for `lv2-midi`. Support for the [`wmidi` crate](https://crates.io/crates/wmidi) can be enabled with the `wmidi` feature.
//! * `lv2-state`: Extension for LV2 plugins to store their state.
//! * `lv2-time`: Specification to describe position in time and passage of time, in both real and musical terms.
//! * `lv2-units`: Measuring unit definitions.
//! * `lv2-urid`: LV2 integration of the URID concept.
//! * `lv2-worker`: Work scheduling library that allows real-time capable LV2 plugins to execute non-real-time actions.
//! * `urid`: Idiomatic URID support.
//!
//! Sub-crates with an `lv2-` prefix implement a certain LV2 specification, which can be looked up in [the reference](https://lv2plug.in/ns/). Enabling a crate only adds new content, it does not remove or break others.
//!
//! There are also feature sets that account for common scenarios:
//! * `minimal_plugin`: The bare minimum to create plugins. Includes `lv2-core` and `urid`.
//! * `plugin`: Usual crates for standard plugins. Includes `lv2-core`, `lv2-atom`, `lv2-midi` with the `wmidi` feature, `lv2-units`, `lv2-urid`, and `urid`. **This is the default.**
//! * `full`: All sub-crates.
//!
//! # Extending
//!
//! Please note that this re-export crate is only meant to be used by plugin projects. If you want to extend the framework with your own crates, please use the sub-crates as your dependencies instead. This will dramatically boost building durations and backwards compability.
/// The super-prelude that contains the preludes of all enabled crates.
pub extern crate lv2_atom;
pub extern crate lv2_core;
pub extern crate lv2_midi;
pub extern crate lv2_state;
pub extern crate lv2_sys;
pub extern crate lv2_time;
pub extern crate urid;
pub extern crate lv2_units;
pub extern crate lv2_urid;
pub extern crate lv2_worker;