# LV2 Options

Runtime options for LV2 plugins and UIs.

ID | http://lv2plug.in/ns/ext/options
Version | 1.4
Date | 2021-01-09
Discuss | devel@lists.lv2plug.in (subscribe)

- Index
- History
- API

This extension defines a facility for options, which are values the host passes to a plugin or UI at run time.

There are two facilities for passing options to an instance: options allows passing options at instantiation time, and the interface interface allows options to be dynamically set and retrieved after instantiation.

Note that this extension is only for allowing hosts to configure plugins, and is not a live control mechanism. For real-time control, use event-based control via an atom:AtomPort with an atom:Sequence buffer.

Instances may indicate they require an option with the requiredOption property, or that they optionally support an option with the supportedOption property.

## Index

Classes | Properties | Instances
--- | --- | ---
Option | requiredOption supportedOption | interface options

## Classes

### Option

Class

Label | Option
Subclass of | rdf:Property

A value for a static option passed to an instance.

It is not required for a property to explicitly be an Option in order to be used as such. However, properties which are primarily intended for use as options, or are at least particularly useful as options, should be explicitly given this type for documentation purposes, and to assist hosts in discovering option definitions.

## Properties

### requiredOption

Property

Label | required option
Range | rdf:Property
Type | Object Property

An option required by the instance to function at all.

The host MUST pass a value for the specified option via options during instantiation.

Note that use of this property may reduce the number of compatible hosts. Wherever possible, it is better to list options with supportedOption and fall back to a reasonable default value if it is not provided.

### supportedOption

Property

Label | supported option
Range | rdf:Property
Type | Object Property

An option supported or by the instance.

The host SHOULD provide a value for the specified option if one is known, or provide the user an opportunity to specify one if possible.

## Instances

### interface

Instance

Label | interface
Type | lv2:ExtensionData

An interface for dynamically setting and getting options.

An interface (LV2_Options_Interface) for dynamically setting and getting options. Note that this is intended for use by the host for configuring plugins only, and is not a live plugin control mechanism.

The plugin data file should advertise this interface like so:

    @prefix opts: <http://lv2plug.in/ns/ext/options#> .

    <plugin>
        a lv2:Plugin ;
        lv2:extensionData opts:interface .

### options

Instance

Label | options
Type | lv2:Feature

The feature used to provide options to an instance.

To implement this feature, hosts MUST pass an LV2_Feature to the appropriate instantiate method with this URI and data pointed to an array of LV2_Options_Option terminated by an element with both key and value set to zero. The instance should cast this data pointer to `const LV2_Options_Option*` and scan the array for any options of interest. The instance MUST NOT modify the options array in any way.

Note that requiring this feature may reduce the number of compatible hosts. Unless some options are strictly required by the instance, this feature SHOULD be listed as an lv2:optionalFeature.

## History

Version 1.4 (2019-02-03)
  - Relax range of opts:requiredOption and opts:supportedOption
Version 1.2 (2013-01-10)
  - Set the range of opts:requiredOption and opts:supportedOption to opts:Option.
Version 1.0 (2012-10-14)
  - Initial release.