---------------------------------------------------------------------
README file for Audio::Wav (0.03).
---------------------------------------------------------------------
Modules for reading & writing Microsoft WAV files.
---------------------------------------------------------------------
INSTALLATION
---------------------------------------------------------------------
tar zxvf Audio-Wav-0.02.tar.gz
cd Audio-Wav-0.02
perl Makefile.PL
make test
make install
---------------------------------------------------------------------
DOCUMENTATION
---------------------------------------------------------------------
Audio::Wav
Modules for reading & writing Microsoft WAV files.
---------------------------------------------------------------------
SYNOPSIS
use Audio::Wav;
my $wav = new Audio::Wav;
my $read = $wav -> read( 'input.wav' );
my $write = $wav -> write( 'output.wav', $read -> details() );
print "input is ", $read -> length_seconds(), " seconds long\n";
$write -> set_info( 'software' => 'Audio::Wav' );
my $data;
while ( defined( $data = $read -> read_raw( $buffer ) ) ) {
$write -> write_raw( $data );
}
my $length = $read -> length_samples();
my( $third, $half, $twothirds ) = map int( $length / $_ ), ( 3, 2, 1.5 );
my %samp_loop = (
'start' => $third,
'end' => $twothirds,
);
$write -> add_sampler_loop( %samp_loop );
$write -> add_cue( $half, "cue label 1", "cue note 1" );
$write -> finish();
NOTES
All sample positions are now in sample offsets (unless option
'.01compatible' is true).
DESCRIPTION
These modules provide a method of reading & writing uncompressed
Microsoft WAV files.
SEE ALSO
L<Audio::Wav::Read>
L<Audio::Wav::Write>
METHODS
new
Returns a blessed Audio::Wav object. All the parameters are optional and
default to 0
my %options = (
'.01compatible' => 0,
'oldcooledithack' => 0,
'debug' => 0,
);
my $wav = Audio::Wav -> new( %options );
write
Returns a blessed Audio::Wav::Write object.
my $details = {
'bits_sample' => 16,
'sample_rate' => 44100,
'channels' => 2,
};
my $write = $wav -> write( 'testout.wav', $details );
See the Audio::Wav::Write manpage for methods.
read
Returns a blessed Audio::Wav::Read object.
my $read = $wav -> read( 'testout.wav' );
See the Audio::Wav::Read manpage for methods.
set_error_handler
Specifies a subroutine for catching errors. The subroutine should take a
hash as input. The keys in the hash are 'filename', 'message' (error
message), and 'warning'. If no error handler is set, die and warn will
be used.
sub myErrorHandler {
my( %parameters ) = @_;
if ( $parameters{'warning'} ) {
# This is a non-critical warning
warn "Warning: $parameters{'filename'}: $parameters{'message'}\n";
} else {
# Critical error!
die "ERROR: $parameters{'filename'}: $parameters{'message'}\n";
}
}
$wav -> set_error_handler( \&myErrorHandler );
---------------------------------------------------------------------
Audio::Wav::Read
Module for reading Microsoft WAV files.
---------------------------------------------------------------------
NAME
Audio::Wav::Read - Module for reading Microsoft WAV files.
SYNOPSIS
use Audio::Wav;
my $wav = new Audio::Wav;
my $read = $wav -> read( 'filename.wav' );
my $details = $read -> details();
DESCRIPTION
Reads Microsoft Wav files.
SEE ALSO
the Audio::Wav manpage
the Audio::Wav::Write manpage
NOTES
This module shouldn't be used directly, a blessed object can be returned
from the Audio::Wav manpage.
METHODS
file_name
Returns the file name.
my $file = $read -> file_name();
get_info
Returns information contained within the wav file.
my $info = $read -> get_info();
Returns a reference to a hash containing; (for example, a file marked up
for use in Audio::Mix)
{
'keywords' => 'bpm:126 key:a',
'name' => 'Mission Venice',
'artist' => 'Nightmares on Wax'
};
get_cues
Returns the cuepoints marked within the wav file.
my $cues = $read -> get_cues();
Returns a reference to a hash containing; (for example, a file marked up
for use in Audio::Mix) (position is byte offset)
{
1 => {
label => 'sig',
position => 764343,
note => 'first'
},
2 => {
label => 'fade_in',
position => 1661774,
note => 'trig'
},
3 => {
label => 'sig',
position => 18033735,
note => 'last'
},
4 => {
label => 'fade_out',
position => 17145150,
note => 'trig'
},
5 => {
label => 'end',
position => 18271676
}
}
read_raw
Reads raw packed bytes from the current audio data position in the file.
my $data = $self -> read_raw( $byte_length );
read
Returns the current audio data position sample across all channels.
my @channels = $self -> read();
Returns an array of unpacked samples. Each element is a channel i.e (
left, right ). The numbers will be in the range;
where $samp_max = ( 2 ** bits_per_sample ) / 2
-$samp_max to +$samp_max
position
Returns the current audio data position (as byte offset).
my $byte_offset = $read -> position();
move_to
Moves the current audio data position to byte offset.
$read -> move_to( $byte_offset );
move_to_sample
Moves the current audio data position to sample offset.
$read -> move_to_sample( $sample_offset );
length
Returns the number of bytes of audio data in the file.
my $audio_bytes = $read -> length();
length_samples
Returns the number of samples of audio data in the file.
my $audio_samples = $read -> length_samples();
length_seconds
Returns the number of seconds of audio data in the file.
my $audio_seconds = $read -> length_seconds();
details
Returns a reference to a hash of lots of details about the file. Too
many to list here, try it with Data::Dumper.....
use Data::Dumper;
my $details = $read -> details();
print Data::Dumper->Dump([ $details ]);
---------------------------------------------------------------------
Audio::Wav::Write
Module for writing Microsoft WAV files.
---------------------------------------------------------------------
SYNOPSIS
use Audio::Wav;
my $wav = new Audio::Wav;
my $sample_rate = 44100;
my $bits_sample = 16;
my $details = {
'bits_sample' => $bits_sample,
'sample_rate' => $sample_rate,
'channels' => 1,
};
my $write = $wav -> write( 'testout.wav', $details );
&add_sine( 200, 1 );
sub add_sine {
my $hz = shift;
my $length = shift;
my $pi = ( 22 / 7 ) * 2;
$length *= $sample_rate;
my $max_no = ( 2 ** $bits_sample ) / 2;
for my $pos ( 0 .. $length ) {
$time = $pos / $sample_rate;
$time *= $hz;
my $val = sin $pi * $time;
my $samp = $val * $max_no;
$write -> write( $samp );
}
}
$write -> finish();
DESCRIPTION
Currently only writes to a file.
SEE ALSO
the Audio::Wav manpage
the Audio::Wav::Read manpage
NOTES
This module shouldn't be used directly, a blessed object can be returned
from the Audio::Wav manpage.
METHODS
finish
Finishes off & closes the current wav file.
$write -> finish();
add_cue
Adds a cue point to the wav file.
# $byte_offset for 01 compatibility mode
$write -> add_cue( $sample, "label", "note" );
set_sampler_info
All parameters are optional.
my %info = (
'midi_pitch_fraction' => 0,
'smpte_format' => 0,
'smpte_offset' => 0,
'product' => 0,
'sample_period' => 0,
'manufacturer' => 0,
'sample_data' => 0,
'midi_unity_note' => 65,
);
$write -> set_sampler_info( %info );
add_sampler_loop
All parameters are optional except start & end.
my $length = $read -> length_samples();
my( $third, $twothirds ) = map int( $length / $_ ), ( 3, 1.5 );
my %loop = (
'start' => $third,
'end' => $twothirds,
'fraction' => 0,
'type' => 0,
);
$write -> add_sampler_loop( %loop );
add_display
set_info
Sets information to be contained in the wav file.
$write -> set_info( 'artist' => 'Nightmares on Wax', 'name' => 'Mission Venice' );
file_name
Returns the current filename.
my $file = $write -> file_name();
write
Adds a sample to the current file.
$write -> write( @sample_channels );
Each element in @sample_channels should be in the range of;
where $samp_max = ( 2 ** bits_per_sample ) / 2
-$samp_max to +$samp_max
write_raw
Adds a some pre-packed data to the current file.
$write -> write_raw( $data, $data_length );
Where;
$data is the packed data
$data_length (optional) is the length in bytes of the data
---------------------------------------------------------------------
AUTHORS
---------------------------------------------------------------------
Nick Peskett <cpan@peskett.com>.
Kurt George Gjerde <kurt.gjerde@media.uib.no>. (from 0.02)
---------------------------------------------------------------------
END
---------------------------------------------------------------------