--------------------------------------------------------------------- README file for Audio::Wav. 3/1/99 - Nick Peskett - nick@soup.demon.co.uk --------------------------------------------------------------------- Modules for reading & writing Microsoft Wav files. --------------------------------------------------------------------- NOTES --------------------------------------------------------------------- I have seperated the module Audio::ByteOrder because I developed these packages on a Win32 machine & I was worried about unpacking types on a big endian processor. I have only tested the Audio::XXX modules on Win32 so far. This module is written entirely in Perl. This is because I don't know any C, however I'm sure the methods read & write in the respective Read & Write classes would benefit from being re-written. These methods unpack bytes from the data block in a wav and repack them again to write. --------------------------------------------------------------------- INSTALLATION --------------------------------------------------------------------- You'll need to install Audio::Tools first. Same as for any CPAN module; tar zxvf Audio-Wav-0.01.tar.gz cd Audio-Wav-0.01 perl Makefile.PL make test make install --------------------------------------------------------------------- DOCUMENTATION --------------------------------------------------------------------- --------------------------------------------------------------------- Audio::Wav Modules for reading & writing Microsoft Wav files. --------------------------------------------------------------------- SYNOPSIS use Audio; my $buffer = 512; my $wav = new Audio::Wav; my $read = $wav -> read( 'testout.wav' ); my $write = $wav -> write( 'testcopy.wav', $read -> details() ); my $total = 0; my $length = $read -> length(); while ( $total < $length ) { my $left = $length - $total; $buffer = $left unless $left > $buffer; my $data = $read -> read_raw( $buffer ); last unless defined( $data ); $write -> write_raw( $data, $buffer ); $total += $buffer; } $write -> finish(); NOTES All sample positions used are in byte offsets (the Audio::Tools::Time manpage for conversion utilities) DESCRIPTION These modules provide a method of reading & writing uncompressed Microsoft Wav files. It was developed on mswin32 so I'm not sure if this version has the correct byte order for big endian machines. METHODS new Returns a blessed Audio::Wav object. my $wav = new Audio::Wav; 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. --------------------------------------------------------------------- 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. 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 ); length Returns the number of bytes of audio data in the file. my $audio_bytes = $read -> length(); 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. 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. $write -> add_cue( $byte_offset, "label", "note" ); file_name Returns the current filename (silly, I know). 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