What Is This?

On this page, you'll find a patch proposal enhancing the Linux Audio Developers' Simple Plugin API, or LADSPA v1.1, to v1.2.

Is your v1.2 Compatible with v1.1?

The patch will not cause breakage in any way: a plugin conforming to the proposed v1.2 standard will work flawlessly in hosts conforming to v1.1, and a v1.1 plugin in a v1.2 host. Of course, compatibility extends to v1.0-conformance. Existing plugins and hosts can be compiled against the proposed v1.2 header without any changes to the sources. Upgrading will be a controlled process, possible to be done one step (new feature) at a time.

What Does the Patch Add to LADSPA?

The patch adds the following features:

• The "_latency" port is a convention that allows hosts to evaluate and adjust to the inherent delay particular DSP algorithms can introduce.
• Hints tell a host more about plugin ports (parameter communication points). The patch adds these hints:
  • NULL_OK means the port can be connected to 'NULL', for 'unconnected' semantics in effect.
  • TRIGGER signifies one-shot process triggering, such as sample playback, wave cycle restart etc.
  • MOMENTARY ports are switched 'on' for brief periods of time, for temporary variations.
  • GROUP allows conceptual grouping of ports, for example individual band parameters (f, width, gain) of a parametric equalizer.
• Value Enumerations allow a plugin to label parameter values. This makes it possible for host programs to display strings instead of numbers when identifying value options. For example, it becomes possible to select one of "sin", "tri", "saw" instead of 0, 1, 2 when choosing an oscillator waveform.
  In addition, it becomes possible for plugins to identify parameter values of particular interest. A resonating filter for example can indicate that a Q setting of 0.8 corresponds to +6 dB at the cutoff frequency, or a stereo chorus can indicate that a phase of 0.5 runs its two LFOs in quadrature phase.
• Parameter Units can be specified by the plugin: "Hz", "dB", "ms" etc.
• Default Values for parameters can be specified in full floating point precision. v1.1 only allows plugins to give a rough idea, sometimes off by more than an order of magnitude.

To the best of my knowledge, these are all features that have found some form of collective — albeit never unanimous ;) — support on the lad mailing list in the past.

In addition to these features, the patch introduces a Version field in the plugin descriptor structure to make future enhancements less painful.

Files

ladspa.h.diff - diff against ladspa.h v1.1
 
host.c - host-side sample source
drive.c - plugin-side sample source

ladspa.h.orig - original v1.1 header

How to Test the Patch

The above claims about compatibility have been verified, but if you'd rather see for yourself, compile the example plugin source from this page against a patched ladspa.h and test it with your favourite host program(s), or compile your favourite hosts or plugins against a patched header.

To compile the example plugin and test the extension, you need the files drive.c, an original ladspa.h (available here as ladspa.h.orig) and the patch, ladspa.h.diff. All necessary steps for downloading and installing:

	$ cd /tmp
	$ wget -qr http://quitte.de/ladspa
	$ cd quitte.de/ladspa
	$ mv ladspa.h.orig ladspa.h
	$ patch < ladspa.h.diff
	$ gcc -Wall -nostartfiles -shared -lm -o drive.so drive.c
	$ sudo cp drive.so $LADSPA_PATH

Obviously, the last command that installs the plugin depends on the availability of the sudo command and the environment variable LADSPA_PATH so you may need to adjust it to reflect your system setup. When you're done, the drive plugin can be tested with any v1.1-conforming host. Make sure you remove the plugin binary, drive.so, from $LADSPA_PATH after testing — it has an invalid LADSPA UniqueID.

This Patch is Too Intrusive! Your LADSPA v1.2 is Not Simple Anymore!

OK, let's go over the new features and evaluate these accusations in detail. We'll see that a lot of the 'new' features in fact aren't so 'new': they only receive official status through the patch, for clarification and consequently ease of use.

• The "_latency" port already is a fact, introducing it in the spec only makes it official.
• The new Hints, one by one:
  • NULL_OK has been accepted by everybody so far. It is a new feature, and a hugely useful one at that.
  • TRIGGER is extremely useful for a number of plugins (envelopes, sample playback, oscillators), and already implemented in some. The new hint simply acknowledges the fact this particular usage of a plugin port exists, and makes it easier for users to understand what's going on.
  • MOMENTARY: same reasoning as with TRIGGER, plus general consensus.
  • GROUP is very useful for hosts that do automatic layout of plugin GUIs. It doesn't change a thing about the core LADSPA functionality.
• The benefits of Value Enumerations have been agreed upon by everybody, but not the terms of implementation. There's another proposal (here's the post describing it) that implements a subset of the solution proposed here. This alternative proposal limits the values that can be labeled to integers, and requires plugins to label all possible integer values of a parameter if they choose to label values of a particular port at all, by introducing another new HINT bit that makes a complete enumeration mandatory.
   
  The aim of both proposals is to clarify (by labeling) something that already is part of LADSPA, for one example switched waveforms of an oscillator plugin.
   
  So the question here seems to become: do we want it, and if we want it, do we want it to be a versatile feature or the comfort of a special case.
• Parameter Units are already part of LADSPA since v1.0. The current spec encourages plugin authors to specify units in the port name, which invites reduced readability, wasted display area and ambiguity. The aim of the patch is to gracefully remove this wart from LADSPA.
• The common consensus is that Default Values in the current LADSPA incarnation are not versatile enough. Some even argue the current implementation is a hack of doubtful merits. In any event, common agreement is that they need a replacement proper. Here again, the patch tries to clean up and clarify something that already is part of LADSPA.