Lilv Python DocumentationΒΆ

Lilv Python interface

class lilv.Instance(plugin, rate, features=None)

Plugin instance.

activate()

Activate a plugin instance.

This resets all state information in the plugin, except for port data locations (as set by connect_port()). This MUST be called before calling run().

connect_port(port_index, data)

Connect a port to a data location.

This may be called regardless of whether the plugin is activated, activation and deactivation does not destroy port connections.

deactivate()

Deactivate a plugin instance.

Note that to run the plugin after this you must activate it, which will reset all state information (except port connections).

get_descriptor()

Get the LV2_Descriptor of the plugin instance.

Normally hosts should not need to access the LV2_Descriptor directly, use the lilv_instance_* functions.

get_extension_data(uri)

Get extension data from the plugin instance.

The type and semantics of the data returned is specific to the particular extension, though in all cases it is shared and must not be deleted.

get_handle()

Get the LV2_Handle of the plugin instance.

Normally hosts should not need to access the LV2_Handle directly, use the lilv_instance_* functions.

get_uri()

Get the URI of the plugin which instance is an instance of.

Returned string is shared and must not be modified or deleted.

run(sample_count)

Run instance for sample_count frames.

If the hint lv2:hardRTCapable is set for this plugin, this function is guaranteed not to block.

class lilv.Iter(collection, iterator, constructor, iter_get, iter_next, iter_is_end)

Collection iterator.

get()

Get the current item.

is_end()

Return true if the end of the collection has been reached.

next()

Move to and return the next item.

class lilv.Namespace(world, prefix)

Namespace prefix.

Use attribute syntax to easily create URIs within this namespace, for example:

>>> world = lilv.World()
>>> ns = Namespace(world, "http://example.org/")
>>> print(ns.foo)
http://example.org/foo
class lilv.Node(node)

Data node (URI, string, integer, etc.).

A Node can be converted to the corresponding Python datatype, and all nodes can be converted to strings, for example:

>>> world = lilv.World()
>>> i = world.new_int(42)
>>> print(i)
42
>>> int(i) * 2
84
get_path(hostname=None)

Return the path of a file URI node.

Returns None if value is not a file URI.

get_turtle_token()

Return this value as a Turtle/SPARQL token.

is_blank()

Return whether the value is a blank node (resource with no URI).

is_bool()

Return whether this value is a boolean.

is_float()

Return whether this value is a decimal literal.

is_int()

Return whether this value is an integer literal.

is_literal()

Return whether this value is a literal (i.e. not a URI).

is_string()

Return whether this value is a string literal.

Returns true if value is a string value (and not numeric).

is_uri()

Return whether the value is a URI (resource).

class lilv.Nodes(collection)

Collection of data nodes.

class lilv.Plugin(world, plugin)

LV2 Plugin.

get_author_email()

Get the email address of the plugin’s author.

Returns None if author email address is not present.

get_author_homepage()

Get the address of the plugin author’s home page.

Returns None if author homepage is not present.

get_author_name()

Get the full name of the plugin’s author.

Returns None if author name is not present.

get_bundle_uri()

Get the (resolvable) URI of the plugin’s “main” bundle.

This returns the URI of the bundle where the plugin itself was found. Note that the data for a plugin may be spread over many bundles, that is, get_data_uris() may return URIs which are not within this bundle.

Typical hosts should not need to use this function. Note this always returns a fully qualified URI. If you want a local filesystem path, use lilv.file_uri_parse().

get_class()

Get the class this plugin belongs to (e.g. Filters).

get_data_uris()

Get the (resolvable) URIs of the RDF data files that define a plugin.

Typical hosts should not need to use this function. Note this always returns fully qualified URIs. If you want local filesystem paths, use lilv.file_uri_parse().

get_extension_data()

Get a sequence of all extension data provided by a plugin.

This can be used to find which URIs get_extension_data() will return a value for without instantiating the plugin.

get_latency_port_index()

Return the index of the plugin’s latency port.

Returns None if the plugin has no latency port.

Any plugin that introduces unwanted latency that should be compensated for (by hosts with the ability/need) MUST provide this port, which is a control rate output port that reports the latency for each cycle in frames.

get_library_uri()

Get the (resolvable) URI of the shared library for plugin.

Note this always returns a fully qualified URI. If you want a local filesystem path, use lilv.file_uri_parse().

get_name()

Get the name of plugin.

This returns the name (doap:name) of the plugin. The name may be translated according to the current locale, this value MUST NOT be used as a plugin identifier (use the URI for that).

get_num_ports()

Get the number of ports on this plugin.

get_num_ports_of_class(*args)

Get the number of ports on this plugin that are members of some class(es).

get_optional_features()

Get the LV2 Features optionally supported by a plugin.

Hosts MAY ignore optional plugin features for whatever reasons. Plugins MUST operate (at least somewhat) if they are instantiated without being passed optional features.

get_port(key)

Get a port on plugin by index or symbol.

get_port_by_designation(port_class, designation)

Get a port on plugin by its lv2:designation.

