Architecture – LV2 Trac

Context Navigation

LV2 plugins are small pieces of software that can process or generate signals, mainly audio, but they can also be used for other types. Since they are 'plugins' they do not run as programs on their own but are loaded into other processes, called 'hosts', at runtime. They can be used e.g. as realtime effects in a harddisk recorder program, unit generators in a modular synth, or batch processing effects in a sample editor.

A plugin consists of some static RDF data (see http://www.w3.org/TR/rdf-primer/ for information about RDF) describing its input and output ports as well as some other properties, and a struct object of the type LV2_Descriptor (defined in the C header file lv2.h) containing function pointers that provide the implementation of the plugin. Each plugin is uniquely identified by an URI (Uniform Resource Identifier, see http://www.ietf.org/rfc/rfc2396.txt).

The RDF data is stored in text files using the Turtle syntax, and the plugin implementations are stored in shared object files. Both these types of files are kept in directories called bundles. For more information about the structure of a bundle, read the wiki:Bundle? Definition.

Some of the text below is not in the bundle definition and should maybe go into a texty description of the RDF format

The format of the RDF data is described in more detail in the file lv2.ttl. Basically, for every plugin in the bundle there will be a triple matching the pattern

where ?uri is the unique URI for the plugin. There will also be data describing all the input and output ports for each plugin; most importantly their datatypes and whether they should contain single values (control rate ports) or arrays of values (audio rate ports). For each plugin there will also be a triple describing where to find the actual plugin implementation. It will look like this:

where ?uri is the plugin URI and ?so-file is a relative path from the bundle directory to a shared object file that can be loaded using dlopen() or the equivalent function on your system, from which the plugin implementation can be retrieved. The shared object files do not have to be unique, a si 1000 ngle file may contain the implementation for multiple plugins.

The file manifest.ttl may also contain references to other Turtle files using triples of the form

<pre>?someuri < http://www.w3.org/2000/01/rdf-schema#seeAlso> ?ttlfile</pre>

where ?ttlfile is a relative path from the bundle directory to another Turtle file. The RDF data in any files referenced in this way should be treated in the same way as if it was contained in manifest.ttl itself, with two exceptions: "seeAlso" references in these other files can be ignored, and any triples of the form

can also be ignored - this is so hosts will only have to parse manifest.ttl in order to see which plugins a bundle contains.

Every shared object file will have a function named lv2_descriptor() that can be found using dlsym() or an equivalent function, and which the host can use to retrieve the LV2_Descriptor object for a plugin. Detailed information about this function and how to handle the LV2_Descriptor can be found in the C API docs.

==Extensions==

LV2 provides a mechanism for defining extensions to the core specification in the form of host features, datatypes, hints and properties.

A host feature is an extension to the LV2 specification that a host may or may not support. If a plugin uses a host feature, it will have one of the triples

<pre>?uri <http://lv2plug.in/ns/lv2core#optionalHostFeature> ?feature

?uri <http://lv2plug.in/ns/lv2core#requiredHostFeature> ?feature</pre>

in its RDF data files, where ?uri is the plugin URI and ?feature is an URI that identifies a particular host feature. If the plugin will work even if the host does not support this feature it will use the optionalHostFeature predicate, otherwise it will use requiredHostFeature. A host that does not support a required host feature should not attempt to load that plugin.

Host features can define additional data such as callback functions to be passed from the host to the plugin (see instantiate()) or from the plugin to the host (see extension_data()).

Port datatypes specify how the data in the plugin port buffers should be interpreted. The only datatype that is defined in the core specification is <http://lv2plug.in/ontology#Float> which denotes a 32-bit floating point value conforming to the IEEE-754 specification. All LV2 hosts should support this datatype.

Other datatypes may be defined, and if a plugin has a port with a datatype that the host does not recognise it should not attempt to load the plugin unless that port also has the port hint connectionOptional, in which case it may load the plugin but must set the data pointer for that port to NULL.

Hints and properties are URIs that can be associated with plugins or plugin ports by using one of the predicates <http://lv2plug.in/ns/lv2core#pluginHint>, <http://lv2plug.in/ns/lv2core#portHint>, <http://lv2plug.in/ns/lv2core#pluginProperty> or <http://lv2plug.in/ns/lv2core#portProperty> in the RDF data for a plugin, for example like this:

Some hints and properties are defined in the LV2 specification, and any plugin writer can use new ones. Hints may be ignored by the host, but properties may not - if a host sees that a plugin has a property that the host does not recognise, it is not safe to load the plugin.

Because of the nature of RDF, any plugin author can add extensions to the RDF data in the form of triples containing new URIs. However, unless an extension explicitly uses one of the mechanisms defined above it must always be safe for a host to ignore it.

Download in other formats:

Plain Text