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

NAME

Audio::Analyzer - Makes using Math::FFT very easy for audio analysis

SYNOPSIS

  use Audio::Analyzer;

  $source = \*FILEHANDLE;
  $source = 'input.pcm';

  $analyzer = Audio::Analyzer->new(file => $source);

  while(defined($chunk = $analyzer->next)) {
    my $done = $analyzer->progress;

    print "$done% completed\n";
  }

  #useful information
  $freqs = $analyzer->freqs; #returns array reference
  

DESCRIPTION

This module makes it easy to analyze audio files with the Fast Fourier Transform and sync the output of the FFT in time for visual representation.

REFERENCE

$analyzer = Audio::Analyzer->new(%opts)

Create a new instance of Audio::Analyzer ready to analyze a file as specified by %opts. The options available are:

file

A required option; must be either a string which is a filename or a reference to an already open filehandle. The format must be little endian linear coded PCM using signed integers; this is the same format as a WAV file with the header ripped off.

dft_size

The size of the number of samples taken per channel for each iteration of next. Default of 1024.

sample_rate

How many samples per second are in the PCM file. Default of 44100.

bits_per_sample

How many bits per sample in the PCM; must be 16. Default of 16.

channels

How many channels of audio is in the PCM; Default 2.

fps

How many frames per second are going to be used for audio/visual sync. Overrides seek_step. No default.

seek_step

How far to move forward every iteration. Overridden by fps. Default is not to do additional seeking which will not create audio/visual synchronized output.

scaler

Use another scaler class besides the default Audio::Analyzer::ACurve; pass in either a string of the name of the class that will be scaling or undef to perform no scaling at all. See below for information on writting your own scaler classes. The currently available scalers are:

Audio::Analyzer::ACurve

A scaling system that maps the output of the Fourier Transform onto an approximation of the human perception of volume for 20-10,000 hz. This makes the most sense of the output of the Fourier Transform if you want to do visual representations of what you are hearing.

Audio::Analyzer::AutoScaler

A scaling system which tracks the peak level and forces all numbers to be between 0 and 1, with 1 being a magnitude of the peak level.

$chunk = $analyzer->next;

Iterate once and return a new chunk; see below for information on Audio::Analyzer::Chunk.

$freqs = $analyzer->freqs;

Return an array reference of the frequency numbers that we analyze. This array ref is the same size as the number of elements in each channel from $chunk->fft.

$completed = $analyzer->progress;

Return a number between 0 and 99 that represents in percent how far along in the file we have processed.

CHUNK SYSTEM

Instances of Audio::Analyzer::Chunk represent a set of PCM from the file. Operations on instances of this class perform the FFT and access the PCM.

$channels = $chunk->pcm;

Return an array ref of channels; each array value is an array ref which contains the samples from the PCM converted to numbers between -1 and 1.

$channels = $chunk->fft;

Return an array ref of channels; each array value is an array ref which contains the magnitudes from the Fast Fourier Transform. Numbers are between 0 and 1.

$combined = $chunk->combine_fft($channels);

Combine together 2 or more channels of FFT output into a single array ref. The returned ref contains the RMS of each of the channel specific readings.

SCALER CLASSES

The scaler classes are simple. The scaler will be created through new and a reference to the analyzer object is provided as an argument. The scaler class must return a blessed instance of itself.

To perform scaling, Audio::Analyzer will periodically invoke the scale method of the scaler class. This method must take an array reference which represents the data returned by the FFT for one channel. The scaler modifies the data inside the array reference and does not return any value.

Your scaler class should also force all output to be between 0 and 1.

EXAMPLE MEDIA

The following pieces of media were done using Audio::Analyzer:

http://www.youtube.com/watch?v=W8Jk8rTP5lg
http://www.youtube.com/watch?v=6yTEUBgvxs4

Templatized PovRay scenes written out one file per frame then rendered into images individually with a make file.

http://www.youtube.com/watch?v=bFp2zZlFgv4

Imager::Graph generated pngs of the output of Audio::Analyzer and the internal state of a software beat detector.

LIMITATIONS

In no way shape or form should this module be considered accurate or correct enough for actual scientific analysis.

AUTHOR

This module was created and documented by Tyler Riddle <triddle@gmail.com>. Many thanks to Andrew Rodland who contributed greatly to getting as far as we got.

BUGS

Please report any bugs or feature requests to bug-audio-analyzer@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Audio::Analyzer. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Known Bugs

This module is still not passing tests on all types of hardware. See http://cpantesters.org/distro/A/Audio-Analyzer.html for details on what is and is not passing.

Copyright 2007 Tyler Riddle, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.