NAME

Audio::Data - module for representing audio data to perl

SYNOPSIS

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

$audio->method(...)

$audio OP ...

DESCRIPTION

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 isn't specified it defaults to the duration of the object, and if start time isn't 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 isn't 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. 0'th 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 system's 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.

Operators

Audio::Data also provides overloaded operators where the Audio::Data object is treated as a vector in a mathematical sense. The other operand of an operator can either be another Audio::Data or a scalar which can be converted to a real number.

$audio * $scalar

Multiply each element by the scalar - e.g. adjust "volume".

$audio * $another

Is ear-marked to perform convolution but does not work yet.

$audio / $scalar

Divide each element by the scalar - e.g. adjust "volume".

$scalar / $audio

Return a new object with each element being result of dividing scalar by the corresponding element in original $audio.

$audio + $scalar

Add $scalar to each element - i.e. apply a DC offset.

$audio + $another

Adds element-by-element - i.e. mixes them.

$audio - $scalar

Subtract $scalar from each element.

$audio - $another

Subtracts element-by-element

$audio . $scalar

Append a new element. (Perhaps if scalar is a string it should append to comment instead - but what is a string ... )

$audio . $another

Appends the two objects to get a longer one.

$audio . [ @things ]

Appends contents of array to the object, the contents can be scalars, Audio::Data objects or (as it recurses) refrences to arrays.

$audio->[$N]

access a sample.

~$audio

Takes complex conjugate

SEE ALSO

See code for tkscope to see most of the above in use.

BUGS AND MISFEATURES

Currently only a single channel can be represented - which is fine for speech applications I am using it for, but precludes using it for music.

Still lack Windows .wav file support.

AUTHOR

Nick Ing-Simmons <Nick@Ing-Simmons.net>