Audio::Data - module for representing audio data to perl
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.
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.
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
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.
Sets elements from @data.
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.
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).
Write a Sun/NeXT .au file to perl file handle. $comment if specified is used as the comment.
Append a sinusoidal tone of specified freqency (in Hz) and duration (in seconds), and peak amplitude $amp.
Append a period of 0 value of specified duration.
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 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.
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
- $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.
access a sample.
Takes complex conjugate
See code for
tkscope to see most of the above in use.
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.
Nick Ing-Simmons <Nick@Ing-Simmons.net>
2 POD Errors
The following errors were encountered while parsing the POD:
- Around line 612:
=back doesn't take any parameters, but you said =back 4
- Around line 680:
=back doesn't take any parameters, but you said =back 4