NAME
Audio::LADSPA::Network - Semi automatic connection of Audio::LADSPA::* objects
SYNOPSIS
use Audio::LADSPA::Network;
use Audio::LADSPA::Plugin::Play;
sub subscriber {
my ($object,$event) = @_;
$object = ref($object);
print "Recieved event '$event' from $object\n";
}
Audio::LADSPA::Network->add_subscriber('*',\&subscriber);
my $net = Audio::LADSPA::Network->new();
my $sine = $net->add_plugin( label => 'sine_fcac' );
my $delay = $net->add_plugin( label => 'delay_5s' );
my $play = $net->add_plugin('Audio::LADSPA::Plugin::Play');
$net->connect($sine,'Output',$delay,'Input');
$net->connect($delay,'Output',$play,'Input');
$sine->set('Frequency (Hz)' => 440); # set freq
$sine->set(Amplitude => 1); # set amp
$delay->set('Delay (Seconds)' => 1); # 1 sec delay
$delay->set('Dry/Wet Balance' => 0.2); # balance - 0.2
for ( 0 .. 100 ) {
$net->run(100);
}
$sine->set(Amplitude => 0); #just delay from now
for ( 0 .. 500 ) {
$net->run(100);
}DESCRIPTION
This module makes it easier to create connecting Audio::LADSPA::Plugin objects. It automatically keeps the sampling frequencies correct for all plugins, adds control and audio buffers to unconnected plugins and prevents illegal connections.
It also implements an observable-type API via Class::Publisher that can be used to recieve notifications of events in the network. Amongst other things, this makes writing loosely coupled GUIs fairly straightforward.
CONSTRUCTOR
new
my $network = Audio::LADSPA::Network->new(
sample_rate => $sample_rate,
buffer_size => $buffer_size
);Construct a new Audio::LADSPA::Network. The sample_rate and buffer_size arguments may be omitted. The default sample_rate is 44100, the default buffer_size is 1024.
COMMON METHODS
add_plugin
my $plugin = $network->add_plugin( EXPR );Adds a $plugin to the $network. All unconnected ports will be connected to new Audio::LADSPA::Buffers. Control buffers will be initalized with the correct default value for the port.
EXPR can be an Audio::LADSPA::Plugin object, an Audio::LADSPA::Plugin classname or any expression supported by Audio::LADSPA->plugin().
Any $plugin added to a $network will have its monitor set to that $network. This means that a $plugin cannot be in more than 1 Audio::LADSPA::Network at any given time, and that all callbacks from the $plugin are handled by the $network.
See also "SETTING CALLBACKS" in Audio::LADSPA::Plugin.
has_plugin
if ($network->has_plugin($plugin)) {
# something interesting...
}Check if a given $plugin object exists in the $network. $plugin must be an Audio::LADSPA::Plugin object.
plugins
my @plugins = $network->plugins();Returns all @plugins in the $network in topological order - this means that the plugins will be sorted so that if $plugin2 recieves input from $plugin1, $plugin1 will be before $plugin2 in the @plugins list.
Because the topological sorting is expensive (that is, for semi-realtime audio generation), the result of this operation is cached as long as the network does not change.
connect
unless ($network->connect( $plugin1, $port1, $plugin2, $port2 )) {
warn "Connection failed";
}Connect $port1 of $plugin1 with $port2 of $plugin2. Plugins are added to the network and new buffers are created if needed.
This method will only connect input ports to output ports. If the output port is a control port, the input port must be a control port, if the output port is an audio port, the type of input port does not matter. The order in which the plugins are specified does not matter.
There is currently no special handling of incompatible value ranges. Well behaved plugins should accept any value on any port, even if they specify a range. Note that generic 0dB audio signals should be in the range -1 .. 1, but that control signals usually have completely different ranges.
Returns true on success, false on failure.
You are advised to use this method instead of $plugin->connect( $buffer ). Some of the magic in this method also works for $plugin->connect(), if the plugin is already added to the network, but that might change if the implementation changes. YMMV.
run
$network->run( $number_of_samples );Call $plugin->run( $number_of_samples ) on all plugins in the $network. Throws an exception when $number_of_samples is higher than the $buffer_size specified at the constructor.
disconnect
$network->disconnect($plugin,$port);Will disconnect the specified port from any buffer, and put a "dummy" buffer in its place. This means that you can still call run() the plugin after disconnecting. See also $network->delete().
delete
$network->delete($plugin);Completely remove the plugin from the network. This will also disconnect the plugin from all buffers that it currently holds.
OBSERVABLE / PUBLISHER API
Audio::LADSPA::Network inherits the observable methods from Class::Publisher. You can subscribe to network instances or the Network class. Subscribers can be subroutines, objects or classes.
See also Class::Publisher.
OBSERVABLE ACTIONS
The following actions can be sent to subscribers.
add_plugin
action = "add_plugin", args = $plugin
Called after successful addition of $plugin to the network.
add_buffer
action = "add_buffer", args = $buffer
Called after successful addition of $buffer to the network.
connect
action = "connect", args = $from_plug, $from_port, $to_plug, $to_port
Called after successful connection is made from $from_plug to $to_plug
disconnect
action = "disconnect", args = $plugin, $port
Called after $plugin's $port is disconnected.
delete
action = "delete", args = $plugin
$plugin was deleted from the network.
new
action = "new", args = $network
A new Audio::LADSPA::Network was created.
ADDITIONAL METHODS
add_buffer
my $buffer = $network->add_buffer( EXPR );Add a $buffer to the $network. EXPR may be an Audio::LADSPA::Buffer object, or an integer specifying the $buffer's size.
This method is usually not needed by users of the module, as the connect() and add_plugin() methods take care of creating new buffers for you. Also note that buffers not immediately connected to a plugin will be removed when the network changes in any other way.
has_buffer
if ($network->has_buffer($buffer)) {
# ...
}Returns true if the $buffer is already in the $network.
buffers
my @buffers = $network->buffers();Returns all the $buffers in the $network.
connections
my @connections = $network->connections($plugin,$port);Returns a $remote_plug1, $remote_port1, $remote_plug2, $remote_port2 ... list of all the plugin/port combinations the $plugin's $port is connected to in this $network. Connecting an input port to more than 1 output port is not supported, and the rules on connection an output port to more than one input port are not fixed yet, but keep in mind that this method MAY return more than one plugin/port pair.
plugin_by_uniqid
my $plugin = $network->plugin_by_uniqid($uid);Returns the $plugin with uniqid $uid from $network, or false if there isn't one. See also "get_uniqid" in Audio::LADSPA::Plugin.
SERIALIZATION
The internal structure of the network prevents easy serialisation (Data::Dumper and the like will not give you a dump that you can read back). To overcome this problem 2 methods have been added:
dump
my $dump = $network->dump;Returns a serializable, nested structure that represents the whole network. You can use YAML or Data::Dumper or something similar to serialize the structure.
YAML is the only serializer I tested this with, because it creates nice, readable files, but other dumpers should work.
from_dump
my $network = Audio::LADSPA::Network->from_dump($dump);Creates new network based on the $dump. If used as on object method (ie, called on an existing $network), it tries to import the network into the existing one.
If a network is loaded from a dump, the plugins uniqids are restored from the dump.
SEE ALSO
COPYRIGHT AND LICENSE
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.