Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  AUDIO::DATA (3)

.ds Aq ’


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



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


  $audio OP ...


<B>Audio::DataB> 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 <B>rateB> 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.


<B>Audio::DataB> also provides overloaded operators where the <B>Audio::DataB> object is treated as a vector in a mathematical sense. The other operand of an operator can either be another <B>Audio::DataB> 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 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 <>


Hey! <B>The above document had some coding errors, which are explained below:B>
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
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 DATA (3) 2004-06-02

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.