The maximum block length the host will ever request the plugin to process at
10: once, that is, the maximum sample_count parameter that will ever be passed to
11: LV2_Descriptor::run().
The minimum block length the host will ever request the plugin to process at
10: once, that is, the minimum sample_count parameter that will ever be passed to
11: LV2_Descriptor::run().
The typical block length the host will request the plugin to process at once,
10: that is, the typical sample_count parameter that will be passed to
11: LV2_Descriptor::run(). This will usually be equivalent, or close to, the
12: maximum block length, but there are no strong guarantees about this value
13: whatsoever. Plugins may use this length for optimization purposes, but MUST
14: NOT assume the host will always process blocks of this length. In particular,
15: the host MAY process longer blocks.
This should be provided as an option by hosts that support event ports 10: (including but not limited to MIDI), so plugins have the ability to allocate 11: auxiliary buffers large enough to copy the input.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/buf-size#boundedBlockLength Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A feature that indicates the host will provide both the minBlockLength 10: and maxBlockLength options to the plugin. Plugins that copy data from 11: audio inputs can require this feature to ensure they know how much space is 12: required for auxiliary buffers. Note the minimum may be zero, this feature is 13: mainly useful to ensure a maximum is available.
14:All hosts SHOULD support this feature, since it is simple to support and 15: necessary for any plugins that may need to copy the input.
16: 17: Invalid documentation for http://lv2plug.in/ns/ext/buf-size#coarseBlockLength Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A feature that indicates the plugin prefers coarse, regular block lengths. For 10: example, plugins that do not implement sample-accurate control use this feature 11: to indicate that the host should not split the run cycle because controls have 12: changed.
13:Note that this feature is merely a hint, and does not guarantee a fixed block 14: length. The run cycle may be split for other reasons, and the blocksize itself 15: may change anytime.
16: 17: Invalid documentation for http://lv2plug.in/ns/ext/buf-size#fixedBlockLength Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A feature that indicates the host will always call LV2_Descriptor::run() with 10: the same value for sample_count. This length MUST be provided as the value of 11: both the minBlockLength and maxBlockLength options.
12:Note that requiring this feature may severely limit the number of hosts capable 13: of running the plugin.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/buf-size#powerOf2BlockLength Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A feature that indicates the host will always call LV2_Descriptor::run() with a 10: power of two sample_count. Note that this feature does not guarantee the value 11: is the same each call, to guarantee a fixed power of two block length plugins 12: must require both this feature and fixedBlockLength.
13:Note that requiring this feature may severely limit the number of hosts capable 14: of running the plugin.
15: 16: Invalid documentation for http://lv2plug.in/ns/ext/buf-size Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension defines a facility for plugins to get information about the 10: block length (the sample_count parameter of LV2_Descriptor::run) and port 11: buffer sizes, as well as several features which can be used to restrict the 12: block length.
13:This extension defines features and properties but has no special purpose 14: API of its own. The host provides all the relevant information to the plugin 15: as options.
16:To require restrictions on the block length, plugins can require additional 17: features: boundedBlockLength, powerOf2BlockLength, and 18: fixedBlockLength. These features are data-only, that is they merely 19: indicate a restriction and do not carry any data or API.
20: 21: [16/52] Generating doc/ns/ext/atom.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() Invalid documentation for http://lv2plug.in/ns/ext/atom#Atom Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:An LV2_Atom has a 32-bit size and type, followed by a body of size bytes.
10: Atoms MUST be 64-bit aligned.
All concrete Atom types (subclasses of this class) MUST define a precise binary 12: layout for their body.
13:The type field is the URI of an Atom type mapped to an integer.
14: Implementations SHOULD gracefully pass through, or ignore, atoms with unknown
15: types.
All atoms are POD by definition except references, which as a special case have
17: type 0. An Atom MUST NOT contain a Reference. It is safe to copy any
18: non-reference Atom with a simple memcpy, even if the implementation does not
19: understand type. Though this extension reserves the type 0 for references,
20: the details of reference handling are currently unspecified. A future revision
21: of this extension, or a different extension, may define how to use non-POD data
22: and references. Implementations MUST NOT send references to another
23: implementation unless the receiver is explicitly known to support references
24: (e.g. by supporting a feature).
The special case of a null atom with both type and size 0 is not considered
26: a reference.
Ports of this type are connected to an LV2_Atom with a type specified by 10: bufferType.
11:Output ports with a variably sized type MUST be initialised by the host before 12: every run() to an Chunk with size set to the available space. The plugin 13: reads this size to know how much space is available for writing. In all cases, 14: the plugin MUST write a complete atom (including header) to outputs. However, 15: to be robust, hosts SHOULD initialise output ports to a safe sentinel (e.g. the 16: null Atom) before calling run().
17: 18: Invalid documentation for http://lv2plug.in/ns/ext/atom#Blank Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This class is deprecated. Use Object with ID 0 instead.
10:An Object where the LV2_Atom_Object::id is a blank node ID (NOT a URI). 11: The ID of a Blank is valid only within the context the Blank appears in. For 12: ports this is the context of the associated run() call, i.e. all ports share 13: the same context so outputs can contain IDs that correspond to IDs of blanks in 14: the input.
15: 16: Invalid documentation for http://lv2plug.in/ns/ext/atom#Chunk Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This type is used to indicate a certain amount of space is available. For 10: example, output ports with a variably sized type are connected to a Chunk so 11: the plugin knows the size of the buffer available for writing.
12:The use of a Chunk should be constrained to a local scope, since 13: interpreting it is impossible without context. However, if serialised to RDF, 14: a Chunk may be represented directly as an xsd:base64Binary string, for example:
15:[] eg:someChunk "vu/erQ=="^^xsd:base64Binary .
16: An Event is typically an element of an Sequence. Note that this is not an Atom type since it begins with a timestamp, not an atom header.
10: 11: Invalid documentation for http://lv2plug.in/ns/ext/atom#Literal Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This type is compatible with rdfs:Literal and is capable of expressing a
10: string in any language or a value of any type. A Literal has a
11: datatype and lang followed by string data in UTF-8
12: encoding. The length of the string data in bytes is size -
13: sizeof(LV2_Atom_Literal), including the terminating NULL character. The
14: lang field SHOULD be a URI of the form
15: http://lexvo.org/id/iso639-3/LANG or
16: http://lexvo.org/id/iso639-1/LANG where LANG is a 3-character ISO 693-3
17: language code, or a 2-character ISO 693-1 language code, respectively.
A Literal may have a datatype or a lang, but never both.
For example, a Literal can be Hello
in English:
void set_to_hello_in_english(LV2_Atom_Literal* lit) {
21: lit->atom.type = map(expand("Literal"));
22: lit->atom.size = 14;
23: lit->body.datatype = 0;
24: lit->body.lang = map("http://lexvo.org/id/iso639-1/en");
25: memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit),
26: "Hello",
27: sizeof("Hello")); // Assumes enough space
28: }
29: or a Turtle string:
32:void set_to_turtle_string(LV2_Atom_Literal* lit, const char* ttl) {
33: lit->atom.type = map(expand("Literal"));
34: lit->atom.size = 64;
35: lit->body.datatype = map("http://www.w3.org/2008/turtle#turtle");
36: lit->body.lang = 0;
37: memcpy(LV2_ATOM_CONTENTS(LV2_Atom_Literal, lit),
38: ttl,
39: strlen(ttl) + 1); // Assumes enough space
40: }
41: An Object
is an atom with a set of properties. This corresponds to an
10: RDF Resource, and can be thought of as a dictionary with URID keys.
An LV2_Atom_Object body has a uint32_t id and type, followed by a series of
12: Property bodies (LV2_Atom_Property_Body). The LV2_Atom_Object_Body::otype
13: field is equivalent to a property with key rdf:type, but is included in the
14: structure to allow for fast dispatching.
Code SHOULD check for objects using lv2_atom_forge_is_object() or 16: lv2_atom_forge_is_blank() if a forge is available, rather than checking the 17: atom type directly. This will correctly handle the deprecated Resource 18: and Blank types.
19:When serialised to RDF, an Object is represented as a resource, for example:
20:eg:someObject
21: eg:firstPropertyKey "first property value" ;
22: eg:secondPropertyKey "first loser" ;
23: eg:andSoOn "and so on" .
24: A Path is a URI reference with only a path component: no scheme, authority, 10: query, or fragment. In particular, paths to files in the same bundle may be 11: cleanly written in Turtle files as a relative URI. However, implementations 12: may assume any binary Path (e.g. in an event payload) is a valid file path 13: which can passed to system functions like fopen() directly, without any 14: character encoding or escape expansion required.
15:Any implementation that creates a Path atom to transmit to another is 16: responsible for ensuring it is valid. A Path SHOULD always be absolute, unless 17: there is some mechanism in place that defines a base path. Since this is not 18: the case for plugin instances, effectively any Path sent to or received from a 19: plugin instance MUST be absolute.
20: 21: Invalid documentation for http://lv2plug.in/ns/ext/atom#Property Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:An LV2_Atom_Property has a URID key and context, and an Atom value. This
10: corresponds to an RDF Property, where the key
is the predicate
11: and the value
is the object.
The context field can be used to specify a different context for each
13: property, where this is useful. Otherwise, it may be 0.
Properties generally only exist as part of an Object. Accordingly, 15: they will typically be represented directly as properties in RDF (see 16: Object). If this is not possible, they may be expressed as partial 17: reified statements, for example:
18:eg:someProperty
19: rdf:predicate eg:theKey ;
20: rdf:object eg:theValue .
21: This class is deprecated. Use Object directly instead.
10:An Object where the id field is a URID, that is, an Object
11: with a URI.
A flat sequence of Event, that is, a series of time-stamped Atoms.
10:LV2_Atom_Sequence_Body.unit describes the time unit for the contained atoms. 11: If the unit is known from context (e.g. run() stamps are always audio frames), 12: this field may be zero. Otherwise, it SHOULD be either units:frame or 13: units:beat, in which case ev.time.frames or ev.time.beats is valid, 14: respectively.
15:If serialised to RDF, a Sequence has a similar form to Vector, but for 16: brevity the elements may be assumed to be Event, for example:
17:eg:someSequence
18: a atom:Sequence ;
19: rdf:value (
20: [
21: atom:frameTime 1 ;
22: rdf:value "901A01"^^midi:MidiEvent
23: ] [
24: atom:frameTime 3 ;
25: rdf:value "902B02"^^midi:MidiEvent
26: ]
27: ) .
28: The format of a Sound is the same as the buffer format for lv2:AudioPort 10: (except the size may be arbitrary). An Sound inherently depends on the 11: sample rate, which is assumed to be known from context. Because of this, 12: directly serialising an Sound is probably a bad idea, use a standard 13: format like WAV instead.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/atom#String Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The body of an LV2_Atom_String is a C string in UTF-8 encoding, i.e. an array
10: of bytes (uint8_t) terminated with a NULL byte ('\0').
This type is for free-form strings, but SHOULD NOT be used for typed data or 12: text in any language. Use Literal unless translating the string does not 13: make sense and the string has no meaningful datatype.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/atom#Tuple Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78)/var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/atom.lv2/atom.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) 1: 2: 4: 5: 6:The body of a Tuple is simply a series of complete atoms, each aligned to 10: 64 bits.
11:If serialised to RDF, a Tuple SHOULD have the form:
12:eg:someVector
13: a atom:Tuple ;
14: rdf:value (
15: "1"^^xsd:int
16: "3.5"^^xsd:float
17: "etc"
18: ) .
19: This is useful when a URI is needed but mapping is inappropriate, for example 10: with temporary or relative URIs. Since the ability to distinguish URIs from 11: plain strings is often necessary, URIs MUST NOT be transmitted as String.
12:This is not strictly a URI, since UTF-8 is allowed. Escaping and related 13: issues are the host's responsibility.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/atom#URID Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A URID is typically generated with the LV2_URID_Map provided by the host .
10: 11: Invalid documentation for http://lv2plug.in/ns/ext/atom#Vector Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A homogeneous series of atom bodies with equivalent type and size.
10:An LV2_Atom_Vector is a 32-bit child_size and child_type followed by size
11: / child_size atom bodies.
For example, an Vector containing 42 elements of type Float:
13:struct VectorOf42Floats {
14: uint32_t size; // sizeof(LV2_Atom_Vector_Body) + (42 * sizeof(float);
15: uint32_t type; // map(expand("Vector"))
16: uint32_t child_size; // sizeof(float)
17: uint32_t child_type; // map(expand("Float"))
18: float elems[42];
19: };
20: Note that it is possible to construct a valid Atom for each element of the
23: vector, even by an implementation which does not understand child_type.
If serialised to RDF, a Vector SHOULD have the form:
25:eg:someVector
26: a atom:Vector ;
27: atom:childType atom:Int ;
28: rdf:value (
29: "1"^^xsd:int
30: "2"^^xsd:int
31: "3"^^xsd:int
32: "4"^^xsd:int
33: ) .
34: Indicates that an AtomPort may be connected to a certain Atom type. A port MAY 10: support several buffer types. The host MUST NOT connect a port to an Atom with 11: a type not explicitly listed with this property. The value of this property 12: MUST be a sub-class of Atom. For example, an input port that is connected 13: directly to an LV2_Atom_Double value is described like so:
14:<plugin>
15: lv2:port [
16: a lv2:InputPort , atom:AtomPort ;
17: atom:bufferType atom:Double ;
18: ] .
19: This property only describes the types a port may be directly connected to. It 22: says nothing about the expected contents of containers. For that, use 23: supports.
24: 25: Invalid documentation for http://lv2plug.in/ns/ext/atom#supports Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This property is defined loosely, it may be used to indicate that anything
10: supports
an Atom type, wherever that may be useful. It applies
11: recursively
where collections are involved.
In particular, this property can be used to describe which event types are 13: expected by a port. For example, a port that receives MIDI events is described 14: like so:
15:<plugin>
16: lv2:port [
17: a lv2:InputPort , atom:AtomPort ;
18: atom:bufferType atom:Sequence ;
19: atom:supports midi:MidiEvent ;
20: ] .
21: Transfer of the complete atom in a port buffer. Useful as the format for a
10: LV2UI_Write_Function.
This protocol applies to atom ports. The host must transfer the complete atom 12: contained in the port, including header.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/atom#eventTransfer Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Transfer of individual events in a port buffer. Useful as the format for a
10: LV2UI_Write_Function.
This protocol applies to ports which contain events, usually in an 12: Sequence. The host must transfer each individual event to the recipient. 13: The format of the received data is an LV2_Atom, there is no timestamp header.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/atom Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:An Atom is a simple generic data container for holding any type of Plain
10: Old Data (POD). An Atom can contain simple primitive types like integers,
11: floating point numbers, and strings; as well as structured data like lists and
12: dictionary-like Objects
. Since Atoms are POD, they can be easily copied
13: (for example, with memcpy()) anywhere and are suitable for use in real-time
14: code.
Every atom starts with an LV2_Atom header, followed by the contents. This 16: allows code to process atoms without requiring special code for every type of 17: data. For example, plugins that mutually understand a type can be used 18: together in a host that does not understand that type, because the host is only 19: required to copy atoms, not interpret their contents. Similarly, plugins (such 20: as routers, delays, or data structures) can meaningfully process atoms of a 21: type unknown to them.
22:Atoms should be used anywhere values of various types must be stored or 23: transmitted. An AtomPort can be used to transmit atoms via ports. An 24: AtomPort that contains a Sequence can be used for sample accurate 25: communication of events, such as MIDI.
26:Each Atom type defines a binary format for use at runtime, but also a 28: serialisation that is natural to express in Turtle format. Thus, this 29: specification defines a powerful real-time appropriate data model, as well as a 30: portable way to serialise any data in that model. This is particularly useful 31: for inter-process communication, saving/restoring state, and describing values 32: in plugin data files.
33:While it is possible to define new Atom types for any binary format, the
35: standard types defined here are powerful enough to describe almost anything.
36: Implementations SHOULD build structures out of the types provided here, rather
37: than define new binary formats (for example, using Object rather than a
38: new C struct type). Host and tool implementations have support for
39: serialising all standard types, so new binary formats are an implementation
40: burden which harms interoperabilty. In particular, plugins SHOULD NOT expect
41: UI communication or state saving with custom binary types to work. In general,
42: new Atom types should only be defined where absolutely necessary due to
43: performance reasons and serialisation is not a concern.
This extension defines a feature, LV2_Extension_Data_Feature, which provides 10: access to LV2_Descriptor::extension_data() for plugin UIs or other potentially 11: remote users of a plugin.
12:Note that the use of this extension by UIs violates the important principle of 13: UI/plugin separation, and is potentially a source of many problems. 14: Accordingly, use of this extension is highly discouraged, and plugins 15: should not expect hosts to support it, since it is often impossible to do so.
16:To support this feature the host must pass an LV2_Feature struct to 17: LV2_Descriptor::extension_data() with URI LV2_DATA_ACCESS_URI and data pointed 18: to an instance of LV2_Extension_Data_Feature.
19: 20: [18/52] Generating doc/ns/lv2core.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() Invalid documentation for http://lv2plug.in/ns/lv2core#AudioPort Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Ports of this type are connected to a buffer of float audio samples, which
10: the host guarantees have sample_count elements in any call to
11: LV2_Descriptor::run().
Audio samples are normalized between -1.0 and 1.0, though there is no 13: requirement for samples to be strictly within this range.
14: 15: Invalid documentation for http://lv2plug.in/ns/lv2core#CVPort Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Ports of this type have the same buffer format as an AudioPort, except the 10: buffer represents audio-rate control data rather than audio. Like a 11: ControlPort, a CV port SHOULD have properties describing its value, in 12: particular minimum, maximum, and default.
13:Hosts may present CV ports to users as controls in the same way as control 14: ports. Conceptually, aside from the buffer format, a CV port is the same as a 15: control port, so hosts can use all the same properties and expectations.
16:In particular, this port type does not imply any range, unit, or meaning for 17: its values. However, if there is no inherent unit to the values, for example 18: if the port is used to modulate some other value, then plugins SHOULD use a 19: normalized range, either from -1.0 to 1.0, or from 0.0 to 1.0.
20:It is generally safe to connect an audio output to a CV input, but not 21: vice-versa. Hosts must take care to prevent data from a CVPort port from being 22: used as audio.
23: 24: Invalid documentation for http://lv2plug.in/ns/lv2core#Channel Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A specific channel, for example the left
channel of a stereo stream. A
10: channel may be audio, or another type such as a MIDI control stream.
A designation is metadata that describes the meaning or role of something. By 10: assigning a designation to a port using designation, the port's content 11: becomes meaningful and can be used more intelligently by the host.
12: 13: Invalid documentation for http://lv2plug.in/ns/lv2core#ExtensionData Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is additional data that a plugin may return from 10: LV2_Descriptor::extension_data(). This is generally used to add APIs to extend 11: that defined by LV2_Descriptor.
12: 13: Invalid documentation for http://lv2plug.in/ns/lv2core#Markdown Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This datatype is typically used for documentation in 10: Markdown syntax.
11:Generally, documentation with this datatype should stay as close to readable 12: plain text as possible, but may use core Markdown syntax for nicer 13: presentation. Documentation can assume that basic extensions like codehilite 14: and tables are available.
15: 16: Invalid documentation for http://lv2plug.in/ns/lv2core#Parameter Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A parameter is a designation for a control.
10:A parameter defines the meaning of a control, not the method of conveying its 11: value. For example, a parameter could be controlled via a ControlPort, 12: messages, or both.
13:A ControlPort can be associated with a parameter using designation.
14: 15: Invalid documentation for http://lv2plug.in/ns/lv2core#Plugin Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:To be discovered by hosts, plugins MUST explicitly have an rdf:type of Plugin 10: in their bundle's manifest, for example:
11:<http://example.org/my-plugin> a lv2:Plugin .
12: Plugins should have a doap:name property that is at most a few words in length
15: using title capitalization, for example Tape Delay Unit
.
An abstract plugin-like resource that may not actually be an LV2 plugin, for 10: example that may not have a binary. This is useful for describing things 11: that share common structure with a plugin, but are not themselves an actual 12: plugin, such as presets.
13: 14: Invalid documentation for http://lv2plug.in/ns/lv2core#Point Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A Point MUST have at least one rdfs:label which is a string.
12:A Point MUST have exactly one rdf:value with a type that is compatible with 15: the type of the corresponding Port.
16:All LV2 port descriptions MUST have a rdf:type that is one of Port, 10: InputPort or OutputPort. Additionally, there MUST be at least one 11: other rdf:type which more precisely describes type of the port, for example 12: AudioPort.
13:Hosts that do not support a specific port class MUST NOT instantiate the 14: plugin, unless that port has the connectionOptional property set.
15:A port has two identifiers: a (numeric) index, and a (textual) symbol. The 16: index can be used as an identifier at run-time, but persistent references to 17: ports (for example in presets or save files) MUST use the symbol. Only the 18: symbol is guaranteed to refer to the same port on all plugins with a given URI, 19: that is the index for a port may differ between plugin binaries.
20: 21: Invalid documentation for http://lv2plug.in/ns/lv2core#PortBase Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Similar to PluginBase, this is an abstract port-like resource that may not 10: be a fully specified LV2 port. For example, this is used for preset "ports" 11: which do not specify an index.
12: 13: Invalid documentation for http://lv2plug.in/ns/lv2core#Specification Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:An LV2 specification typically contains a vocabulary description, C headers to 10: define an API, and any other resources that may be useful. Specifications, 11: like plugins, are distributed and installed as bundles so that hosts may 12: discover them.
13: 14: Invalid documentation for http://lv2plug.in/ns/lv2core#Symbol Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The first character of a symbol must be one of _, a-z or A-Z, and
10: subsequent characters may additionally be 0-9. This is, among other things,
11: a valid C identifier, and generally compatible in most contexts which have
12: restrictions on string identifiers, such as file paths.
This is primarily intended for discovery purposes: bundles that describe
10: resources that work with particular plugins (like presets or user interfaces)
11: SHOULD specify this in their manifest.ttl so the host can associate them with
12: the correct plugin. For example:
<thing>
14: a ext:Thing ;
15: lv2:appliesTo <plugin> ;
16: rdfs:seeAlso <thing.ttl> .
17: Using this pattern is preferable for large amounts of data, since the host may 20: choose whether/when to load the data.
21: 22: Invalid documentation for http://lv2plug.in/ns/lv2core#binary Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The value of this property must be the URI of a shared library object, 10: typically in the same bundle as the data file which contains this property. 11: The actual type of the library is platform specific.
12:This is a required property of a Plugin which MUST be included in the
13: bundle's manifest.ttl file. The binary of a Plugin is the shared
14: object containing the lv2_descriptor() or lv2_lib_descriptor() function. This
15: probably may also be used similarly by extensions to relate other resources to
16: their implementations (it is not implied that a binary on an arbitrary
17: resource is an LV2 plugin library).
The host SHOULD set the port to this value initially, and in any situation 10: where the port value should be cleared or reset.
11: 12: Invalid documentation for http://lv2plug.in/ns/lv2core#designation Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This property is used to give a port's contents a well-defined meaning. For
10: example, if a port has the designation eg:gain, then the value of that port
11: represents the eg:gain of the plugin instance.
Ports should be given designations whenever possible, particularly if a 13: suitable designation is already defined. This allows the host to act more 14: intelligently and provide a more effective user interface. For example, if the 15: plugin has a BPM parameter, the host may automatically set that parameter to 16: the current tempo.
17: 18: Invalid documentation for http://lv2plug.in/ns/lv2core#documentation Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Relates a Resource to extended documentation.
10:LV2 specifications are documented using this property with an Markdown 11: datatype.
12:If the value has no explicit datatype, it is assumed to be a valid XHTML Basic
13: 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 15: intended to be reasonable to implement with limited resources, for exampe on 16: embedded devices. See XHTML Basic, Section 17: 3 for a list of valid tags.
18: 19: Invalid documentation for http://lv2plug.in/ns/lv2core#enabled Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:If this value is greater than zero, the plugin processes normally. If this 10: value is zero, the plugin is expected to bypass all signals unmodified. The 11: plugin must provide a click-free transition between the enabled and disabled 12: (bypassed) states.
13:Values less than zero are reserved for future use (such as click-free 14: insertion/removal of latent plugins), and should be treated like zero 15: (bypassed) by current implementations.
16: 17: Invalid documentation for http://lv2plug.in/ns/lv2core#extensionData Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:If a plugin has a value for this property, it must be a URI that defines the 10: extension data. The plugin should return the appropriate data when 11: LV2_Descriptor::extension_data() is called with that URI as a parameter.
12: 13: Invalid documentation for http://lv2plug.in/ns/lv2core#freeWheeling Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:If true, this means that all processing is happening as quickly as possible, 10: not in real-time. When free-wheeling there is no relationship between the 11: passage of real wall-clock time and the passage of time in the data being 12: processed.
13: 14: Invalid documentation for http://lv2plug.in/ns/lv2core#maximum Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is a soft limit: the plugin is required to gracefully accept all values in 10: the range of a port's data type.
11: 12: Invalid documentation for http://lv2plug.in/ns/lv2core#microVersion Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Releases of plugins and extensions MUST be explicitly versioned. Correct 10: version numbers MUST always be maintained for any versioned resource that is 11: published. For example, after a release, if a change is made in the development 12: version in source control, the micro version MUST be incremented (to an odd 13: number) to distinguish this modified version from the previous release.
14:This property describes half of a resource version. For detailed documentation 15: on LV2 resource versioning, see minorVersion.
16: 17: Invalid documentation for http://lv2plug.in/ns/lv2core#minimum Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is a soft limit: the plugin is required to gracefully accept all values in 10: the range of a port's data type.
11: 12: Invalid documentation for http://lv2plug.in/ns/lv2core#minorVersion Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This, along with microVersion, is used to distinguish between different
10: versions of the same
resource, for example to load only the bundle with
11: the most recent version of a plugin. An LV2 version has a minor and micro
12: number with the usual semantics:
The minor version MUST be incremented when backwards (but not forwards) 16: compatible additions are made, for example the addition of a port to a 17: plugin.
18:The micro version is incremented for changes which do not affect 21: compatibility at all, for example bug fixes or documentation updates.
22:Note that there is deliberately no major version: all versions with the same 25: URI are compatible by definition. Replacing a resource with a newer version of 26: that resource MUST NOT break anything. If a change violates this rule, then 27: the URI of the resource (which serves as the major version) MUST be changed.
28:Plugins and extensions MUST adhere to at least the following rules:
29:All versions of a plugin with a given URI MUST have the same
set of
32: mandatory (not connectionOptional) ports with respect to symbol and
33: rdf:type. In other words, every port on a particular version is guaranteed
34: to exist on a future version with same symbol and at least those
35: rdf:types.
New ports MAY be added without changing the plugin URI if and only if they 39: are connectionOptional and the minor version is incremented.
40:The minor version MUST be incremented if the index of any port (identified 43: by its symbol) is changed.
44:All versions of a specification MUST be compatible in the sense that an 47: implementation of the new version can interoperate with an implementation 48: of any previous version.
49:Anything that depends on a specific version of a plugin (including referencing 52: ports by index) MUST refer to the plugin by both URI and version. However, 53: implementations should be tolerant where possible.
54:When hosts discover several installed versions of a resource, they SHOULD warn 55: the user and load only the most recent version.
56:An odd minor or micro version, or minor version zero, indicates that the 57: resource is a development version. Hosts and tools SHOULD clearly indicate 58: this wherever appropriate. Minor version zero is a special case for 59: pre-release development of plugins, or experimental plugins that are not 60: intended for stable use at all. Hosts SHOULD NOT expect such a plugin to 61: remain compatible with any future version. Where feasible, hosts SHOULD NOT 62: expose such plugins to users by default, but may provide an option to display 63: them.
64: 65: Invalid documentation for http://lv2plug.in/ns/lv2core#name Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Unlike symbol, this is unrestricted, may be translated, and is not relevant 10: for compatibility. The name is not necessarily unique and MUST NOT be used as 11: an identifier.
12: 13: Invalid documentation for http://lv2plug.in/ns/lv2core#optionalFeature Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:To support this feature, the host MUST pass its URI and any additional data to 10: the plugin in LV2_Descriptor::instantiate().
11:The plugin MUST NOT fail to instantiate if an optional feature is not supported 12: by the host.
13: 14: Invalid documentation for http://lv2plug.in/ns/lv2core#portProperty Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:States that a port has a particular PortProperty. This may be ignored 10: without catastrophic effects, though it may be useful, for example to provide a 11: sensible user interface for the port.
12: 13: Invalid documentation for http://lv2plug.in/ns/lv2core#project Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This property provides a way to group plugins and/or related resources. A 10: project may have useful metadata common to all plugins (such as homepage, 11: author, version history) which would be wasteful to list separately for each 12: plugin.
13:Grouping via projects also allows users to find plugins in hosts by project,
14: which is often how they are remembered. For this reason, a project that
15: contains plugins SHOULD always have a doap:name. It is also a good idea for
16: each plugin and the project itself to have an symbol property, which allows
17: nice quasi-global identifiers for plugins, for example myproj.superamp which
18: can be useful for display or fast user entry.
This property can be used to include
common properties in several
10: descriptions, serving as a sort of template mechanism. If a plugin has a
11: prototype, then the host must load all the properties for the prototype as if
12: they were properties of the plugin. That is, if :plug prototype :prot,
13: 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 15: common binary, for example those where the internal state is loaded from some 16: other file. Such plugins can refer to a prototype in a template LV2 bundle 17: which is installed by the corresponding software.
18: 19: Invalid documentation for http://lv2plug.in/ns/lv2core#requiredFeature Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:To support this feature, the host MUST pass its URI and any additional data to 10: the plugin in LV2_Descriptor::instantiate().
11:The host MUST check this property before attempting to instantiate a plugin, 12: and not attempt to instantiate plugins which require features it does not 13: support. The plugin MUST fail to instantiate if a required feature is not 14: supported by the host. Note that these rules are intentionally redundant for 15: resilience: neither host nor plugin should assume that the other does not 16: violate them.
17: 18: Invalid documentation for http://lv2plug.in/ns/lv2core#shortName Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is the same as name, with the additional requirement that the value is 10: shorter than 16 characters.
11: 12: Invalid documentation for http://lv2plug.in/ns/lv2core#symbol Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The value of this property MUST be a valid Symbol, and MUST NOT have a 10: language tag.
11:A symbol is a unique identifier with respect to the parent, for example a 12: port's symbol is a unique identifiers with respect to its plugin. The plugin 13: author MUST change the plugin URI if any port symbol is changed or removed.
14: 15: Invalid documentation for http://lv2plug.in/ns/lv2core#connectionOptional Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This property means that the port does not have to be connected to valid data
10: by the host. To leave a port unconnected
, the host MUST explicitly
11: connect the port to NULL.
This should be used as the designation of ports that are used to send 10: commands and receive responses. Typically this will be an event port that 11: supports some protocol, for example MIDI or LV2 Atoms.
12: 13: Invalid documentation for http://lv2plug.in/ns/lv2core#enumeration Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that all the rasonable values for a port are defined by 10: 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.
11:Note that this is only a hint, and that the plugin MUST operate reasonably even 12: if such a port has a value that does not correspond to a scale point.
13: 14: Invalid documentation for http://lv2plug.in/ns/lv2core#hardRTCapable Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This feature indicates that the plugin is capable of running in a hard
10: real-time
environment. This should be the case for most audio processors,
11: so most plugins are expected to have this feature.
To support this feature, plugins MUST adhere to the following in all of their 13: audio class functions (LV2_Descriptor::run() and 14: LV2_Descriptor::connect_port()):
15:There is no use of malloc(), free() or any other heap memory management
18: functions.
There is no use of any library functions which do not adhere to these 22: rules. The plugin may assume that the standard C math library functions 23: are safe.
24:There is no access to files, devices, pipes, sockets, system calls, or any 27: other mechanism that might result in the process or thread blocking.
28:The maximum amount of time for a run() call is bounded by some expression
31: of the form A + B * sample_count, where A and B are platform specific
32: constants. Note that this bound does not depend on input signals or plugin
33: state.
This feature indicates that the plugin may not work correctly if the host
10: elects to use the same data location for both input and output. Plugins that
11: will fail to work correctly if ANY input port is connected to the same location
12: as ANY output port MUST require this feature. Doing so should be avoided
13: whenever possible since it prevents hosts from running the plugin on data
14: in-place
.
Indicates that all the reasonable values for a port are integers. For such 10: ports, a user interface should provide a stepped control that only allows 11: choosing integer values.
12:Note that this is only a hint, and that the plugin MUST operate reasonably even 13: if such a port has a non-integer value.
14: 15: Invalid documentation for http://lv2plug.in/ns/lv2core#isLive Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This feature is for plugins that have time-sensitive internals, for example
10: communicating in real time over a socket. It indicates to the host that its
11: input and output must not be cached or subject to significant latency, and that
12: calls to LV2_Descriptor::run() should be made at a rate that roughly
13: corresponds to wall clock time (according to the sample_count parameter).
Note that this feature is not related to hard real-time
execution
15: requirements (see hardRTCapable).
Indicates that a port is a sidechain
, which affects the output somehow
10: but should not be considered a part of the main signal chain. Sidechain ports
11: SHOULD be connectionOptional, and may be ignored by hosts.
This property indicates that the port is used to express the processing latency
10: incurred by the plugin, expressed in samples. The latency may be affected by
11: the current sample rate, plugin settings, or other factors, and may be changed
12: by the plugin at any time. Where the latency is frequency dependent the plugin
13: may choose any appropriate value. If a plugin introduces latency it MUST
14: provide EXACTLY ONE port with this property set. In fuzzy
cases the
15: value should be the most reasonable one based on user expectation of
16: input/output alignment. For example, musical delay plugins should not report
17: their delay as latency, since it is an intentional effect that the host should
18: not compensate for.
This property is deprecated, use a designation of latency instead, 20: following the same rules as above:
21:<http://example.org/plugin>
22: lv2:port [
23: a lv2:OutputPort , lv2:ControlPort ;
24: lv2:designation lv2:latency ;
25: lv2:symbol "latency" ;
26: ]
27: Indicates that any specified bounds should be interpreted as multiples of the 10: sample rate. For example, a frequency range from 0 Hz to the Nyquist frequency 11: (half the sample rate) can be specified by using this property with minimum 12: 0.0 and maximum 0.5. Hosts that support bounds at all MUST support this 13: property.
14: 15: Invalid documentation for http://lv2plug.in/ns/lv2core#toggled Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that the data item should be considered a boolean toggle. Data less
10: than or equal to zero should be considered off
or false
, and data
11: above zero should be considered on
or true
.
LV2 is an interface for writing audio plugins in C or compatible languages, 10: which can be dynamically loaded into many host applications. This core 11: specification is simple and minimal, but is designed so that extensions can 12: be defined to add more advanced features, making it possible to implement 13: nearly any feature.
14:LV2 maintains a strong distinction between code and data. Plugin code is in a 15: shared library, while data is in a companion data file written in 16: Turtle. Code, data, and any other resources 17: (such as waveforms) are shipped together in a bundle directory. The code 18: contains only the executable portions of the plugin. All other data is 19: provided in the data file(s). This makes plugin data flexible and extensible, 20: and allows the host to do everything but run the plugin without loading or 21: executing any code. Among other advantages, this makes hosts more robust 22: (broken plugins can't crash a host during discovery) and allows generic tools 23: written in any language to work with LV2 data. The LV2 specification itself is 24: distributed in a similar way.
25:An LV2 plugin library is suitable for dynamic loading (for example with
26: dlopen()) and provides one or more plugin descriptors via lv2_descriptor()
27: or lv2_lib_descriptor(). These can be instantiated to create plugin
28: instances, which can be run directly on data or connected together to perform
29: advanced signal processing tasks.
Plugins communicate via ports, which can transmit any type of data. Data is
31: processed by first connecting each port to a buffer, then repeatedly calling
32: the run() method to process blocks of data.
This core specification defines two types of port, equivalent to those in
34: LADSPA, ControlPort and AudioPort, as well as
35: CVPort which has the same format as an audio port but is interpreted as
36: non-audible control data. Audio ports contain arrays with one float element
37: per sample, allowing a block of audio to be processed in a single call to
38: run(). Control ports contain single float values, which are fixed and
39: valid for the duration of the call to run(). Thus the control rate is
40: determined by the block size, which is controlled by the host (and not
41: necessarily constant).
To facilitate use in multi-threaded programs, LV2 functions are partitioned into 44: several threading classes:
45:| Discovery Class | 48:Instantiation Class | 49:Audio Class | 50:
|---|---|---|
| lv2_descriptor() | 53:LV2_Descriptor::instantiate() | 54:LV2_Descriptor::run() | 55:
| lv2_lib_descriptor() | 58:LV2_Descriptor::cleanup() | 59:LV2_Descriptor::connect_port() | 60:
| LV2_Descriptor::extension_data() | 63:LV2_Descriptor::activate() | 64:65: |
| 68: | LV2_Descriptor::deactivate() | 69:70: |
Hosts MUST guarantee that:
73:A function in any class is never called concurrently with another function 76: in that class.
77:A Discovery function is never called concurrently with any other function 80: in the same shared object file.
81:An Instantiation function for an instance is never called concurrently 84: with any other function for that instance.
85:Any simultaneous calls that are not explicitly forbidden by these rules are
88: allowed. For example, a host may call run() for two different plugin
89: instances simultaneously.
Plugin functions in any class MUST NOT manipulate any state which might affect 91: other plugins or the host (beyond the contract of that function), for example 92: by using non-reentrant global functions.
93:Extensions to this specification which add new functions MUST declare in which 94: of these classes the functions belong, define new classes for them, or 95: otherwise precisely describe their threading rules.
96: 97: [19/52] Generating doc/ns/ext/dynmanifest.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/dynmanifest.lv2/dynmanifest.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/dynmanifest#DynManifest Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:There MUST NOT be any instances of DynManifest in the generated manifest.
10:All relative URIs in the generated data MUST be relative to the base path that 11: would be used to parse a normal LV2 manifest (the bundle path).
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/dynmanifest Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The LV2 API, on its own, cannot be used to write plugin libraries where data is 10: dynamically generated at runtime, since LV2 requires needed information to be 11: provided in one or more static data (RDF) files. This API addresses this 12: limitation by extending the LV2 API.
13:To detect that a plugin library implements a dynamic manifest generator, the 14: host checks its static manifest for a description like:
15:<http://example.org/my-dynamic-manifest>
16: a dman:DynManifest ;
17: lv2:binary <mydynmanifest.so> .
18: To load the data, the host loads the library (mydynmanifest.so in this
21: example) as usual and fetches the dynamic Turtle data from it using this API.
The host is allowed to request regeneration of the dynamic manifest multiple 23: times, and the plugin library is expected to provide updated data if/when 24: possible. All data and references provided via this API before the last 25: regeneration of the dynamic manifest is to be considered invalid by the host, 26: including plugin descriptors whose URIs were discovered using this API.
27:To access data using this API, the host must:
29:Call lv2_dyn_manifest_open().
32:Create a FILE for functions to write data to (for example with tmpfile()).
Get a list of exposed subject URIs using lv2_dyn_manifest_get_subjects().
38:Call lv2_dyn_manifest_get_data() for each URI of interest to write the 41: related data to the file.
42:Call lv2_dyn_manifest_close().
45:Parse the content of the file(s).
48:Remove the file(s).
51:Each call to the above mentioned dynamic manifest functions MUST write a 54: complete, valid Turtle document (including all needed prefix definitions) to 55: the output FILE.
56:Each call to lv2_dyn_manifest_open() causes the (re)generation of the dynamic 57: manifest data, and invalidates all data fetched before the call.
58:In case the plugin library uses this same API to access other dynamic 59: manifests, it MUST implement some mechanism to avoid potentially endless loops 60: (such as A loads B, B loads A, etc.) and, in case such a loop is detected, the 61: operation MUST fail. For this purpose, use of a static boolean flag is 62: suggested.
63:All of the functions defined by this specification belong to the Discovery 65: class.
66: 67: [20/52] Generating doc/ns/ext/event.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/event.lv2/event.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/event#Event Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:An EventPort contains an LV2_Event_Buffer which contains a sequence of these 10: events. The binary format of LV2 events is defined by the LV2_Event struct in 11: event.h.
12:Specific event types (such as MIDI or OSC) are defined by extensions, and 13: should be rdfs:subClassOf this class.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/event#EventPort Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Ports of this type will be connected to a struct of type LV2_Event_Buffer, 10: defined in event.h. These ports contain a sequence of generic events (possibly 11: several types mixed in a single stream), the specific types of which are 12: defined by some URI in another LV2 extension.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/event#FrameStamp Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The default time stamp unit for an LV2 event: the frames field represents audio 10: frames (in the sample rate passed to instantiate), and the subframes field is 11: 1/UINT32_MAX of a frame.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/event#TimeStamp Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This defines the meaning of the 'frames' and 'subframes' fields of an LV2_Event 10: (both unsigned 32-bit integers).
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/event#generatesTimeStamp Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this port may output a certain time stamp type, regardless of 10: the time stamp type of any input ports.
11:If the port outputs stamps based on what type inputs are connected to, this 12: property should not be set (use the inheritsTimeStamp property for that). 13: Hosts MUST check the time_stamp value of any output port buffers after a call 14: to connect_port on ANY event input port on the plugin.
15:If the plugin changes the stamp_type field of an output event buffer during a 16: call to run(), the plugin must call the stamp_type_changed function provided by 17: the host in the LV2_Event_Feature struct, if it is non-NULL.
18: 19: Invalid documentation for http://lv2plug.in/ns/ext/event#inheritsEvent Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this output port might pass through events that arrived at some 10: other input port (or generate an event of the same type as events arriving at 11: that input). The host must always check the stamp type of all outputs when 12: connecting an input, but this property should be set whenever it applies.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/event#inheritsTimeStamp Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this port follows the time stamp type of an input port.
10:This property is not necessary, but it should be set for outputs that base 11: their output type on an input port so the host can make more sense of the 12: plugin and provide a more sensible interface.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/event#supportsEvent Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this port supports or "understands" a certain event type.
10:For input ports, this means the plugin understands and does something useful 11: with events of this type. For output ports, this means the plugin may generate 12: events of this type. If the plugin never actually generates events of this 13: type, but might pass them through from an input, this property should not be 14: set (use inheritsEvent for that).
15:Plugins with event input ports must always gracefully handle any type of event, 16: even if it does not 'support' it. This property should always be set for event 17: types the plugin understands/generates so hosts can discover plugins 18: appropriate for a given scenario (for example, plugins with a MIDI input). 19: Hosts are not expected to consider event ports suitable for some type of event 20: if the relevant :supportsEvent property is not set, unless the generic 21: property for that port is also set.
22: 23: Invalid documentation for http://lv2plug.in/ns/ext/event#supportsTimeStamp Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this port supports or "understands" a certain time stamp type. 10: Meaningful only for input ports, the host must never connect a port to an event 11: buffer with a time stamp type that isn't supported by the port.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/event#generic Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this port does something meaningful for any event type. This is 10: useful for things like event mixers, delays, serialisers, and so on.
11:If this property is set, hosts should consider the port suitable for any type 12: of event. Otherwise, hosts should consider the port 'appropriate' only for the 13: specific event types listed with :supportsEvent. Note that plugins must 14: gracefully handle unknown event types whether or not this property is present.
15: 16: Invalid documentation for http://lv2plug.in/ns/ext/event Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension is deprecated. New implementations 10: should use LV2 Atom instead.
11:This extension defines a generic time-stamped event port type, which can be 12: used to create plugins that read and write real-time events, such as MIDI, 13: OSC, or any other type of event payload. The type(s) of event supported by 14: a port is defined in the data file for a plugin, for example:
15:<http://example.org/some-plugin>
16: lv2:port [
17: a ev:EventPort, lv2:InputPort ;
18: lv2:index 0 ;
19: ev:supportsEvent <http://lv2plug.in/ns/ext/midi#MidiEvent> ;
20: lv2:symbol "midi_input" ;
21: lv2:name "MIDI input" ;
22: ] .
23: This extension defines a feature which allows plugin UIs to get a direct handle 10: to an LV2 plugin instance (LV2_Handle), if possible.
11:Note that the use of this extension by UIs violates the important principle of 12: UI/plugin separation, and is potentially a source of many problems. 13: Accordingly, use of this extension is highly discouraged, and plugins 14: should not expect hosts to support it, since it is often impossible to do so.
15:To support this feature the host must pass an LV2_Feature struct to the UI 16: instantiate method with URI LV2_INSTANCE_ACCESS_URI and data pointed directly 17: to the LV2_Handle of the plugin instance.
18: 19: [22/52] Generating doc/ns/ext/log.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/log.lv2/log.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/log#Entry Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Subclasses of this are passed as the type parameter to LV2_Log_Log methods to
10: describe the nature of the log entry.
An error should only be posted when a serious unexpected error occurs, and 10: should be actively shown to the user by the host.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/log#Note Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A note records some useful piece of information, but may be ignored. The host 10: should provide passive access to note entries to the user.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/log#Trace Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A trace should not be displayed during normal operation, but the host may 10: implement an option to display them for debugging purposes.
11:This entry type is special in that one may be posted in a real-time thread. It 12: is assumed that if debug tracing is enabled, real-time performance is not a 13: concern. However, the host MUST guarantee that posting a trace is real-time 14: safe if debug tracing is not enabled (for example, by simply ignoring the call 15: as early as possible).
16: 17: Invalid documentation for http://lv2plug.in/ns/ext/log#Warning Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A warning should be posted when an unexpected, but non-critical, error occurs. 10: The host should provide passive access to warnings entries to the user, but may 11: also choose to actively show them.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/log#log Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A feature which plugins may use to log messages. To support this feature, 10: the host must pass an LV2_Feature to LV2_Descriptor::instantiate() with URI 11: LV2_LOG__log and data pointed to an instance of LV2_Log_Log.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/log Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension defines a feature, log, which allows plugins to print log
10: messages with an API similar to the standard C printf function. This allows,
11: for example, plugin logs to be nicely presented to the user in a graphical user
12: interface.
Different log levels are defined by URI and passed as an LV2_URID. This 14: extensions defines standard levels which are expected to be understood by all 15: implementations and should be sufficient in most cases, but advanced 16: implementations may define and use additional levels to suit their needs.
17: 18: [23/52] Generating doc/ns/ext/morph.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/morph.lv2/morph.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/morph#AutoMorphPort Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Ports of this type MUST have another type which defines the default buffer 10: format (for example, lv2:ControlPort) but may dynamically change types based on 11: the configured types of any MorphPort ports on the same plugin instance.
12:The type of a port may only change in response to a host call to 13: LV2_Options_Interface::set(). Whenever any port type on the instance changes, 14: the host MUST check the type of all AutoMorphPort ports with 15: LV2_Options_Interface::get() before calling run() again, since they may have 16: changed. If the type of any port is zero, it means the current configuration 17: is invalid and the plugin may not be run (unless that port is 18: lv2:connectionOptional and connected to NULL).
19:This is mainly useful for outputs whose type depends on the type of 20: corresponding inputs.
21: 22: Invalid documentation for http://lv2plug.in/ns/ext/morph#MorphPort Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Ports of this type MUST have another type which defines the default buffer 10: format (for example lv2:ControlPort) but can be dynamically changed to a 11: different type in hosts that support opts:interface.
12:The host may change the type of a MorphPort by setting its currentType 13: with LV2_Options_Interface::set(). If the plugin has any AutoMorphPort 14: ports, the host MUST check their types after changing any port type since they 15: may have changed.
16: 17: Invalid documentation for http://lv2plug.in/ns/ext/morph#currentType Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The currently active type of the port. This is for dynamic use as an option 10: and SHOULD NOT be listed in the static plugin data.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/morph#supportsType Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that a port supports being switched to a certain type. A MorphPort 10: MUST list each type it supports being switched to in the plugin data using this 11: property.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/morph Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension defines two port types: MorphPort, which has a 10: host-configurable type, and AutoMorphPort, which may automatically change 11: type when a MorphPort's type is changed. These ports always have a default 12: type and work normally work in hosts that are unaware of this extension. Thus, 13: this extension provides a backwards compatibility mechanism which allows 14: plugins to use new port types but gracefully fall back to a default type in 15: hosts that do not support them.
16:This extension only defines port types and properties for describing morph 17: ports. The actual run-time switching is done via the opts:interface API.
18: 19: [24/52] Generating doc/ns/ext/midi.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/midi.lv2/midi.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/midi#MidiEvent Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A single raw MIDI message (a sequence of bytes).
10:This is equivalent to a standard MIDI messages, except with the following 11: restrictions to simplify handling:
12:Running status is not allowed, every message must have its own status byte.
15:Note On messages with velocity 0 are not allowed. These messages are 18: equivalent to Note Off in standard MIDI streams, but here only proper Note 19: Off messages are allowed.
20:"Realtime messages" (status bytes 0xF8 to 0xFF) are allowed, but may not 23: occur inside other messages like they can in standard MIDI streams.
24:All messages are complete valid MIDI messages. This means, for example, 27: that only the first byte in each event (the status byte) may have the 28: eighth bit set, that Note On and Note Off events are always 3 bytes long, 29: etc.
30:Where messages are communicated, the writer is responsible for writing valid 33: messages, and the reader may assume that all events are valid.
34:If a MidiEvent is serialised to a string, the format should be 35: xsd:hexBinary, for example:
36:[] eg:someEvent "901A01"^^midi:MidiEvent .
37: This is a status byte with the lower nibble set to zero.
10: 11: Invalid documentation for http://lv2plug.in/ns/ext/midi Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This specification defines a data type for a MIDI message, MidiEvent,
10: which is normalised for fast and convenient real-time processing. MIDI is the
11: Musical Instrument Digital Interface
, a ubiquitous binary standard for
12: controlling digital music devices.
For plugins that process MIDI (or other situations where MIDI is sent via a 14: generic transport) the main type defined here, MidiEvent, can be mapped to 15: an integer and used as the type of an LV2 Atom or 16: Event.
17:This specification also defines a complete vocabulary for the MIDI standard, 18: except for standard controller numbers. These descriptions are detailed enough 19: to express any MIDI message as properties.
20: 21: [25/52] Generating doc/ns/ext/options.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/options.lv2/options.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/options#Option Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:It is not required for a property to explicitly be an Option in order to be 10: used as such. However, properties which are primarily intended for use as 11: options, or are at least particularly useful as options, should be explicitly 12: given this type for documentation purposes, and to assist hosts in discovering 13: option definitions.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/options#requiredOption Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The host MUST pass a value for the specified option via options during 10: instantiation.
11:Note that use of this property may reduce the number of compatible hosts. 12: Wherever possible, it is better to list options with supportedOption and 13: fall back to a reasonable default value if it is not provided.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/options#supportedOption Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The host SHOULD provide a value for the specified option if one is known, or 10: provide the user an opportunity to specify one if possible.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/options#interface Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:An interface (LV2_Options_Interface) for dynamically setting and getting
10: options. Note that this is intended for use by the host for configuring
11: plugins only, and is not a live
plugin control mechanism.
The plugin data file should advertise this interface like so:
13:@prefix opts: <http://lv2plug.in/ns/ext/options#> .
14:
15: <plugin>
16: a lv2:Plugin ;
17: lv2:extensionData opts:interface .
18: To implement this feature, hosts MUST pass an LV2_Feature to the appropriate
10: instantiate method with this URI and data pointed to an array of
11: LV2_Options_Option terminated by an element with both key and value set to
12: zero. The instance should cast this data pointer to const
13: LV2_Options_Option* and scan the array for any options of interest. The
14: instance MUST NOT modify the options array in any way.
Note that requiring this feature may reduce the number of compatible hosts. 16: Unless some options are strictly required by the instance, this feature SHOULD 17: be listed as an lv2:optionalFeature.
18: 19: Invalid documentation for http://lv2plug.in/ns/ext/options Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension defines a facility for options
, which are values the host
10: passes to a plugin or UI at run time.
There are two facilities for passing options to an instance: options 12: allows passing options at instantiation time, and the interface interface 13: allows options to be dynamically set and retrieved after instantiation.
14:Note that this extension is only for allowing hosts to configure plugins, and
15: is not a live
control mechanism. For real-time control, use event-based
16: control via an atom:AtomPort with an atom:Sequence buffer.
Instances may indicate they require an option with the requiredOption 18: property, or that they optionally support an option with the 19: supportedOption property.
20: 21: [26/52] Generating doc/ns/ext/parameters.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/parameters.lv2/parameters.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/parameters#wetDryRatio Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The ratio between processed and bypass components in output signal. The dry 10: and wet percentages can be calculated from the following equations:
11:dry = (wetDryRatio.maximum - wetDryRatio.value) / wetDryRatio.maximum
12: wet = wetDryRatio.value / wetDryRatio.maximum
13: Typically, maximum value of 1 or 100 and minimum value of 0 should be used.
16: 17: Invalid documentation for http://lv2plug.in/ns/ext/parameters Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is a vocabulary for parameters that are common in audio processing
10: software. A parameter
is purely a metadata concept, unrelated to any
11: particular code mechanism. Parameters are used to assign meaning to controls
12: (for example, using lv2:designation for ports) so they can be used more
13: intelligently or presented to the user more efficiently.
After this, the destination has the same description as the subject, 10: and the subject is unchanged.
11:It is an error if the subject does not exist, 12: or if the destination already exists.
13:Multiple subjects may be given if the destination is a container, 14: but the semantics of this case are application-defined.
15: 16: Invalid documentation for http://lv2plug.in/ns/ext/patch#Get Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:If a property is given, 10: then the receiver should respond with a Set message that gives only that property.
11:Otherwise, it should respond with a concise bounded description in a Put message, 12: that is, a description that recursively includes any blank node values.
13:If a subject is given, then the response should have the same subject. 14: If no subject is given, then the receiver is implicitly the subject.
15:If a request node or a sequenceNumber is given, 16: then the response should be a Response and have the same property. 17: If neither is given, then the receiver can respond with a simple Put message. 18: For example:
19:[]
20: a patch:Get ;
21: patch:subject eg:something .
22: Could result in:
25:[]
26: a patch:Put ;
27: patch:subject eg:something ;
28: patch:body [
29: eg:name "Something" ;
30: eg:ratio 1.6180339887 ;
31: ] .
32: If the subject does not exist, it is created. If the subject does already 10: exist, it is added to.
11:This request only adds properties, it never removes them. The user must take 12: care that multiple values are not set for properties which should only have 13: one.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/patch#Message Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is an abstract base class for all patch messages. Concrete messages are 10: either a Request or a Response.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/patch#Move Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:After this, the destination has the description that the subject had, and the 10: subject no longer exists.
11:It is an error if the subject does not exist, or if the destination already 12: exists.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/patch#Patch Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This method always has at least one subject, and exactly one add and 10: remove property. The value of add and remove are nodes which 11: have the properties to add or remove from the subject(s), respectively. The 12: special value wildcard may be used as the value of a remove property to 13: remove all properties with the given predicate. For example:
14:[]
15: a patch:Patch ;
16: patch:subject <something> ;
17: patch:add [
18: eg:name "New name" ;
19: eg:age 42 ;
20: ] ;
21: patch:remove [
22: eg:name "Old name" ;
23: eg:age patch:wildcard ; # Remove all old eg:age properties/var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC).
build_date = datetime.datetime.utcfromtimestamp(now)
error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/patch.lv2/patch.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96)
24: ] .
25: If the subject does not already exist, it is created. If the subject does 10: already exist, the body is considered an updated version of it, and the 11: previous version is replaced.
12:[]
13: a patch:Put ;
14: patch:subject <something> ;
15: patch:body [
16: eg:name "New name" ;
17: eg:age 42 ;
18: ] .
19: A request may have a subject property, which specifies the resource that 10: the request applies to. The subject may be omitted in contexts where it is 11: implicit, for example if the recipient is the subject.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/patch#Set Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is equivalent to a Patch which removes all pre-existing values for 10: the property before setting the new value. For example:
11:[]
12: a patch:Set ;
13: patch:subject <something> ;
14: patch:property eg:name ;
15: patch:value "New name" .
16: Which is equivalent to:
19:[]
20: a patch:Patch ;
21: patch:subject <something> ;
22: patch:add [
23: eg:name "New name" ;
24: ] ;
25: patch:remove [
26: eg:name patch:wildcard ;
27: ] .
28: The details of this property's value depend on the type of message it is a part 10: of.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/patch#context Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:For example, a plugin may have a special context for ephemeral properties which 10: are only relevant during the lifetime of the instance and should not be saved 11: in state.
12:The specific uses for contexts are application specific. However, the context 13: MUST be a URI, and can be interpreted as the ID of a data model where 14: properties should be stored. Implementations MAY have special support for 15: contexts, for example by storing in a quad store or serializing to a format 16: that supports multiple RDF graphs such as TriG.
17: 18: Invalid documentation for http://lv2plug.in/ns/ext/patch#readable Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:See the similar writable property for details.
10: 11: Invalid documentation for http://lv2plug.in/ns/ext/patch#request Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This can be used if referring directly to the URI or blank node ID of the 10: request is possible. Otherwise, use sequenceNumber.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/patch#sequenceNumber Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This property is used to associate replies with requests when it is not 10: feasible to refer to request URIs with request. A Response with a 11: given sequence number is the reply to the previously send Request with 12: the same sequence number.
13:The special sequence number 0 means that no reply is desired.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/patch#writable Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is used to list properties that can be changed, for example to allow user 10: interfaces to present appropriate controls. For example:
11:@prefix eg: <http://example.org/> .
12: @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
13: @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
14: @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
15:
16: eg:title
17: a rdf:Property ;
18: rdfs:label "title" ;
19: rdfs:range xsd:string .
20:
21: eg:plugin
22: patch:writable eg:title .
23: This makes it possible to describe the removal of all values for a given 10: property.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/patch Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is a vocabulary for messages that access and manipulate properties. 10: It can be used as a dynamic control interface for plugins, 11: or anything else with a property-based model.
12:The key underlying concept here is to control things by manipulating arbitrary properties, 13: rather than by calling application-specific methods. 14: This allows implementations to understand what messages do 15: (at least in a mechanical sense), 16: which makes things like caching, proxying, or undo relatively straightforward to implement. 17: Note, however, that this is only conceptual: 18: there is no requirement to implement a general property store. 19: Typically, a plugin will understand a fixed set of properties that represent its parameters or other internal state, and ignore everything else.
20:This protocol is syntax-agnostic, 21: and homoiconic 22: in the sense that the messages use the same format as the data they manipulate. 23: In particular, messages can be serialised as a binary Object for realtime plugin control, 24: or as Turtle for saving to a file, 25: sending over a network, 26: printing for debugging purposes, 27: and so on.
28:This specification only defines a semantic protocol, 29: there is no corresponding API. 30: It can be used with the Atom extension to control plugins which support message-based parameters as defined by the Parameters extension.
31:For example, if a plugin defines a eg:volume parameter, it can be controlled by the host by sending a Set message to the plugin instance:
[
33: a patch:Set ;
34: patch:property eg:volume ;
35: patch:value 11.0 ;
36: ]
37: Similarly, the host could get the current value for this parameter by sending a Get message:
40:[
41: a patch:Get ;
42: patch:property eg:volume ;
43: ]
44: The plugin would then respond with the same Set message as above. 47: In this case, the plugin instance is implicitly the subject, 48: but a specific subject can also be given for deeper control.
49: 50: [28/52] Generating doc/ns/ext/port-props.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/port-props.lv2/port-props.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/port-props#displayPriority Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates how important a port is to controlling the plugin. If a host can 10: only display some ports of a plugin, it should prefer ports with a higher 11: display priority. Priorities do not need to be unique, and are only meaningful 12: when compared to each other.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/port-props#rangeSteps Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This value indicates into how many evenly-divided points the (control) port 10: range should be divided for step-wise control. This may be used for changing 11: the value with step-based controllers like arrow keys, mouse wheel, rotary 12: encoders, and so on.
13:Note that when used with a logarithmic port, the steps are logarithmic 14: too, and port value can be calculated as:
15:value = lower * pow(upper / lower, step / (steps - 1))
16: and the step from value is:
19:step = (steps - 1) * log(value / lower) / log(upper / lower)
20: where:
23:value is the port value.
step is the step number (0..steps).
steps is the number of steps (= value of :rangeSteps property).
lower and upper are the bounds.
Input ports only. Indicates that any changes to the port value may produce 10: slight artifacts to produced audio signals (zipper noise and other results of 11: signal discontinuities). Connecting ports of this type to continuous signals 12: is not recommended, and when presenting a list of automation targets, those 13: ports may be marked as artifact-producing.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/port-props#continuousCV Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that the port carries a "smooth" modulation signal. Control input 10: ports of this type are well-suited for being connected to sources of smooth 11: signals (knobs with smoothing, modulation rate oscillators, output ports with 12: continuousCV type, etc.). Typically, the plugin with ports which have this 13: property will implement appropriate smoothing to avoid audio artifacts. For 14: output ports, this property suggests the value of the port is likely to change 15: frequently, and describes a smooth signal (so successive values may be 16: considered points along a curve).
17: 18: Invalid documentation for http://lv2plug.in/ns/ext/port-props#discreteCV Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that the port carries a "discrete" modulation signal. Input ports of 10: this type are well-suited for being connected to sources of discrete signals 11: (switches, buttons, classifiers, event detectors, etc.). May be combined with 12: trigger property. For output ports, this property suggests the value of 13: the port describe discrete values that should be interpreted as steps (and not 14: points along a curve).
15: 16: Invalid documentation for http://lv2plug.in/ns/ext/port-props#expensive Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Input ports only. Indicates that any changes to the port value may trigger 10: expensive background calculation (for example, regeneration of lookup tables in 11: a background thread). Any value changes may have not have immediate effect, or 12: may cause silence or diminished-quality version of the output until background 13: processing is finished. Ports having this property are typically not well 14: suited for connection to outputs of other plugins, and should not be offered as 15: connection targets or for automation by default.
16: 17: Invalid documentation for http://lv2plug.in/ns/ext/port-props#hasStrictBounds Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:For hosts that support supportsStrictBounds, this indicates that the 10: value of the port should never exceed the port's minimum and maximum control 11: points. For input ports, it moves the responsibility for limiting the range of 12: values to host, if it supports supportsStrictBounds. For output ports, 13: it indicates that values within specified range are to be expected, and 14: breaking that should be considered by the host as error in plugin 15: implementation.
16: 17: Invalid documentation for http://lv2plug.in/ns/ext/port-props#logarithmic Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that port value behaviour within specified range (bounds) is a value 10: using logarithmic scale. The lower and upper bounds must be specified, and 11: must be of the same sign.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/port-props#notAutomatic Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that the port is not primarily intended to be fed with modulation 10: signals from external sources (other plugins, etc.). It is merely a UI hint 11: and hosts may allow the user to override it.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/port-props#notOnGUI Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that the port is not primarily intended to be represented by a 10: separate control in the user interface window (or any similar mechanism used 11: for direct, immediate control of control ports). It is merely a UI hint and 12: hosts may allow the user to override it.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/port-props#supportsStrictBounds Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates use of host support for hasStrictBounds port property. A 10: plugin that specifies it as optional feature can omit value clamping for 11: hasStrictBounds ports, if the feature is supported by the host. When specified 12: as required feature, it indicates that the plugin does not do any clamping for 13: input ports that have a hasStrictBounds property.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/port-props#trigger Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that the data item corresponds to a momentary event that has been 10: detected (control output ports) or is to be triggered (control input ports). 11: For input ports, the port needs to be reset to lv2:default value after run() 12: function of the plugin has returned. If the control port is assigned a GUI 13: widget by the host, the widget should be of auto-off (momentary, one-shot) type 14: - for example, a push button if the port is also declared as lv2:toggled, or a 15: series of push button or auto-clear input box with a "Send" button if the port 16: is also lv2:integer.
17: 18: Invalid documentation for http://lv2plug.in/ns/ext/port-props Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This vocabulary defines various properties for plugin ports, which can be used 10: to better describe how a plugin can be controlled. Using this metadata, hosts 11: can build better UIs for plugins, and provide more advanced automatic 12: functionality.
13: 14: [29/52] Generating doc/ns/ext/port-groups.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/port-groups.lv2/port-groups.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/port-groups#AmbisonicGroup Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:These groups are divided into channels which together represent a position in 10: an abstract n-dimensional space. The position of sound in one of these groups 11: does not depend on a particular speaker configuration; a decoder can be used to 12: convert an ambisonic stream for any speaker configuration.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/port-groups#DiscreteGroup Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:These groups are divided into channels where each represents a particular 10: speaker location. The position of sound in one of these groups depends on a 11: particular speaker configuration.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/port-groups#Group Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A group logically combines ports which should be considered part of the same 10: stream. For example, two audio ports in a group may form a stereo stream.
11:Like ports, groups have a lv2:symbol that is unique within the context of the 12: plugin, where group symbols and port symbols reside in the same namespace. In 13: other words, a group on a plugin MUST NOT have the same symbol as any other 14: group or port on that plugin. This makes it possible to uniquely reference a 15: port or group on a plugin with a single identifier and no context.
16:Group definitions may be shared across plugins for brevity. For example, a 17: plugin collection may define a single URI for a StereoGroup with the symbol 18: "input" and use it in many plugins.
19: 20: Invalid documentation for http://lv2plug.in/ns/ext/port-groups#group Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this port is a part of a group of ports on the plugin. The port 10: should also have an lv2:designation property to define its designation within 11: that group.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/port-groups#mainInput Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this group should be considered the "main" input, i.e. the 10: primary task is processing the signal in this group. A plugin MUST NOT have 11: more than one mainInput property.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/port-groups#mainOutput Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this group should be considered the "main" output. The main 10: output group SHOULD have the main input group as a source.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/port-groups#sideChainOf Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this port or group should be considered a "side chain" of some 10: other port or group. The precise definition of "side chain" depends on the 11: plugin, but in general this group should be considered a modifier to some other 12: group, rather than an independent input itself.
13: 14: Invalid documentation for http://lv2plug.in/ns/ext/port-groups#source Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this port or group should be considered the "result" of some 10: other port or group. This property only makes sense on groups with outputs 11: when the source is a group with inputs. This can be used to convey a 12: relationship between corresponding input and output groups with different 13: types, for example in a mono to stereo plugin.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/port-groups#subGroupOf Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Indicates that this group is a child of another group. This property has no 10: meaning with respect to plugin execution, but the host may find this 11: information useful to provide a better user interface. Note that being a 12: sub-group does not relax the restriction that the group MUST have a unique 13: symbol with respect to the plugin.
14: 15: [30/52] Generating doc/ns/ext/presets.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/presets.lv2/presets.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/presets#Preset Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The structure of a Preset deliberately mirrors that of a plugin, so existing 10: predicates can be used to describe any data associated with the preset. For 11: example:
12:@prefix eg: <http://example.org/> .
13:
14: eg:mypreset
15: a pset:Preset ;
16: rdfs:label "One louder" ;
17: lv2:appliesTo eg:myplugin ;
18: lv2:port [
19: lv2:symbol "volume1" ;
20: pset:value 11.0
21: ] , [
22: lv2:symbol "volume2" ;
23: pset:value 11.0
24: ] .
25: A Preset SHOULD have at least one lv2:appliesTo property. Each Port on a 28: Preset MUST have at least a lv2:symbol property and a value property.
29:Hosts SHOULD save user presets to a bundle in the user-local LV2 directory (for
30: example ~/.lv2) with a name like <Plugin_Name>_<Preset_Name>.preset.lv2
31: (for example LV2_Amp_At_Eleven.preset.lv2), where names are transformed to be
32: valid LV2 symbols for maximum compatibility.
Specifies the preset currently applied to a plugin instance. This property may 10: be useful for saving state, or notifying a plugin instance at run-time about a 11: preset change.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/presets#value Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This property is used in a similar way to lv2:default.
10: 11: Invalid documentation for http://lv2plug.in/ns/ext/presets Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is a vocabulary for LV2 plugin presets, that is, named sets of control 10: values and possibly other state. The structure of a Preset is 11: deliberately identical to that of an lv2:Plugin, and can be thought of as a 12: plugin template or overlay.
13:Presets may be defined in any bundle, including the plugin's bundle, separate
14: third party preset bundles, or user preset bundles saved by hosts. Since
15: preset data tends to be large, it is recommended that plugins describe presets
16: in a separate file(s) to avoid slowing down hosts. The manifest.ttl of a
17: bundle containing presets should list them like so:
eg:mypreset
19: a pset:Preset ;
20: lv2:appliesTo eg:myplugin ;
21: rdfs:seeAlso <mypreset.ttl> .
22: Indicates that a port requires at least as much buffer space as the port with 10: the given symbol on the same plugin instance. This may be used for any ports, 11: but is generally most useful to indicate an output port must be at least as 12: large as some input port (because it will copy from it). If a port is 13: asLargeAs several ports, it is asLargeAs the largest such port (not the sum of 14: those ports' sizes).
15:The host guarantees that whenever an ObjectPort's run method is called, any
16: output O that is asLargeAs an input I is connected to a buffer large
17: enough to copy I, or NULL if the port is lv2:connectionOptional.
Indicates that a port requires a buffer at least this large, in bytes. Any 10: host that supports the resize-port feature MUST connect any port with a 11: minimumSize specified to a buffer at least as large as the value given for this 12: property. Any host, especially those that do NOT support dynamic port 13: resizing, SHOULD do so or reduced functionality may result.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/resize-port#resize Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A feature to resize output port buffers in LV2_Plugin_Descriptor::run().
10:To support this feature, the host must pass an LV2_Feature to the plugin's 11: instantiate method with URI LV2_RESIZE_PORT__resize and a pointer to a 12: LV2_Resize_Port_Resize structure. This structure provides a resize_port 13: function which plugins may use to resize output port buffers as necessary.
14: 15: Invalid documentation for http://lv2plug.in/ns/ext/resize-port Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension defines a feature, resize, which allows plugins to 10: dynamically resize their output port buffers.
11:In addition to the dynamic feature, there are properties which describe the 12: space required for a particular port buffer which can be used statically in 13: data files.
14: 15: [32/52] Generating doc/ns/ext/state.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() Invalid documentation for http://lv2plug.in/ns/ext/state#State Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This type should be used wherever instance state is described. The properties 10: of a resource with this type correspond directly to the properties of the state 11: dictionary (except the property that states it has this type).
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/state#StateChanged Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A notification that the internal state of the plugin has been changed in a way 10: that the host can not otherwise know about.
11:This is a one-way notification, intended to be used as the type of an 12: Object sent from plugins when necessary.
13:Plugins SHOULD emit such an event whenever a change has occurred that would 14: result in a different state being saved, but not when the host explicitly makes 15: a change which it knows is likely to have that effect, such as changing a 16: parameter.
17: 18: Invalid documentation for http://lv2plug.in/ns/ext/state#state Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This property may be used anywhere a state needs to be described, for example:
10:@prefix eg: <http://example.org/> .
11:
12: <plugin-instance>
13: state:state [
14: eg:somekey "some value" ;
15: eg:someotherkey "some other value" ;
16: eg:favourite-number 2
17: ] .
18: This feature provides a function that can be used by plugins to free paths that 10: were allocated by the host via other state features (mapPath and 11: makePath).
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/state#interface Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A structure (LV2_State_Interface) which contains functions to be called by the 10: host to save and restore state. In order to support this extension, the plugin 11: must return a valid LV2_State_Interface from LV2_Descriptor::extension_data() 12: when it is called with URI LV2_STATE__interface.
13:The plugin data file should describe this like so:
14:@prefix state: <http://lv2plug.in/ns/ext/state#> .
15:
16: <plugin>
17: a lv2:Plugin ;
18: lv2:extensionData state:interface .
19: This feature indicates that the plugin has default state listed with the 10: state property which should be loaded by the host before running the 11: plugin. Requiring this feature allows plugins to implement a single state 12: loading mechanism which works for initialisation as well as restoration, 13: without having to hard-code default state.
14:To support this feature, the host MUST restore the default state after 15: instantiating the plugin but before calling run().
16: 17: Invalid documentation for http://lv2plug.in/ns/ext/state#makePath Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This feature allows plugins to create new files and/or directories. To support 10: this feature the host passes an LV2_Feature with URI LV2_STATE__makePath and 11: data pointed to an LV2_State_Make_Path to the plugin. The host may make this 12: feature available only during save by passing it to 13: LV2_State_Interface::save(), or available any time by passing it to 14: LV2_Descriptor::instantiate(). If passed to LV2_State_Interface::save(), the 15: feature MUST NOT be used beyond the scope of that call.
16:The plugin is guaranteed a hierarchical namespace unique to that plugin 17: instance, and may expect the returned path to have the requested path as a 18: suffix. There is one such namespace, even if the feature is passed to both 19: LV2_Descriptor::instantiate() and LV2_State_Interface::save(). Beyond this, 20: the plugin MUST NOT make any assumptions about the returned paths.
21:Like any other paths, the plugin MUST map these paths using mapPath 22: before storing them in state. The plugin MUST NOT assume these paths will be 23: available across a save/restore otherwise, that is, only mapped paths saved to 24: state are persistent, any other created paths are temporary.
25:For example, a plugin may create a file in a subdirectory like so:
26:char* save_myfile(LV2_State_Make_Path* make_path)
27: {
28: char* path = make_path->path(make_path->handle, "foo/bar/myfile.txt");
29: FILE* myfile = fopen(path, 'w');
30: fprintf(myfile, "I am some data");
31: fclose(myfile);
32: return path;
33: }
34: This feature maps absolute paths to/from abstract paths
which are stored
10: in state. To support this feature a host must pass an LV2_Feature with URI
11: LV2_STATE__mapPath and data pointed to an LV2_State_Map_Path to the plugin's
12: LV2_State_Interface methods.
The plugin MUST map all paths stored in its state (including those inside any 14: files). This is necessary so that hosts can handle file system references 15: correctly, for example to share common files, or bundle state for distribution 16: or archival.
17:For example, a plugin may write a path to a state file like so:
18:void write_path(LV2_State_Map_Path* map_path, FILE* myfile, const char* path)
19: {
20: char* abstract_path = map_path->abstract_path(map_path->handle, path);
21: fprintf(myfile, "%s", abstract_path);
22: free(abstract_path);
23: }
24: Then, later reload the path like so:
27:char* read_path(LV2_State_Map_Path* map_path, FILE* myfile)
28: {
29: /* Obviously this is not production quality code! */
30: char abstract_path[1024];
31: fscanf(myfile, "%s", abstract_path);
32: return map_path->absolute_path(map_path->handle, abstract_path);
33: }
34: If a plugin supports this feature, its LV2_State_Interface::restore method is 10: thread-safe and may be called concurrently with audio class functions.
11:To support this feature, the host MUST pass a 12: work:schedule feature to the restore method, which will 13: be used to complete the state restoration. The usual mechanics of the worker 14: apply: the host will call the plugin's work method, which emits a response 15: which is later applied in the audio thread.
16:The host is not required to block audio processing while restore() and work() 17: load the state, so this feature allows state to be restored without dropouts.
18: 19: Invalid documentation for http://lv2plug.in/ns/ext/state Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension defines a simple mechanism that allows hosts to save and restore 10: a plugin instance's state. The goal is for an instance's state to be 11: completely described by port values and a simple dictionary.
12:The state
defined here is conceptually a key:value dictionary, with URI keys
13: and values of any type. For performance reasons the key and value type are
14: actually a "URID", a URI mapped to an integer. A single key:value pair is
15: called a "property".
This state model is simple yet has many benefits:
17:Both fast and extensible thanks to URID keys.
20:No limitations on possible value types.
23:Easy to serialise in almost any format.
26:Easy to store in a typical "map" or "dictionary" data structure.
29:Elegantly described in Turtle, so state can be described in LV2 data files 32: (including presets).
33:Does not impose any file formats, data structures, or file system 36: requirements.
37:Suitable for portable persistent state as well as fast in-memory snapshots.
40:Keys may be well-defined and used meaningfully across several 43: implementations.
44:State may be dynamic, but plugins are not required to have a dynamic 47: dictionary data structure available.
48:To implement state, the plugin provides a interface to the host. To save 51: or restore, the host calls LV2_State_Interface::save() or 52: LV2_State_Interface::restore(), passing a callback to be used for handling a 53: single property. The host is free to implement property storage and retrieval 54: in any way.
55:Since value types are defined by URI, any type is possible. However, a set of 56: standard types is defined by the LV2 Atom extension. Use of these 57: types is recommended. Hosts MUST implement at least 58: atom:String, which is simply a C string.
59:Plugins may need to refer to existing files (such as loaded samples) in their 61: state. This is done by storing the file's path as a property just like any 62: other value. However, there are some rules which MUST be followed when storing 63: paths, see mapPath for details. Plugins MUST use the type 64: atom:Path for all paths in their state.
65:Plugins are strongly encouraged to avoid creating files, instead storing all 66: state as properties. However, occasionally the ability to create files is 67: necessary. To make this possible, the host can provide the feature 68: makePath which allocates paths for plugin-created files. Plugins MUST 69: NOT create files in any other locations.
70:/* Namespace for this plugin's keys. This SHOULD be something that could be
72: published as a document, even if that document does not exist right now.
73: */
74: #define NS_MY "http://example.org/myplugin/schema#"
75:
76: #define DEFAULT_GREETING "Hello"
77:
78: LV2_Handle
79: my_instantiate(...)
80: {
81: MyPlugin* plugin = ...;
82: plugin->uris.atom_String = map_uri(LV2_ATOM__String);
83: plugin->uris.my_greeting = map_uri(NS_MY "greeting");
84: plugin->state.greeting = strdup(DEFAULT_GREETING);
85: return plugin;
86: }
87:
88: LV2_State_Status
89: my_save(LV2_Handle instance,
90: LV2_State_Store_Function store,
91: LV2_State_Handle handle,
92: uint32_t flags,
93: const LV2_Feature *const * features)
94: {
95: MyPlugin* plugin = (MyPlugin*)instance;
96: const char* greeting = plugin->state.greeting;
97:
98: store(handle,
99: plugin->uris.my_greeting,
100: greeting,
101: strlen(greeting) + 1, // Careful! Need space for terminator
102: plugin->uris.atom_String,
103: LV2_STATE_IS_POD | LV2_STATE_IS_PORTABLE);
104:
105: return LV2_STATE_SUCCESS;
106: }
107:
108: LV2_State_Status
109: my_restore(LV2_Handle instance,
110: LV2_State_Retrieve_Function retrieve,
111: LV2_State_Handle handle,
112: uint32_t flags,
113: const LV2_Feature *const * features)
114: {
115: MyPlugin* plugin = (MyPlugin*)instance;
116:
117: size_t size;
118: uint32_t type;
119: uint32_t flags;
120: const char* greeting = retrieve(
121: handle, plugin->uris.my_greeting, &size, &type, &flags);
122:
123: if (greeting) {
124: free(plugin->state->greeting);
125: plugin->state->greeting = strdup(greeting);
126: } else {
127: plugin->state->greeting = strdup(DEFAULT_GREETING);
128: }
129:
130: return LV2_STATE_SUCCESS;/var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC).
build_date = datetime.datetime.utcfromtimestamp(now)
error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/state.lv2/state.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96)
131: }
132:
133: const void*
134: my_extension_data(const char* uri)
135: {
136: static const LV2_State_Interface state_iface = { my_save, my_restore };
137: if (!strcmp(uri, LV2_STATE__interface)) {
138: return &state_iface;
139: }
140: }
141: LV2_State_Status
145: store_callback(LV2_State_Handle handle,
146: uint32_t key,
147: const void* value,
148: size_t size,
149: uint32_t type,
150: uint32_t flags)
151: {
152: if ((flags & LV2_STATE_IS_POD)) {
153: // We only care about POD since we're keeping state in memory only.
154: // Disk or network use would also require LV2_STATE_IS_PORTABLE.
155: Map* state_map = (Map*)handle;
156: state_map->insert(key, Value(copy(value), size, type));
157: return LV2_STATE_SUCCESS;;
158: } else {
159: return LV2_STATE_ERR_BAD_FLAGS; // Non-POD events are unsupported
160: }
161: }
162:
163: Map
164: get_plugin_state(LV2_Handle instance)
165: {
166: LV2_State* state = instance.extension_data(LV2_STATE__interface);
167:
168: // Request a fast/native/POD save, since we're just copying in memory
169: Map state_map;
170: state.save(instance, store_callback, &state_map,
171: LV2_STATE_IS_POD|LV2_STATE_IS_NATIVE);
172:
173: return state_map;
174: }
175: It is likely that other interfaces for working with plugin state will be 179: developed as needed. This is encouraged, however everything SHOULD work within 180: the state model defined here. That is, do not complicate the state 181: model. Implementations can assume the following:
182:The current port values and state dictionary completely describe a plugin 185: instance, at least well enough that saving and restoring will yield an 186: "identical" instance from the user's perspective.
187:Hosts are not expected to save and/or restore any other attributes of a 190: plugin instance.
191:The main benefit of this meaningful state model is that it can double as a 195: plugin control/query mechanism. For plugins that require more advanced control 196: than simple control ports, instead of defining a set of commands, define 197: properties whose values can be set appropriately. This provides both a way to 198: control and save that state "for free", since there is no need to define 199: commands and a set of properties for storing their effects. In particular, 200: this is a good way for UIs to achieve more advanced control of plugins.
201:This "property principle" is summed up in the phrase: "Don't stop; set playing 202: to false".
203:This extension does not define a dynamic mechanism for state access and 204: manipulation. The LV2 Patch extension defines a generic set of 205: messages which can be used to access or manipulate properties, and the LV2 206: Atom extension defines a port type and data container capable of 207: transmitting those messages.
208: 209: [33/52] Generating doc/ns/ext/time.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/time.lv2/time.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/time#Position Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A point in time and/or the speed at which time is passing. A position is both 10: a point and a speed, which precisely defines a time within a timeline.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/time#Rate Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The rate of passage of time in terms of one unit with respect to another.
10: 11: Invalid documentation for http://lv2plug.in/ns/ext/time#beat Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is not the beat within a bar like barBeat, but relative to the same 10: origin as bar and monotonically increases unless the transport is 11: repositioned.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/time#beatUnit Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Beat unit, the note value that counts as one beat. This is the bottom number 10: in a time signature: 2 for half note, 4 for quarter note, and so on.
11: 12: Invalid documentation for http://lv2plug.in/ns/ext/time#speed Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The rate of the progress of time as a fraction of normal speed. For example, a 10: rate of 0.0 is stopped, 1.0 is rolling at normal speed, 0.5 is rolling at half 11: speed, -1.0 is reverse, and so on.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/time Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is a vocabulary for describing a position in time and the speed of time 10: passage, in both real and musical terms.
11:In addition to real time (based on seconds), two units of time are used: 12: frames and beats. A frame is a numbered quantum of time. Frame time is 13: related to real-time by the frame rate or sample rate, 14: framesPerSecond. A beat is a single pulse of musical time. Beat time is 15: related to real-time by the tempo, beatsPerMinute.
16:Musical time additionally has a meter which describes passage of time in 17: terms of musical bars. A bar is a higher level grouping of beats. The meter 18: describes how many beats are in one bar.
19: 20: [34/52] Generating doc/ns/ext/uri-map.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/uri-map.lv2/uri-map.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/uri-map Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension is deprecated. New implementations 10: should use LV2 URID instead.
11:This extension defines a simple mechanism for plugins to map URIs to integers, 12: usually for performance reasons (e.g. processing events typed by URIs in real 13: time). The expected use case is for plugins to map URIs to integers for things 14: they 'understand' at instantiation time, and store those values for use in the 15: audio thread without doing any string comparison. This allows the 16: extensibility of RDF with the performance of integers (or centrally defined 17: enumerations).
18: 19: [35/52] Generating doc/ns/ext/urid.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/urid.lv2/urid.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/ext/urid#map Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:To support this feature, the host must pass an LV2_Feature to 10: LV2_Descriptor::instantiate() with URI LV2_URID__map and data pointed to an 11: instance of LV2_URID_Map.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/urid#unmap Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:To support this feature, the host must pass an LV2_Feature to 10: LV2_Descriptor::instantiate() with URI LV2_URID__unmap and data pointed to an 11: instance of LV2_URID_Unmap.
12: 13: Invalid documentation for http://lv2plug.in/ns/ext/urid Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension defines a simple mechanism for plugins to map URIs to and from 10: integers. This is usually used for performance reasons, for example for 11: processing events with URI types in real-time audio code). Typically, plugins 12: map URIs to integers for things they "understand" at instantiation time, and 13: store those values for use in the audio thread without doing any string 14: comparison. This allows for the extensibility of RDF but with the performance 15: of integers.
16:This extension is intended as an improved and simplified replacement for the
17: uri-map extension, since the map context parameter there has
18: proven problematic. This extension is functionally equivalent to the uri-map
19: extension with a NULL context. New implementations are encouraged to use this
20: extension for URI mapping.
The work interface provided by a plugin, LV2_Worker_Interface.
10:@prefix work: <http://lv2plug.in/ns/ext/worker#> .
11:
12: <plugin>
13: a lv2:Plugin ;
14: lv2:extensionData work:interface .
15: The work scheduling feature provided by a host, LV2_Worker_Schedule.
10:If the host passes this feature to LV2_Descriptor::instantiate, the plugin MAY 11: use it to schedule work in the audio thread, and MUST NOT call it in any other 12: context. Hosts MAY pass this feature to other functions as well, in which case 13: the plugin MAY use it to schedule work in the calling context. The plugin MUST 14: NOT assume any relationship between different schedule features.
15: 16: Invalid documentation for http://lv2plug.in/ns/ext/worker Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension allows plugins to schedule work that must be performed in 10: another thread. Plugins can use this interface to safely perform work that is 11: not real-time safe, and receive the result in the run context. The details of 12: threading are managed by the host, allowing plugins to be simple and portable 13: while using resources more efficiently.
14:This interface is designed to gracefully support single-threaded synchronous
15: execution, which allows the same code to work with sample accuracy for offline
16: rendering. For example, a sampler plugin may schedule a sample to be loaded
17: from disk in another thread. During live execution, the host will call the
18: plugin's work method from another thread, and deliver the result to the audio
19: thread when it is finished. However, during offline export, the
20: scheduled
load would be executed immediately in the same thread. This
21: enables reproducible offline rendering, where any changes affect the output
22: immediately regardless of how long the work takes to execute.
This is the native UI type on Mac OS X.
10: 11: Invalid documentation for http://lv2plug.in/ns/extensions/ui#Gtk3UI Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The host must guarantee that the Gtk+ 3 library has been initialised and the 10: Glib main loop is running before the UI is instantiated. Note that this UI 11: type is not suitable for binary distribution since multiple versions of Gtk can 12: not be used in the same process.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#GtkUI Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The host must guarantee that the Gtk+ 2 library has been initialised and the 10: Glib main loop is running before the UI is instantiated. Note that this UI 11: type is not suitable for binary distribution since multiple versions of Gtk can 12: not be used in the same process.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#PortNotification Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This describes which ports the host must send notifications to the UI about. 10: The port must be specific either by index, using the portIndex property, or 11: symbol, using the lv2:symbol property. Since port indices are not guaranteed 12: to be stable, using the symbol is recommended, and the inde MUST NOT be used 13: except by UIs that are shipped in the same bundle as the corresponding plugin.
14: 15: Invalid documentation for http://lv2plug.in/ns/extensions/ui#PortProtocol Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A PortProtocol MUST define:
10:A PortProtocol for an output port MUST define:
17:A PortProtocol for an input port MUST define:
26:For an example, see floatProtocol or peakProtocol.
33:PortProtocol is a subclass of lv2:Feature, so UIs use lv2:optionalFeature and 34: lv2:requiredFeature to specify which PortProtocols they want to use.
35: 36: Invalid documentation for http://lv2plug.in/ns/extensions/ui#Qt4UI Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The host must guarantee that the Qt4 library has been initialised and the Qt4 10: main loop is running before the UI is instantiated. Note that this UI type is 11: not suitable for binary distribution since multiple versions of Qt can not be 12: used in the same process.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#Qt5UI Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The host must guarantee that the Qt5 library has been initialised and the Qt5 10: main loop is running before the UI is instantiated. Note that this UI type is 11: not suitable for binary distribution since multiple versions of Qt can not be 12: used in the same process.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#WindowsUI Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Note that the LV2UI_Widget for this type of UI is not a pointer, but should be
10: interpreted directly as a HWND. This is the native UI type on Microsoft
11: Windows.
Note that the LV2UI_Widget for this type of UI is not a pointer, but should be
10: interpreted directly as an X11 Window ID. This is the native UI type on most
11: POSIX systems.
The background color of the host's UI. The host can pass this as an option so 10: that UIs can integrate nicely with the host window around it.
11:Hosts should pass this as an option to UIs with an integer RGBA32 color value. 12: If the value is a 32-bit integer, it is guaranteed to be in RGBA32 format, but 13: the UI must check the value type and not assume this, to allow for other types 14: of color in the future.
15: 16: Invalid documentation for http://lv2plug.in/ns/extensions/ui#binary Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This property is redundant and deprecated: new UIs should use lv2:binary 10: instead, however hosts must still support binary.
11: 12: Invalid documentation for http://lv2plug.in/ns/extensions/ui#foregroundColor Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:The foreground color of the host's UI. The host can pass this as an option so 10: that UIs can integrate nicely with the host window around it.
11:Hosts should pass this as an option to UIs with an integer RGBA32 color value. 12: If the value is a 32-bit integer, it is guaranteed to be in RGBA32 format, but 13: the UI must check the value type and not assume this, to allow for other types 14: of color in the future.
15: 16: Invalid documentation for http://lv2plug.in/ns/extensions/ui#notifyType Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Specifies a particular type that the UI should be notified of.
10:This is useful for message-based ports where several types of data can be 11: present, but only some are interesting to the UI. For example, if UI control 12: is multiplexed in the same port as MIDI, this property can be used to ensure 13: that only the relevant events are forwarded to the UI, and not potentially high 14: frequency MIDI data.
15: 16: Invalid documentation for http://lv2plug.in/ns/extensions/ui#portNotification Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:Specifies that a UI should receive notifications about changes to a particular 10: port's value via LV2UI_Descriptor::port_event().
11:For example:
12:eg:ui
13: a ui:X11UI ;
14: ui:portNotification [
15: ui:plugin eg:plugin ;
16: lv2:symbol "gain" ;
17: ui:protocol ui:floatProtocol
18: ] .
19: HiDPI (High Dots Per Inch) displays have a high resolution on a relatively 10: small form factor. Many systems use a scale factor to compensate for this, so 11: for example, a scale factor of 2 means things are drawn twice as large as 12: normal.
13:Hosts can pass this as an option to UIs to communicate this information, so 14: that the UI can draw at an appropriate scale.
15: 16: Invalid documentation for http://lv2plug.in/ns/extensions/ui#fixedSize Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:If a UI has this feature, it indicates the same thing as noUserResize, and 10: additionally that the UI will not resize itself on its own. That is, the UI 11: will always remain the same size. This feature may not make sense for all UI 12: types. The data pointer for this feature should always be set to NULL.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#floatProtocol Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:A protocol for transferring single floating point values. The rules for this 10: protocol are:
11:float.float.To support this feature, the UI should list it as a lv2:optionalFeature or 10: lv2:requiredFeature in its data, and also as lv2:extensionData. When the UI's 11: extension_data() is called with this URI (LV2_UI__idleInterface), it should 12: return a pointer to an LV2UI_Idle_Interface.
13:To indicate support, the host should pass a feature to instantiate() with this 14: URI, with NULL for data.
15: 16: Invalid documentation for http://lv2plug.in/ns/extensions/ui#makeSONameResident Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This feature was intended to support UIs that link against toolkit libraries
10: which may not be unloaded during the lifetime of the host. This is better
11: achieved by using the appropriate flags when linking the UI, for example gcc
12: -Wl,-z,nodelete.
If a UI has this feature, it indicates that it does not make sense to let the 10: user resize the main widget, and the host should prevent that. This feature 11: may not make sense for all UI types. The data pointer for this feature should 12: always be set to NULL.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#parent Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This feature can be used to pass a parent that the UI should be a child of.
10: The format of data pointer of this feature is determined by the UI type, and is
11: generally the same type as the LV2UI_Widget that the UI would return. For
12: example, for a X11UI, the parent should be a Window. This is particularly
13: useful for embedding, where the parent often must be known at construction time
14: for embedding to work correctly.
UIs should not require this feature unless it is necessary for them to work 16: at all, but hosts should provide it whenever possible.
17: 18: Invalid documentation for http://lv2plug.in/ns/extensions/ui#peakProtocol Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This port protocol defines a way for the host to send continuous peak 10: measurements of the audio signal at a certain port to the UI. The intended use 11: is visualisation, for example an animated meter widget that shows the level of 12: the audio input or output.
13:A contiguous sequence of audio samples for which a peak value has been computed 14: is called a measurement period.
15:The rules for this protocol are:
16:This makes it possible to implement and distribute UIs separately from the 10: plugin binaries they control.
11:This feature corresponds to the LV2UI_Port_Index struct, which should be passed 12: with the URI LV2_UI__portIndex.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#portSubscribe Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/ui.lv2/ui.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) 5: 6:This makes it possible for a UI to explicitly request a particular style of 10: update from a port at run-time, in a more flexible and powerful way than 11: listing subscriptions statically allows.
12:This feature corresponds to the LV2UI_Port_Subscribe struct, which should be 13: passed with the URI LV2_UI__portSubscribe.
14: 15: Invalid documentation for http://lv2plug.in/ns/extensions/ui#requestValue Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This allows a plugin UI to request a new parameter value using the host's UI, 10: for example by showing a dialog or integrating with the host's built-in content 11: browser. This should only be used for complex parameter types where the plugin 12: UI is not capable of showing the expected native platform or host interface to 13: choose a value, such as file path parameters.
14:This feature corresponds to the LV2UI_Request_Value struct, which should be 15: passed with the URI LV2_UI__requestValue.
16: 17: Invalid documentation for http://lv2plug.in/ns/extensions/ui#resize Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This feature corresponds to the LV2UI_Resize struct, which should be passed 10: with the URI LV2_UI__resize. This struct may also be provided by the UI as 11: extension data using the same URI, in which case it is used by the host to 12: request that the UI change its size.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#showInterface Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This allows UIs to gracefully degrade to separate windows when the host is 10: unable to embed the UI widget for whatever reason. When the UI's 11: extension_data() is called with this URI (LV2_UI__showInterface), it should 12: return a pointer to an LV2UI_Show_Interface.
13: 14: Invalid documentation for http://lv2plug.in/ns/extensions/ui#touch Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is useful for automation, so the host can allow the user to take control 10: of a port, even if that port would otherwise be automated (much like grabbing a 11: physical motorised fader).
12:It can also be used for MIDI learn or in any other situation where the host 13: needs to do something with a particular control and it would be convenient for 14: the user to select it directly from the plugin UI.
15:This feature corresponds to the LV2UI_Touch struct, which should be passed with 16: the URI LV2_UI__touch.
17: 18: Invalid documentation for http://lv2plug.in/ns/extensions/ui Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This extension makes it possible to create user interfaces for LV2 plugins.
10:UIs are implemented as an LV2UI_Descriptor loaded via lv2ui_descriptor() in a 11: shared library, and are distributed in bundles just like plugins.
12:UIs are associated with plugins in data:
13:@prefix ui: <http://lv2plug.in/ns/extensions/ui#> .
14:
15: <http://my.plugin> ui:ui <http://my.pluginui> .
16: <http://my.pluginui> a ui:X11UI ;
17: lv2:binary <myui.so> .
18: where http://my.plugin is the URI of the plugin, http://my.pluginui is the
21: URI of the plugin UI and myui.so is the relative URI to the shared object
22: file.
While it is possible to have the plugin UI and the plugin in the same shared
24: object file, it is a good idea to keep them separate so that hosts can avoid
25: loading the UI code if they do not need it. A UI MUST specify its class in the
26: RDF data (X11UI in the above example). The class defines what type the UI
27: is, for example what graphics toolkit it uses. Any type of UI class can be
28: defined separately from this extension.
It is possible to have multiple UIs for the same plugin, or to have the UI for 30: a plugin in a different bundle from the actual plugin. This allows plugin UIs 31: to be written independently.
32:Note that the process that loads the shared object file containing the UI code 33: and the process that loads the shared object file containing the actual plugin 34: implementation are not necessarily the same process (and not even necessarily 35: on the same machine). This means that plugin and UI code MUST NOT use 36: singletons and global variables and expect them to refer to the same objects in 37: the UI and the actual plugin. The function callback interface defined in this 38: header is the only method of communication between UIs and plugin instances 39: (extensions may define more, though this is discouraged unless absolutely 40: necessary since the significant benefits of network transparency and 41: serialisability are lost).
42:UI functionality may be extended via features, much like plugins:
43:<http://my.pluginui> lv2:requiredFeature <http://my.feature> .
44: <http://my.pluginui> lv2:optionalFeature <http://my.feature> .
45: The rules for a UI with a required or optional feature are identical to those 48: of lv2:Plugin instances: if a UI declares a feature as required, the host is 49: NOT allowed to load it unless it supports that feature; and if it does support 50: a feature, it MUST pass an appropriate LV2_Feature struct to the UI's 51: instantiate() method. This extension defines several standard features for 52: common functionality.
53:UIs written to this specification do not need to be thread-safe. All functions
54: may only be called in the UI thread
. There is only one UI thread (for
55: toolkits, the one the UI main loop runs in). There is no requirement that a
56: UI
actually be a graphical widget.
Note that UIs are completely separate from plugins. From the plugin's 58: perspective, control from a UI is indistinguishable from any other control, as 59: it all occurs via ports.
60: 61: [38/52] Linking target plugins/eg-amp.lv2/amp.dylib [39/52] Linking target plugins/eg-fifths.lv2/fifths.dylib [40/52] Generating doc/ns/index.html with a custom command (wrapped by meson to capture output) /var/tmp/work/audio/lv2/work/lv2-1.18.10/scripts/lv2_build_index.py:39: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. model = rdflib.ConjunctiveGraph() [41/52] Generating doc/ns/extensions/units.html with a custom command /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1168: DeprecationWarning: ConjunctiveGraph is deprecated, use Dataset instead. m = rdflib.ConjunctiveGraph() /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2specgen/lv2specgen.py:1331: DeprecationWarning: datetime.datetime.utcfromtimestamp() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.fromtimestamp(timestamp, datetime.UTC). build_date = datetime.datetime.utcfromtimestamp(now) error: Validation failed for /var/tmp/work/audio/lv2/work/lv2-1.18.10/lv2/units.lv2/units.ttl: Entity 'xhtml-prefw-redecl.module' not defined, line 96, column 31 (xhtml-rdfa-1.dtd, line 96) Invalid documentation for http://lv2plug.in/ns/extensions/units Entity 'XHTML.bidi' not defined, line 78, column 46 (xhtml-basic11.dtd, line 78) 1: 2: 4: 5: 6:This is a vocabulary for units typically used for control values in audio 10: processing.
11:For example, to say that a gain control is in decibels:
12:@prefix units: <http://lv2plug.in/ns/extensions/units#> .
13: @prefix eg: <http://example.org/> .
14:
15: eg:plugin lv2:port [
16: a lv2:ControlPort , lv2:InputPort ;
17: lv2:index 0 ;
18: lv2:symbol "gain" ;
19: lv2:name "Gain" ;
20: units:unit units:db
21: ] .
22: Using the same form, plugins may also specify one-off units inline, to give 25: better display hints to hosts:
26:eg:plugin lv2:port [
27: a lv2:ControlPort , lv2:InputPort ;
28: lv2:index 0 ;
29: lv2:symbol "frob" ;
30: lv2:name "frob level" ;
31: units:unit [
32: a units:Unit ;
33: rdfs:label "frobnication" ;
34: units:symbol "fr" ;
35: units:render "%f f"
36: ]
37: ] .
38: It is also possible to define conversions between various units, which makes it 41: possible for hosts to automatically convert between units where possible. The 42: units defined in this extension include conversion definitions where it makes 43: sense to do so.
44: 45: [42/52] Linking target plugins/eg-metro.lv2/metro.dylib [43/52] Linking target plugins/eg-midigate.lv2/midigate.dylib [44/52] Linking target plugins/eg-params.lv2/params.dylib [45/52] Linking target plugins/eg-sampler.lv2/sampler_ui.dylib [46/52] Linking target plugins/eg-sampler.lv2/sampler.dylib [47/52] Linking target plugins/eg-scope.lv2/examploscope.dylib [48/52] Linking target plugins/eg-scope.lv2/examploscope_ui.dylib [49/52] Linking target test/test_build_c [50/52] Linking target test/atom [51/52] Linking target test/forge_overflow [52/52] Generating plugins/book.html with a custom command *** Please use pkgtools/verifypc to sanity check dependencies.