Next Previous Contents

2. The LADSPA Plugin Format

2.1 Finding and providing LADSPA_Descriptors

The ladspa format specifies how to obtain the LADSPA_Descriptors from a given plugin library. All LADSPA plugin libraries must define a function

LADSPA_Descriptor* ladspa_descriptor(unsigned long Index);

which will return each LADSPA_Descriptor by index. It must return NULL for all invalid indices. So a simple way to determine the number of plugins for a given plugin is:

  unsigned long num_plugins = 0;
  while ((*ladspa_descriptor_func)(num_plugins) != NULL)

More commonly though, you'll need to store and use the LADSPA_Descriptor that that function returns.

2.2 The descriptor's data

Now let's examine the LADSPA_Descriptor structure. It consists of a number of members which describe the plugin, and a collection of function pointers which provide its implementation.

Here are the data members:

unsigned long UniqueID

This numeric identifier indicates the plugin type uniquely. Plugin programmers may reserve ranges of IDs from a central body to avoid clashes. Hosts may assume that IDs are below 0x1000000.

const char * Label

This identifier can be used as a unique, case-sensitive identifier for the plugin type within the plugin file. Plugin types should be identified by file and label rather than by index or plugin name, which may be changed in new plugin versions. Labels must not contain white-space characters.

LADSPA_Properties Properties

This contains a number of properties of the plugin.

const char * Name

This member points to the NUL-terminated name of the plugin (e.g. "Sine Oscillator").

const char * Maker

This member points to the NUL-terminated string indicating the maker of the plugin. This can be an empty string but not NULL.

const char * Copyright

This member points to the NUL-terminated string indicating any copyright applying to the plugin. If no copyright applies, the string "None" should be used.

unsigned long PortCount

This indicates the number of ports, both input and output, present in the plugin. All the ports must be initialized by the host to valid pointer; this will be described better below.

const LADSPA_PortDescriptor * PortDescriptors

This member indicates an array of port descriptors. Valid indices vary from 0 to PortCount-1.

const char * const * PortNames

This member indicates an array of NUL-terminated strings describing ports (e.g. "Frequency (Hz)"). Valid indices vary from 0 to PortCount-1.

const LADSPA_PortRangeHint * PortRangeHints

This member indicates an array of range hints for each port (see above). Valid indices vary from 0 to PortCount-1.

void* ImplementationData

This may be used by the plugin developer to pass any custom implementation data into an instantiate call. It must not be used or interpreted by the host. It is expected that most plugin writers will not use this facility as the ladspa instance should be used to hold instance data, and plugin-descriptor data may as well be global, since it has to be cleaned up by _fini anyway.

The PortDescriptors and PortRangeHints members describe the available ports. The PortDescriptors are just bitmasks that are OR'd together:


indicates that the port is an input.


indicates that the port is an output.


indicates that the port is a control port.


indicates that the port is a audio port.

It is required that the port be an INPUT or an OUTPUT but not both, and a CONTROL or an AUDIO but not both. So there are really four possibilities which we can describe concretely.


an audio input. The host is responsible for filling the port buffer with SampleCount samples before calling the plugin's run function.


an input control. The host must set the single sample which the port buffer contains before calling run.


an audio output. The plugin's run function fills this port buffer with SampleCount samples.


an meter. This is a slowly varying signal produced by the plugin. For example a pitch estimator or level meter might have one of these.

2.3 The descriptor's implementation

The LADSPA_Descriptor contains a number of function pointers which implement the plugin. The primary function is run which renders and processes samples, but you must also define functions to manage the plugin's memory.


function is the function which should allocate a new plugin handle. Generally I think all the allocation should be done here, although you may do it in activate as well.


function is the function which clears and resets a plugin handle. For example, it should zero out delay buffers and filter buffers.


function allows the host to specify input buffers to the plugin. Write the code so that the input and output buffers must be the same.


function processes samples. The host is responsible for filling each of the input port buffers before calling run and the run function is responsible for filling the output buffers.


function is optional. It is the same as run except it adds the output to the output buffer with a host-settable gain instead of overwriting it. If you don't want to implement this, leave the function pointer NULL. I (daveb) don't recommend implementing or using this function as it is not usually much of a savings.


adjusts the gain that run_adding should use.


function should free the memory allocated by activate. Often there is no need for a deactivate function: you may leave the pointer NULL in this case.


function should free a plugin handle and all the memory it owns. (You must use the _fini function to free the data associated with LADSPA_Descriptor.)

Next Previous Contents