- Description
- Index
- Documentation
- Releases
- Files
- lv2.h - Documentation
- lv2core.doap.ttl
- lv2core.ttl
URI | http://lv2plug.in/ns/lv2core |
---|---|
Version | 8.2 (2012-10-14) |
Prefixes | dcs doap foaf lv2 meta owl rdf rdfs xsd |
Discuss | devel@lists.lv2plug.in (subscribe) |
Developers | , |
Maintainer |
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 the
lv2_descriptor()
function. 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).
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_Descriptor::extension_data() | LV2_Descriptor::cleanup() | LV2_Descriptor::connect_port() |
LV2_Descriptor::activate() | ||
LV2_Descriptor::deactivate() |
The rules that hosts MUST follow are:
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.
Sub-class of | lv2:FilterPlugin |
---|
Sub-class of | lv2:DynamicsPlugin |
---|
Any plugin that analyses input to output some useful information.
Sub-class of | lv2:UtilityPlugin |
---|
Ports of this type will be connected to an array of length sample_count
with elements of C type float
.
Sub-class of | lv2:Port |
---|
Sub-class of | lv2:FilterPlugin |
---|
Ports of this type have the same buffer format as an lv2:AudioPort, except the buffer represents audio-rate control data rather than audio. Like an lv2:ControlPort, a CVPort SHOULD have properties describing its value (e.g. lv2:minimum, lv2:maximum, and lv2:default), and may be presented to the user as a control.
It is generally safe to connect an audio output to a CV input, but not vice versa. Hosts SHOULD take care to prevent data from a CVPort port from being used as audio.
Sub-class of | lv2:Port |
---|
A specific channel of audio, e.g. left
or right
.
Sub-class of | lv2:Designation |
---|
Sub-class of | lv2:ModulatorPlugin |
---|
Sub-class of | lv2:FilterPlugin |
---|
Sub-class of | lv2:DynamicsPlugin |
---|
Sub-class of | lv2:GeneratorPlugin |
---|
Ports of this type will be connected to a pointer to a single value of C
type float
.
Sub-class of | lv2:Port |
---|
Any plugin that converts some form of input into a different form of output.
Sub-class of | lv2:UtilityPlugin |
---|
Plugins that intentionally delay their input signal as an effect.
Sub-class of | lv2:Plugin |
---|
The designation (or assignment
) of an input or output. A designation
is metadata that describes the meaning or role of data. By assigning a
designation to a port using lv2:designation, the port's content becomes
meaningful and can be used more intelligently by the host.
Sub-class of | lv2:Plugin |
---|
Plugins that alter the envelope or dynamic range of audio.
Sub-class of | lv2:Plugin |
---|
Sub-class of | lv2:FilterPlugin |
---|
Sub-class of | lv2:DynamicsPlugin |
---|
Additional data and/or functions a plugin may return from LV2_Descriptor:extension_data() which can be used to add additional API beyond that defined by LV2_Descriptor.
In range of | lv2:extensionData |
---|
An additional feature which a plugin or other resource may use or require.
In range of | lv2:optionalFeature |
---|---|
lv2:requiredFeature |
Sub-class of | lv2:Plugin |
---|
Sub-class of | lv2:ModulatorPlugin |
---|
Sub-class of | lv2:UtilityPlugin |
---|
Sub-class of | lv2:DynamicsPlugin |
---|
Any plugin that generates sound internally, rather than processing its input.
Sub-class of | lv2:Plugin |
---|
Sub-class of | lv2:FilterPlugin |
---|
Ports of this type will be connected to a pointer to some value, which will be read by the plugin during their run method.
Sub-class of | lv2:Port |
---|
Any plugin that is intended to be played as a musical instrument.
Sub-class of | lv2:GeneratorPlugin |
---|
Sub-class of | lv2:DynamicsPlugin |
---|
Sub-class of | lv2:FilterPlugin |
---|
A plugin which mixes some number of inputs into some number of outputs.
Sub-class of | lv2:UtilityPlugin |
---|
Sub-class of | lv2:Plugin |
---|
Sub-class of | lv2:EQPlugin |
---|
Sub-class of | lv2:GeneratorPlugin |
---|
Ports of this type will be connected to a pointer to some value, which will be written to by the plugin during their run method.
Sub-class of | lv2:Port |
---|
Sub-class of | lv2:EQPlugin |
---|
A parameter, i.e. a recognized property. A parameter is a designation for a control.
A parameter defines the meaning of a control (not the method of conveying its value). The standard way of exposing a plugin parameter is via an lv2:ControlPort, which can be given a parameter designation with lv2:designation. Other methods, such as setting dynamic parameters via messages, are possible but not defined here.
Sub-class of | lv2:Designation |
---|
Sub-class of | lv2:ModulatorPlugin |
---|
Sub-class of | lv2:SpectralPlugin |
---|
The class which represents an LV2 plugin.
To be discovered by hosts, plugins MUST explicitly have rdf:type lv2:Plugin listed in their bundle's manifest, e.g.:
<http://example.org/my-plugin> a lv2:Plugin .
Plugins SHOULD have a doap:license property whenever possible. The doap:name
property should be at most a few words in length using title capitalization,
e.g. Tape Delay Unit
. Use doap:shortdesc or doap:description for more
detailed descriptions.
Sub-class of | lv2:PluginBase | ||
---|---|---|---|
Restriction on doap:name |
| ||
In range of | lv2:appliesTo |
An abstract plugin-like resource that MAY not actually be an LV2 plugin (e.g. may not actually have a plugin binary).
PluginBase SHOULD be used as a base type for any resource that may have
ports or otherwise mimic the structure of a Plugin (e.g. a preset), since
hosts and other tools already understand
this structure.
In domain of | lv2:port |
---|
A Point describes an interesting value in a Port's range (much like a labeled
notch
on a physical knob).
The class which represents an LV2 port.
All LV2 port descriptions MUST have a rdf:type that is one of lv2:Port lv2:InputPort or lv2:OutputPort. Additionally there MUST be at least one other rdf:type which more precisely describes type of the port (e.g. lv2:AudioPort).
Hosts that do not support a specific port class MUST NOT instantiate the
plugin, unless that port has the connectionOptional property set (in which case
the host can simply connect
that port to NULL). If a host is interested
in plugins to insert in a certain signal path (e.g. stereo audio), it SHOULD
consider all the classes of a port to determine which ports are most suitable
for connection (e.g. by ignoring ports with additional classes the host does
not recognize).
A port has two identifiers: a (numeric) index, and a (textual) symbol. The index can be used as an identifier at run-time, but persistent references to ports (e.g. in a saved preset) MUST use the symbol. A symbol is guaranteed to refer to the same port on all plugins with a given URI. An index does NOT necessarily refer to the same port on all plugins with a given URI (i.e. the index for a port may differ between plugin binaries).
Restriction on lv2:name |
| ||||
---|---|---|---|---|---|
Restriction on lv2:symbol |
| ||||
Restriction on lv2:index |
| ||||
In domain of | lv2:default | ||||
lv2:portProperty | |||||
lv2:maximum | |||||
lv2:minimum | |||||
lv2:scalePoint | |||||
In range of | lv2:port |
A port property - a useful piece of information that allows a host to make more sensible decisions (e.g. to provide a better interface).
In range of | lv2:portProperty |
---|
Sub-class of | lv2:DelayPlugin |
---|---|
lv2:Plugin | |
lv2:SimulatorPlugin |
A single float Point (for control inputs).
Sub-class of | lv2:Point |
---|---|
In range of | lv2:scalePoint |
Plugins that aim to duplicate the effect of some environmental effect or musical equipment.
Sub-class of | lv2:Plugin |
---|
Plugins that manipulate the position of audio in space (e.g. panning, stereo width, surround encoding, etc.).
Sub-class of | lv2:Plugin |
---|
An LV2 specification (i.e. this specification, or an LV2 extension).
Specification data, like plugin data, is distributed in bundles so hosts may discover all present LV2 data.
Sub-class of | doap:Project |
---|
Plugins that alter the spectral properties (e.g. frequency) of audio.
Sub-class of | lv2:Plugin |
---|
A short restricted name used as a machine and human readable identifier. The first character must be one of _, a-z or A-Z and subsequent characters can be from _, a-z, A-Z and 0-9. This is a valid C identifier, and compatible in most other contexts with restricted string identifiers (e.g. file paths).
In range of | lv2:symbol | ||||||
---|---|---|---|---|---|---|---|
owl:onDatatype | xsd:string | ||||||
owl:withRestrictions |
|
Includes things like mathematical functions and non-musical delays.
Sub-class of | lv2:Plugin |
---|
Sub-class of | lv2:DistortionPlugin |
---|
Specifies that a resource is related to a plugin. This is primarily intended for discovery purposes: bundles that describe resources that work with particular plugins (e.g. presets or user interfaces) SHOULD use this predicate in manifest.ttl to relate the resource to the applicable plugin(s), e.g.:
<thing> a ext:Thing ; lv2:appliesTo <plugin> ; rdfs:seeAlso <thing.ttl> .
Particularly for large amounts of data, this is preferable to extending the plugin description with rdfs:seeAlso since the host may choose if/when to load the data, knowing that it describes an additional resource and not the plugin itself.
OWL Type | Object Property |
---|---|
Range | lv2:Plugin |
The binary of an LV2 resource. The value of this property must be a URI that resolves to a shared library object (the actual type of this library is system specific).
This is a required property of a Plugin which MUST be included in the
bundle's manifest.ttl file. The lv2:binary of an lv2:Plugin is the
shared object containing the lv2_descriptor()
function which can
be used to access the descriptor for that plugin. This property may be used
similarly by extensions to relate other resources to their implementations.
OWL Type | Object Property |
---|---|
Range | owl:Thing |
The default value that the host SHOULD set this port to when there is no other information available.
OWL Type | Datatype Property |
---|---|
Domain | lv2:Port |
Indicates a channel or parameter designation.
This property is used to give the port's contents a well-defined meaning. For example, if a port has lv2:designation eg:gain, then the value of that port represents the eg:gain of the plugin instance.
Ports should be given designations whenever a well-defined designation exists. This allows the host to act more intelligently and/or provide a more effective user interface. For example, if the plugin has a BPM parameter, the host may automatically set that parameter to the current tempo.
OWL Type | Object Property |
---|
Relates a Resource to documentation markup. The value of this property MUST be a string literal which is a valid XHTML Basic 1.1 fragment suitable for use as the content of the <body> element. This can be used by hosts to provide rich online documentation or by tools to generate external documentation pages. The standard language tagging facility of RDF can be used to provide multi-lingual documentation.
XHTML Basic is a W3C Recommendation which defines a basic subset of XHTML intended to be reasonable to implement with limited resources (e.g. on embedded devices). See XHTML Basic, Section 3 for a list of legal tags.
OWL Type | Annotation Property |
---|---|
Range | rdfs:Literal |
rdfs:seeAlso | http://www.w3.org/TR/xhtml-basic/ |
Signifies that a plugin provides additional data or functions (as defined by some extension) via LV2:Descriptor::instantiate().
OWL Type | Object Property |
---|---|
Range | lv2:ExtensionData |
Whether or not processing is currently free-wheeling. If true, this means that all processing is happening as quickly as possible, not in real-time. When free-wheeling there is no relationship between the passage of real wall-clock time and the passage of time in the data being processed (e.g. audio frames).
OWL Type | Datatype Property |
---|---|
Range | xsd:boolean |
A non-negative zero-based 32-bit index.
OWL Type | Datatype Property |
---|---|
Range | xsd:unsignedInt |
The latency introduced by the plugin (or similar), in frames.
OWL Type | Datatype Property |
---|
A hint to the host for the maximum useful value that the port will use.
This is a soft
limit; the plugin is required to gracefully accept all
values in the range of a port's data type.
OWL Type | Datatype Property |
---|---|
Domain | lv2:Port |
The micro component of a Resource's version.
Releases of plugins and extensions MUST be explicitly versioned. Correct version numbers MUST always be maintained for any versioned resource that is published. For example, after a release, if a change is made in the development version in source control, the micro version MUST be incremented (to an odd number) to distinguish this modified version from the previous release.
This property describes half of a resource version. For detailed documentation on LV2 resource versioning, see lv2:minorVersion.
OWL Type | Datatype Property |
---|---|
Range | xsd:nonNegativeInteger |
A hint to the host for the minimum useful value that the port will use. This
is a soft
limit; the plugin is required to gracefully accept all values
in the range of a port's data type.
OWL Type | Datatype Property |
---|---|
Domain | lv2:Port |
The minor version of an LV2 Resource. This property is used (along with lv2:microVersion) by hosts to distinguish different versions of a compatible resource, e.g. to load only the bundle with the most recent version.
The version of an LV2 resource is composed of two fields: minor version, and micro version. These have the usual semantics:
Note there is deliberately no concept of a major version: all versions of an LV2 resource with a given URI are by definition backwards compatible. More precisely: replacing a resource with a newer version of that resource MUST NOT break anything. If a change is made which breaks this rule, the URI of the resource MUST be changed. In contexts where a full (e.g. SemVer conformant) version number is required, the major version of all released LV2 resources is 1.
Plugins and extensions MUST adhere to the following rules:
sameset of mandatory (i.e. not lv2:connectionOptional) ports with respect to lv2:symbol and rdf:type. In other words, every port on a specific version of a plugin has a lv2:symbol and a set of rdf:types; all future versions of that plugin are guaranteed to have a port with the same lv2:symbol and at least those rdf:types. New types may be added only if doing so does not break compatibility, i.e. if old hosts will continue to work correctly with the new plugin.
(Note these rules are not necessarily exhaustive)
Anything that depends on a specific version of a plugin (e.g. a serialisation that references ports by index) MUST refer to the plugin by both URI and version. However, implementations should be tolerant and extensions should be designed such that there is no need to do this (e.g. indices should only be meaningful for a particular plugin instance at run-time).
When hosts discover several installed versions of a resource, they SHOULD warn the user and load only the most recent version.
An odd minor or micro version indicates that the resource is a possibly unstable development version. Hosts and tools SHOULD clearly indicate this wherever appropriate. Several versions of a resource with an odd version may exist; i.e. it is acceptable to work on a development version of a resource (e.g. in source control) without worrying about version numbers as long as either the minor or micro version is odd.
This property describes half of a resource version. See lv2:minorVersion for the description of the other half.
OWL Type | Datatype Property |
---|---|
Range | xsd:nonNegativeInteger |
A display name for labeling in a user interface. Unlike lv2:symbol this is unrestricted and may be translated. The lv2:name MUST NOT be used as an identifier. This property is required for Ports, but MUST NOT be used by the host for port identification. The plugin author may change the values of this property without changing the Plugin URI.
OWL Type | Datatype Property |
---|
Signifies that a plugin or other resource supports a certain feature. If the host supports this feature, it MUST pass its URI and any additional data to the plugin in LV2_Descriptor::instantiate(). The plugin MUST NOT fail to instantiate if an optional feature is not supported by the host.
OWL Type | Object Property |
---|---|
Range | lv2:Feature |
Relates a Plugin to the Ports it contains
OWL Type | Object Property |
---|---|
Domain | lv2:PluginBase |
Range | lv2:Port |
Relates Ports to PortProperties. The PortProperty may be ignored without catastrophic effects, though it may be useful e.g. for providing a sensible interface for the port.
OWL Type | Object Property |
---|---|
Domain | lv2:Port |
Range | lv2:PortProperty |
The project this is a component of.
This property provides a way to group plugins and/or related resources. A project may have useful metadata common to all plugins (such as homepage, author, version history) which would be wasteful to list separately for each plugin.
Grouping via projects also allows users to find plugins in hosts by project,
which is often how they are remembered. For this reason, a project that
contains plugins SHOULD always have a doap:name. It is also a good idea for
each plugin and the project itself to have an lv2:symbol property, which allows
nice quasi-global identifiers for plugins, e.g. myproj.superamp
which
can be useful for display or fast user entry.
OWL Type | Object Property |
---|---|
Range | doap:Project |
Signifies that a plugin or other resource requires a certain feature. If the host supports this feature, it MUST pass its URI and any additional data to the plugin in LV2_Descriptor::instantiate(). The plugin MUST fail to instantiate if a required feature is not present; hosts SHOULD always check this before attempting to instantiate a plugin (i.e. discovery by attempting to instantiate is strongly discouraged).
OWL Type | Object Property |
---|---|
Range | lv2:Feature |
Relates a Port to its ScalePoints.
OWL Type | Object Property |
---|---|
Domain | lv2:Port |
Range | lv2:ScalePoint |
The value of this property MUST conform to the rules for lv2:Symbol, and MUST NOT have a language tag.
A symbol is a unique identifier with respect to the parent (e.g. a port's symbol is a unique identifier with respect to its plugin). The plugin author MUST change the plugin URI if a port symbol is changed or removed.
OWL Type | Datatype Property |
---|---|
Range | lv2:Symbol |
Indicates that this port does not have to be connected to valid data by the host. If it is to be disconnected then the port MUST set to NULL with a call to the connectPort method.
Type | lv2:PortProperty |
---|
Indicates that a port's only reasonable values are the scale points defined for that port. A host SHOULD NOT allow a user to set the value of such a port to anything other than a scale point. However, a plugin MUST operate reasonably even if such a port has an input that is not a scale point, preferably by simply choosing the largest enumeration value less than or equal to the actual input value (i.e. round the input value down).
Type | lv2:PortProperty |
---|
Indicates that the plugin is capable of running not only in a conventional
host but also in a hard real-time
environment. To qualify for this the
plugin MUST satisfy all of the following:
A + B * sample_count
where A
and B
depend on the machine and host in use. This amount of
time MUST NOT depend on input signals or plugin state.Note these rules apply to the connect_port() function as well as run().
Type | lv2:Feature |
---|
Indicates that the plugin may cease to work correctly if the host elects to
use the same data location for both input and output. Plugins that will fail
to work correctly if ANY input port is connected to the same location as ANY
output port MUST require this Feature. Doing so should be avoided as it makes
it impossible for hosts to use the plugin to process data in-place
.
Type | lv2:Feature |
---|
Indicates that a port's reasonable values are integers (eg. a user interface would likely wish to provide a stepped control allowing only integer input). A plugin MUST operate reasonably even if such a port has a non-integer input.
Type | lv2:PortProperty |
---|
Indicates that the plugin has a real-time dependency (e.g. queues data from
a socket) and so its output must not be cached or subject to significant
latency, and calls to the run method should be done in rapid succession. This
property is not related to hard real-time
execution requirements (see
lv2:hardRTCapable).
Type | lv2:Feature |
---|
Indicates that the port is used to express the processing latency incurred
by the plugin, expressed in samples. The latency may be affected by the current
sample rate, plugin settings, or other factors, and may be changed by the
plugin at any time. Where the latency is frequency dependent the plugin may
choose any appropriate value. If a plugin introduces latency it MUST provide
EXACTLY ONE port with this property set which informs the host of the
correct
latency. In fuzzy
cases the value output should be the
most reasonable based on user expectation of input/output alignment
(eg. musical delay/echo plugins should not report their delay as latency, as it
is an intentional effect).
Type | lv2:PortProperty |
---|
Indicates that any bounds specified should be interpreted as multiples of the sample rate. For instance, a frequency range from 0Hz to the Nyquist frequency (half the sample rate) could be requested by this property in conjunction with lv2:minimum 0.0 and lv2:maximum 0.5. Hosts that support bounds at all MUST support this property.
Type | lv2:PortProperty |
---|
Indicates that the data item should be considered a Boolean toggle. Data
less than or equal to zero should be considered off
or false
, and
data above zero should be considered on
or true
.
Type | lv2:PortProperty |
---|