1--------------------------------------------------------------------- 2 README file for Audio::Wav (0.11). 3--------------------------------------------------------------------- 4 5Modules for reading & writing Microsoft WAV files. 6 7--------------------------------------------------------------------- 8 INSTALLATION 9--------------------------------------------------------------------- 10 11tar zxvf Audio-Wav-0.06.tar.gz 12cd Audio-Wav-0.06 13perl Makefile.PL 14make test 15make install 16 17--------------------------------------------------------------------- 18 LICENSE AND COPYRIGHT 19--------------------------------------------------------------------- 20 21his program is free software; you can redistribute it and/or 22modify it under the same terms as Perl itself. 23 24Copyright (c) 2010 Brian Szymanski <ski-cpan@allafrica.com> 25Copyright (c) 1999-2001,2004-2006 Nick Peskett (http://www.peskett.co.uk/) 26Copyright (c) 2004 Kurt George Gjerde <KJERDE@cpan.org> 27 28--------------------------------------------------------------------- 29 DOCUMENTATION 30--------------------------------------------------------------------- 31 32 Audio::Wav 33 Modules for reading & writing Microsoft WAV files. 34--------------------------------------------------------------------- 35 36NAME 37 Audio::Wav - Modules for reading & writing Microsoft WAV files. 38 39SYNOPSIS 40 # copying a file and adding some cue points to the output file 41 use Audio::Wav; 42 my $wav = new Audio::Wav; 43 my $read = $wav -> read( 'input.wav' ); 44 my $write = $wav -> write( 'output.wav', $read -> details() ); 45 print "input is ", $read -> length_seconds(), " seconds long\n"; 46 47 $write -> set_info( 'software' => 'Audio::Wav' ); 48 my $data; 49 #read 512 bytes 50 while ( defined( $data = $read -> read_raw( 512 ) ) ) { 51 $write -> write_raw( $data ); 52 } 53 my $length = $read -> length_samples(); 54 my( $third, $half, $twothirds ) = map int( $length / $_ ), ( 3, 2, 1.5 ); 55 my %samp_loop = ( 56 'start' => $third, 57 'end' => $twothirds, 58 ); 59 $write -> add_sampler_loop( %samp_loop ); 60 $write -> add_cue( $half, "cue label 1", "cue note 1" ); 61 $write -> finish(); 62 63 # splitting a multi-channel file to seperate mono files (slowly!); 64 use Audio::Wav; 65 my $read = $wav -> read( '4ch.wav' ); 66 my $details = $read -> details(); 67 my %out_details = map { $_ => $details -> {$_} } 'bits_sample', 'sample_rate'; 68 $out_details{'channels'} = 1; 69 my @out_files; 70 my $in_channels = $details -> {'channels'}; 71 foreach my $channel ( 1 .. $in_channels ) { 72 push @out_files, $wav -> write( 'multi_' . $channel . '.wav', \%out_details ); 73 } 74 75 while ( 1 ) { 76 my @channels = $read -> read(); 77 last unless @channels; 78 foreach my $channel_id ( 0 .. $#channels ) { 79 $out_files[$channel_id] -> write( $channels[$channel_id] ); 80 } 81 } 82 83 # not entirely neccessary as finish is done in DESTROY now (if the file hasn't been finished already). 84 foreach my $write ( @out_files ) { 85 $write -> finish(); 86 } 87 88NOTES 89 All sample positions are now in sample offsets (unless option 90 '.01compatible' is true). 91 92 There is now *very* basic support for WAVEFORMATEXTENSIBLE (in fact it 93 only recognises that the file is in this format). The key 'wave-ex' is 94 used in the detail hash to denote this format when reading or writing. 95 I'd like to do more with this, but don't have any hardware or software 96 to test these files, also don't really have any spare time to do the 97 implementation at present. 98 99 One day I plan to learn enough C to do the sample reading/ writing in 100 XS, but for the time being it's done using pack/ unpack in Perl and is 101 slow. Working with the raw format doesn't suffer in this way. 102 103 It's likely that reading/ writing files with bit-depth greater than 16 104 won't work properly, I need to look at this at some point. 105 106DESCRIPTION 107 These modules provide a method of reading & writing uncompressed 108 Microsoft WAV files. 109 110METHODS 111 new 112 Returns a blessed Audio::Wav object. All the parameters are optional and 113 default to 0 114 115 my %options = ( 116 '.01compatible' => 0, 117 'oldcooledithack' => 0, 118 'debug' => 0, 119 ); 120 my $wav = Audio::Wav -> new( %options ); 121 122 write 123 Returns a blessed Audio::Wav::Write object. 124 125 my $details = { 126 'bits_sample' => 16, 127 'sample_rate' => 44100, 128 'channels' => 2, 129 }; 130 131 my $write = $wav -> write( 'testout.wav', $details ); 132 133 See Audio::Wav::Write for methods. 134 135 read 136 Returns a blessed Audio::Wav::Read object. 137 138 my $read = $wav -> read( 'testout.wav' ); 139 140 See Audio::Wav::Read for methods. 141 142 set_error_handler 143 Specifies a subroutine for catching errors. The subroutine should take a 144 hash as input. The keys in the hash are 'filename', 'message' (error 145 message), and 'warning'. If no error handler is set, die and warn will 146 be used. 147 148 sub myErrorHandler { 149 my( %parameters ) = @_; 150 if ( $parameters{'warning'} ) { 151 # This is a non-critical warning 152 warn "Warning: $parameters{'filename'}: $parameters{'message'}\n"; 153 } else { 154 # Critical error! 155 die "ERROR: $parameters{'filename'}: $parameters{'message'}\n"; 156 } 157 } 158 $wav -> set_error_handler( \&myErrorHandler ); 159 160--------------------------------------------------------------------- 161 Audio::Wav::Read 162 Module for reading Microsoft WAV files. 163--------------------------------------------------------------------- 164 165NAME 166 Audio::Wav::Read - Module for reading Microsoft WAV files. 167 168SYNOPSIS 169 use Audio::Wav; 170 171 my $wav = new Audio::Wav; 172 my $read = $wav -> read( 'filename.wav' ); 173OR 174 my $read = Audio::Wav -> read( 'filename.wav' ); 175 176 my $details = $read -> details(); 177 178DESCRIPTION 179 Reads Microsoft Wav files. 180 181SEE ALSO 182 Audio::Wav 183 184 Audio::Wav::Write 185 186NOTES 187 This module shouldn't be used directly, a blessed object can be returned 188 from Audio::Wav. 189 190METHODS 191 file_name 192 Returns the file name. 193 194 my $file = $read -> file_name(); 195 196 get_info 197 Returns information contained within the wav file. 198 199 my $info = $read -> get_info(); 200 201 Returns a reference to a hash containing; (for example, a file marked up 202 for use in Audio::Mix) 203 204 { 205 'keywords' => 'bpm:126 key:a', 206 'name' => 'Mission Venice', 207 'artist' => 'Nightmares on Wax' 208 }; 209 210 get_cues 211 Returns the cuepoints marked within the wav file. 212 213 my $cues = $read -> get_cues(); 214 215 Returns a reference to a hash containing; (for example, a file marked up 216 for use in Audio::Mix) (position is sample position) 217 218 { 219 1 => { 220 label => 'sig', 221 position => 764343, 222 note => 'first' 223 }, 224 2 => { 225 label => 'fade_in', 226 position => 1661774, 227 note => 'trig' 228 }, 229 3 => { 230 label => 'sig', 231 position => 18033735, 232 note => 'last' 233 }, 234 4 => { 235 label => 'fade_out', 236 position => 17145150, 237 note => 'trig' 238 }, 239 5 => { 240 label => 'end', 241 position => 18271676 242 } 243 } 244 245 read_raw 246 Reads raw packed bytes from the current audio data position in the file. 247 248 my $data = $self -> read_raw( $byte_length ); 249 250 read_raw_samples 251 Reads raw packed samples from the current audio data position in the 252 file. 253 254 my $data = $self -> read_raw_samples( $samples ); 255 256 read 257 Returns the current audio data position sample across all channels. 258 259 my @channels = $self -> read(); 260 261 Returns an array of unpacked samples. Each element is a channel i.e ( 262 left, right ). The numbers will be in the range; 263 264 where $samp_max = ( 2 ** bits_per_sample ) / 2 265 -$samp_max to +$samp_max 266 267 position 268 Returns the current audio data position (as byte offset). 269 270 my $byte_offset = $read -> position(); 271 272 position_samples 273 Returns the current audio data position (in samples). 274 275 my $samples = $read -> position_samples(); 276 277 move_to 278 Moves the current audio data position to byte offset. 279 280 $read -> move_to( $byte_offset ); 281 282 move_to_sample 283 Moves the current audio data position to sample offset. 284 285 $read -> move_to_sample( $sample_offset ); 286 287 length 288 Returns the number of bytes of audio data in the file. 289 290 my $audio_bytes = $read -> length(); 291 292 length_samples 293 Returns the number of samples of audio data in the file. 294 295 my $audio_samples = $read -> length_samples(); 296 297 length_seconds 298 Returns the number of seconds of audio data in the file. 299 300 my $audio_seconds = $read -> length_seconds(); 301 302 details 303 Returns a reference to a hash of lots of details about the file. Too 304 many to list here, try it with Data::Dumper..... 305 306 use Data::Dumper; 307 my $details = $read -> details(); 308 print Data::Dumper->Dump([ $details ]); 309 310 reread_length 311 Rereads the length of the file in case it is being written to as we are 312 reading it. 313 314 my $new_data_length = $read -> reread_length(); 315 316--------------------------------------------------------------------- 317 Audio::Wav::Write 318 Module for writing Microsoft WAV files. 319--------------------------------------------------------------------- 320 321NAME 322 Audio::Wav::Write - Module for writing Microsoft WAV files. 323 324SYNOPSIS 325 use Audio::Wav; 326 327 my $wav = new Audio::Wav; 328 329 my $sample_rate = 44100; 330 my $bits_sample = 16; 331 332 my $details = { 333 'bits_sample' => $bits_sample, 334 'sample_rate' => $sample_rate, 335 'channels' => 1, 336 # if you'd like this module not to use a write cache, uncomment the next line 337 #'no_cache' => 1, 338 339 }; 340 341 my $write = $wav -> write( 'testout.wav', $details ); 342 343 &add_sine( 200, 1 ); 344 345 sub add_sine { 346 my $hz = shift; 347 my $length = shift; 348 my $pi = ( 22 / 7 ) * 2; 349 $length *= $sample_rate; 350 my $max_no = ( 2 ** $bits_sample ) / 2; 351 for my $pos ( 0 .. $length ) { 352 $time = $pos / $sample_rate; 353 $time *= $hz; 354 my $val = sin $pi * $time; 355 my $samp = $val * $max_no; 356 $write -> write( $samp ); 357 } 358 } 359 360 $write -> finish(); 361 362DESCRIPTION 363 Currently only writes to a file. 364 365SEE ALSO 366 Audio::Wav 367 368 Audio::Wav::Read 369 370NOTES 371 This module shouldn't be used directly, a blessed object can be returned 372 from Audio::Wav. 373 374METHODS 375 finish 376 Finishes off & closes the current wav file. 377 378 $write -> finish(); 379 380 add_cue 381 Adds a cue point to the wav file. If $sample is undefined then the 382 position will be the current position (end of all data written so far). 383 384 # $byte_offset for 01 compatibility mode 385 $write -> add_cue( $sample, "label", "note" ); 386 387 set_sampler_info 388 All parameters are optional. 389 390 my %info = ( 391 'midi_pitch_fraction' => 0, 392 'smpte_format' => 0, 393 'smpte_offset' => 0, 394 'product' => 0, 395 'sample_period' => 0, 396 'manufacturer' => 0, 397 'sample_data' => 0, 398 'midi_unity_note' => 65, 399 ); 400 $write -> set_sampler_info( %info ); 401 402 add_sampler_loop 403 All parameters are optional except start & end. 404 405 my $length = $read -> length_samples(); 406 my( $third, $twothirds ) = map int( $length / $_ ), ( 3, 1.5 ); 407 my %loop = ( 408 'start' => $third, 409 'end' => $twothirds, 410 'fraction' => 0, 411 'type' => 0, 412 ); 413 $write -> add_sampler_loop( %loop ); 414 415 add_display 416 set_info 417 Sets information to be contained in the wav file. 418 419 $write -> set_info( 'artist' => 'Nightmares on Wax', 'name' => 'Mission Venice' ); 420 421 file_name 422 Returns the current filename. 423 424 my $file = $write -> file_name(); 425 426 write 427 Adds a sample to the current file. 428 429 $write -> write( @sample_channels ); 430 431 Each element in @sample_channels should be in the range of; 432 433 where $samp_max = ( 2 ** bits_per_sample ) / 2 434 -$samp_max to +$samp_max 435 436 write_raw 437 Adds some pre-packed data to the current file. 438 439 $write -> write_raw( $data, $data_length ); 440 441 Where; 442 443 $data is the packed data 444 $data_length (optional) is the length in bytes of the data 445 446 write_raw_samples 447 Adds some pre-packed data to the current file, returns number of samples 448 written. 449 450 $write -> write_raw_samples( $data, $data_length ); 451 452 Where; 453 454 $data is the packed data 455 $data_length (optional) is the length in bytes of the data 456 457--------------------------------------------------------------------- 458 AUTHORS 459--------------------------------------------------------------------- 460 461 Nick Peskett (see http://www.peskett.co.uk/ for contact details). 462 Brian Szymanski <ski-cpan@allafrica.com> (0.07-0.11) 463 Wolfram humann (pureperl 24 and 32 bit read support in 0.09) 464 Kurt George Gjerde <kurt.gjerde@media.uib.no>. (0.02-0.03) 465 466--------------------------------------------------------------------- 467 END 468--------------------------------------------------------------------- 469