# Lilv

Lilv is a library for working with LV2 plugins. It provides several types and functions that can be used to discover plugins, investigate their data, load and run them, and save and restore their state.

Lilv is the standard implementation used by nearly all LV2 hosts. It implements the details of the LV2 specification on POSIX, MacOS, and Windows, and provides a simpler portable API for applications.

## Overview

The complete API is declared in `lilv.h`:

    #include <lilv/lilv.h>

### World

The world is the top-level object which represents an instance of Lilv. It is used to discover and load LV2 data, and stores an internal cache of loaded data for fast searching.

An application typically has a single world, which is constructed once on startup and used throughout the application’s lifetime.

#### Construction

A world must be created before anything else. A world is created with `lilv_world_new()`, for example:

    LilvWorld* world = lilv_world_new();

#### Setting Options

Various options to control Lilv’s behavior can be set with `lilv_world_set_option()`. The currently supported options are `LILV_OPTION_FILTER_LANG`, `LILV_OPTION_DYN_MANIFEST`, `LILV_OPTION_LV2_PATH`, and `LILV_OPTION_OBJECT_INDEX`.

For example, to set the LV2 path to only load plugins bundled in the application:

    LilvNode* lv2_path = lilv_new_string(world, "/myapp/lv2");

    lilv_world_set_option(world, LILV_OPTION_LV2_PATH, lv2_path);

#### Loading Data

Before using anything, data must be loaded from disk. All LV2 data (plugins, UIs, specifications, presets, and so on) is installed in bundles, a standard directory format

##### Discovering and Loading Bundles

Typical hosts will simply load all bundles in the standard LV2 locations on the system:

    lilv_world_load_all(world);

This will discover all bundles on the system, as well as load the required data defined in any discovered specifications.

It is also possible to load a specific bundle:

    LilvNode* bundle_uri = lilv_new_file_uri(world, NULL, "/some/plugin.lv2");

    lilv_world_load_bundle(world, bundle_uri);

The LV2 specification itself is also installed in bundles, so if you are not using `lilv_world_load_all()`, it is necessary to manually load the discovered specification data:

    lilv_world_load_specifications(world);
    lilv_world_load_plugin_classes(world);

#### Querying Data

The world contains a model of all the loaded data in memory which can be queried.

##### Data Model

LV2 data is a set of “statements”, where a statement is a bit like a simple machine-readable sentence. The “subject” and “object” are as in natural language, and the “predicate” is like the verb, but more general.

For example, we could make a statement about a plugin in english:

> MyOsc has the name “Super Oscillator”

We can break this statement into 3 pieces like so:

Subject | Predicate | Object
--- | --- | ---
MyOsc | has the name | “My Super Oscillator”

Statements use URIs to identify things. In this case, we assume that this plugin has the URI `http://example.org/Osc`. The LV2 specification defines that `http://usefulinc.com/ns/doap#name` is the property used to describe a plugin’s name. So, this statement is:

Subject | Predicate | Object
--- | --- | ---
`http://example.org/Osc` | `http://usefulinc.com/ns/doap#name` | “My Oscillator”

##### Finding Values

Based on this model, you can find all values that match a certain pattern. Patterns are just statements, but with `NULL` used as a wildcard that matches anything. So, for example, you can get the name of a plugin using `lilv_world_find_nodes()`:

    LilvNode* plugin_uri = lilv_new_uri(world, "http://example.org/Osc");
    LilvNode* doap_name  = lilv_new_uri(world, "http://usefulinc.com/ns/doap#name");

    LilvNodes* values = lilv_world_find_nodes(world, plugin_uri, doap_name, NULL);

Note that a set of values is returned, because some properties may have several values. When you are only interested in one value, you can use the simpler `lilv_world_get()` instead:

    LilvNode* value = lilv_world_get(world, plugin_uri, doap_name, NULL);

If you are only interested if a value exists at all, use `lilv_world_ask()`:

    bool has_name = lilv_world_ask(world, plugin_uri, doap_name, NULL);

### Plugins

After bundles are loaded, all discovered plugins can be accessed via `lilv_world_get_all_plugins()`:

    LilvPlugins* plugins = lilv_world_get_all_plugins(world);

`LilvPlugins` is a collection of plugins that can be accessed by index or plugin URI. The convenicne macro `LILV_FOREACH` is provided to make iterating over collections simple. For example, to print the URI of every plugin:

    LILV_FOREACH (plugins, i, list) {
      const LilvPlugin* p = lilv_plugins_get(list, i);
        printf("%s\n", lilv_node_as_uri(lilv_plugin_get_uri(p)));
      }
    }

More typically, you want to load a specific plugin, which can be done with `lilv_plugins_get_by_uri()`:

    LilvNode* plugin_uri = lilv_new_uri(world, "http://example.org/Osc");

    const LilvPlugin* plugin = lilv_plugins_get_by_uri(list, plugin_uri);

`LilvPlugin` has various accessors that can be used to get information about the plugin. See the API reference for details.

#### Instances

`LilvPlugin` only represents the data of the plugin, it does not load or access the actual plugin code. To do that, you must instantiate a plugin to create `LilvInstance`:

    LilvInstance* instance = lilv_plugin_instantiate(plugin, 48000.0, NULL);

##### Connecting Ports

Before running a plugin instance, its ports must be connected to some data. This is done with `lilv_instance_connect_port()`. Assuming the plugins has two control input ports and one audio output port, in that order:

    float control_in_1 = 0.0f;
    float control_in_2 = 0.0f;

    float audio_out[128];

    lilv_instance_connect_port(instance, 0, &control_in_1);
    lilv_instance_connect_port(instance, 1, &control_in_2);
    lilv_instance_connect_port(instance, 2, &audio_out);

##### Processing Data

