Lilv

Lilv is a simple yet powerful C API for using LV2 plugins. More...

Node
const char *	lilv_uri_to_path (const char *uri)
LilvNode *	lilv_new_uri (LilvWorld *world, const char *uri)
LilvNode *	lilv_new_string (LilvWorld *world, const char *str)
LilvNode *	lilv_new_int (LilvWorld *world, int val)
LilvNode *	lilv_new_float (LilvWorld *world, float val)
LilvNode *	lilv_new_bool (LilvWorld *world, bool val)
void	lilv_node_free (LilvNode *val)
LilvNode *	lilv_node_duplicate (const LilvNode *val)
bool	lilv_node_equals (const LilvNode *value, const LilvNode *other)
char *	lilv_node_get_turtle_token (const LilvNode *value)
bool	lilv_node_is_uri (const LilvNode *value)
const char *	lilv_node_as_uri (const LilvNode *value)
bool	lilv_node_is_blank (const LilvNode *value)
const char *	lilv_node_as_blank (const LilvNode *value)
bool	lilv_node_is_literal (const LilvNode *value)
bool	lilv_node_is_string (const LilvNode *value)
const char *	lilv_node_as_string (const LilvNode *value)
bool	lilv_node_is_float (const LilvNode *value)
float	lilv_node_as_float (const LilvNode *value)
bool	lilv_node_is_int (const LilvNode *value)
int	lilv_node_as_int (const LilvNode *value)
bool	lilv_node_is_bool (const LilvNode *value)
bool	lilv_node_as_bool (const LilvNode *value)
Collections
Lilv has several collection types for holding various types of value: LilvPlugins (function prefix "lilv_plugins_") LilvPluginClasses (function prefix "lilv_plugin_classes_") LilvScalePoints (function prefix "lilv_scale_points_") LilvNodes (function prefix "lilv_nodes_") LilvUIs (function prefix "lilv_uis_") Each collection type supports a similar basic API: void PREFIX_free (coll) unsigned PREFIX_size (coll) LilvIter* PREFIX_begin (coll)
void	lilv_plugin_classes_free (LilvPluginClasses *collection)
unsigned	lilv_plugin_classes_size (const LilvPluginClasses *collection)
LilvIter *	lilv_plugin_classes_begin (const LilvPluginClasses *collection)
const LilvPluginClass *	lilv_plugin_classes_get (const LilvPluginClasses *collection, LilvIter *i)
LilvIter *	lilv_plugin_classes_next (const LilvPluginClasses *collection, LilvIter *i)
bool	lilv_plugin_classes_is_end (const LilvPluginClasses *collection, LilvIter *i)
const LilvPluginClass *	lilv_plugin_classes_get_by_uri (const LilvPluginClasses *classes, const LilvNode *uri)
void	lilv_scale_points_free (LilvScalePoints *collection)
unsigned	lilv_scale_points_size (const LilvScalePoints *collection)
LilvIter *	lilv_scale_points_begin (const LilvScalePoints *collection)
const LilvScalePoint *	lilv_scale_points_get (const LilvScalePoints *collection, LilvIter *i)
LilvIter *	lilv_scale_points_next (const LilvScalePoints *collection, LilvIter *i)
bool	lilv_scale_points_is_end (const LilvScalePoints *collection, LilvIter *i)
void	lilv_uis_free (LilvUIs *collection)
unsigned	lilv_uis_size (const LilvUIs *collection)
LilvIter *	lilv_uis_begin (const LilvUIs *collection)
const LilvUI *	lilv_uis_get (const LilvUIs *collection, LilvIter *i)
LilvIter *	lilv_uis_next (const LilvUIs *collection, LilvIter *i)
bool	lilv_uis_is_end (const LilvUIs *collection, LilvIter *i)
const LilvUI *	lilv_uis_get_by_uri (const LilvUIs *uis, const LilvNode *uri)
void	lilv_nodes_free (LilvNodes *collection)
unsigned	lilv_nodes_size (const LilvNodes *collection)
LilvIter *	lilv_nodes_begin (const LilvNodes *collection)
const LilvNode *	lilv_nodes_get (const LilvNodes *collection, LilvIter *i)
LilvIter *	lilv_nodes_next (const LilvNodes *collection, LilvIter *i)
bool	lilv_nodes_is_end (const LilvNodes *collection, LilvIter *i)
LilvNode *	lilv_nodes_get_first (const LilvNodes *collection)
bool	lilv_nodes_contains (const LilvNodes *values, const LilvNode *value)
unsigned	lilv_plugins_size (const LilvPlugins *collection)
LilvIter *	lilv_plugins_begin (const LilvPlugins *collection)
const LilvPlugin *	lilv_plugins_get (const LilvPlugins *collection, LilvIter *i)
LilvIter *	lilv_plugins_next (const LilvPlugins *collection, LilvIter *i)
bool	lilv_plugins_is_end (const LilvPlugins *collection, LilvIter *i)
const LilvPlugin *	lilv_plugins_get_by_uri (const LilvPlugins *plugins, const LilvNode *uri)
#define	LILV_FOREACH(colltype, iter, collection)
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.
LilvWorld *	lilv_world_new (void)
void	lilv_world_set_option (LilvWorld *world, const char *uri, const LilvNode *value)
void	lilv_world_free (LilvWorld *world)
void	lilv_world_load_all (LilvWorld *world)
void	lilv_world_load_bundle (LilvWorld *world, LilvNode *bundle_uri)
const LilvPluginClass *	lilv_world_get_plugin_class (const LilvWorld *world)
const LilvPluginClasses *	lilv_world_get_plugin_classes (const LilvWorld *world)
const LilvPlugins *	lilv_world_get_all_plugins (const LilvWorld *world)
LilvNodes *	lilv_world_find_nodes (LilvWorld *world, const LilvNode *subject, const LilvNode *predicate, const LilvNode *object)
#define	LILV_OPTION_FILTER_LANG   "http://drobilla.net/ns/lilv#filter-lang"
#define	LILV_OPTION_DYN_MANIFEST   "http://drobilla.net/ns/lilv#dyn-manifest"
Plugin
bool	lilv_plugin_verify (const LilvPlugin *plugin)
const LilvNode *	lilv_plugin_get_uri (const LilvPlugin *plugin)
const LilvNode *	lilv_plugin_get_bundle_uri (const LilvPlugin *plugin)
const LilvNodes *	lilv_plugin_get_data_uris (const LilvPlugin *plugin)
const LilvNode *	lilv_plugin_get_library_uri (const LilvPlugin *plugin)
LilvNode *	lilv_plugin_get_name (const LilvPlugin *plugin)
const LilvPluginClass *	lilv_plugin_get_class (const LilvPlugin *plugin)
LilvNodes *	lilv_plugin_get_value (const LilvPlugin *p, const LilvNode *predicate)
bool	lilv_plugin_has_feature (const LilvPlugin *p, const LilvNode *feature_uri)
LilvNodes *	lilv_plugin_get_supported_features (const LilvPlugin *p)
LilvNodes *	lilv_plugin_get_required_features (const LilvPlugin *p)
LilvNodes *	lilv_plugin_get_optional_features (const LilvPlugin *p)
uint32_t	lilv_plugin_get_num_ports (const LilvPlugin *p)
void	lilv_plugin_get_port_ranges_float (const LilvPlugin *p, float *min_values, float *max_values, float *def_values)
uint32_t	lilv_plugin_get_num_ports_of_class (const LilvPlugin *p, const LilvNode *class_1,...)
bool	lilv_plugin_has_latency (const LilvPlugin *p)
uint32_t	lilv_plugin_get_latency_port_index (const LilvPlugin *p)
const LilvPort *	lilv_plugin_get_port_by_index (const LilvPlugin *plugin, uint32_t index)
const LilvPort *	lilv_plugin_get_port_by_symbol (const LilvPlugin *plugin, const LilvNode *symbol)
LilvNode *	lilv_plugin_get_author_name (const LilvPlugin *plugin)
LilvNode *	lilv_plugin_get_author_email (const LilvPlugin *plugin)
LilvNode *	lilv_plugin_get_author_homepage (const LilvPlugin *plugin)
bool	lilv_plugin_is_replaced (const LilvPlugin *plugin)
Port
LilvNodes *	lilv_port_get_value (const LilvPlugin *plugin, const LilvPort *port, const LilvNode *predicate)
LilvNodes *	lilv_port_get_properties (const LilvPlugin *plugin, const LilvPort *port)
bool	lilv_port_has_property (const LilvPlugin *p, const LilvPort *port, const LilvNode *property_uri)
bool	lilv_port_supports_event (const LilvPlugin *p, const LilvPort *port, const LilvNode *event_uri)
const LilvNode *	lilv_port_get_symbol (const LilvPlugin *plugin, const LilvPort *port)
LilvNode *	lilv_port_get_name (const LilvPlugin *plugin, const LilvPort *port)
const LilvNodes *	lilv_port_get_classes (const LilvPlugin *plugin, const LilvPort *port)
bool	lilv_port_is_a (const LilvPlugin *plugin, const LilvPort *port, const LilvNode *port_class)
void	lilv_port_get_range (const LilvPlugin *plugin, const LilvPort *port, LilvNode **deflt, LilvNode **min, LilvNode **max)
LilvScalePoints *	lilv_port_get_scale_points (const LilvPlugin *plugin, const LilvPort *port)
Scale Point
const LilvNode *	lilv_scale_point_get_label (const LilvScalePoint *point)
const LilvNode *	lilv_scale_point_get_value (const LilvScalePoint *point)
Plugin Class
const LilvNode *	lilv_plugin_class_get_parent_uri (const LilvPluginClass *plugin_class)
const LilvNode *	lilv_plugin_class_get_uri (const LilvPluginClass *plugin_class)
const LilvNode *	lilv_plugin_class_get_label (const LilvPluginClass *plugin_class)
LilvPluginClasses *	lilv_plugin_class_get_children (const LilvPluginClass *plugin_class)
Plugin Instance
LilvInstance *	lilv_plugin_instantiate (const LilvPlugin *plugin, double sample_rate, const LV2_Feature *const *features)
void	lilv_instance_free (LilvInstance *instance)
static const char *	lilv_instance_get_uri (const LilvInstance *instance)
static void	lilv_instance_connect_port (LilvInstance *instance, uint32_t port_index, void *data_location)
static void	lilv_instance_activate (LilvInstance *instance)
static void	lilv_instance_run (LilvInstance *instance, uint32_t sample_count)
static void	lilv_instance_deactivate (LilvInstance *instance)
static const void *	lilv_instance_get_extension_data (const LilvInstance *instance, const char *uri)
static const LV2_Descriptor *	lilv_instance_get_descriptor (const LilvInstance *instance)
static LV2_Handle	lilv_instance_get_handle (const LilvInstance *instance)
Plugin UI
typedef unsigned(*	LilvUISupportedFunc )(const char *container_type_uri, const char *ui_type_uri)
LilvUIs *	lilv_plugin_get_uis (const LilvPlugin *plugin)
const LilvNode *	lilv_ui_get_uri (const LilvUI *ui)
const LilvNodes *	lilv_ui_get_classes (const LilvUI *ui)
bool	lilv_ui_is_a (const LilvUI *ui, const LilvNode *class_uri)
unsigned	lilv_ui_is_supported (const LilvUI *ui, LilvUISupportedFunc supported_func, const LilvNode *container_type, const LilvNode **ui_type)
const LilvNode *	lilv_ui_get_bundle_uri (const LilvUI *ui)
const LilvNode *	lilv_ui_get_binary_uri (const LilvUI *ui)

