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

NAME

Audio::LADSPA::Buffer

SYNOPSIS

    use Audio::LADSPA;

    my $buffer = Audio::LADSPA::Buffer->new($size);

    $plugin->connect('Port name' => $buffer);
    
    $buffer->set( @values );

    # or get a buffer from a plugin..

    $buffer2 = $plugin->get_buffer('Other port');

    # make audio buffer louder
    
    $buffer *= 2;

DESCRIPTION

Audio::LADSPA::Buffer objects implement the connections between Audio::LADSA::Plugin objects. You can set up the buffer, and let some plugin write to it, while others read from it, or read from or write to it yourself.

There is no real difference between audio and control buffers, except that control buffers have a size of 1 sample *) and audio buffers are usually bigger.

*) Samples in LADSPA are implemented as native floats.

Methods

new

 my $buffer = Audio::LADSPA::Buffer->new( $size );

Contstructs a buffer of $size samples. Failure to allocate the buffer will result in an exception.

set_1

 $buffer->set_1($value);

Set the first sample in the buffer to value $value. This method can only be used on buffers of size 1 (usually control buffers), to avoid confusion and nasty sound effects.

get_1

 my $value = $buffer->get_1();

Gets the first sample from a buffer. This method can only be used on buffers of size 1.

Will return undef if the buffer is not filled yet.

set_list

 $buffer->set_list( @values );

Fill the buffer with some values. Useful when you are generating data with some pure perl functions. Otherwise use "set_raw" for best performance.

Trying to write more samples than the buffer size specified in the constructor will result in an exception.

get_list

 my @values = $buffer->get_list();

Returns perl-friendly representation of the buffer. Returns an empty list if if the buffer is not filled. Note that it will not nessicarily return the total buffer content, only the data that was last written to it. Use "get_raw" for best performance.

get

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

Calls $buffer->get_list() in list context, calls $buffer->get_1() otherwise.

set

 $buffer->set( @values );
 $buffer->set( $value );

Calls $buffer->set_list( @values ) when called with more than 1 argument, calls $buffer->set_1( $value ) otherwise.

set_raw

 $buffer->set_raw($packed_string);

Fills the buffer with packed floats. This is the internal data type for LADSPA, so you can save some processing time by using this method instead of the other get_* methods.

Trying to write more samples than the buffer size will result in an exception.

get_raw

 my $packed_string = $buffer->get_raw();

Get the buffer data unconverted. Whatever your machine thinks a float array looks like, dumped into a perl string. This is the LADSPA internal data format: fast, reasonably high resolution and very non-portable.

set_words

 $buffer->set_words($packed_string, $amp);

Get the buffer data as a packed string of little-endian words. This is useful for reading from WAV audio files, maybe for reading from audio devices and probably not much else.

$amp is the multiplication factor for the buffer data; many LADSPA plugins assume range of 1 .. -1, which integers represent rather badly, so you can have them multiplied first. You can leave out the $amp parameter or set it to 0 to ignore it.

get_words

 my $packed_string = $buffer->get_words($amp);

Get the buffer data as a packed string of little-endian words. This is useful for writing WAV audio files, maybe for writing to some audio devices and probably not much else.

$amp is the multiplication factor for the buffer data; many LADSPA plugins assume range of 1 .. -1, which is not very useful converted to integers, so you can have them multiplied first. Leave out the $amp parameter or set it to 0 to ignore it.

filled

 my $current_fill = $buffer->filled;

Returns the number of samples last written to the buffer, which is how many samples you will get back from the get_* methods.

Buffer Volume adjustment

For convinience, the Audio::LADSPA::Buffer objects gain be 'gained' by using the following operators:

'*'

 my $louder_or_softer_buffer = $original_buffer * $gain;

Create a $louder_or_softer_buffer with all samples from the $original_buffer multiplied by $gain.

This method is less efficient than using the *= operator described below, because it has to allocate new memory for the new buffer.

'*='

 $buffer *= $gain;

Modify the content of $buffer; multiply all samples by $gain. Should be more efficient than *

SEE ALSO

Audio::LADSPA etc. and "pack" in perlfunc.

COPYRIGHT AND LICENSE

Copyright (C) 2003 - 2005 Joost Diepenmaat <jdiepen AT 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.