--------------------------------------------------------------------- README file for Audio::Tools. 3/1/99 - Nick Peskett - nick@soup.demon.co.uk --------------------------------------------------------------------- These tools are required for the follwing modules; Audio::Wav Audio::Mix Audio::CoolEdit --------------------------------------------------------------------- NOTES --------------------------------------------------------------------- These modules are common tools used by my other Audio::XXX applications. 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. --------------------------------------------------------------------- INSTALLATION --------------------------------------------------------------------- Same as for any CPAN module; tar zxvf Audio-Tools-0.01.tar.gz cd Audio-Tools-0.01 perl Makefile.PL make test make install You'll need to install this module before any of the other related Audio::XXX modules I've written --------------------------------------------------------------------- DOCUMENTATION --------------------------------------------------------------------- --------------------------------------------------------------------- Audio::Tools Common Tools for Audio::Wav, Audio::Mix & Audio::CoolEdit --------------------------------------------------------------------- DESCRIPTION The modules in this package are ByteOrder, Time & Fades. They are all independent and the only use, so far, for Audio::Tools is a place to hold the documentation. ByteOrder is currently the unpacking rules for little endian machines, I've seperated this from the other modules for ease of porting to big endian machines. Fades is a collection of algorithms for fading in/ out audio files. Time is a collection of tools for conversion between time, samples & bytes among other things. --------------------------------------------------------------------- Audio::Tools::ByteOrder Unpacking rules for little endian machines. --------------------------------------------------------------------- SYNOPSIS use Audio::Tools::ByteOrder; my $pack_order = new Audio::Tools::ByteOrder; my $pack_type = $pack_order -> pack_type(), my $pack_length = $pack_order -> pack_length(), DESCRIPTION This is currently the unpacking rules for little endian machines, METHODS new Returns a blessed Audio::Tools::ByteOrder object. my $pack_order = new Audio::Tools::ByteOrder; pack_type Returns a reference to a hash containing the pack types for various data formats. my $pack_type = $pack_order -> pack_type(), pack_length Returns a reference to a hash containing the packed lengths for various data formats. my $pack_length = $pack_order -> pack_length(), --------------------------------------------------------------------- Audio::Tools::Fades Fading in & out algorithms. --------------------------------------------------------------------- DESCRIPTION Fades is a collection of algorithms for fading in/ out audio files. SYNOPSIS use Audio::Tools::Fades; my $up_to = 5; my @names = qw( in out ); my $volume = 1; my $fades = new Audio::Tools::Fades; foreach my $type ( qw( linear exp invexp trig invtrig ) ) { for my $direction ( 0, 1 ) { my $fade = $fades -> fade( $up_to, $direction, $type ); print "fade $names[$direction] type: $type;\n\t"; for my $sample ( 0 .. $up_to ) { printf ' %2d->%2.2f', $sample, &$fade( $sample, $volume ); } print "\n"; } } METHODS new Returns a blessed Audio::Tools::Fades object. my $fades = new Audio::Tools::Fades; fade Returns a reference to a subroutine that is initialised to the length of samples the fade is to last for. The subroutine returned takes the current sample offset & the current sample value as parameters. In the example I have used sample value 1 so you can see the effect of the fade. my $fade = $fades -> fade( $length, $direction, $type ); for my $sample ( 0 .. $length ) { printf ' %2d->%2.2f', $sample, &$fade( $sample, 1 ); } print "\n"; Where; $length = length of fade $direction = 0 for in, 1 for out $type is one of; linear = smooth gradient exp = exponential (gets loud quickly) invexp = inverse exponential (gets loud slowly) trig = trigonomic, roughly in between linear & exp invtrig = inverse trigonomic --------------------------------------------------------------------- Audio::Tools::Time time / sample / byte conversion tools. --------------------------------------------------------------------- DESCRIPTION Tools for converting bytes into samples, samples into time etc. SYNOPSIS my $time = new Audio::Tools::Time 44100, 16, 2; my $bytes = $time -> nice_bytes( 11025 ); my $sample = $time -> bytes_to_samples( $bytes ); my $secs = $time -> samples_to_seconds( $sample ); my( $mins, $secs, $fract_secs ) = $time -> split_time( $secs ); my $dao_time = $time -> dao_time( $secs ); AUTHOR Nick Peskett - nick@soup.demon.co.uk SEE ALSO the Audio::Wav manpage the Audio::Mix manpage the Audio::CoolEdit manpage METHODS new Returns a blessed Audio::Tools::Time object. my $time = new Audio::Tools::Time sample_rate, bits_per_sample, channels; Where; sample_rate = number of samples per second (44100 is cd quality) bits_per_sample = number of bits per samples (16 is cd quality) channels = number of channels of sound (stereo is 2) samples_to_bytes Converts a sample offset to it's byte offset. my $bytes = $time -> samples_to_bytes( $sample ); bytes_to_samples Converts a byte offset to it's sample offset. my $sample = $time -> bytes_to_samples( $bytes ); samples_to_seconds Converts a sample offset to it's position as floating point seconds. my $secs = $time -> samples_to_seconds( $sample ); bytes_to_seconds Converts a byte offset to it's position as floating point seconds. my $secs = $time -> bytes_to_seconds( $samples ); seconds_to_samples Converts a position in seconds (can be floating point) to it's sample offset. my $sample = $time -> seconds_to_samples( $secs ); seconds_to_bytes Converts a position in seconds (can be floating point) to it's byte offset. my $sample = $time -> seconds_to_bytes( $secs ); nice_bytes Rounds down a byte offset to a appropriate byte offset for the current settings. $bytes = $time -> nice_bytes( $bytes ); split_time Converts a floating point seconds position to minutes, seconds & fractional seconds. my( $mins, $secs, $fract_secs ) = $time -> split_time( $secs ); dao_time Converts a floating point seconds position to a string containing the format used by disk-at-once & CDRWin. (the section on "/www.goldenhawk.com" in the http: manpage) my $dao_time = $time -> dao_time( $secs ); nice_time Converts a floating point seconds position into a string that verbosely describes the time. If $terse is true then the output will only show the most significant value (to one decimal place if hour or minute). print $time -> nice_time( 90 ); # returns "1 min, 30 secs" print $time -> nice_time( 90, 1 ); # returns "1.5 mins" dao_cue_file Writes a cue file in the format used by disk-at-once & CDRWin. (the section on "/www.goldenhawk.com" in the http: manpage) $time -> dao_cue_file( $breaks, './audio.wav', './output.cue' ); Where $breaks is a reference to an array of byte offsets. block_align Returns the current block alignment, ie 44.1khz 16 bit stereo: 1 sample = 4 bytes my block_align = $time -> block_align();