---

Detailed Description

Lilv is a simple yet powerful C API for using LV2 plugins.

For more information about LV2, see <http://lv2plug.in>. For more information about Lilv, see <http://drobilla.net/software/lilv>.

---

Define Documentation

#define LILV_FOREACH	(		colltype,
			iter,
			collection
	)

Value:

for (LilvIter* (iter) = lilv_ ## colltype ## _begin(collection); \
         !lilv_ ## colltype ## _is_end(collection, iter); \
         (iter) = lilv_ ## colltype ## _next(collection, iter))

Iterate over each element of a collection.

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

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

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

---

Typedef Documentation

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.

---

Function Documentation

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.

Returns:

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

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.

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_int	(	LilvWorld *	world,
		int	val
	)

Create a new integer value.

Returned value must be freed by caller with lilv_node_free.

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_bool	(	LilvWorld *	world,
		bool	val
	)

Create a new boolean value.

Returned value must be freed by caller with lilv_node_free.

void lilv_node_free

(

LilvNode *

val

)

Free a LilvNode.

It is safe to call this function on NULL.

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.

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

Example Turtle Tokens

URI	<http://example.org/foo >
QName	doap:name
String	"this is a string"
Float	1.0
Integer	1
Boolean	true

bool lilv_node_is_uri

(

const LilvNode *

value

)

Return whether the value is a URI (resource).

const char* lilv_node_as_uri

(

const LilvNode *

value

)

Return this value as a URI string, e.g.

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

bool lilv_node_is_blank

(

const LilvNode *

value

)

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

const char* lilv_node_as_blank

(

const LilvNode *

value

)

Return this value as a blank node identifier, e.g.

"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_is_literal

(

const LilvNode *

value

)

Return whether this value is a literal (i.e.

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

const char* lilv_node_as_string

(

const LilvNode *

value

)

Return value as a string.

bool lilv_node_is_float

(

const LilvNode *

value

)

Return whether this value is a decimal literal.

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.

bool lilv_node_is_int

(

const LilvNode *

value

)

Return whether this value is an integer literal.

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.

bool lilv_node_is_bool

(

const LilvNode *

value

)

Return whether this value is a boolean.

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.

void lilv_plugin_classes_free

(

LilvPluginClasses *

collection

)

unsigned lilv_plugin_classes_size

(

const LilvPluginClasses *

collection

)

LilvIter* lilv_plugin_classes_begin

(

const LilvPluginClasses *

collection

)

const LilvPluginClass* lilv_plugin_classes_get	(	const LilvPluginClasses *	collection,
		LilvIter *	i
	)

LilvIter* lilv_plugin_classes_next	(	const LilvPluginClasses *	collection,
		LilvIter *	i
	)

bool lilv_plugin_classes_is_end	(	const LilvPluginClasses *	collection,
		LilvIter *	i
	)

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.

void lilv_scale_points_free

(

LilvScalePoints *

collection

)

unsigned lilv_scale_points_size

(

const LilvScalePoints *

collection

)

LilvIter* lilv_scale_points_begin

(

const LilvScalePoints *

collection

)

const LilvScalePoint* lilv_scale_points_get	(	const LilvScalePoints *	collection,
		LilvIter *	i
	)

LilvIter* lilv_scale_points_next	(	const LilvScalePoints *	collection,
		LilvIter *	i
	)

bool lilv_scale_points_is_end	(	const LilvScalePoints *	collection,
		LilvIter *	i
	)

void lilv_uis_free

(

LilvUIs *

collection

)

unsigned lilv_uis_size

(

const LilvUIs *

collection

)

LilvIter* lilv_uis_begin

(

const LilvUIs *

collection

)

const LilvUI* lilv_uis_get	(	const LilvUIs *	collection,
		LilvIter *	i
	)

LilvIter* lilv_uis_next	(	const LilvUIs *	collection,
		LilvIter *	i
	)

bool lilv_uis_is_end	(	const LilvUIs *	collection,
		LilvIter *	i
	)

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.

void lilv_nodes_free

(

LilvNodes *

collection

)

unsigned lilv_nodes_size

(

const LilvNodes *

collection

)

LilvIter* lilv_nodes_begin

(

const LilvNodes *

collection

)

const LilvNode* lilv_nodes_get	(	const LilvNodes *	collection,
		LilvIter *	i
	)

LilvIter* lilv_nodes_next	(	const LilvNodes *	collection,
		LilvIter *	i
	)

bool lilv_nodes_is_end	(	const LilvNodes *	collection,
		LilvIter *	i
	)

LilvNode* lilv_nodes_get_first

(

const LilvNodes *

collection

)

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

Return whether values contains value.

unsigned lilv_plugins_size

(

const LilvPlugins *

collection

)

LilvIter* lilv_plugins_begin

(

const LilvPlugins *

collection

)

const LilvPlugin* lilv_plugins_get	(	const LilvPlugins *	collection,
		LilvIter *	i
	)

LilvIter* lilv_plugins_next	(	const LilvPlugins *	collection,
		LilvIter *	i
	)

bool lilv_plugins_is_end	(	const LilvPlugins *	collection,
		LilvIter *	i
	)

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.

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 option for world.

Currently recognized options: LILV_OPTION_FILTER_LANG LILV_OPTION_DYN_MANIFEST

void lilv_world_free

(

LilvWorld *

world

)

Destroy the world, mwahaha.

It is safe to call this function on NULL. Note that destroying world will destroy all the objects it contains (e.g. instances of LilvPlugin). Do not destroy the world until you are finished with all objects that came from it.

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

void lilv_world_load_bundle	(	LilvWorld *	world,
		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 (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.

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.

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.

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 (i.e. a wildcard), but not both.

Returns:

All matches for the wildcard field, or NULL.

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

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

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

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

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 (e.g.

Filters).

LilvNodes* lilv_plugin_get_value	(	const LilvPlugin *	p,
		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 (e.g. blank nodes). Return value must be freed by caller with lilv_nodes_free.

bool lilv_plugin_has_feature	(	const LilvPlugin *	p,
		const LilvNode *	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.

LilvNodes* lilv_plugin_get_supported_features

(

const LilvPlugin *

p

)

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 *

p

)

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 *

p

)

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.

uint32_t lilv_plugin_get_num_ports

(

const LilvPlugin *

p

)

Get the number of ports on this plugin.

void lilv_plugin_get_port_ranges_float	(	const LilvPlugin *	p,
		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 *	p,
		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.

bool lilv_plugin_has_latency

(

const LilvPlugin *

p

)

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 *

p

)

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.

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 email address of the plugin's author.

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.

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

Port analog of lilv_plugin_get_value.

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

Return the LV2 port properties of a port.

bool lilv_port_has_property	(	const LilvPlugin *	p,
		const LilvPort *	port,
		const LilvNode *	property_uri
	)

Return whether a port has a certain property.

bool lilv_port_supports_event	(	const LilvPlugin *	p,
		const LilvPort *	port,
		const LilvNode *	event_uri
	)

Return whether a port is an event port and supports a certain event type.

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.

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

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 are defined (e.g. LILV_PORT_CLASS_INPUT) for convenience, but this function is designed so that Lilv is usable with any port types without requiring explicit support in Lilv.

void lilv_port_get_range	(	const LilvPlugin *	plugin,
		const LilvPort *	port,
		LilvNode **	deflt,
		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 (e.g. appropriate entries for a UI selector associated with this port). 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_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.

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.

const LilvNode* lilv_plugin_class_get_label

(

const LilvPluginClass *

plugin_class

)

Get the label of this plugin class, ie "Oscillators".

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

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.

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.

Returns:

NULL if instantiation failed.

void lilv_instance_free

(

LilvInstance *

instance

)

Free a plugin instance.

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

static const char* lilv_instance_get_uri

(

const LilvInstance *

instance

)

[inline, static]

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

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

static void lilv_instance_connect_port	(	LilvInstance *	instance,
		uint32_t	port_index,
		void *	data_location
	)		[inline, static]

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.

static void lilv_instance_activate

(

LilvInstance *

instance

)

[inline, static]

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.

static void lilv_instance_run	(	LilvInstance *	instance,
		uint32_t	sample_count
	)		[inline, static]

Run instance for sample_count frames.

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

static void lilv_instance_deactivate

(

LilvInstance *

instance

)

[inline, static]

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

static const void* lilv_instance_get_extension_data	(	const LilvInstance *	instance,
		const char *	uri
	)		[inline, static]

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.

static const LV2_Descriptor* lilv_instance_get_descriptor

(

const LilvInstance *

instance

)

[inline, static]

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.

static LV2_Handle lilv_instance_get_handle

(

const LilvInstance *

instance

)

[inline, static]

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.

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_uri

(

const LilvUI *

ui

)

Get the URI of a Plugin UI.

Parameters:

ui	The Plugin UI

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.

Parameters:

ui	The Plugin UI

Returns:

a shared value which must not be modified or freed.

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

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 the caller must free with lilv_node_free.

Returns:

The embedding quality level returned by supported_func.

const LilvNode* lilv_ui_get_bundle_uri

(

const LilvUI *

ui

)

Get the URI for a Plugin UI's bundle.

Parameters:

ui	The Plugin UI

Returns:

a shared value which must not be modified or freed.

const LilvNode* lilv_ui_get_binary_uri

(

const LilvUI *

ui

)

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

Parameters:

ui	The Plugin UI

Returns:

a shared value which must not be modified or freed.