The designation of a port describes the meaning, assignment, allocation or role of the port, e.g. “left channel” or “gain”. If found, the port with matching port_class and designation is be returned, otherwise None is returned. The port_class can be used to distinguish the input and output ports for a particular designation. If port_class is None, any port with the given designation will be returned.

get_port_by_index(index)

Get a port on plugin by index.

get_port_by_symbol(symbol)

Get a port on plugin by symbol.

Note this function is slower than get_port_by_index(), especially on plugins with a very large number of ports.

get_project()

Get the project the plugin is a part of.

More information about the project can be read via find_nodes(), typically using properties from DOAP (e.g. doap:name).

get_related(resource_type)

Get the resources related to plugin with lv2:appliesTo.

Some plugin-related resources are not linked directly to the plugin with rdfs:seeAlso and thus will not be automatically loaded along with the plugin data (usually for performance reasons). All such resources of the given @c type related to plugin can be accessed with this function.

If resource_type is None, all such resources will be returned, regardless of type.

To actually load the data for each returned resource, use world.load_resource().

get_required_features()

Get the LV2 Features required by a plugin.

If a feature is required by a plugin, hosts MUST NOT use the plugin if they do not understand (or are unable to support) that feature.

All values returned here MUST be return plugin_(self.plugin)ed to the plugin’s instantiate method (along with data, if necessary, as defined by the feature specification) or plugin instantiation will fail.

get_supported_features()

Get the LV2 Features supported (required or optionally) by a plugin.

A feature is “supported” by a plugin if it is required OR optional.

Since required features have special rules the host must obey, this function probably shouldn’t be used by normal hosts. Using get_optional_features() and get_required_features() separately is best in most cases.

get_uis()

Get all UIs for plugin.

get_uri()

Get the URI of plugin.

Any serialization that refers to plugins should refer to them by this. Hosts SHOULD NOT save any filesystem paths, plugin indexes, etc. in saved files pass save only the URI.

The URI is a globally unique identifier for one specific plugin. Two plugins with the same URI are compatible in port signature, and should be guaranteed to work in a compatible and consistent way. If a plugin is upgraded in an incompatible way (eg if it has different ports), it MUST have a different URI than it’s predecessor.

get_value(predicate)

Get a value associated with the plugin in a plugin’s data files.

predicate must be either a URI or a QName.

Returns the ?object of all triples found of the form:

plugin-uri predicate ?object

May return None if the property was not found, or if object(s) is not sensibly represented as a LilvNodes (e.g. blank nodes).

has_extension_data(uri)

Return whether or not a plugin provides a specific extension data.

has_feature(feature_uri)

Return whether a feature is supported by a plugin.

This will return true if the feature is an optional or required feature of the plugin.

has_latency()

Return whether or not the plugin introduces (and reports) latency.

The index of the latency port can be found with get_latency_port() ONLY if this function returns true.

is_replaced()

Return true iff plugin has been replaced by another plugin.

The plugin will still be usable, but hosts should hide them from their user interfaces to prevent users from using deprecated plugins.

verify()

Check if plugin is valid.

This is not a rigorous validator, but can be used to reject some malformed plugins that could cause bugs (e.g. plugins with missing required fields).

Note that normal hosts do NOT need to use this - lilv does not load invalid plugins into plugin lists. This is included for plugin testing utilities, etc.

class lilv.PluginClass(plugin_class)

Plugin Class (type/category).

get_children()

Get the subclasses of this plugin class.

get_label()

Get the label of this plugin class, ie “Oscillators”.

get_parent_uri()

Get the URI of this class’ superclass.

May return None if class has no parent.

get_uri()

Get the URI of this plugin class.

class lilv.PluginClasses(collection)

Collection of plugin classes.

class lilv.Plugins(world, collection)

Collection of plugins.

class lilv.Port(plugin, port)

Port on a Plugin.

get(predicate)

Get a single property value of a port.

This is equivalent to lilv_nodes_get_first(lilv_port_get_value(...)) but is simpler to use in the common case of only caring about one value. The caller is responsible for freeing the returned node.

get_classes()

Get all the classes of a port.

This can be used to determine if a port is an input, output, audio, control, midi, etc, etc, though it’s simpler to use is_a(). The returned list does not include lv2:Port, which is implied. Returned value is shared and must not be destroyed by caller.

get_index()

Get the index of a port.

The index is only valid for the life of the plugin and may change between versions. For a stable identifier, use the symbol.

get_name()

Get the name of a port.

This is guaranteed to return the untranslated name (the doap:name in the data file without a language tag).

get_node()

Get the RDF node of port.

Ports nodes may be may be URIs or blank nodes.

get_properties()

Return the LV2 port properties of a port.

get_range()

Return the default, minimum, and maximum values of a port as a tuple.

get_scale_points()

Get the scale points (enumeration values) of a port.

This returns a collection of ‘interesting’ named values of a port (e.g. appropriate entries for a UI selector associated with this port). Returned value may be None if port has no scale points.

get_symbol()

Get the symbol of a port.

The ‘symbol’ is a short string, a valid C identifier.

