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