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