Title: lv2plugin~ Author: Albert Gräf email@example.com Date: 2014-02-14
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.
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.
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
/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
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.
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
The external and related patches are installed in the
directory of your Pd installation (usually under
/usr/lib/pd or similar).
The installation also includes two little helper patches
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.
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
listplugins message to do this.) Each printed line will show
plugin subtractive http://faustlv2.bitbucket.org/subtractive
subtractive is the name and
the URI of the plugin. You can use either as an argument of
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
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
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
lv2plugin~ instance will have n+1 inlets and m+1 outlets,
lv2plugin~ external understands the following special messages:
activechanges 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.)
controlchanges 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 Mixshould 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.
guigenerates a GOP patch with a generic GUI for the plugin. See GUI Instantiation below.
infoprints 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 (
inout), type (
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
ampplugin 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
listpluginslists the names and URIs of all known LV2 plugins on your system.
listpresetslists all known presets of the plugin. You can also save presets and load them with the
presetmessages, please check Preset Management below for details.
resetresets all control values of a plugin to their defaults.
MIDI Input and Output
lv2plugin~ also understands MIDI messages in the following
special format (
n denotes a note or controller number,
v the velocity or
c the MIDI channel number in the range 1..16):
||pitch bend (14 bit value)|
||system realtime messages|
||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
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-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.
lv2plugin~ has some rudimentary preset management functionality which can be
invoked with the following messages:
listpresetsoutputs the names and URIs of all known presets for the instantiated plugin. E.g., with the
MDA EPianoplugin 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
savepresetwith the desired preset name as argument saves the preset in your
~/.lv2folder, from where it can then be reloaded using the
Please check the included help patch for examples showing how to use this.
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
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
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
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
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"
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.
Albert Gräf firstname.lastname@example.org