Audio::LADSPA::Plugin - Base class for LADSPA plugins in Perl.


    use Audio::LADSPA;

    my (@plugin_classes) = Audio::LADSPA->plugins();
    # or ...
    my $plugin_class = Audio::LADSPA->plugin( label => "delay_5s", id => 1043);

    my $plugin = $plugin_class->new($sample_rate);


Audio::LADSPA::Plugin is a base class for LADSPA plugins. Default behaviour of the Audio::LADSPA module is to generate a subclass for each plugin found in LADSPA_PATH, using the Audio::LADSPA::LibraryLoader module.

You can use the Audio::LADSPA::Plugin classes to query the capabilities of the loaded plugin, and you can instantiate new objects from them to do some actual audio processing.

A list of all available classnames on your system can be retrieved from Audio::LADSPA->plugins(), or you can get one by label and / or id via Audio::LADSPA->plugin( %ARGS ).

Plugin Information

These methods can all be used as class methods as well as object methods, So you can query plugins without creating a new instance, or query an object you've already created.


 my $id = $plugin_class->id();

Returns the unique id of the plugin class, as reported by the plugin itself.


 my $label = $plugin_class->label();

The short name of the plugin.


 my $name = $plugin_class->name();

A more descriptive name of the plugin.


 my $maker = $plugin_class->maker();

The author of the plugin.

 my $copy = $plugin_class->copyright();

