The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Audio-LADSPA-0.009
River stage zero No dependents
/ Audio::LADSPA::UserGuide

NAME

Audio::LADSPA::UserGuide - What you can do with these modules.

GETTING STARTED

Overview of the LADSPA plugin API

Layout of a LADSPA library

A LADSPA library contains the code and description for one or more Plugins, each of which can be completely independent. The library is mostly a a convenient way of storing multiple plugins in a file.

Layout of a LADSPA Plugin

A plugin is an object that can create audio and control streams, based on other audio and control streams. In this system, the difference between audio and control streams is only in their frequency - an audio stream has a fixed sample rate, a control stream can have a variable sample rate.

Figure 1: Plugin layout with input (I) and output (O) ports

+- Plugin ----+
| Description |
| I Port 1    |
| O Port 2    |
| . ...       |
+-------------+

A plugin consists of a description, a number of ports that can send or recieve audio or control streams, and methods to connect the streams and run the plugins etc. See Audio::LADSPA::Plugin for more info.

The Audio::LADSPA::Buffer

The buffer object implements the audio and control streams. You can connect multiple ports from different plugins to a buffer, and they will read from it or write to it, according to their port type. The plugin and buffer objects do not protect you from making silly (or even dangerous) connections, so take care when connecting, or use Audio::LADSPA::Network.

Figure 2: Example of plugin/buffer connections

                               +-Plugin 2-+
   +-Plugin 1-+                | O Port 1 +-> Buffer3
   | O Port 1 +--> Buffer1 --> + I Port 2 |
   | O Port 2 +-+              +----------+
   +----------+ |
                |              +-Plugin 3-+
	        +-> Buffer2 -> + I Port 1 |
                               +----------+

Audio::LADSPA::Network

The Audio::LADSPA::Network class contains a plugin network; a number of plugins and buffers that are connected and need to be run in sync. The network can take care of testing the connections and keeping all plugins running at the same sample rate.

Loading libraries

By default, the statement

use Audio::LADSPA;

loads all LADSPA libraries it can find from in the paths defined by the evironment variable $LADSPA_PATH, if it's defined or from "/usr/lib/ladspa" and "/usr/local/lib/ladspa" otherwise.

For each library, it creates a class inheriting from Audio::LADSPA::Library and then proceeds to create a class inheriting from Audio::LADSPA::Plugin for each plugin in the library.

After that, you can query the loaded libraries by using:

my @libs = Audio::LADSPA->libraries();

Which will return the class names of all loaded libraries.

Similary, you can get the list of all loaded plugins with:

my @plugins = Audio::LADSPA->plugins();

Or, get the plugins from a library:

my ($lib1,$lib2) = Audio::LADSPA->libraries();
my @plugins = $lib1->plugins();

Both will return a list of classes (package names) that you can use to query the capabilities of the plugins, or instantiate new plugin objects that you can use to process some audio data.

Querying plugins

Once your libraries are loaded, you can query the plugins - for instance, you can ask for the plugin name like:

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

Or ask for its input ports like:

my @ports = grep { $plugin->is_input($_) } $plugin->ports();

See Audio::LADSPA::Plugin for the full story.

Processing audio data

TODO: This section needs to be written. For now, take a look at Audio::LADSPA::Network and Audio::LADSPA::Plugin.

SEE ALSO

Modules and scripts in this distribution

pluginfo - query ladspa plugins.

Audio::LADSPA::Library - a library containing one or more plugins

Audio::LADSPA::Plugin - the actual ladspa plugins

Audio::LADSPA::Buffer - audio/data buffer that can be used to control a plugin or to connect plugins together

Audio::LADSPA::Network - a set of connected plugins and buffers

Audio::LADSPA::LibraryLoader - loads ladspa shared libraries (.so files) into Audio::LADSPA::Library classes

For more information about the LADSPA API, and how to obtain more plugins, see http://www.ladspa.org/

The website for these modules is located at: http://www.hortus-mechanicus.net/perl/

COPYRIGHT AND LICENSE

Copyright (C) 2003 Joost Diepenmaat <joost AT hortus-mechanicus.net>

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.