Once the ports are connected, the instance can be activated and run:

    lilv_instance_activate(instance);

    lilv_instance_run(instance, 128);
    // Copy buffers around and probably run several times here...

    lilv_instance_deactivate(instance);

Once you are done with an instance, it can be destroyed with `lilv_instance_free()`:

    lilv_instance_free(instance);

### User Interfaces

Plugins may have custom user interfaces, or UIs, which are installed in bundles just like plugins.

The available UIs for a plugin can be accessed with `lilv_plugin_get_uis()`:

    LilvUIs* uis = lilv_plugin_get_uis(plugin);

`LilvUIs` is a collection much like LilvPlugins, except it is of course a set of `LilvUI` rather than a set of `LilvPlugin`. Also like plugins, the `LilvUI` class has various accessors that can be used to get information about the UI. See the API reference for details.

## Lilv C API

This is the complete public C API of lilv.

### Nodes

char *lilv_file_uri_parse(const char *uri, char **hostname)

  Convert a file URI string to a local path string.

  For example, “file://foo/bar%20one/baz.ttl” returns “/foo/bar one/baz.ttl”. Return value must be freed by caller with `lilv_free()`.

  Parameters:

    - uri – The file URI to parse.

    - hostname – If non-NULL, set to the hostname in the URI, if any.

  Returns:

    `uri` converted to a path, or NULL on failure (URI is not local).

LilvNode *lilv_new_bool(LilvWorld *world, bool val)

  Create a new boolean value.

  Returned value must be freed by caller with `lilv_node_free()`.

LilvNode *lilv_new_file_uri(LilvWorld *world, const char *host, const char *path)

  Create a new file URI value.

  Relative paths are resolved against the current working directory. Note that this may yield unexpected results if `host` is another machine.

  Parameters:

    - world – The world.

    - host – Host name, or NULL.

    - path – Path on host.

  Returns:

    A new node that must be freed by caller.

LilvNode *lilv_new_float(LilvWorld *world, float val)

  Create a new floating point value.

  Returned value must be freed by caller with `lilv_node_free()`.

LilvNode *lilv_new_int(LilvWorld *world, int val)

  Create a new integer value.

  Returned value must be freed by caller with `lilv_node_free()`.

LilvNode *lilv_new_string(LilvWorld *world, const char *str)

  Create a new string value (with no language).

  Returned value must be freed by caller with `lilv_node_free()`.

LilvNode *lilv_new_uri(LilvWorld *world, const char *uri)

  Create a new URI value.

  Returned value must be freed by caller with `lilv_node_free()`.

const char *lilv_node_as_blank(const LilvNode *value)

  Return this value as a blank node identifier, like “genid03”.

  Valid to call only if `lilv_node_is_blank(value)` returns true. Returned value is owned by `value` and must not be freed by caller.

bool lilv_node_as_bool(const LilvNode *value)

  Return `value` as a bool.

  Valid to call only if `lilv_node_is_bool(value)` returns true.

float lilv_node_as_float(const LilvNode *value)

  Return `value` as a float.

  Valid to call only if `lilv_node_is_float(value)` or `lilv_node_is_int(value)` returns true.

int lilv_node_as_int(const LilvNode *value)

  Return `value` as an integer.

  Valid to call only if `lilv_node_is_int(value)` returns true.

const char *lilv_node_as_string(const LilvNode *value)

  Return `value` as a string.

const char *lilv_node_as_uri(const LilvNode *value)

  Return this value as a URI string, like “http://example.org/foo”.

  Valid to call only if `lilv_node_is_uri(value)` returns true. Returned value is owned by `value` and must not be freed by caller.

LilvNode *lilv_node_duplicate(const LilvNode *val)

  Duplicate a `LilvNode`.

bool lilv_node_equals(const LilvNode *value, const LilvNode *other)

  Return whether two values are equivalent.

void lilv_node_free(LilvNode *val)

  Free a `LilvNode`.

  It is safe to call this function on NULL.

char *lilv_node_get_path(const LilvNode *value, char **hostname)

  Return the path of a file URI node.

  Returns NULL if `value` is not a file URI. Returned value must be freed by caller with `lilv_free()`.

char *lilv_node_get_turtle_token(const LilvNode *value)

  Return this value as a Turtle/SPARQL token.

  Returned value must be freed by caller with `lilv_free()`.

  Example tokens:

  - URI: <http://example.org/foo&gt;

  - QName: doap:name

  - String: “this is a string”

  - Float: 1.0

  - Integer: 1

  - Boolean: true

bool lilv_node_is_blank(const LilvNode *value)

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

bool lilv_node_is_bool(const LilvNode *value)

  Return whether this value is a boolean.

bool lilv_node_is_float(const LilvNode *value)

  Return whether this value is a decimal literal.

bool lilv_node_is_int(const LilvNode *value)

  Return whether this value is an integer literal.

bool lilv_node_is_literal(const LilvNode *value)

  Return whether this value is a literal (that is, not a URI).

  Returns true if `value` is a string or numeric value.

bool lilv_node_is_string(const LilvNode *value)

  Return whether this value is a string literal.

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

bool lilv_node_is_uri(const LilvNode *value)

  Return whether the value is a URI (resource).

const char *lilv_uri_to_path(const char *uri)

  Convert a file URI string to a local path string.

  For example, “file://foo/bar/baz.ttl” returns “/foo/bar/baz.ttl”. Return value is shared and must not be deleted by caller. This function does not handle escaping correctly and should not be used for general file URIs. Use `lilv_file_uri_parse()` instead.

  Returns:

    `uri` converted to a path, or NULL on failure (URI is not local).

### Collections

Lilv has several collection types for holding various types of value.

Each collection type supports a similar basic API, except `LilvPlugins` which is internal and thus lacks a free function:

- void PREFIX_free (coll)

- unsigned PREFIX_size (coll)

- LilvIter* PREFIX_begin (coll)

The types of collection are:

