Debian Codegraph @

Doc/library/wave.rst

raw
1 :mod:`!wave` --- Read and write WAV files
2 =========================================
3
4 .. module:: wave
5 :synopsis: Provide an interface to the WAV sound format.
6
7 .. sectionauthor:: Moshe Zadka <[email protected]>
8 .. Documentations stolen from comments in file.
9
10 **Source code:** :source:`Lib/wave.py`
11
12 --------------
13
14 The :mod:`!wave` module provides a convenient interface to the Waveform Audio
15 "WAVE" (or "WAV") file format. Only uncompressed PCM encoded wave files are
16 supported.
17
18 .. versionchanged:: 3.12
19
20 Support for ``WAVE_FORMAT_EXTENSIBLE`` headers was added, provided that the
21 extended format is ``KSDATAFORMAT_SUBTYPE_PCM``.
22
23 The :mod:`!wave` module defines the following function and exception:
24
25
26 .. function:: open(file, mode=None)
27
28 If *file* is a string, open the file by that name, otherwise treat it as a
29 file-like object. *mode* can be:
30
31 ``'rb'``
32 Read only mode.
33
34 ``'wb'``
35 Write only mode.
36
37 Note that it does not allow read/write WAV files.
38
39 A *mode* of ``'rb'`` returns a :class:`Wave_read` object, while a *mode* of
40 ``'wb'`` returns a :class:`Wave_write` object. If *mode* is omitted and a
41 file-like object is passed as *file*, ``file.mode`` is used as the default
42 value for *mode*.
43
44 If you pass in a file-like object, the wave object will not close it when its
45 ``close()`` method is called; it is the caller's responsibility to close
46 the file object.
47
48 The :func:`.open` function may be used in a :keyword:`with` statement. When
49 the :keyword:`!with` block completes, the :meth:`Wave_read.close` or
50 :meth:`Wave_write.close` method is called.
51
52 .. versionchanged:: 3.4
53 Added support for unseekable files.
54
55 .. exception:: Error
56
57 An error raised when something is impossible because it violates the WAV
58 specification or hits an implementation deficiency.
59
60
61 .. _wave-read-objects:
62
63 Wave_read Objects
64 -----------------
65
66 .. class:: Wave_read
67
68 Read a WAV file.
69
70 Wave_read objects, as returned by :func:`.open`, have the following methods:
71
72
73 .. method:: close()
74
75 Close the stream if it was opened by :mod:`!wave`, and make the instance
76 unusable. This is called automatically on object collection.
77
78
79 .. method:: getnchannels()
80
81 Returns number of audio channels (``1`` for mono, ``2`` for stereo).
82
83
84 .. method:: getsampwidth()
85
86 Returns sample width in bytes.
87
88
89 .. method:: getframerate()
90
91 Returns sampling frequency.
92
93
94 .. method:: getnframes()
95
96 Returns number of audio frames.
97
98
99 .. method:: getcomptype()
100
101 Returns compression type (``'NONE'`` is the only supported type).
102
103
104 .. method:: getcompname()
105
106 Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
107 parallels ``'NONE'``.
108
109
110 .. method:: getparams()
111
112 Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth,
113 framerate, nframes, comptype, compname)``, equivalent to output of the
114 ``get*()`` methods.
115
116
117 .. method:: readframes(n)
118
119 Reads and returns at most *n* frames of audio, as a :class:`bytes` object.
120
121
122 .. method:: rewind()
123
124 Rewind the file pointer to the beginning of the audio stream.
125
126 The following two methods are defined for compatibility with the old :mod:`!aifc`
127 module, and don't do anything interesting.
128
129
130 .. method:: getmarkers()
131
132 Returns ``None``.
133
134 .. deprecated-removed:: 3.13 3.15
135 The method only existed for compatibility with the :mod:`!aifc` module
136 which has been removed in Python 3.13.
137
138
139 .. method:: getmark(id)
140
141 Raise an error.
142
143 .. deprecated-removed:: 3.13 3.15
144 The method only existed for compatibility with the :mod:`!aifc` module
145 which has been removed in Python 3.13.
146
147 The following two methods define a term "position" which is compatible between
148 them, and is otherwise implementation dependent.
149
150
151 .. method:: setpos(pos)
152
153 Set the file pointer to the specified position.
154
155
156 .. method:: tell()
157
158 Return current file pointer position.
159
160
161 .. _wave-write-objects:
162
163 Wave_write Objects
164 ------------------
165
166 .. class:: Wave_write
167
168 Write a WAV file.
169
170 Wave_write objects, as returned by :func:`.open`.
171
172 For seekable output streams, the ``wave`` header will automatically be updated
173 to reflect the number of frames actually written. For unseekable streams, the
174 *nframes* value must be accurate when the first frame data is written. An
175 accurate *nframes* value can be achieved either by calling
176 :meth:`setnframes` or :meth:`setparams` with the number
177 of frames that will be written before :meth:`close` is called and
178 then using :meth:`writeframesraw` to write the frame data, or by
179 calling :meth:`writeframes` with all of the frame data to be
180 written. In the latter case :meth:`writeframes` will calculate
181 the number of frames in the data and set *nframes* accordingly before writing
182 the frame data.
183
184 .. versionchanged:: 3.4
185 Added support for unseekable files.
186
187 Wave_write objects have the following methods:
188
189 .. method:: close()
190
191 Make sure *nframes* is correct, and close the file if it was opened by
192 :mod:`!wave`. This method is called upon object collection. It will raise
193 an exception if the output stream is not seekable and *nframes* does not
194 match the number of frames actually written.
195
196
197 .. method:: setnchannels(n)
198
199 Set the number of channels.
200
201
202 .. method:: getnchannels()
203
204 Return the number of channels.
205
206
207 .. method:: setsampwidth(n)
208
209 Set the sample width to *n* bytes.
210
211
212 .. method:: getsampwidth()
213
214 Return the sample width in bytes.
215
216
217 .. method:: setframerate(n)
218
219 Set the frame rate to *n*.
220
221 .. versionchanged:: 3.2
222 A non-integral input to this method is rounded to the nearest
223 integer.
224
225
226 .. method:: getframerate()
227
228 Return the frame rate.
229
230
231 .. method:: setnframes(n)
232
233 Set the number of frames to *n*. This will be changed later if the number
234 of frames actually written is different (this update attempt will
235 raise an error if the output stream is not seekable).
236
237
238 .. method:: getnframes()
239
240 Return the number of audio frames written so far.
241
242
243 .. method:: setcomptype(type, name)
244
245 Set the compression type and description. At the moment, only compression type
246 ``NONE`` is supported, meaning no compression.
247
248
249 .. method:: getcomptype()
250
251 Return the compression type (``'NONE'``).
252
253
254 .. method:: getcompname()
255
256 Return the human-readable compression type name.
257
258
259 .. method:: setparams(tuple)
260
261 The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
262 compname)``, with values valid for the ``set*()`` methods. Sets all
263 parameters.
264
265
266 .. method:: getparams()
267
268 Return a :func:`~collections.namedtuple`
269 ``(nchannels, sampwidth, framerate, nframes, comptype, compname)``
270 containing the current output parameters.
271
272
273 .. method:: tell()
274
275 Return current position in the file, with the same disclaimer for the
276 :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
277
278
279 .. method:: writeframesraw(data)
280
281 Write audio frames, without correcting *nframes*.
282
283 .. versionchanged:: 3.4
284 Any :term:`bytes-like object` is now accepted.
285
286
287 .. method:: writeframes(data)
288
289 Write audio frames and make sure *nframes* is correct. It will raise an
290 error if the output stream is not seekable and the total number of frames
291 that have been written after *data* has been written does not match the
292 previously set value for *nframes*.
293
294 .. versionchanged:: 3.4
295 Any :term:`bytes-like object` is now accepted.
296
297 Note that it is invalid to set any parameters after calling :meth:`writeframes`
298 or :meth:`writeframesraw`, and any attempt to do so will raise
299 :exc:`wave.Error`.