HTTPS SSH

Title: lv2plugin~ Author: Albert Gräf aggraef@gmail.com Date: 2014-02-14

lv2plugin~

This is a Pd external which provides a simple LV2 host so that you can run LV2 plugins inside Pd. The overall operation is similar to the LADSPA plugin~ external, but it works with LV2, the new Linux plugin standard. It supports both audio and MIDI plugins. lv2plugin~ is based on lilv, the reference LV2 host library, so it should work with almost any LV2 plugin.

License

lv2plugin~ is Copyright (c) 2014-2016 by Albert Gräf. It is distributed under the 3-clause BSD license, please check the COPYING file for details.

Installation

lv2plugin~ is written in the author's Pure programming language, so you need to have the Pure interpreter installed, as well as the pd-pure plugin loader and the pure-lilv module. You can find all of these on the Pure website. You'll also need the lilv library itself and the LV2 headers, which can be downloaded at http://drobilla.net/software, and should also be readily available on most Linux distributions.

Users of Arch Linux may want to check the Arch User Repositories (AUR), as we try to maintain a fairly complete and recent collection of Pure- and Pd-related packages there.

Mac OS X users can find a ready-made binary package for 64 bit Intel systems here: pd-lv2plugin-0.3-macosx-x86_64.zip. The zip file contains the lv2plugin~ directory which you'll have to copy to a directory on Pd's library path (usually /Library/Pd for system-wide and ~/Library/Pd for personal installation on the Mac). (You'll also need the Pure interpreter which is available in MacPorts. Please check the Pure On Mac OS X wiki page for details.)

To compile the software yourself, check the included Makefile for settings that might need to be adjusted for your system, then run:

make
sudo make install

This works with vanilla Pd. If you're running pd-extended or pd-l2ork then during installation you need to specify the Pd flavor using the PD make variable, e.g.:

sudo make install PD=pd-extended

Or just copy the extra/lv2plugin~ folder from the vanilla installation, the plugin binary should work with all Pd flavors.

Getting Started

A help patch is available which demonstrates how to use the external. Open the Pd help browser and look for a section named lv2plugin~. You'll find a patch named lv2plugin~-help there.

The external and related patches are installed in the extra/lv2plugin~ directory of your Pd installation (usually under /usr/lib/pd or similar). The installation also includes two little helper patches midi-input.pd and midi-output.pd which translate between Pd's MIDI input and output and the MIDI message format understood by lv2plugin~. If you want to use these, you'll have to copy them somewhere where Pd finds them, or put the extra/lv2plugin~ directory on your Pd search path.

Usage

The external is to be invoked with the URI or the name of the LV2 plugin to be instantiated. To get a list of known LV2 plugins on your system, use the listplugins message in the help patch. (You can also just create an lv2plugin~ object without arguments, hook it up to a print object and send it the listplugins message to do this.) Each printed line will show something like:

plugin subtractive http://faustlv2.bitbucket.org/subtractive

Here, subtractive is the name and http://faustlv2.bitbucket.org/subtractive the URI of the plugin. You can use either as an argument of lv2plugin~ when instantiating the plugin. If the name is a valid Pure symbol then it can be used as is; otherwise (or if using the URI) you must enclose the argument in double quotes.

Instantiated plugins always have a pair of control in- and outlets on the left-hand side. The leftmost inlet can be used to change control values, send MIDI data and to execute a number of special operations as explained below. The leftmost outlet sends control messages for output controls of the plugin (if it has any), as well as MIDI data and other output from the special operations. The remaining inlets and outlets of the lv2plugin~ instance are the audio inputs and outputs of the plugin. Thus, if an LV2 plugin has n audio inputs and m audio outputs (n,m >= 0) then the corresponding lv2plugin~ instance will have n+1 inlets and m+1 outlets, respectively.

The lv2plugin~ external understands the following special messages:

  • active changes the activation status of a plugin. It takes one numeric argument which should be 0 to deactivate and nonzero to activate the plugin. Note that it's entirely up to the plugin how this feature is implemented, if at all. (faust-lv2 plugins will generally bypass or mute the plugin if it's deactivated, depending on their number of audio inputs and outputs.)

  • control changes control values. It takes two arguments, the index or name of the control port (as shown by info, see below) and the new value (a number). This kind of message may also be output to the object's left control outlet if the plugin has control output ports.

    NOTE: As Pd makes it hard to enter symbols containing spaces and other special characters, lv2plugin~ actually accepts "mangled" control names in which each contiguous sequence of non-alphanumeric characters in the control name is replaced with a single dash. Thus, e.g., the control name Dry/Wet Mix should be entered as Dry-Wet-Mix. The same format is also used for control output and control labels in the generated GUIs.

    Also note that lv2plugin~ always employs human-readable port names in its user interface, rather than the internal LV2 port symbols which may look rather funky for some plugins. In contrast to the latter, the former are not guaranteed to be unique, so a plugin may have different controls with the same (clear and mangled) control names. In such a case you will have to use the index of the control to specify the control value to be changed in an unambiguous way.

  • gui generates a GOP patch with a generic GUI for the plugin. See GUI Instantiation below.

  • info prints information about the LV2 ports of the plugin. This includes all control, audio and MIDI input and output ports of the plugin. The listed information shows the port numbers, category (in, out or inout), type (control, audio, midi and cv) and (unmangled) name of the port. (CV a.k.a. "control voltage" ports are treated like audio ports but carry control information, so you probably don't want to hook them up to your DAC.) Control ports also have their ranges (min and max value), default and current values listed. For instance, the amp plugin from the faust-lv2 package will give you something like:

    port 0 in control bass -20 20 0 0
    port 1 in control treble -20 20 0 0
    port 2 in control gain -96 10 0 0
    port 3 in control balance -1 1 0 -0.488189
    port 4 out control left -96 10 -96 -102.837
    port 5 out control right -96 10 -96 -108.655
    port 6 in audio in0
    port 7 in audio in1
    port 8 out audio out0
    port 9 out audio out1
    port 10 in midi midiin
    
  • listplugins lists the names and URIs of all known LV2 plugins on your system.

  • listpresets lists all known presets of the plugin. You can also save presets and load them with the savepreset and preset messages, please check Preset Management below for details.

  • reset resets all control values of a plugin to their defaults.

MIDI Input and Output

Besides these, lv2plugin~ also understands MIDI messages in the following special format (n denotes a note or controller number, v the velocity or controller value, c the MIDI channel number in the range 1..16):

Message Meaning
ctl v n c control change
note n v c note
pgm n c program change
polytouch v n c key pressure
touch v c channel pressure
bend v c pitch bend (14 bit value)
start, stop, cont system realtime messages
sysex b1 b2 ... system exclusive message

MIDI input in this format will be passed as proper MIDI messages to the plugin's first MIDI input (if it has any). If the plugin has MIDI output ports, MIDI messages emitted by the plugin will be translated back to the above format and output on the object's left control outlet.

Note that most of these messages closely correspond to the inlets and outlets of Pd's MIDI objects, so translating between these and the lv2plugin~ format is fairly straightforward. A few special system realtime and system exclusive messages are also understood, which don't have a direct counterpart in Pd. The distribution includes two little helper patches (midi-input.pd and midi-output.pd in the examples folder) which handle the conversion, you might want to look at these and adjust them for your needs as you see fit.

Preset Management

lv2plugin~ has some rudimentary preset management functionality which can be invoked with the following messages:

  • listpresets outputs the names and URIs of all known presets for the instantiated plugin. E.g., with the MDA EPiano plugin from the MDA LV2 plugins you'll get something like:

    preset Default http://drobilla.net/plugins/mda/presets#EPiano-default
    preset Bright http://drobilla.net/plugins/mda/presets#EPiano-bright
    preset Autopan http://drobilla.net/plugins/mda/presets#EPiano-autopan
    preset Tremolo http://drobilla.net/plugins/mda/presets#EPiano-tremolo
    preset Mellow http://drobilla.net/plugins/mda/presets#EPiano-mellow
    
  • savepreset with the desired preset name as argument saves the preset in your ~/.lv2 folder, from where it can then be reloaded using the preset message.

Please check the included help patch for examples showing how to use this.

GUI Instantiation

As of version 0.2, lv2plugin~ also provides a built-in capability to generate generic GUIs for LV2 plugins using Pd GOP (graph-on-parent) subpatches. Please see the help patch for an example. The GUI for each plugin has two special controls (a bang and a checkbox) in its title bar to send the special reset and active messages, as well as pairs consisting of a horizontal slider and a number entry for each control port, which are used to show and edit the corresponding control values. (This works with both input and output control ports; the latter are shown with a special background color.)

To utilize this in your patches, simply create a one-off subpatch named after the plugin (i.e., pd name for the lv2plugin~ name plugin instance). If the plugin instance already exists, you then have to send the plugin the gui message in order to populate the subpatch and set its GOP area. (This step isn't necessary if you create the plugin instance after the subpatch, or if the hosting patch is reloaded, as each plugin instance takes care of creating its GUI at creation time if a corresponding one-off subpatch is available.)

Note that the name of the GUI subpatch should match the name of the plugin (as given by the listplugins message), even if the plugin is instantiated using its URI. We also refer to this as the instance name of the plugin. The instance name is also used as a prefix on the send and receive symbols of the GUI elements of the patch, so that the control ports don't get mixed up between different plugin instances even if the ports happen to have the same names.

If you need several instances of the same plugin in a patch, you can distinguish them by specifying the instance name explicitly as the optional second argument of the lv2plugin~ object. This can also be used if you want to name the GUI patch differently for some reason. E.g.,

lv2plugin~ amp "amplifier-gui-1"

creates the amp plugin with amplifier-gui-1 as its instance name, so the GUI for this instance would go into the pd amplifier-gui-1 subpatch.

Note that the contents of the GUI subpatch is regenerated automatically every time its parent patch is loaded. You may want to prevent this, e.g., when you've edited the GUI patch manually. For that it is sufficient to just rename the GUI subpatch before you save its parent patch.

Feedback and Bug Reports

As usual, bug reports, patches, feature requests and other comments and source contributions are more than welcome. Just drop me an email, file an issue at the tracker or send me a pull request on lv2plugin's Bitbucket page https://bitbucket.org/agraef/pd-lv2plugin.

Enjoy! :)

Albert Gräf aggraef@gmail.com