source: python/trunk/Lib/wave.py@ 779

Last change on this file since 779 was 391, checked in by dmik, 11 years ago

python: Merge vendor 2.7.6 to trunk.

  • Property svn:eol-style set to native
File size: 17.8 KB
Line 
1"""Stuff to parse WAVE files.
2
3Usage.
4
5Reading WAVE files:
6 f = wave.open(file, 'r')
7where file is either the name of a file or an open file pointer.
8The open file pointer must have methods read(), seek(), and close().
9When the setpos() and rewind() methods are not used, the seek()
10method is not necessary.
11
12This returns an instance of a class with the following public methods:
13 getnchannels() -- returns number of audio channels (1 for
14 mono, 2 for stereo)
15 getsampwidth() -- returns sample width in bytes
16 getframerate() -- returns sampling frequency
17 getnframes() -- returns number of audio frames
18 getcomptype() -- returns compression type ('NONE' for linear samples)
19 getcompname() -- returns human-readable version of
20 compression type ('not compressed' linear samples)
21 getparams() -- returns a tuple consisting of all of the
22 above in the above order
23 getmarkers() -- returns None (for compatibility with the
24 aifc module)
25 getmark(id) -- raises an error since the mark does not
26 exist (for compatibility with the aifc module)
27 readframes(n) -- returns at most n frames of audio
28 rewind() -- rewind to the beginning of the audio stream
29 setpos(pos) -- seek to the specified position
30 tell() -- return the current position
31 close() -- close the instance (make it unusable)
32The position returned by tell() and the position given to setpos()
33are compatible and have nothing to do with the actual position in the
34file.
35The close() method is called automatically when the class instance
36is destroyed.
37
38Writing WAVE files:
39 f = wave.open(file, 'w')
40where file is either the name of a file or an open file pointer.
41The open file pointer must have methods write(), tell(), seek(), and
42close().
43
44This returns an instance of a class with the following public methods:
45 setnchannels(n) -- set the number of channels
46 setsampwidth(n) -- set the sample width
47 setframerate(n) -- set the frame rate
48 setnframes(n) -- set the number of frames
49 setcomptype(type, name)
50 -- set the compression type and the
51 human-readable compression type
52 setparams(tuple)
53 -- set all parameters at once
54 tell() -- return current position in output file
55 writeframesraw(data)
56 -- write audio frames without pathing up the
57 file header
58 writeframes(data)
59 -- write audio frames and patch up the file header
60 close() -- patch up the file header and close the
61 output file
62You should set the parameters before the first writeframesraw or
63writeframes. The total number of frames does not need to be set,
64but when it is set to the correct value, the header does not have to
65be patched up.
66It is best to first set all parameters, perhaps possibly the
67compression type, and then write audio frames using writeframesraw.
68When all frames have been written, either call writeframes('') or
69close() to patch up the sizes in the header.
70The close() method is called automatically when the class instance
71is destroyed.
72"""
73
74import __builtin__
75
76__all__ = ["open", "openfp", "Error"]
77
78class Error(Exception):
79 pass
80
81WAVE_FORMAT_PCM = 0x0001
82
83_array_fmts = None, 'b', 'h', None, 'i'
84
85# Determine endian-ness
86import struct
87if struct.pack("h", 1) == "\000\001":
88 big_endian = 1
89else:
90 big_endian = 0
91
92from chunk import Chunk
93
94class Wave_read:
95 """Variables used in this class:
96
97 These variables are available to the user though appropriate
98 methods of this class:
99 _file -- the open file with methods read(), close(), and seek()
100 set through the __init__() method
101 _nchannels -- the number of audio channels
102 available through the getnchannels() method
103 _nframes -- the number of audio frames
104 available through the getnframes() method
105 _sampwidth -- the number of bytes per audio sample
106 available through the getsampwidth() method
107 _framerate -- the sampling frequency
108 available through the getframerate() method
109 _comptype -- the AIFF-C compression type ('NONE' if AIFF)
110 available through the getcomptype() method
111 _compname -- the human-readable AIFF-C compression type
112 available through the getcomptype() method
113 _soundpos -- the position in the audio stream
114 available through the tell() method, set through the
115 setpos() method
116
117 These variables are used internally only:
118 _fmt_chunk_read -- 1 iff the FMT chunk has been read
119 _data_seek_needed -- 1 iff positioned correctly in audio
120 file for readframes()
121 _data_chunk -- instantiation of a chunk class for the DATA chunk
122 _framesize -- size of one frame in the file
123 """
124
125 def initfp(self, file):
126 self._convert = None
127 self._soundpos = 0
128 self._file = Chunk(file, bigendian = 0)
129 if self._file.getname() != 'RIFF':
130 raise Error, 'file does not start with RIFF id'
131 if self._file.read(4) != 'WAVE':
132 raise Error, 'not a WAVE file'
133 self._fmt_chunk_read = 0
134 self._data_chunk = None
135 while 1:
136 self._data_seek_needed = 1
137 try:
138 chunk = Chunk(self._file, bigendian = 0)
139 except EOFError:
140 break
141 chunkname = chunk.getname()
142 if chunkname == 'fmt ':
143 self._read_fmt_chunk(chunk)
144 self._fmt_chunk_read = 1
145 elif chunkname == 'data':
146 if not self._fmt_chunk_read:
147 raise Error, 'data chunk before fmt chunk'
148 self._data_chunk = chunk
149 self._nframes = chunk.chunksize // self._framesize
150 self._data_seek_needed = 0
151 break
152 chunk.skip()
153 if not self._fmt_chunk_read or not self._data_chunk:
154 raise Error, 'fmt chunk and/or data chunk missing'
155
156 def __init__(self, f):
157 self._i_opened_the_file = None
158 if isinstance(f, basestring):
159 f = __builtin__.open(f, 'rb')
160 self._i_opened_the_file = f
161 # else, assume it is an open file object already
162 try:
163 self.initfp(f)
164 except:
165 if self._i_opened_the_file:
166 f.close()
167 raise
168
169 def __del__(self):
170 self.close()
171 #
172 # User visible methods.
173 #
174 def getfp(self):
175 return self._file
176
177 def rewind(self):
178 self._data_seek_needed = 1
179 self._soundpos = 0
180
181 def close(self):
182 if self._i_opened_the_file:
183 self._i_opened_the_file.close()
184 self._i_opened_the_file = None
185 self._file = None
186
187 def tell(self):
188 return self._soundpos
189
190 def getnchannels(self):
191 return self._nchannels
192
193 def getnframes(self):
194 return self._nframes
195
196 def getsampwidth(self):
197 return self._sampwidth
198
199 def getframerate(self):
200 return self._framerate
201
202 def getcomptype(self):
203 return self._comptype
204
205 def getcompname(self):
206 return self._compname
207
208 def getparams(self):
209 return self.getnchannels(), self.getsampwidth(), \
210 self.getframerate(), self.getnframes(), \
211 self.getcomptype(), self.getcompname()
212
213 def getmarkers(self):
214 return None
215
216 def getmark(self, id):
217 raise Error, 'no marks'
218
219 def setpos(self, pos):
220 if pos < 0 or pos > self._nframes:
221 raise Error, 'position not in range'
222 self._soundpos = pos
223 self._data_seek_needed = 1
224
225 def readframes(self, nframes):
226 if self._data_seek_needed:
227 self._data_chunk.seek(0, 0)
228 pos = self._soundpos * self._framesize
229 if pos:
230 self._data_chunk.seek(pos, 0)
231 self._data_seek_needed = 0
232 if nframes == 0:
233 return ''
234 if self._sampwidth > 1 and big_endian:
235 # unfortunately the fromfile() method does not take
236 # something that only looks like a file object, so
237 # we have to reach into the innards of the chunk object
238 import array
239 chunk = self._data_chunk
240 data = array.array(_array_fmts[self._sampwidth])
241 assert data.itemsize == self._sampwidth
242 nitems = nframes * self._nchannels
243 if nitems * self._sampwidth > chunk.chunksize - chunk.size_read:
244 nitems = (chunk.chunksize - chunk.size_read) / self._sampwidth
245 data.fromfile(chunk.file.file, nitems)
246 # "tell" data chunk how much was read
247 chunk.size_read = chunk.size_read + nitems * self._sampwidth
248 # do the same for the outermost chunk
249 chunk = chunk.file
250 chunk.size_read = chunk.size_read + nitems * self._sampwidth
251 data.byteswap()
252 data = data.tostring()
253 else:
254 data = self._data_chunk.read(nframes * self._framesize)
255 if self._convert and data:
256 data = self._convert(data)
257 self._soundpos = self._soundpos + len(data) // (self._nchannels * self._sampwidth)
258 return data
259
260 #
261 # Internal methods.
262 #
263
264 def _read_fmt_chunk(self, chunk):
265 wFormatTag, self._nchannels, self._framerate, dwAvgBytesPerSec, wBlockAlign = struct.unpack('<HHLLH', chunk.read(14))
266 if wFormatTag == WAVE_FORMAT_PCM:
267 sampwidth = struct.unpack('<H', chunk.read(2))[0]
268 self._sampwidth = (sampwidth + 7) // 8
269 else:
270 raise Error, 'unknown format: %r' % (wFormatTag,)
271 self._framesize = self._nchannels * self._sampwidth
272 self._comptype = 'NONE'
273 self._compname = 'not compressed'
274
275class Wave_write:
276 """Variables used in this class:
277
278 These variables are user settable through appropriate methods
279 of this class:
280 _file -- the open file with methods write(), close(), tell(), seek()
281 set through the __init__() method
282 _comptype -- the AIFF-C compression type ('NONE' in AIFF)
283 set through the setcomptype() or setparams() method
284 _compname -- the human-readable AIFF-C compression type
285 set through the setcomptype() or setparams() method
286 _nchannels -- the number of audio channels
287 set through the setnchannels() or setparams() method
288 _sampwidth -- the number of bytes per audio sample
289 set through the setsampwidth() or setparams() method
290 _framerate -- the sampling frequency
291 set through the setframerate() or setparams() method
292 _nframes -- the number of audio frames written to the header
293 set through the setnframes() or setparams() method
294
295 These variables are used internally only:
296 _datalength -- the size of the audio samples written to the header
297 _nframeswritten -- the number of frames actually written
298 _datawritten -- the size of the audio samples actually written
299 """
300
301 def __init__(self, f):
302 self._i_opened_the_file = None
303 if isinstance(f, basestring):
304 f = __builtin__.open(f, 'wb')
305 self._i_opened_the_file = f
306 try:
307 self.initfp(f)
308 except:
309 if self._i_opened_the_file:
310 f.close()
311 raise
312
313 def initfp(self, file):
314 self._file = file
315 self._convert = None
316 self._nchannels = 0
317 self._sampwidth = 0
318 self._framerate = 0
319 self._nframes = 0
320 self._nframeswritten = 0
321 self._datawritten = 0
322 self._datalength = 0
323 self._headerwritten = False
324
325 def __del__(self):
326 self.close()
327
328 #
329 # User visible methods.
330 #
331 def setnchannels(self, nchannels):
332 if self._datawritten:
333 raise Error, 'cannot change parameters after starting to write'
334 if nchannels < 1:
335 raise Error, 'bad # of channels'
336 self._nchannels = nchannels
337
338 def getnchannels(self):
339 if not self._nchannels:
340 raise Error, 'number of channels not set'
341 return self._nchannels
342
343 def setsampwidth(self, sampwidth):
344 if self._datawritten:
345 raise Error, 'cannot change parameters after starting to write'
346 if sampwidth < 1 or sampwidth > 4:
347 raise Error, 'bad sample width'
348 self._sampwidth = sampwidth
349
350 def getsampwidth(self):
351 if not self._sampwidth:
352 raise Error, 'sample width not set'
353 return self._sampwidth
354
355 def setframerate(self, framerate):
356 if self._datawritten:
357 raise Error, 'cannot change parameters after starting to write'
358 if framerate <= 0:
359 raise Error, 'bad frame rate'
360 self._framerate = framerate
361
362 def getframerate(self):
363 if not self._framerate:
364 raise Error, 'frame rate not set'
365 return self._framerate
366
367 def setnframes(self, nframes):
368 if self._datawritten:
369 raise Error, 'cannot change parameters after starting to write'
370 self._nframes = nframes
371
372 def getnframes(self):
373 return self._nframeswritten
374
375 def setcomptype(self, comptype, compname):
376 if self._datawritten:
377 raise Error, 'cannot change parameters after starting to write'
378 if comptype not in ('NONE',):
379 raise Error, 'unsupported compression type'
380 self._comptype = comptype
381 self._compname = compname
382
383 def getcomptype(self):
384 return self._comptype
385
386 def getcompname(self):
387 return self._compname
388
389 def setparams(self, params):
390 nchannels, sampwidth, framerate, nframes, comptype, compname = params
391 if self._datawritten:
392 raise Error, 'cannot change parameters after starting to write'
393 self.setnchannels(nchannels)
394 self.setsampwidth(sampwidth)
395 self.setframerate(framerate)
396 self.setnframes(nframes)
397 self.setcomptype(comptype, compname)
398
399 def getparams(self):
400 if not self._nchannels or not self._sampwidth or not self._framerate:
401 raise Error, 'not all parameters set'
402 return self._nchannels, self._sampwidth, self._framerate, \
403 self._nframes, self._comptype, self._compname
404
405 def setmark(self, id, pos, name):
406 raise Error, 'setmark() not supported'
407
408 def getmark(self, id):
409 raise Error, 'no marks'
410
411 def getmarkers(self):
412 return None
413
414 def tell(self):
415 return self._nframeswritten
416
417 def writeframesraw(self, data):
418 self._ensure_header_written(len(data))
419 nframes = len(data) // (self._sampwidth * self._nchannels)
420 if self._convert:
421 data = self._convert(data)
422 if self._sampwidth > 1 and big_endian:
423 import array
424 data = array.array(_array_fmts[self._sampwidth], data)
425 assert data.itemsize == self._sampwidth
426 data.byteswap()
427 data.tofile(self._file)
428 self._datawritten = self._datawritten + len(data) * self._sampwidth
429 else:
430 self._file.write(data)
431 self._datawritten = self._datawritten + len(data)
432 self._nframeswritten = self._nframeswritten + nframes
433
434 def writeframes(self, data):
435 self.writeframesraw(data)
436 if self._datalength != self._datawritten:
437 self._patchheader()
438
439 def close(self):
440 if self._file:
441 try:
442 self._ensure_header_written(0)
443 if self._datalength != self._datawritten:
444 self._patchheader()
445 self._file.flush()
446 finally:
447 self._file = None
448 if self._i_opened_the_file:
449 self._i_opened_the_file.close()
450 self._i_opened_the_file = None
451
452 #
453 # Internal methods.
454 #
455
456 def _ensure_header_written(self, datasize):
457 if not self._headerwritten:
458 if not self._nchannels:
459 raise Error, '# channels not specified'
460 if not self._sampwidth:
461 raise Error, 'sample width not specified'
462 if not self._framerate:
463 raise Error, 'sampling rate not specified'
464 self._write_header(datasize)
465
466 def _write_header(self, initlength):
467 assert not self._headerwritten
468 self._file.write('RIFF')
469 if not self._nframes:
470 self._nframes = initlength / (self._nchannels * self._sampwidth)
471 self._datalength = self._nframes * self._nchannels * self._sampwidth
472 self._form_length_pos = self._file.tell()
473 self._file.write(struct.pack('<L4s4sLHHLLHH4s',
474 36 + self._datalength, 'WAVE', 'fmt ', 16,
475 WAVE_FORMAT_PCM, self._nchannels, self._framerate,
476 self._nchannels * self._framerate * self._sampwidth,
477 self._nchannels * self._sampwidth,
478 self._sampwidth * 8, 'data'))
479 self._data_length_pos = self._file.tell()
480 self._file.write(struct.pack('<L', self._datalength))
481 self._headerwritten = True
482
483 def _patchheader(self):
484 assert self._headerwritten
485 if self._datawritten == self._datalength:
486 return
487 curpos = self._file.tell()
488 self._file.seek(self._form_length_pos, 0)
489 self._file.write(struct.pack('<L', 36 + self._datawritten))
490 self._file.seek(self._data_length_pos, 0)
491 self._file.write(struct.pack('<L', self._datawritten))
492 self._file.seek(curpos, 0)
493 self._datalength = self._datawritten
494
495def open(f, mode=None):
496 if mode is None:
497 if hasattr(f, 'mode'):
498 mode = f.mode
499 else:
500 mode = 'rb'
501 if mode in ('r', 'rb'):
502 return Wave_read(f)
503 elif mode in ('w', 'wb'):
504 return Wave_write(f)
505 else:
506 raise Error, "mode must be 'r', 'rb', 'w', or 'wb'"
507
508openfp = open # B/W compatibility
Note: See TracBrowser for help on using the repository browser.