| 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`. |