view release on metacpan or  search on metacpan

lib/Audio/Analyzer.pm  view on Meta::CPAN

  $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
  
=head1 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.

=head1 REFERENCE

=over 4

=item $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:

=over 4

=item 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. 

=item dft_size

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

=item sample_rate

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

=item bits_per_sample

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

=item channels

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

=item fps 

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

=item 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.

=item 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:

=over 4

=item 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.

=item 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.

=back 

=back

=item $chunk = $analyzer->next;

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

=item $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.


=item $completed = $analyzer->progress;

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

=back

=head1 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.

=over 4

=item $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.

=item $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.