The copyright message for the plugin.


 if ($plugin_class->is_realtime()) {
     warn "This plugin uses realtime input";

From the LADSPA SDK: "Indicates that the plugin has a real-time dependency (e.g. listens to a MIDI device) and so its output must not be cached or subject to significant latency."

The Audio::LADSPA environment might not be fast enough for these kinds of plugins though. Report back to me if you can get it to do something interesting in real time.


 if ($plugin->is_inplace_broken()) {
    # connect plugin to seperate output buffer
 else {
    # connect plugin to shared output buffer

Returns true if the plugin doesn't use the run_adding() method, so you should not connect it need to a shared buffer. See run_adding for more info.


 if ($plugin->is_hard_rt_capable) {
    # do something in realtime

Returns true if the plugin can be run in a realtime environment. Whether the Audio::LADSPA host is a realtime environment, probably depends on you hardware and the complexity of your plugin network. Let me know.


Returns true if the plugin has a run() method.


Returns true if the plugin has a run_adding() method.


Returns true if the plugin has an activate() method.


Returns true if the plugin has an deactivate() method.


A plugin may have zero or more port to connect to other plugins via an Audio::LADSPA::Buffer.


 my @ports = $plugin->ports();

Returns the names of all input/output ports for this plugin, ordered by port index.


 my $num_ports = $plugin_class->port_count();

The number of input / output / audio / control ports for the plugin, added together.


 my $port = $plugin->port($index);

Returns the name of an input/output port for the plugin given its index.


 my $index = $plugin->port2index($port);

Gives the index of $port.

Per port information

These methods all take a $port argument, that can be the port's index (an integer) or the port name. These methods can be called as class methods and object methods.


 my $bool = $plugin->is_input($port);

Returns true if the $port is an input port, false if it's an output port.


 my $bool = $plugin->is_control($port);

Returns true if the $port is a control port, false if it's an audio port. Note that not all audio ports actually send or recieve audio signals. It's quite common to use audio ports for high-resolution control signals.


 my $min = $plugin->lower_bound($port);

Returns the minimal value for the $port, or undef if none is given, you can assume -1 in that case.

Also /is_sample_rate.

Plugins should accept ranges outside the lower and upper bounds, but don't count on it doing anything useful!


 my $max = $plugin->upper_bound($port);

Returns the maximum value for the $port, or undef if none is given (assume 1).

Also /is_sample_rate.


 my $max = $plugin->upper_bound($port):
 $max *= $sample_rate if $plugin->is_sample_rate($port);

Returns true if the bounds should be interpreted as relative to the sample rate.


 my $bool = $plugin->is_logarithmic($port);

From the SDK: indicates that it is likely that the user will find it more intuitive to view values using a logarithmic scale. This is particularly useful for frequencies and gains.


 my $default = $plugin->default($port);

The recommended default value for the $port. This can be any of

"minimum", "maximum", "low", "middle", "high", "maximum", 0, 1, 100, 440 or undef

Should be reasonably intuitive, use default_value if you want an actual value.

See the LADSPA SDK for exact interpretations, or look at the code for Audio::LADSPA::Plugin for the implementation of "default_value".


 my $value = $plugin->default($port);

Returns a reasonable default for the given $port, considering all the port hints (even if there aren't any)


 my $bool = $plugin->is_toggled($port);

Returns true if the $port is toggled, false otherwise.

From the SDK: Indicates that the data item should be considered a Boolean toggle. Data less than or equal to zero should be considered `off' or `false,' and data above zero should be considered `on' or `true.'


 my $bool = $plugin->is_integer($port);

Returns true if the $port should recieve integer values, false otherwise (port accepts floating points). Note that, because all data in LADSPA is passed as floats, you can expect slightly inaccurate values. If you need real integers when reading from the port, round it yourself.

Creating plugin instances


 my $plugin_object = $plugin_class->new($sample_rate, $uniqid);

 # now do something interesting involving audio

Create a new plugin object of $plugin_class with uniqid $uniqid and set its sample rate to $sample_rate.

If $uniqid is not specified or false a new uniqid will be generated via Data::Uniqid::luniqid() which should ensure that the id is always unique over multiple machines and time.

Usually you will want to set all connected plugins to the same sample rate. Audio::LADSPA::Network objects will do this automatically for you.

See also "add_plugin" in Audio::LADSPA::Network, "dump" in Audio::LADSPA::Network and Data::Uniqid.

Connecting plugins

The following methods involve connections to buffers, handling audio data etc.


 $plugin->connect( $port => $buffer);

Connects the $port to the Audio::LADSPA::Buffer $buffer. Returns true on success, false otherwise. Does not check for loops in the resulting connections or conflicting sample rates between plugins. It's probably easer to use <$network-connect()>> instead. Do not use this method if the plugin already is part of an Audio::LADSPA::Network

See also "connect" in Audio::LADSPA::Network and cb_connect.


 $plugin->disconnect( $port );

Disconnect a $port from its buffer. Do not use this method if the plugin is part of an Audio::LADSPA::Network. Use <$network-disconnect($plugin => $port)>> instead.

See also "cb_disconnect".

Getting and setting data


 my $buffer = $plugin->get_buffer( $port );

Returns the buffer connected to the specified port. Returns undef if not connected.


 $plugin->set( $port => @values );

 # eg..
 $drum->set( Velocity => 10 );
 $echo->set( Input    => 1, 1, 0, 0, -1, -1, 0, 0 );

Set the Audio::LADSPA::Buffer connected to the $port. Note that if the $port is an output port, you will probably influence another plugin than this one.

This is a shortcut for <$plugin-get_buffer($port)->set( @values )>>.

See "set" in Audio::LADSPA::Buffer.


 my @values = $plugin->get( $port );
 my $value  = $plugin->get( $port );

 # eg

 @output = $sine_fcac->get('Output');

Get the data from the Audio::LADSPA::Buffer connected to the $port. A shortcut for <$plugin-get_buffer($port)->get()>>

See "get" in Audio::LADSPA::Buffer.


 my $uid = $plugin->get_uniqid();

Returns the uniqid for this plugin instance. See also "new".

Running the plugin



Run the plugin for $num_samples samples. All ports should be connected to a buffer, and activate is called automatically if the plugin isn't active already.

Usually $plugin will read from all buffers connected to its input ports and write to all buffers connected to its output ports.



Same as run() except that the plugin will add its output to the data in its output buffers, instead of overwriting it. Use $plugin->has_run_adding() to check whether the plugin supports this mode. Will throw an exception if not supported.



Set the output gain for the run_adding() method. Will throw an exception if the plugin has no run_adding() method. Check $plugin->has_run_adding().



Signal that the plugin should get ready to run. Is called automatically when run, run_adding or run_adding_gain is called and the plugin is not active. Is ignored after the first call, except when deactivate() is called.



Signal that the plugin can stop. Calling deactivate() and then activate() should reset the plugin.


To ease the creation of 'container' objects for Audio::LADSPA::Plugins, you can register a 'monitor' object (usually, the container itself) that will recieve callbacks whenever certain methods are called on the plugin.

Note that the monitor object should be kept in scope by the container; the reference counting for the $monitor object is NOT increased by calling $plugin->set_monitor($monitor). This is intentional; it allows the container to be the monitor, while still being DESTROYED when going out of scope (this means you don't have to worry when the container is the monitor; the Perl garbage collector will work as you would expect it to). See Audio::LADSPA::Network for a (as of yet buggy) implementation.



Sets the $monitor object for $plugin. Use $plugin->set_monitor(undef) to remove a monitor object.


 my $monitor = $plugin->monitor();

Returns the $monitor object for $plugin, or undef if there is no monitor set.


In general, the callback methods will be called when the corresponing event is called, before any processing of the event is done. Some callback methods can return true or false indicating that the event should be processed or not. When a plugin has no monitor, or the callback is not implemented, the event is processed (the plugin acts as if the callback returned true).

The monitor object may implement the following methods:


 $monitor->cb_connect( $plugin, $port, $buffer );

Will be called when $plugin->connect($port, $buffer) is called. If cb_connect returns false, the connection will not be made.


 $monitor->cb_disconnect( $plugin, $port );

Will be called when $plugin->disconnect($port) is called.


Audio::LADSPA::UserGuide, Audio::LADSPA::Network. And the LADSPA SDK: or the ladspa.h file in this distribution.


Copyright (C) 2003 - 2004 Joost Diepenmaat <>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 191:

alternative text '/is_sample_rate' contains non-escaped | or /

Around line 202:

alternative text '/is_sample_rate' contains non-escaped | or /