Audio::Data 1.029

Audio::Data is a module for representing audio data to perl.

SYNOPSIS

use Audio::Data;
my $audio = Audio::Data->new(rate => , ...);

$audio->method(...)

$audio OP ...

Audio::Data represents audio data to perl in a fairly compact and efficient manner using C via XS to hold data as a C array of float values. The use of float avoids many issues with dynamic range, and typical float has 24-bit mantissa so quantization noise should be acceptable. Many machines have floating point hardware these days, and in such cases operations on float should be as fast or faster than some kind of "scaled integer".

Nominally data is expected to be between +1.0 and -1.0 - although only code which interacts with outside world (reading/writing files or devices) really cares.
It can also represent elements (samples) which are "complex numbers" which simplifies many Digital Signal Processing methods.

Methods

The interface is object-oriented, and provides the methods below.
$audio = Audio::Data->new([method => value ...])
The "constructor" - takes a list of method/value pairs and calls $audio->method(value) on the object in order. Typically first "method" will be rate to set sampling rate of the object.

$rate = $audio->rate
Get sampling rate of object.
$audio->rate($newrate)
Set sampling rate of the object. If object contains existing data it is re-sampled to the new rate. (Code to do this was derived from a now dated version of sox.)
$audio->comment($string)
Sets simple string comment associated with data.
$string = $audio->comment
Get the comment
$time = $audio->duration
Return duration of object (in seconds).
$time = $audio->samples
Return number of samples in the object.
@data = $audio->data
Return data as list of values - not recommended for large data.
$audio->data(@data)
Sets elements from @data.
$audio->length($N)
Set number of samples to $N - tuncating or padding with zeros (silence).
($max,$min) = $audio->bounds([$start_time[,$end_time]])
Returns a list of two values representing the limits of the values between the two times if $end_time isnt specified it defaults to the duration of the object, and if start time isnt specified it defaults to zero.
$copy = $audio->clone
Creates copy of data carrying over sample rate and complex-ness of data.
$slice = $audio->timerange($start_time,$end_time);
Returns a time-slice between specified times.
$audio->Load($fh)
Reads Sun/NeXT .au data from the perl file handle (which should have binmode() applied to it.)
This will eventually change - to allow it to load other formats and perhaps to return list of Audio::Data objects to represnt multiple channels (e.g. stereo).
$audio->Save($fh[,$comment])
Write a Sun/NeXT .au file to perl file handle. $comment if specified is used as the comment.
$audio->tone($freq,$dur,$amp);
Append a sinusoidal tone of specified freqency (in Hz) and duration (in seconds), and peak amplitude $amp.
$audio->silence($dur);
Append a period of 0 value of specified duration.
$audio->noise($dur,$amp);
Append burst of (white) noise of specified duration and peak amplitude.
$window = $audio->hamming($SIZE,$start_sample[,$k])
Returns a "raised cosine window" sample of $SIZE samples starting at specified sample. If $k is specified it overrides the default value of 0.46 (e.g. a value of 0.5 would give a Hanning window as opposed to a Hamming window.)
windowed = ((1.0-k)+k*cos(x*PI))
$freq = $audio->fft($SIZE)
$time = $freq->ifft($SIZE);
Perform a Fast Fourier Transform (or its inverse). (Note that in general result of these methods have complex numbers as the elements. $SIZE should be a power-of-two (if it isnt next larger power of two is used). Data is padded with zeros as necessary to get to $SIZE samples.
@values = $audio->amplitude([$N[,$count]])
Return values of amplitude for sample $N..$N+$count inclusive. if $N is not specified it defaults to zero. If $count is not specified it defaults to 1 for scalar context and rest-of-data in array context.
@values = $audio->dB([$N[,$count]])
Return amplitude - in deci-Bells. (0dB is 1/2**15 i.e. least detectable value to 16-bit device.) Defaults as for amplitude.
@values = $audio->phase([$N [,$count]])
Return Phase - (if data are real returns 0). Defaults as for amplitude.
$diff = $audio->difference
Returns the first difference between successive elements of the data - so result is one sample shorter. This is a simple high-pass filter and is much used to remove DC offsets.
$Avalues = $audio->lpc($NUM_POLES,[$auto [,$refl]])
Perform Linear Predictive Coding analysis of $audio and return coefficents of resulting All-Pole filter. 0th Element is not a filter coefficent (there is no A[0] in such a filter) - but is a measure of the "error" in the matching process. $auto is an output argument and returns computed autocorrelation. $refl is also output and are so-called reflection coefficents used in "lattice" realization of the filter. (Code for this lifted from "Festival" speech systems speech_tools.)
$auto = $audio->autocorrelation($LENGTH)
Returns an (unscaled) autocorrelation function - can be used to cause peaks when data is periodic - and is used as a precursor to LPC analysis.