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

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.

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

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.

const LilvPluginClass *lilv_plugin_get_class(const LilvPlugin *plugin)

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

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

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

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

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

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

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_num_ports(const LilvPlugin *plugin)

  Get the number of ports on this plugin.

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

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

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.

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

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.

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

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.

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.

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.

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.

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