- `LilvPlugins`, with function prefix `lilv_plugins_`.

- `LilvPluginClasses`, with function prefix `lilv_plugin_classes_`.

- `LilvScalePoints`, with function prefix `lilv_scale_points_`.

- `LilvNodes`, with function prefix `lilv_nodes_`.

- `LilvUIs`, with function prefix `lilv_uis_`.

LILV_FOREACH(colltype, iter, collection)

  Iterate over each element of a collection.

      LILV_FOREACH(plugin_classes, i, classes) {
         LilvPluginClass c = lilv_plugin_classes_get(classes, i);
         // ...
      }

bool lilv_nodes_contains(const LilvNodes *nodes, const LilvNode *value)

  Return whether `values` contains `value`.

LilvNodes *lilv_nodes_merge(const LilvNodes *a, const LilvNodes *b)

  Return a new `LilvNodes` that contains all nodes from both `a` and `b`.

const LilvPluginClass *lilv_plugin_classes_get_by_uri(const LilvPluginClasses *classes, const LilvNode *uri)

  Get a plugin class from `classes` by URI.

  Return value is shared (stored in `classes`) and must not be freed or modified by the caller in any way.

  Returns:

    NULL if no plugin class with `uri` is found in `classes`.

const LilvPlugin *lilv_plugins_get_by_uri(const LilvPlugins *plugins, const LilvNode *uri)

  Get a plugin from `plugins` by URI.

  Return value is shared (stored in `plugins`) and must not be freed or modified by the caller in any way.

  Returns:

    NULL if no plugin with `uri` is found in `plugins`.

const LilvUI *lilv_uis_get_by_uri(const LilvUIs *uis, const LilvNode *uri)

  Get a UI from `uis` by URI.

  Return value is shared (stored in `uis`) and must not be freed or modified by the caller in any way.

  Returns:

    NULL if no UI with `uri` is found in `list`.

### World

The “world” represents all Lilv state, and is used to discover/load/cache LV2 data (plugins, UIs, and extensions).

Normal hosts which just need to load plugins by URI should simply use `lilv_world_load_all()` to discover/load the system’s LV2 resources.

LILV_OPTION_DYN_MANIFEST

  “http://drobilla.net/ns/lilv#dyn-manifest”

  Enable/disable dynamic manifest support.

  Dynamic manifest data will only be loaded if this option is true.

LILV_OPTION_FILTER_LANG

  “http://drobilla.net/ns/lilv#filter-lang”

  Enable/disable language filtering.

  Language filtering applies to any functions that return (a) value(s). With filtering enabled, Lilv will automatically return the best value(s) for the current LANG. With filtering disabled, all matching values will be returned regardless of language tag. Filtering is enabled by default.

LILV_OPTION_LANG

  “http://drobilla.net/ns/lilv#lang”

  Set application-specific LANG.

  This overrides the LANG from the environment.

LILV_OPTION_LV2_PATH

  “http://drobilla.net/ns/lilv#lv2-path”

  Set application-specific LV2_PATH.

  This overrides the LV2_PATH from the environment, so that lilv will only look inside the given path. This can be used to make self-contained applications.

LILV_OPTION_OBJECT_INDEX

  “http://drobilla.net/ns/lilv#object-index”

  Enable/disable object-first index for queries with subject wildcards.

  This enables additional indexing so that arbitrary query functions like `lilv_world_find_nodes()` efficiently support queries with subject wildcards, at the cost of increased load time and memory consumption.

  This option is enabled by default for backwards compatibility, although most applications can and should disable it to improve performance.

bool lilv_world_ask(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)

  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.

  Parameters:

    - world – The world.

    - subject – Subject of statement, or NULL for anything.

    - predicate – Predicate (key) of statement, or NULL for anything.

    - object – Object (value) of statement, or NULL for anything.

LilvNodes *lilv_world_find_nodes(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)

  Find nodes matching a triple pattern.

  Either `subject` or `object` may be NULL (a wildcard), but not both.

  Returns:

    All matches for the wildcard field, or NULL.

void lilv_world_free(LilvWorld *world)

  Destroy the world.

  It is safe to call this function on NULL. Note that destroying `world` will destroy all the objects it contains. Do not destroy the world until you are finished with all objects that came from it.

LilvNode *lilv_world_get(LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)

  Find a single node that matches a pattern.

  Either `subject` or `object` may be NULL (a wildcard), but not both. This is simplified alternative to `lilv_world_find_nodes()` and lilv_nodes_get_first() for when only a single value is needed.

  Returns:

    The first matching node, or NULL if no matches are found.

const LilvPlugins *lilv_world_get_all_plugins(const LilvWorld *world)

  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.

const LilvPluginClass *lilv_world_get_plugin_class(const LilvWorld *world)

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

const LilvPluginClasses *lilv_world_get_plugin_classes(const LilvWorld *world)

  Return a list of all found plugin classes.

  Returned list is owned by world and must not be freed by the caller.

LilvNode *lilv_world_get_symbol(LilvWorld *world, const LilvNode *subject)

  Get an LV2 symbol for some subject.

  This will return the lv2:symbol property of the subject if it is given explicitly, and otherwise will attempt to derive a symbol from the URI.

  Returns:

    A string node that is a valid LV2 symbol, or NULL on error.

void lilv_world_load_all(LilvWorld *world)

  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 such as development utilities, or hosts that ship with special plugin bundles which are installed to a known location.

