# LV2

An extensible open standard for audio plugins

ID | http://lv2plug.in/ns/lv2core
Version | 18.0
Date | 2021-01-09
Discuss | devel@lists.lv2plug.in (subscribe)

- Index
- History
- API

LV2 is an interface for writing audio plugins in C or compatible languages, which can be dynamically loaded into many host applications. This core specification is simple and minimal, but is designed so that extensions can be defined to add more advanced features, making it possible to implement nearly any feature.

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 (such as waveforms) are shipped together in a bundle directory. The code contains only the executable portions of the plugin. 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 written in any language to work with LV2 data. The LV2 specification itself is distributed in a similar way.

An LV2 plugin library is suitable for dynamic loading (for example with `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 the `run()` method to process blocks of data.

This core specification defines two types of port, equivalent to those in LADSPA, ControlPort and AudioPort, as well as CVPort which has the same format as an audio port but is interpreted as non-audible control data. 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() |

Hosts MUST guarantee that:

- A function in any class is never called concurrently with another function in that class.

- A Discovery function is never called concurrently with any other fuction in the same shared object file.

- An Instantiation function for an instance is never called concurrently with any other function for that instance.

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 plugins or the host (beyond the contract of that function), for example 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.

## Index

Classes | Properties | Instances
--- | --- | ---
Designation Channel Parameter ExtensionData Feature Markdown PluginBase Plugin DelayPlugin ReverbPlugin DistortionPlugin WaveshaperPlugin DynamicsPlugin AmplifierPlugin CompressorPlugin EnvelopePlugin ExpanderPlugin GatePlugin LimiterPlugin FilterPlugin AllpassPlugin BandpassPlugin CombPlugin EQPlugin MultiEQPlugin ParaEQPlugin HighpassPlugin LowpassPlugin GeneratorPlugin ConstantPlugin InstrumentPlugin OscillatorPlugin MIDIPlugin ModulatorPlugin ChorusPlugin FlangerPlugin PhaserPlugin ReverbPlugin SimulatorPlugin ReverbPlugin SpatialPlugin SpectralPlugin PitchPlugin UtilityPlugin AnalyserPlugin ConverterPlugin FunctionPlugin MixerPlugin Point ScalePoint PortBase Port AudioPort CVPort ControlPort InputPort OutputPort PortProperty Specification Symbol | appliesTo binary default designation documentation enabled extensionData freeWheeling index latency maximum microVersion minimum minorVersion name optionalFeature port portProperty project prototype requiredFeature scalePoint shortName symbol | connectionOptional control enumeration hardRTCapable inPlaceBroken integer isLive isSideChain reportsLatency sampleRate toggled

## Classes

### AllpassPlugin

Class

Label | Allpass Plugin
Subclass of | FilterPlugin

A filter that changes the phase relationship between frequency components.

### AmplifierPlugin

Class

Label | Amplifier Plugin
Subclass of | DynamicsPlugin

A plugin that primarily changes the volume of its input.

### AnalyserPlugin

Class

Label | Analyser Plugin
Subclass of | UtilityPlugin

A plugin that analyses its input and emits some useful information.

### AudioPort

Class

Label | Audio Port
Subclass of | Port

A port connected to an array of float audio samples.

Ports of this type are connected to a buffer of `float` audio samples, which the host guarantees have `sample_count` elements in any call to LV2_Descriptor::run().

Audio samples are normalized between -1.0 and 1.0, though there is no requirement for samples to be strictly within this range.

### BandpassPlugin

Class

Label | Bandpass Filter Plugin
Subclass of | FilterPlugin

A filter that attenuates frequencies outside of some band.

### CVPort

Class

Label | CV Port
Subclass of | Port

A port connected to an array of float control values.

Ports of this type have the same buffer format as an AudioPort, except the buffer represents audio-rate control data rather than audio. Like a ControlPort, a CV port SHOULD have properties describing its value, in particular minimum, maximum, and default.

Hosts may present CV ports to users as controls in the same way as control ports. Conceptually, aside from the buffer format, a CV port is the same as a control port, so hosts can use all the same properties and expectations.

In particular, this port type does not imply any range, unit, or meaning for its values. However, if there is no inherent unit to the values, for example if the port is used to modulate some other value, then plugins SHOULD use a normalized range, either from -1.0 to 1.0, or from 0.0 to 1.0.

It is generally safe to connect an audio output to a CV input, but not vice-versa. Hosts must take care to prevent data from a CVPort port from being used as audio.

### Channel

Class

Label | Channel
Subclass of | Designation

An individual channel, such as left or right.

A specific channel, for example the left channel of a stereo stream. A channel may be audio, or another type such as a MIDI control stream.

### ChorusPlugin

Class

Label | Chorus Plugin
Subclass of | ModulatorPlugin

An effect that mixes significantly delayed copies of its input.

### CombPlugin

Class

Label | Comb FilterPlugin
Subclass of | FilterPlugin

A filter that adds a delayed version of its input to itself.

### CompressorPlugin

Class

Label | Compressor Plugin
Subclass of | DynamicsPlugin

A plugin that reduces the dynamic range of its input.

### ConstantPlugin

Class

Label | Constant Plugin
Subclass of | GeneratorPlugin

A plugin that emits constant values.

### ControlPort

Class

Label | Control Port
Subclass of | Port

A port connected to a single `float`.

### ConverterPlugin

Class

Label | Converter Plugin
Subclass of | UtilityPlugin

A plugin that converts its input into a different form.

### DelayPlugin

Class

Label | Delay Plugin
Subclass of | Plugin
Superclass of | ReverbPlugin

An effect that intentionally delays its input as an effect.

### Designation

Class

Label | Designation
Subclass of | rdf:Property
Superclass of | Channel
| Parameter

A designation which defines the meaning of some data.

A designation is metadata that describes the meaning or role of something. By assigning a designation to a port using designation, the port's content becomes meaningful and can be used more intelligently by the host.

### DistortionPlugin

Class

Label | Distortion Plugin
Subclass of | Plugin
Superclass of | WaveshaperPlugin

A plugin that adds distortion to its input.

### DynamicsPlugin

Class

Label | Dynamics Plugin
Subclass of | Plugin
Superclass of | AmplifierPlugin
| CompressorPlugin
| EnvelopePlugin
| ExpanderPlugin
| GatePlugin
| LimiterPlugin

A plugin that alters the envelope or dynamic range of its input.

### EQPlugin

Class

Label | Equaliser Plugin
Subclass of | FilterPlugin
Superclass of | MultiEQPlugin
| ParaEQPlugin

A plugin that adjusts the balance between frequency components.

### EnvelopePlugin

Class

Label | Envelope Plugin
Subclass of | DynamicsPlugin

A plugin that applies an envelope to its input.

### ExpanderPlugin

Class

Label | Expander Plugin
Subclass of | DynamicsPlugin

A plugin that expands the dynamic range of its input.

### ExtensionData

Class

Label | Extension Data
In range of | extensionData

Additional data defined by an extension.

This is additional data that a plugin may return from LV2_Descriptor::extension_data(). This is generally used to add APIs to extend that defined by LV2_Descriptor.

### Feature

Class

Label | Feature
In range of | optionalFeature
| requiredFeature

An additional feature which may be used or required.

### FilterPlugin

Class

Label | Filter Plugin
Subclass of | Plugin
Superclass of | AllpassPlugin
| BandpassPlugin
| CombPlugin
| EQPlugin
| HighpassPlugin
| LowpassPlugin

An effect that manipulates the frequency spectrum of its input.

### FlangerPlugin

Class

Label | Flanger Plugin
Subclass of | ModulatorPlugin

An effect that mixes slightly delayed copies of its input.

### FunctionPlugin

Class

Label | Function Plugin
Subclass of | UtilityPlugin

A plugin whose output is a mathmatical function of its input.

### GatePlugin

Class

Label | Gate Plugin
Subclass of | DynamicsPlugin

A plugin that attenuates signals below some threshold.

### GeneratorPlugin

Class

Label | Generator Plugin
Subclass of | Plugin
Superclass of | ConstantPlugin
| InstrumentPlugin
| OscillatorPlugin

A plugin that generates new sound internally.

### HighpassPlugin

Class

Label | Highpass Filter Plugin
Subclass of | FilterPlugin

A filter that attenuates frequencies below some cutoff.

### InputPort

Class

Label | Input Port
Subclass of | Port

A port connected to constant data which is read during `run()`.

### InstrumentPlugin

Class

Label | Instrument Plugin
Subclass of | GeneratorPlugin

A plugin intended to be played as a musical instrument.

### LimiterPlugin

Class

Label | Limiter Plugin
Subclass of | DynamicsPlugin

A plugin that limits its input to some maximum level.

### LowpassPlugin

Class

Label | Lowpass Filter Plugin
Subclass of | FilterPlugin

A filter that attenuates frequencies above some cutoff.

### MIDIPlugin

Class

Label | MIDI Plugin
Subclass of | Plugin

A plugin that primarily processes MIDI messages.

### Markdown

Class

Label | Markdown
owl:onDatatype | xsd:string

A string in Markdown syntax.

This datatype is typically used for documentation in Markdown syntax.

Generally, documentation with this datatype should stay as close to readable plain text as possible, but may use core Markdown syntax for nicer presentation. Documentation can assume that basic extensions like codehilite and tables are available.

### MixerPlugin

Class

Label | Mixer Plugin
Subclass of | UtilityPlugin

A plugin that mixes some number of inputs into some number of outputs.

### ModulatorPlugin

Class

Label | Modulator Plugin
Subclass of | Plugin
Superclass of | ChorusPlugin
| FlangerPlugin
| PhaserPlugin

An effect that modulats its input as an effect.

### MultiEQPlugin

Class

Label | Multiband EQ Plugin
Subclass of | EQPlugin

A plugin that adjusts the balance between a fixed set of frequency components.

### OscillatorPlugin

Class

Label | Oscillator Plugin
Subclass of | GeneratorPlugin

A plugin that generates output with an oscillator.

### OutputPort

Class

Label | Output Port
Subclass of | Port

A port connected to data which is written during `run()`.

### ParaEQPlugin

Class

Label | Parametric EQ Plugin
Subclass of | EQPlugin

A plugin that adjusts the balance between configurable frequency components.

### Parameter

Class

Label | Parameter
Subclass of | Designation
| rdf:Property

A property that is a plugin parameter.

A parameter is a designation for a control.

A parameter defines the meaning of a control, not the method of conveying its value. For example, a parameter could be controlled via a ControlPort, messages, or both.

A ControlPort can be associated with a parameter using designation.

### PhaserPlugin

Class

Label | Phaser Plugin
Subclass of | ModulatorPlugin

An effect that periodically sweeps a filter over its input.

### PitchPlugin

Class

Label | Pitch Shifter Plugin
Subclass of | SpectralPlugin

A plugin that shifts the pitch of its input.

### Plugin

Class

Label | Plugin
Subclass of | PluginBase
Superclass of | DelayPlugin
| DistortionPlugin
| DynamicsPlugin
| FilterPlugin
| GeneratorPlugin
| MIDIPlugin
| ModulatorPlugin
| ReverbPlugin
| SimulatorPlugin
| SpatialPlugin
| SpectralPlugin
| UtilityPlugin
In range of | appliesTo

An LV2 plugin.

To be discovered by hosts, plugins MUST explicitly have an rdf:type of Plugin in their bundle's manifest, for example:

    <http://example.org/my-plugin> a lv2:Plugin .

Plugins should have a doap:name property that is at most a few words in length using title capitalization, for example Tape Delay Unit.

Restriction on doap:name
  owl:someValuesFrom rdf:PlainLiteral
  A plugin MUST have at least one untranslated doap:name.
Restriction on port
  owl:allValuesFrom Port
  All ports on a plugin MUST be fully specified lv2:Port instances.

### PluginBase

Class

Label | Plugin Base
Superclass of | Plugin
In domain of | port

Base class for a plugin-like resource.

An abstract plugin-like resource that may not actually be an LV2 plugin, for example that may not have a binary. This is useful for describing things that share common structure with a plugin, but are not themselves an actul plugin, such as presets.

### Point

Class

Label | Point
Superclass of | ScalePoint

An interesting point in a value range.

- A Point MUST have at least one rdfs:label which is a string.

- A Point MUST have exactly one rdf:value with a type that is compatible with the type of the corresponding Port.

### Port

Class

Label | Port
Subclass of | PortBase
Superclass of | AudioPort
| CVPort
| ControlPort
| InputPort
| OutputPort
In domain of | portProperty

An LV2 plugin port.

All LV2 port descriptions MUST have a rdf:type that is one of Port, InputPort or OutputPort. Additionally, there MUST be at least one other rdf:type which more precisely describes type of the port, for example AudioPort.

Hosts that do not support a specific port class MUST NOT instantiate the plugin, unless that port has the connectionOptional property set.

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 (for example in presets or save files) MUST use the symbol. Only the symbol is guaranteed to refer to the same port on all plugins with a given URI, that is the index for a port may differ between plugin binaries.

Restriction on name
  owl:minCardinality 1
  A port MUST have at least one lv2:name.

### PortBase

Class

Label | Port Base
Superclass of | Port
In range of | port

Base class for a port-like resource.

Similar to PluginBase, this is an abstract port-like resource that may not be a fully specified LV2 port. For example, this is used for preset "ports" which do not specify an index.

Restriction on symbol
  owl:cardinality 1
  A port MUST have exactly one lv2:symbol.

### PortProperty

Class

Label | Port Property
In range of | portProperty

A particular property that a port has.

### ReverbPlugin

Class

Label | Reverb Plugin
Subclass of | DelayPlugin
| Plugin
| SimulatorPlugin

An effect that adds reverberation to its input.

### ScalePoint

Class

Label | Scale Point
Subclass of | Point
In range of | scalePoint

A single `float` Point for control inputs.

### SimulatorPlugin

Class

Label | Simulator Plugin
Subclass of | Plugin
Superclass of | ReverbPlugin

A plugin that aims to emulate some environmental effect or musical equipment.

### SpatialPlugin

Class

Label | Spatial Plugin
Subclass of | Plugin

A plugin that manipulates the position of audio in space.

### Specification

Class

Label | Specification
Subclass of | doap:Project

An LV2 specifiation.

An LV2 specification typically contains a vocabulary description, C headers to define an API, and any other resources that may be useful. Specifications, like plugins, are distributed and installed as bundles so that hosts may discover them.

### SpectralPlugin

Class

Label | Spectral Plugin
Subclass of | Plugin
Superclass of | PitchPlugin

A plugin that alters the spectral properties of audio.

### Symbol

Class

Label | Symbol
In range of | symbol
owl:onDatatype | xsd:string

A short restricted name used as a strong identifier.

The first character of a symbol must be one of `_`, `a-z` or `A-Z`, and subsequent characters may additionally be `0-9`. This is, among other things, a valid C identifier, and generally compatible in most contexts which have restrictions on string identifiers, such as file paths.

### UtilityPlugin

Class

Label | Utility Plugin
Subclass of | Plugin
Superclass of | AnalyserPlugin
| ConverterPlugin
| FunctionPlugin
| MixerPlugin

A utility plugin that is not a typical audio effect or generator.

### WaveshaperPlugin

Class

Label | Waveshaper Plugin
Subclass of | DistortionPlugin

An effect that alters the shape of input waveforms.

## Properties

### appliesTo

Property

Label | applies to
Range | Plugin
Type | Object Property

The plugin this resource is related to.

This is primarily intended for discovery purposes: bundles that describe resources that work with particular plugins (like presets or user interfaces) SHOULD specify this in their `manifest.ttl` so the host can associate them with the correct plugin. For example:

    <thing>
        a             ext:Thing ;
        lv2:appliesTo <plugin> ;
        rdfs:seeAlso  <thing.ttl> .

Using this pattern is preferable for large amounts of data, since the host may choose whether/when to load the data.

### binary

Property

Label | binary
Range | owl:Thing
Type | Object Property

The binary of this resource.

The value of this property must be the URI of a shared library object, typically in the same bundle as the data file which contains this property. The actual type of the library is platform specific.

This is a required property of a Plugin which MUST be included in the bundle's `manifest.ttl` file. The binary of a Plugin is the shared object containing the lv2_descriptor() or lv2_lib_descriptor() function. This probably may also be used similarly by extensions to relate other resources to their implementations (it is not implied that a binary on an arbitrary resource is an LV2 plugin library).

### default

Property

Label | default
Type | Datatype Property

The default value for this control.

The host SHOULD set the port to this value initially, and in any situation where the port value should be cleared or reset.

### designation

Property

Label | designation
Range | rdf:Property
Type | Object Property

The designation that defines the meaning of this input or output.

This property is used to give a port's contents a well-defined meaning. For example, if a port has the designation `eg:gain`, then the value of that port represents the `eg:gain` of the plugin instance.

Ports should be given designations whenever possible, particularly if a suitable designation is already defined. This allows the host to act more intelligently and 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.

### documentation

Property

Label | documentation
Range | rdfs:Literal
Type | Annotation Property
See also | http://www.w3.org/TR/xhtml-basic/

Extended documentation.

Relates a Resource to extended documentation.

LV2 specifications are documented using this property with an Markdown datatype.

If the value has no explicit datatype, it is assumed to be a valid XHTML Basic 1.1 fragment suitable for use as the content of the `body` element of a page.

XHTML Basic is a W3C Recommendation which defines a simplified subset of XHTML intended to be reasonable to implement with limited resources, for exampe on embedded devices. See XHTML Basic, Section 3 for a list of valid tags.

### enabled

Property

Label | enabled
Range | xsd:int
Type | Datatype Property

Whether processing is currently enabled (not bypassed).

If this value is greater than zero, the plugin processes normally. If this value is zero, the plugin is expected to bypass all signals unmodified. The plugin must provide a click-free transition between the enabled and disabled (bypassed) states.

Values less than zero are reserved for future use (such as click-free insertion/removal of latent plugins), and should be treated like zero (bypassed) by current implementations.

### extensionData

Property

Label | extension data
Range | ExtensionData
Type | Object Property

Extension data provided by a plugin or other binary.

If a plugin has a value for this property, it must be a URI that defines the extension data. The plugin should return the appropriate data when LV2_Descriptor::extension_data() is called with that URI as a parameter.

### freeWheeling

Property

Label | free-wheeling
Range | xsd:boolean
Type | Datatype Property

Whether 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.

### index

Property

Label | index
Range | xsd:unsignedInt
Type | Datatype Property

A non-negative zero-based 32-bit index.

### latency

Property

Label | latency
Range | xsd:nonNegativeInteger
Type | Datatype Property

The latency introduced, in frames.

### maximum

Property

Label | maximum
Type | Datatype Property

The maximum value for this control.

This is a soft limit: the plugin is required to gracefully accept all values in the range of a port's data type.

### microVersion

Property

Label | micro version
Range | xsd:nonNegativeInteger
Type | Datatype Property

The micro version of this resource.

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 minorVersion.

### minimum

Property

Label | minimum
Type | Datatype Property

The minimum value for this control.

This is a soft limit: the plugin is required to gracefully accept all values in the range of a port's data type.

### minorVersion

Property

Label | minor version
Range | xsd:nonNegativeInteger
Type | Datatype Property

The minor version of this resource.

This, along with microVersion, is used to distinguish between different versions of the same resource, for example to load only the bundle with the most recent version of a plugin. An LV2 version has a minor and micro number with the usual semantics:

- The minor version MUST be incremented when backwards (but not forwards) compatible additions are made, for example the addition of a port to a plugin.

- The micro version is incremented for changes which do not affect compatibility at all, for example bug fixes or documentation updates.

Note that there is deliberately no major version: all versions with the same URI are compatible by definition. Replacing a resource with a newer version of that resource MUST NOT break anything. If a change violates this rule, then the URI of the resource (which serves as the major version) MUST be changed.

Plugins and extensions MUST adhere to at least the following rules:

- All versions of a plugin with a given URI MUST have the same set of mandatory (not connectionOptional) ports with respect to symbol and rdf:type. In other words, every port on a particular version is guaranteed to exist on a future version with same symbol and at least those rdf:types.

- New ports MAY be added without changing the plugin URI if and only if they are connectionOptional and the minor version is incremented.

- The minor version MUST be incremented if the index of any port (identified by its symbol) is changed.

- All versions of a specification MUST be compatible in the sense that an implementation of the new version can interoperate with an implementation of any previous version.

Anything that depends on a specific version of a plugin (including referencing ports by index) MUST refer to the plugin by both URI and version. However, implementations should be tolerant where possible.

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, or minor version zero, indicates that the resource is a development version. Hosts and tools SHOULD clearly indicate this wherever appropriate. Minor version zero is a special case for pre-release development of plugins, or experimental plugins that are not intended for stable use at all. Hosts SHOULD NOT expect such a plugin to remain compatible with any future version. Where feasible, hosts SHOULD NOT expose such plugins to users by default, but may provide an option to display them.

### name

Property

Label | name
Range | xsd:string
Type | Datatype Property

A display name for labeling in a user interface.

Unlike symbol, this is unrestricted, may be translated, and is not relevant for compatibility. The name is not necessarily unique and MUST NOT be used as an identifier.

### optionalFeature

Property

Label | optional feature
Range | Feature
Type | Object Property

An optional feature that is supported if available.

To support this feature, the host 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.

### port

Property

Label | port
Domain | PluginBase
Range | PortBase
Type | Object Property

A port (input or output) on this plugin.

### portProperty

Property

Label | port property
Domain | Port
Range | PortProperty
Type | Object Property

A property of this port hosts may find useful.

States that a port has a particular PortProperty. This may be ignored without catastrophic effects, though it may be useful, for example to provide a sensible user interface for the port.

### project

Property

Label | project
Range | doap:Project
Type | Object Property

The project this is a part 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 symbol property, which allows nice quasi-global identifiers for plugins, for example `myproj.superamp` which can be useful for display or fast user entry.

### prototype

Property

Label | prototype
Type | Object Property

The prototype to inherit properties from.

This property can be used to include common properties in several descriptions, serving as a sort of template mechanism. If a plugin has a prototype, then the host must load all the properties for the prototype as if they were properties of the plugin. That is, if `:plug prototype :prot`, then for each triple `:prot p o`, the triple `:plug p o` should be loaded.

This facility is useful for distributing data-only plugins that rely on a common binary, for example those where the internal state is loaded from some other file. Such plugins can refer to a prototype in a template LV2 bundle which is installed by the corresponding software.

### requiredFeature

Property

Label | required feature
Range | Feature
Type | Object Property

A required feature that must be available to run.

To support this feature, the host MUST pass its URI and any additional data to the plugin in LV2_Descriptor::instantiate().

The host MUST check this property before attempting to instantiate a plugin, and not attempt to instantiate plugins which require features it does not support. The plugin MUST fail to instantiate if a required feature is not supported by the host. Note that these rules are intentionally redundant for resilience: neither host nor plugin should assume that the other does not violate them.

### scalePoint

Property

Label | scale point
Range | ScalePoint
Type | Object Property

A scale point of a port or parameter.

### shortName

Property

Label | short name
Range | xsd:string
Type | Datatype Property

A short display name for labeling in a user interface.

This is the same as name, with the additional requirement that the value is shorter than 16 characters.

### symbol

Property

Label | symbol
Range | Symbol
| rdf:PlainLiteral
Type | Datatype Property

The symbol that identifies this resource in the context of its parent.

The value of this property MUST be a valid Symbol, and MUST NOT have a language tag.

A symbol is a unique identifier with respect to the parent, for example a port's symbol is a unique identifiers with respect to its plugin. The plugin author MUST change the plugin URI if any port symbol is changed or removed.

## Instances

### connectionOptional

Instance

Label | connection optional
Type | PortProperty

The property that this port may be connected to NULL.

This property means that the port does not have to be connected to valid data by the host. To leave a port unconnected, the host MUST explicitly connect the port to `NULL`.

### control

Instance

Label | control
Type | Channel

The primary control channel.

This should be used as the designation of ports that are used to send commands and receive responses. Typically this will be an event port that supports some protocol, for example MIDI or LV2 Atoms.

### enumeration

Instance

Label | enumeration
Type | PortProperty

Control port scale points represent all useful values.

Indicates that all the rasonable values for a port are defined by scalePoint properties. For such ports, a user interface should provide a selector that allows the user to choose any of the scale point values by name. It is recommended to show the value as well if possible.

Note that this is only a hint, and that the plugin MUST operate reasonably even if such a port has a value that does not correspond to a scale point.

### hardRTCapable

Instance

Label | hard real-time capable
Type | Feature

Plugin is capable of running in a hard real-time environment.

This feature indicates that the plugin is capable of running in a hard real-time environment. This should be the case for most audio processors, so most plugins are expected to have this feature.

To support this feature, plugins MUST adhere to the following in all of their audio class functions (LV2_Descriptor::run() and LV2_Descriptor::connect_port()):

- There is no use of `malloc()`, `free()` or any other heap memory management functions.

- There is no use of any library functions which do not adhere to these rules. The plugin may assume that the standard C math library functions are safe.

- There is no access to files, devices, pipes, sockets, system calls, or any other mechanism that might result in the process or thread blocking.

- The maximum amount of time for a `run()` call is bounded by some expression of the form `A + B * sample_count`, where `A` and `B` are platform specific constants. Note that this bound does not depend on input signals or plugin state.

### inPlaceBroken

Instance

Label | in-place broken
Type | Feature

Plugin requires separate locations for input and output.

This feature indicates that the plugin may not 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 whenever possible since it prevents hosts from running the plugin on data in-place.

### integer

Instance

Label | integer
Type | PortProperty

Control port values are treated as integers.

Indicates that all the reasonable values for a port are integers. For such ports, a user interface should provide a stepped control that only allows choosing integer values.

Note that this is only a hint, and that the plugin MUST operate reasonably even if such a port has a non-integer value.

### isLive

Instance

Label | is live
Type | Feature

Plugin has a real-time dependency.

This feature is for plugins that have time-sensitive internals, for example communicating in real time over a socket. It indicates to the host that its input and output must not be cached or subject to significant latency, and that calls to LV2_Descriptor::run() should be made at a rate that roughly corresponds to wall clock time (according to the `sample_count` parameter).

Note that this feature is not related to hard real-time execution requirements (see hardRTCapable).

### isSideChain

Instance

Label | is side-chain
Type | PortProperty

Signal for port should not be considered a main input or output.

Indicates that a port is a sidechain, which affects the output somehow but should not be considered a part of the main signal chain. Sidechain ports SHOULD be connectionOptional, and may be ignored by hosts.

### reportsLatency

Instance

Label | reports latency
Type | PortProperty
owl:deprecated | true

Deprecated

Control port value is the plugin latency in frames.

This property 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. In fuzzy cases the value should be the most reasonable one based on user expectation of input/output alignment. For example, musical delay plugins should not report their delay as latency, since it is an intentional effect that the host should not compensate for.

This property is deprecated, use a designation of latency instead, following the same rules as above:

    <http://example.org/plugin>
        lv2:port [
            a lv2:OutputPort , lv2:ControlPort ;
            lv2:designation lv2:latency ;
            lv2:symbol "latency" ;
        ]

### sampleRate

Instance

Label | sample rate
Type | PortProperty

Control port bounds are interpreted as multiples of the sample rate.

Indicates that any specified bounds should be interpreted as multiples of the sample rate. For example, a frequency range from 0 Hz to the Nyquist frequency (half the sample rate) can be specified by using this property with minimum 0.0 and maximum 0.5. Hosts that support bounds at all MUST support this property.

### toggled

Instance

Label | toggled
Type | PortProperty

Control port value is considered a boolean toggle.

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.

## History

Version 18.0 (2020-04-26)
  - Add lv2:Markdown datatype.
  - Deprecate lv2:reportsLatency.
Version 16.0 (2019-02-03)
  - Add lv2:MIDIPlugin class.
  - Rework port restrictions so that presets can be validated.
Version 14.0 (2016-09-18)
  - Add lv2_util.h with lv2_features_data() and lv2_features_query().
  - Add lv2:enabled designation.
Version 12.4 (2015-04-07)
  - Relax domain of lv2:minimum lv2:maximum and lv2:default so they can be used to describe properties/parameters as well.
  - Add extern C and visibility attribute to LV2_SYMBOL_EXPORT.
  - Add lv2:isSideChain port property.
Version 12.2 (2014-08-08)
  - Clarify lv2_descriptor() and lv2_lib_descriptor() documentation.
Version 12.0 (2014-01-04)
  - Add lv2:prototype for property inheritance.
Version 10.0 (2013-02-17)
  - Reserve minor version 0 for unstable development plugins.
  - Add lv2:EnvelopePlugin class.
  - Add lv2:control for designating primary event-based control ports.
  - Set range of lv2:designation to lv2:Designation.
  - Make lv2:Parameter rdfs:subClassOf rdf:Property.
Version 8.2 (2012-10-14)
  - Use consistent label style.
Version 8.0 (2012-04-17)
  - Fix LV2_SYMBOL_EXPORT and lv2_descriptor prototype for Windows.
  - Add metadata concept of a designation, a channel or parameter description which can be assigned to ports for more intelligent use by hosts.
  - Add new discovery API which allows libraries to read bundle files during discovery, makes library construction/destruction explicit, and adds extensibility to prevent future breakage.
  - Relax the range of lv2:index so it can be used for things other than ports.
  - Remove lv2:Resource, which turned out to be meaningless.
  - Add lv2:CVPort.
  - Merge with unified LV2 package.
Version 6.0 (2011-11-21)
  - Rename core.lv2 and lv2.ttl to lv2core.lv2 and lv2core.ttl to adhere to modern conventions.
  - Add lv2:extensionData and lv2:ExtensionData for plugins to indicate that they support some URI for extension_data().
  - Remove lv2config in favour of the simple convention that specifications install headers to standard URI-based paths.
  - Switch to the ISC license, a simple BSD-style license (with permission of all contributors to lv2.h and its ancestor, ladspa.h).
  - Make lv2core.ttl a valid OWL 2 DL ontology.
  - Improve documentation.
Version 4.0 (2011-03-18)
  - Make doap:license suggested, but not required (for wrappers).
  - Define lv2:binary (MUST be in manifest.ttl).
  - Define lv2:minorVersion and lv2:microVersion (MUST be in manifest.ttl).
  - Define lv2:documentation and use it to document lv2core.
  - Add lv2:FunctionPlugin and lv2:ConstantPlugin classes.
  - Move lv2:AmplifierPlugin under lv2:DynamicsPlugin.
  - Loosen domain of lv2:optionalFeature and lv2:requiredFeature (to allow re-use in extensions).
  - Add generic lv2:Resource and lv2:PluginBase classes.
  - Fix definition of lv2:minimum etc. (used for values, not scale points).
  - More precisely define properties with OWL.
  - Move project metadata to manifest.
  - Add lv2:enumeration port property.
  - Define run() pre-roll special case (sample_count == 0).
Version 3.0 (2008-11-08)
  - Require that serialisations refer to ports by symbol rather than index.
  - Minor stylistic changes to lv2.ttl.
  - No header changes.
Version 2.0 (2008-02-10)
  - Initial release.