get_value(predicate)

Port analog of Plugin.get_value().

has_property(property_uri)

Return whether a port has a certain property.

is_a(port_class)

Determine if a port is of a given class (input, output, audio, etc).

For convenience/performance/extensibility reasons, hosts are expected to create a LilvNode for each port class they “care about”. Well-known type URI strings are defined (e.g. LILV_URI_INPUT_PORT) for convenience, but this function is designed so that Lilv is usable with any port types without requiring explicit support in Lilv.

supports_event(event_type)

Return whether a port supports a certain event type.

More precisely, this returns true iff the port has an atom:supports or an ev:supportsEvent property with event_type as the value.

class lilv.ScalePoint(point)

Scale point (detent).

get_label()

Get the label of this scale point (enumeration value).

get_value()

Get the value of this scale point (enumeration value).

class lilv.ScalePoints(collection)

Collection of scale points.

class lilv.State

Plugin state (TODO).

class lilv.UI(ui)

Plugin UI.

get_binary_uri()

Get the URI for the UI’s shared library.

get_bundle_uri()

Get the URI of the UI’s bundle.

get_classes()

Get the types (URIs of RDF classes) of a Plugin UI.

Note that in most cases is_supported() should be used, which avoids
the need to use this function (and type specific logic).
get_uri()

Get the URI of a Plugin UI.

is_a(class_uri)

Check whether a plugin UI has a given type.

class lilv.UIs(collection)

Collection of plugin UIs.

class lilv.World

Library context.

Includes a set of namespaces as the instance variable ns, so URIs can be constructed like:

uri = world.ns.lv2.Plugin
Variables:ns – Common LV2 namespace prefixes: atom, doap, foaf, lilv, lv2, midi, owl, rdf, rdfs, ui, xsd.
ask(subject, predicate, obj)

Return true iff a statement matching a certain pattern exists.

This is useful for checking if particular statement exists without having to bother with collections and memory management.

find_nodes(subject, predicate, obj)

Find nodes matching a triple pattern.

Either subject or object may be None (i.e. a wildcard), but not both. Returns all matches for the wildcard field, or None.

get(subject, predicate, obj)

Find a single node that matches a pattern.

Exactly one of subject, predicate, object must be None.

Returns the first matching node, or None if no matches are found.

get_all_plugins()

Return a list of all found plugins.

The returned list contains just enough references to query or instantiate plugins. The data for a particular plugin will not be loaded into memory until a call to an lilv_plugin_* function results in a query (at which time the data is cached with the LilvPlugin so future queries are very fast).

The returned list and the plugins it contains are owned by world and must not be freed by caller.

get_plugin_class()

Get the parent of all other plugin classes, lv2:Plugin.

get_plugin_classes()

Return a list of all found plugin classes.

load_all()

Load all installed LV2 bundles on the system.

This is the recommended way for hosts to load LV2 data. It implements the established/standard best practice for discovering all LV2 data on the system. The environment variable LV2_PATH may be used to control where this function will look for bundles.

Hosts should use this function rather than explicitly load bundles, except in special circumstances (e.g. development utilities, or hosts that ship with special plugin bundles which are installed to a known location).

load_bundle(bundle_uri)

Load a specific bundle.

bundle_uri must be a fully qualified URI to the bundle directory, with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/

Normal hosts should not need this function (use load_all()).

Hosts MUST NOT attach any long-term significance to bundle paths (e.g. in save files), since there are no guarantees they will remain unchanged between (or even during) program invocations. Plugins (among other things) MUST be identified by URIs (not paths) in save files.

load_plugin_classes()

Load all plugin classes from currently loaded specifications.

Must be called after load_specifications(). This is for hosts that explicitly load specific bundles, its use is not necessary when using load_all().

load_resource(resource)

Load all the data associated with the given resource.

The resource must be a subject (i.e. a URI or a blank node). Returns the number of files parsed, or -1 on error.

All accessible data files linked to resource with rdfs:seeAlso will be loaded into the world model.

load_specifications()

Load all specifications from currently loaded bundles.

This is for hosts that explicitly load specific bundles, its use is not necessary when using load_all(). This function parses the specifications and adds them to the model.

new_bool(val)

Create a new bool node.

new_file_uri(host, path)

Create a new file URI node. The host may be None.

new_float(val)

Create a new float node.

new_int(val)

Create a new int node.

new_string(string)

Create a new string node.

new_uri(uri)

Create a new URI node.

set_option(uri, value)

Set a world option.

Currently recognized options: lilv.OPTION_FILTER_LANG lilv.OPTION_DYN_MANIFEST

unload_bundle(bundle_uri)

Unload a specific bundle.

This unloads statements loaded by load_bundle(). Note that this is not necessarily all information loaded from the bundle. If any resources have been separately loaded with load_resource(), they must be separately unloaded with unload_resource().

unload_resource(resource)

Unload all the data associated with the given resource.

The resource must be a subject (i.e. a URI or a blank node).

This unloads all data loaded by a previous call to load_resource() with the given resource.