The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

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

Audio::LADSPA, Graph::Base

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.