void lilv_world_load_bundle(LilvWorld *world, const LilvNode *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 `lilv_world_load_all()`).

  Hosts MUST NOT attach any long-term significance to bundle paths (for example 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.

void lilv_world_load_plugin_classes(LilvWorld *world)

  Load all plugin classes from currently loaded specifications.

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

int lilv_world_load_resource(LilvWorld *world, const LilvNode *resource)

  Load all the data associated with the given `resource`.

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

  Parameters:

    - world – The world.

    - resource – Must be a subject (a URI or a blank node).

  Returns:

    The number of files parsed, or -1 on error

void lilv_world_load_specifications(LilvWorld *world)

  Load all specifications from currently loaded bundles.

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

LilvWorld *lilv_world_new(void)

  Initialize a new, empty world.

  If initialization fails, NULL is returned.

void lilv_world_set_option(LilvWorld *world, const char *uri, const LilvNode *value)

  Set an option for `world`.

  For boolean options, passing a null value sets the option to false. For options of any other type, null is considered invalid and will produce a warning.

  Currently recognized options:

  - `LILV_OPTION_DYN_MANIFEST`

  - `LILV_OPTION_FILTER_LANG`

  - `LILV_OPTION_LANG`

  - `LILV_OPTION_LV2_PATH`

  - `LILV_OPTION_OBJECT_INDEX`

int lilv_world_unload_bundle(LilvWorld *world, const LilvNode *bundle_uri)

  Unload a specific bundle.

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

int lilv_world_unload_resource(LilvWorld *world, const LilvNode *resource)

  Unload all the data associated with the given `resource`.

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

  Parameters:

    - world – The world.

    - resource – Must be a subject (a URI or a blank node).

### Plugins

LilvNode *lilv_plugin_get_author_email(const LilvPlugin *plugin)

  Get the email address of the plugin’s author.

  Returns NULL if author email address is not present. Returned value must be freed by caller.

LilvNode *lilv_plugin_get_author_homepage(const LilvPlugin *plugin)

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

  Returns NULL if author homepage is not present. Returned value must be freed by caller.

LilvNode *lilv_plugin_get_author_name(const LilvPlugin *plugin)

  Get the full name of the plugin’s author.

  Returns NULL if author name is not present. Returned value must be freed by caller.

const LilvNode *lilv_plugin_get_bundle_uri(const LilvPlugin *plugin)

  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, `lilv_plugin_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()`.

  Returns:

    A shared string which must not be modified or freed.

const LilvPluginClass *lilv_plugin_get_class(const LilvPlugin *plugin)

  Get the class this plugin belongs to (like “Filters” or “Effects”).

const LilvNodes *lilv_plugin_get_data_uris(const LilvPlugin *plugin)

  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()`.

  Returns:

    A list of complete URLs eg. “file:///foo/ABundle.lv2/aplug.ttl”, which is shared and must not be modified or freed.

LilvNodes *lilv_plugin_get_extension_data(const LilvPlugin *plugin)

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

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

uint32_t lilv_plugin_get_latency_port_index(const LilvPlugin *plugin)

  Return the index of the plugin’s latency port.

  It is a fatal error to call this on a plugin without checking if the port exists by first calling `lilv_plugin_has_latency()`.

  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.

const LilvNode *lilv_plugin_get_library_uri(const LilvPlugin *plugin)

  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()`.

  Returns:

    A shared string which must not be modified or freed.

LilvNode *lilv_plugin_get_name(const LilvPlugin *plugin)

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

  Returned value must be freed by the caller.

uint32_t lilv_plugin_get_num_ports(const LilvPlugin *plugin)

  Get the number of ports on this plugin.

uint32_t lilv_plugin_get_num_ports_of_class(const LilvPlugin *plugin, const LilvNode *class_1, ...)

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

  Note that this is a varargs function so ports fitting any type ‘profile’ desired can be found quickly. REMEMBER TO TERMINATE THE PARAMETER LIST OF THIS FUNCTION WITH NULL OR VERY NASTY THINGS WILL HAPPEN.

uint32_t lilv_plugin_get_num_ports_of_class_va(const LilvPlugin *plugin, const LilvNode *class_1, va_list args)

  Variant of `lilv_plugin_get_num_ports_of_class()` that takes a va_list.

  This function calls va_arg() on `args` but does not call va_end().

LilvNodes *lilv_plugin_get_optional_features(const LilvPlugin *plugin)

  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.

  Return value must be freed by caller with lilv_nodes_free().

const LilvPort *lilv_plugin_get_port_by_designation(const LilvPlugin *plugin, const LilvNode *port_class, const LilvNode *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, like “left channel” or “gain”. If found, the port with matching `port_class` and `designation` is be returned, otherwise NULL is returned. The `port_class` can be used to distinguish the input and output ports for a particular designation. If `port_class` is NULL, any port with the given designation will be returned.

const LilvPort *lilv_plugin_get_port_by_index(const LilvPlugin *plugin, uint32_t index)

  Get a port on `plugin` by `index`.

const LilvPort *lilv_plugin_get_port_by_symbol(const LilvPlugin *plugin, const LilvNode *symbol)

  Get a port on `plugin` by `symbol`.

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

void lilv_plugin_get_port_ranges_float(const LilvPlugin *plugin, float *min_values, float *max_values, float *def_values)

  Get the port ranges (minimum, maximum and default values) for all ports.

  `min_values`, `max_values` and `def_values` must either point to an array of N floats, where N is the value returned by `lilv_plugin_get_num_ports()` for this plugin, or NULL. The elements of the array will be set to the the minimum, maximum and default values of the ports on this plugin, with array index corresponding to port index. If a port doesn’t have a minimum, maximum or default value, or the port’s type is not float, the corresponding array element will be set to NAN.

  This is a convenience method for the common case of getting the range of all float ports on a plugin, and may be significantly faster than repeated calls to `lilv_port_get_range()`.

LilvNode *lilv_plugin_get_project(const LilvPlugin *plugin)

  Get the project the plugin is a part of.

  More information about the project can be read via `lilv_world_find_nodes()`, typically using properties from DOAP (such as doap:name).

LilvNodes *lilv_plugin_get_related(const LilvPlugin *plugin, const LilvNode *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 `type` related to `plugin` can be accessed with this function.

  If `type` is NULL, all such resources will be returned, regardless of type.

  To actually load the data for each returned resource, use `lilv_world_load_resource()`.

LilvNodes *lilv_plugin_get_required_features(const LilvPlugin *plugin)

  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 passed to the plugin’s instantiate method (along with data, if necessary, as defined by the feature specification) or plugin instantiation will fail.

  Return value must be freed by caller with lilv_nodes_free().

LilvNodes *lilv_plugin_get_supported_features(const LilvPlugin *plugin)

  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 `lilv_plugin_get_optional_features()` and `lilv_plugin_get_required_features()` separately is best in most cases.

  Returned value must be freed by caller with lilv_nodes_free().

const LilvNode *lilv_plugin_get_uri(const LilvPlugin *plugin)

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

  Returns:

    A shared URI value which must not be modified or freed.

LilvNodes *lilv_plugin_get_value(const LilvPlugin *plugin, const LilvNode *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 NULL if the property was not found, or if object(s) is not sensibly represented as a `LilvNodes`.

  Return value must be freed by caller with lilv_nodes_free().

bool lilv_plugin_has_extension_data(const LilvPlugin *plugin, const LilvNode *uri)

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

bool lilv_plugin_has_feature(const LilvPlugin *plugin, const LilvNode *feature)

  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.

bool lilv_plugin_has_latency(const LilvPlugin *plugin)

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

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

bool lilv_plugin_is_replaced(const LilvPlugin *plugin)

  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.

bool lilv_plugin_verify(const LilvPlugin *plugin)

  Check if `plugin` is valid.

  This is not a rigorous validator, but can be used to reject some malformed plugins that could cause bugs (for example, 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.

  Returns:

    True iff `plugin` is valid.

void lilv_plugin_write_description(LilvWorld *world, const LilvPlugin *plugin, const LilvNode *base_uri, FILE *plugin_file)

  Write the Turtle description of `plugin` to `plugin_file`.

  This function is particularly useful for porting plugins in conjunction with an LV2 bridge such as NASPRO.

void lilv_plugin_write_manifest_entry(LilvWorld *world, const LilvPlugin *plugin, const LilvNode *base_uri, FILE *manifest_file, const char *plugin_file_path)

  Write a manifest entry for `plugin` to `manifest_file`.

  This function is intended for use with `lilv_plugin_write_description()` to write a complete description of a plugin to a bundle.

### Ports

LilvNode *lilv_port_get(const LilvPlugin *plugin, const LilvPort *port, const LilvNode *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.

const LilvNodes *lilv_port_get_classes(const LilvPlugin *plugin, const LilvPort *port)

  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 `lilv_port_is_a()`. The returned list does not include lv2:Port, which is implied. Returned value is shared and must not be destroyed by caller.

uint32_t lilv_port_get_index(const LilvPlugin *plugin, const LilvPort *port)

  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.

LilvNode *lilv_port_get_name(const LilvPlugin *plugin, const LilvPort *port)

  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). Returned value must be freed by the caller.

const LilvNode *lilv_port_get_node(const LilvPlugin *plugin, const LilvPort *port)

  Get the RDF node of `port`.

  Ports nodes may be may be URIs or blank nodes.

  Returns:

    A shared node which must not be modified or freed.

LilvNodes *lilv_port_get_properties(const LilvPlugin *plugin, const LilvPort *port)

  Return the LV2 port properties of a port.

void lilv_port_get_range(const LilvPlugin *plugin, const LilvPort *port, LilvNode **def, LilvNode **min, LilvNode **max)

  Get the default, minimum, and maximum values of a port.

  `def`, `min`, and `max` are outputs, pass pointers to uninitialized LilvNode* variables. These will be set to point at new values (which must be freed by the caller using `lilv_node_free()`), or NULL if the value does not exist.

LilvScalePoints *lilv_port_get_scale_points(const LilvPlugin *plugin, const LilvPort *port)

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

  This returns a collection of ‘interesting’ named values of a port, which for example might be appropriate entries for a value selector in a UI.

  Returned value may be NULL if `port` has no scale points, otherwise it must be freed by caller with lilv_scale_points_free().

const LilvNode *lilv_port_get_symbol(const LilvPlugin *plugin, const LilvPort *port)

  Get the symbol of a port.

  The ‘symbol’ is a short string, a valid C identifier. Returned value is owned by `port` and must not be freed.

LilvNodes *lilv_port_get_value(const LilvPlugin *plugin, const LilvPort *port, const LilvNode *predicate)

  Port analog of `lilv_plugin_get_value()`.

bool lilv_port_has_property(const LilvPlugin *plugin, const LilvPort *port, const LilvNode *property)

  Return whether a port has a certain property.

bool lilv_port_is_a(const LilvPlugin *plugin, const LilvPort *port, const LilvNode *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 like `LILV_URI_INPUT_PORT` are defined for convenience, but this function is designed so that Lilv is usable with any port types without requiring explicit support in Lilv.

bool lilv_port_supports_event(const LilvPlugin *plugin, const LilvPort *port, const LilvNode *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.

### Plugin State

typedef const void *(*LilvGetPortValueFunc)(const char *port_symbol, void *user_data, uint32_t *size, uint32_t *type)

  Function to get a port value.

  This function MUST set `size` and `type` appropriately.

  Param port_symbol:

    The symbol of the port.

  Param user_data:

    The user_data passed to `lilv_state_new_from_instance()`.

  Param size:

    (Output) The size of the returned value.

  Param type:

    (Output) The URID of the type of the returned value.

  Returns:

    A pointer to the port value.

typedef void (*LilvSetPortValueFunc)(const char *port_symbol, void *user_data, const void *value, uint32_t size, uint32_t type)

  Function to set a port value.

  Param port_symbol:

    The symbol of the port.

  Param user_data:

    The user_data passed to `lilv_state_restore()`.

  Param size:

    The size of `value`.

  Param type:

    The URID of the type of `value`.

  Param value:

    A pointer to the port value.

int lilv_state_delete(LilvWorld *world, const LilvState *state)

  Unload a state from the world and delete all associated files.

  This function DELETES FILES/DIRECTORIES FROM THE FILESYSTEM! It is intended for removing user-saved presets, but can delete any state the user has permission to delete, including presets shipped with plugins.

  The rdfs:seeAlso file for the state will be removed. The entry in the bundle’s manifest.ttl is removed, and if this results in an empty manifest, then the manifest file is removed. If this results in an empty bundle, then the bundle directory is removed as well.

  Parameters:

    - world – The world.

    - state – State to remove from the system.

void lilv_state_emit_port_values(const LilvState *state, LilvSetPortValueFunc set_value, void *user_data)

  Enumerate the port values in a state snapshot.

  This function is a subset of `lilv_state_restore()` that only fires the `set_value` callback and does not directly affect a plugin instance. This is useful in hosts that need to retrieve the port values in a state snapshot for special handling.

  Parameters:

    - state – The state to retrieve port values from.

    - set_value – A function to receive port values.

    - user_data – User data to pass to `set_value`.

bool lilv_state_equals(const LilvState *a, const LilvState *b)

  Return true iff `a` is equivalent to `b`.

void lilv_state_free(LilvState *state)

  Free `state`.

const char *lilv_state_get_bundle_path(const LilvState *state)

  Get the bundle that contains `state`, if any.

  This will return a path for states loaded from the filesystem, or from an instance using `lilv_state_new_from_instance()` with a `save_dir`. Note that this can return a directory for states that haven’t been saved yet, so the returned path isn’t guaranteed to be a valid bundle with a `manifest.ttl`.

  Returns NULL if the state isn’t stored in a directory for whatever reason.

const char *lilv_state_get_label(const LilvState *state)

  Get the label of `state`.

unsigned lilv_state_get_num_properties(const LilvState *state)

  Return the number of properties in `state`.

const LilvNode *lilv_state_get_plugin_uri(const LilvState *state)

  Get the URI of the plugin `state` applies to.

const LilvNode *lilv_state_get_uri(const LilvState *state)

  Get the URI of `state`.

  This may return NULL if the state has not been saved and has no URI.

LilvState *lilv_state_new_from_file(LilvWorld *world, LV2_URID_Map *map, const LilvNode *subject, const char *path)

  Load a state snapshot from a file or directory.

  If no `subject` is given, then it will be automatically determined from `path`, possibly by loading the file and investigating its contents for a unique instance of a plugin or preset.

  Parameters:

    - world – The world.

    - map – URID mapper.

    - subject – The subject of the state description (such as a preset URI).

    - path – The path of the file containing the state description.

  Returns:

    A new `LilvState` which must be freed with `lilv_state_free()`.

LilvState *lilv_state_new_from_instance(const LilvPlugin *plugin, LilvInstance *instance, LV2_URID_Map *map, const char *scratch_dir, const char *copy_dir, const char *link_dir, const char *save_dir, LilvGetPortValueFunc get_value, void *user_data, uint32_t flags, const LV2_Feature *const *features)

  Create a new state snapshot from a plugin instance.

  This function may be called simultaneously with any instance function (except discovery functions) unless the threading class of that function explicitly disallows this.

  To support advanced file functionality, there are several directory parameters. The multiple parameters are necessary to support saving an instance’s state many times, or saving states from multiple instances, while avoiding any duplication of data. For example, a host could pass the same `copy_dir` and `link_dir` for all plugins in a session (for example `session/shared/copy/` `session/shared/link/`), while the `save_dir` would be unique to each plugin instance (for example `session/states/state1.lv2` for one instance and `session/states/state2.lv2` for another instance). Simple hosts that only wish to save a single plugin’s state once may simply use the same directory for all of them, or pass NULL to not support files at all.

  If supported (via state:makePath passed to LV2_Descriptor::instantiate()), `scratch_dir` should be the directory where any files created by the plugin (for example during instantiation or while running) are stored. Any files here that are referred to in the state will be copied to preserve their contents at the time of the save. Lilv will assume any files within this directory (recursively) are created by the plugin and that all other files are immutable. Note that this function does not completely save the state, use `lilv_state_save()` for that.

  See state.h from the LV2 State extension for details on the `flags` and `features` parameters.

  Parameters:

    - plugin – The plugin this state applies to.

    - instance – An instance of `plugin`.

    - map – The map to use for mapping URIs in state.

    - scratch_dir – Directory of files created by the plugin earlier, or NULL. This is for hosts that support file creation at any time with state state:makePath. These files will be copied as necessary to `copy_dir` and not be referred to directly in state (a temporary directory is appropriate).

    - copy_dir – Directory of copies of files in `scratch_dir`, or NULL. This directory will have the same structure as `scratch_dir` but with possibly modified file names to distinguish revisions. This allows the saved state to contain the exact contents of the scratch file at save time, so that the state is not ruined if the file is later modified (for example, by the plugin continuing to record). This can be the same as `save_dir` to create a copy in the state bundle, but can also be a separate directory which allows multiple state snapshots to share a single copy if the file has not changed.

    - link_dir – Directory of links to external files, or NULL. Links will be made here to any external file referred to in plugin state. In turn, these will be linked to from `save_dir` (like save_dir/file => link_dir/file => /some/file). This allows several state snapshots to share links to external files, so an archive (created by naive tools like `tar`) will only contain one copy of the file. This can be the same as `save_dir` to link directly from there (without sharing). If NULL, the state will contain absolute paths to any any external files.

    - save_dir – Directory of files created by plugin during save (or NULL). This is typically the bundle directory later passed to `lilv_state_save()`.

    - get_value – Function to get port values (or NULL). If NULL, the returned state will not represent port values. This should only be NULL in hosts that save and restore port values via some other mechanism.

    - user_data – User data to pass to `get_value`.

    - flags – Bitwise OR of LV2_State_Flags values.

    - features – Features to pass LV2_State_Interface.save().

  Returns:

    A new `LilvState` which must be freed with `lilv_state_free()`.

LilvState *lilv_state_new_from_string(LilvWorld *world, LV2_URID_Map *map, const char *str)

  Load a state snapshot from a string made by `lilv_state_to_string()`.

LilvState *lilv_state_new_from_world(LilvWorld *world, LV2_URID_Map *map, const LilvNode *node)

  Load a state snapshot from the world RDF model.

  If `node` is a known plugin URI, then that plugin’s default state is returned. Otherwise, the saved state or preset `node` (which lv2:appliesTo some plugin, has an rdfs:label, and so on) is returned.

  Parameters:

    - world – The world.

    - map – URID mapper.

    - node – The subject of the state description (such as a preset URI).

  Returns:

    A new `LilvState` which must be freed with `lilv_state_free()`, or NULL.

void lilv_state_restore(const LilvState *state, LilvInstance *instance, LilvSetPortValueFunc set_value, void *user_data, uint32_t flags, const LV2_Feature *const *features)

  Restore a plugin instance from a state snapshot.

  This will set all the properties of `instance`, if given, to the values stored in `state`. If `set_value` is provided, it will be called (with the given `user_data`) to restore each port value, otherwise the host must restore the port values itself (using lilv_state_get_port_value()) in order to completely restore `state`.

  If the state has properties and `instance` is given, this function is in the “instantiation” threading class, so it MUST NOT be called simultaneously with any function on the same plugin instance. If the state has no properties, only port values are set via `set_value`.

  See state.h from the LV2 State extension for details on the `flags` and `features` parameters.

  Parameters:

    - state – The state to restore, which must apply to the correct plugin.

    - instance – An instance of the plugin `state` applies to, or NULL.

    - set_value – A function to set a port value (may be NULL).

    - user_data – User data to pass to `set_value`.

    - flags – Bitwise OR of LV2_State_Flags values.

    - features – Features to pass LV2_State_Interface.restore().

int lilv_state_save(LilvWorld *world, LV2_URID_Map *map, LV2_URID_Unmap *unmap, const LilvState *state, const char *uri, const char *dir, const char *filename)

  Save state to a file.

  The format of state on disk is compatible with that defined in the LV2 preset extension, so this function may be used to save presets which can be loaded by any host.

  If `uri` is NULL, the preset URI will be a file URI, but the bundle can safely be moved (the state file will use `<>` as the subject).

  The given directory and its manifest.ttl will be created if necessary, and file references in state will be linked to any special directories given to `lilv_state_new_from_instance()` when it was created, if possible. Links in the saved bundle to any of those directories will be relative, any other link (to external files) will be absolute. The general idea is that all these directories are part of some greater session which should be relocatable.

  Parameters:

    - world – The world.

    - map – URID mapper.

    - unmap – URID unmapper.

    - state – State to save.

    - uri – URI of state, may be NULL.

    - dir – Path of the bundle directory to save into.

    - filename – Path of the state file relative to `dir`.

void lilv_state_set_label(LilvState *state, const char *label)

  Set the label of `state`.

int lilv_state_set_metadata(LilvState *state, uint32_t key, const void *value, size_t size, uint32_t type, uint32_t flags)

  Set a metadata property on `state`.

  This is a generic version of `lilv_state_set_label()`, which sets metadata properties visible to hosts, but not plugins. This allows storing useful information such as comments or preset banks.

  Parameters:

    - state – The state to set the metadata for.

    - key – The key to store `value` under (URID).

    - value – Pointer to the value to be stored.

    - size – The size of `value` in bytes.

    - type – The type of `value` (URID).

    - flags – LV2_State_Flags for `value`.

  Returns:

    Zero on success.

char *lilv_state_to_string(LilvWorld *world, LV2_URID_Map *map, LV2_URID_Unmap *unmap, const LilvState *state, const char *uri, const char *base_uri)

  Save state to a string.

  This function does not use the filesystem.

  Parameters:

    - world – The world.

    - map – URID mapper.

    - unmap – URID unmapper.

    - state – The state to serialize.

    - uri – URI for the state description (mandatory).

    - base_uri – Base URI for serialisation. Unless you know what you are doing, pass NULL for this, otherwise the state may not be restorable via `lilv_state_new_from_string()`.

### Scale Points

const LilvNode *lilv_scale_point_get_label(const LilvScalePoint *point)

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

  Returned value is owned by `point` and must not be freed.

const LilvNode *lilv_scale_point_get_value(const LilvScalePoint *point)

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

  Returned value is owned by `point` and must not be freed.

### Plugin Classes

LilvPluginClasses *lilv_plugin_class_get_children(const LilvPluginClass *plugin_class)

  Get the subclasses of this plugin class.

  Returned value must be freed by caller with lilv_plugin_classes_free().

const LilvNode *lilv_plugin_class_get_label(const LilvPluginClass *plugin_class)

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

  Returned value is owned by `plugin_class` and must not be freed by caller.

const LilvNode *lilv_plugin_class_get_parent_uri(const LilvPluginClass *plugin_class)

  Get the URI of this class’ superclass.

  Returned value is owned by `plugin_class` and must not be freed by caller. Returned value may be NULL, if class has no parent.

const LilvNode *lilv_plugin_class_get_uri(const LilvPluginClass *plugin_class)

  Get the URI of this plugin class.

  Returned value is owned by `plugin_class` and must not be freed by caller.

### Plugin Instances

void lilv_instance_activate(LilvInstance *instance)

  Activate a plugin instance.

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

  This function is in the “instantiation” threading class: it isn’t real-time safe, and may not be called concurrently with any other function for the same instance.

void lilv_instance_connect_port(LilvInstance *instance, uint32_t port_index, void *data_location)

  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.

  This function is in the “audio” threading class: it’s real-time safe if the plugin is http://lv2plug.in/ns/lv2core#hardRTCapable, but may not be called concurrently with any other function for the same instance.

void lilv_instance_deactivate(LilvInstance *instance)

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

  This function is in the “instantiation” threading class: it isn’t real-time safe and may not be called concurrently with any other function for the same instance.

void lilv_instance_free(LilvInstance *instance)

  Free a plugin instance.

  It is safe to call this function on NULL. The `instance` is invalid after this call.

  This function is in the “discovery” threading class: it isn’t real-time safe, and may not be called concurrently with any other function for the same instance, or with `lilv_plugin_instantiate()` for the same plugin.

const LV2_Descriptor *lilv_instance_get_descriptor(const LilvInstance *instance)

  Get the LV2_Descriptor of the plugin instance.

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

  The returned descriptor is shared and must not be deleted.

  This function is a simple accessor and may be called at any time.

const void *lilv_instance_get_extension_data(const LilvInstance *instance, const char *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.

  This function is in the “discovery” threading class: it isn’t real-time safe and may not be called concurrently with any other function for the same instance.

LV2_Handle lilv_instance_get_handle(const LilvInstance *instance)

  Get the LV2_Handle of the plugin instance.

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

  The returned handle is shared and must not be deleted.

  This function is a simple accessor and may be called at any time.

const char *lilv_instance_get_uri(const LilvInstance *instance)

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

  This function is a simple accessor and may be called at any time. The returned string is shared and must not be modified or deleted.

void lilv_instance_run(LilvInstance *instance, uint32_t 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.

  This function is in the “audio” threading class: it’s real-time safe if the plugin is http://lv2plug.in/ns/lv2core#hardRTCapable, but may not be called concurrently with any other function for the same instance.

LilvInstance *lilv_plugin_instantiate(const LilvPlugin *plugin, double sample_rate, const LV2_Feature *const *features)

  Instantiate a plugin.

  The returned value is a lightweight handle for an LV2 plugin instance, it does not refer to `plugin`, or any other Lilv state. The caller must eventually free it with `lilv_instance_free()`. `features` is a NULL-terminated array of features the host supports. NULL may be passed if the host supports no additional features.

  This function is in the “discovery” threading class: it isn’t real-time safe, and may not be called concurrently with itself for the same plugin.

  Returns:

    NULL if instantiation failed.

### Plugin UIs

typedef unsigned (*LilvUISupportedFunc)(const char *container_type_uri, const char *ui_type_uri)

  Function to determine whether a UI type is supported.

  This is provided by the user and must return non-zero iff using a UI of type `ui_type_uri` in a container of type `container_type_uri` is supported.

LilvUIs *lilv_plugin_get_uis(const LilvPlugin *plugin)

  Get all UIs for `plugin`.

  Returned value must be freed by caller using lilv_uis_free().

const LilvNode *lilv_ui_get_binary_uri(const LilvUI *ui)

  Get the URI for a Plugin UI’s shared library.

  Returns:

    A shared value which must not be modified or freed.

const LilvNode *lilv_ui_get_bundle_uri(const LilvUI *ui)

  Get the URI for a Plugin UI’s bundle.

  Returns:

    A shared value which must not be modified or freed.

const LilvNodes *lilv_ui_get_classes(const LilvUI *ui)

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

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

  Returns:

    A shared value which must not be modified or freed.

const LilvNode *lilv_ui_get_uri(const LilvUI *ui)

  Get the URI of a Plugin UI.

  Returns:

    A shared value which must not be modified or freed.

bool lilv_ui_is_a(const LilvUI *ui, const LilvNode *class_uri)

  Check whether a plugin UI has a given type.

  Parameters:

    - ui – The Plugin UI

    - class_uri – The URI of the LV2 UI type to check this UI against

unsigned lilv_ui_is_supported(const LilvUI *ui, LilvUISupportedFunc supported_func, const LilvNode *container_type, const LilvNode **ui_type)

  Return true iff a Plugin UI is supported as a given widget type.

  Parameters:

    - ui – The Plugin UI

    - supported_func – User provided supported predicate.

    - container_type – The widget type to host the UI within.

    - ui_type – (Output) If non-NULL, set to the native type of the UI which is owned by `ui` and must not be freed by the caller.

  Returns:

    The embedding quality level returned by `supported_func`.

typedef struct LilvInstanceImpl LilvInstance

  Plugin instance.

typedef void LilvIter

  Collection iterator.

typedef struct LilvNodeImpl LilvNode

  Typed Value.

typedef void LilvNodes

  A set of `LilvNode`.

typedef struct LilvPluginImpl LilvPlugin

  LV2 Plugin.

typedef struct LilvPluginClassImpl LilvPluginClass

  Plugin Class.

typedef void LilvPluginClasses

  A set of `LilvPluginClass`.

typedef void LilvPlugins

  A set of `LilvPlugin`.

typedef struct LilvPortImpl LilvPort

  Port.

typedef struct LilvScalePointImpl LilvScalePoint

  Scale Point.

typedef void LilvScalePoints

  A set of `LilvScalePoint`.

typedef struct LilvStateImpl LilvState

  Plugin state.

typedef struct LilvUIImpl LilvUI

  Plugin UI.

typedef void LilvUIs

  A set of `LilvUI`.

typedef struct LilvWorldImpl LilvWorld

  Lilv World.

void lilv_free(void *ptr)

  Free memory allocated by Lilv.

  This function exists because some systems require memory allocated by a library to be freed by code in the same library. It is otherwise equivalent to the standard C free() function.