Python code coverage for Lib/wave.py

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