Audio::LADSPA::UserGuide - What you can do with these modules.
This document is not finished, and only gives an overview. For exact information look at Audio::LADSPA::Plugin and Audio::LADSPA::Network and proceed from there.
Linux Audio Developer's Simple Plugin API
From http://www.ladspa.org/
Many audio synthesis and recording packages are in use or in development on Linux. These work in many different ways. LADSPA provides a standard way for "plugin" audio processors to be used with a wide range of these packages.
These modules provide a way to use LADSPA plugins in Perl programs.
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.
Basically, the library is just a shared object (.so) file. The Audio::LADSPA module creates classes for all available libraries. All these classes inherit from Audio::LADSPA::Library.
You can find the available LADSPA libraries on your system using
my @libs = Audio::LADSPA->libraries();
This returns a list of all classnames that represent a LADSPA library.
See also "Loading libraries".
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 plugin etc. See Audio::LADSPA::Plugin for more info.
+ Class -----------------+ | Audio::LADSPA::Library | +------------------------+ ^ | ISA | + Class -------------------------------+ + Class --------+ | Audio::LADSPA::Library::library_name | <- provides - | Audio::LADSPA | +--------------------------------------+ +===============+ | | + libraries() | provides | + plugins() | | +---------------+ V | + Class -----------------------------+ | | Audio::LADSPA::Plugin::plugin_name | | +====================================| | | + name() | <-- provides -----------+ | + maker() | | + is_input( $port ) | | ... | +------------------------------------+ | instantiates | V + Object ----------------------------+ | Audio::LADSPA::Plugin::plugin_name | +====================================+ | ... | | + connect($port, $plugin2, $port2) | | + run($samples) | | ... | +------------------------------------+
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.
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 | +----------+
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.
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.
$LADSPA_PATH
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.
Audio::LADSPA::Library
Audio::LADSPA::Plugin
After that, you can query the loaded libraries by using:
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.
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.
TODO: This section needs to be written. For now, take a look at Audio::LADSPA::Network and Audio::LADSPA::Plugin.
pluginfo
Audio::LADSPA::Buffer
For more information about the LADSPA API, and how to obtain more plugins, see http://www.ladspa.org/
Copyright (C) 2003 - 2004 Joost Diepenmaat <jdiepen@cpan.org>
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.
To install Audio::LADSPA, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Audio::LADSPA
CPAN shell
perl -MCPAN -e shell install Audio::LADSPA
For more information on module installation, please visit the detailed CPAN module installation guide.