LV2 is an interface for writing audio processors, or plugins
, in
C/C++ which can be dynamically loaded into many applications, or hosts
.
This core
specification is simple and minimal, but is designed so that
extensions
can be defined to add more advanced features, making it
possibly to implement nearly any feature imaginable.
LV2 maintains a strong distinction between code
and data
.
Plugin code is in a shared library, while data is in a companion data file
written in Turtle.
Code, data, and any other resources (e.g. waveforms) are shipped together in a
bundle
directory. The code contains only the executable portions of the
plugin which inherently must be written in code. All other data is
provided in the data file(s). This makes plugin data flexible and extensible,
and allows the host to do everything but run the plugin without loading or
executing any code. Among other advantages, this makes hosts more robust
(broken plugins can't crash a host during discovery) and allows generic tools
and non-C programs to work with LV2 data. LV2 itself and extensions are
distributed in a similar way.
An LV2 plugin library is suitable for dynamic loading (e.g. via
dlopen()
) and provides one or more plugin descriptors via
lv2_descriptor()
or lv2_lib_descriptor()
. These can
be instantiated to create plugin instances
, which can be run directly on
data or connected together to perform advanced signal processing tasks.
Plugins communicate via ports
, which can transmit any type of data.
Data is processed by first connecting
each port to a buffer, then
repeatedly calling a plugin's run()
method to process blocks of
data.
This core specification defines two types of port, equivalent to those in LADSPA: lv2:ControlPort and lv2:AudioPort.
Audio ports contain arrays with one float
element per sample,
allowing a block of audio to be processed in a single call to
run()
. Control ports contain single float
values,
which are fixed and valid for the duration of the call to run()
.
Thus the control rate
is determined by the block size, which is
controlled by the host (and not necessarily constant).
Threading Rules
To faciliate use in multi-threaded programs, LV2 functions are partitioned into several threading classes:
Discovery Class | Instantiation Class | Audio Class |
---|---|---|
lv2_descriptor() | LV2_Descriptor::instantiate() | LV2_Descriptor::run() |
lv2_lib_descriptor() | LV2_Descriptor::cleanup() | LV2_Descriptor::connect_port() |
LV2_Descriptor::extension_data() | LV2_Descriptor::activate() | |
LV2_Descriptor::deactivate() |
The rules that hosts MUST follow are:
- When any function is running for a plugin instance, no other function in the same class may run for that instance.
- When a Discovery function is running, no other functions in the same shared object file may run.
- When an Instantiation function is running for a plugin instance, no other functions for that instance may run.
Any simultaneous calls that are not explicitly forbidden by these rules are
allowed. For example, a host may call run()
for two different
plugin instances simultaneously.
Plugin functions in any class MUST NOT manipulate any state which might affect other plugin or host code, e.g. by using non-reentrant global functions.
Extensions to this specification which add new functions MUST declare in which of these classes the functions belong, define new classes for them, or otherwise precisely describe their threading rules.