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 <moshez@zadka.site.co.il> 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. Only uncompressed PCM encoded wave files are 16supported. 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 23The :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 63Wave_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 163Wave_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:: setsampwidth(n) 203 204 Set the sample width to *n* bytes. 205 206 207 .. method:: setframerate(n) 208 209 Set the frame rate to *n*. 210 211 .. versionchanged:: 3.2 212 A non-integral input to this method is rounded to the nearest 213 integer. 214 215 216 .. method:: setnframes(n) 217 218 Set the number of frames to *n*. This will be changed later if the number 219 of frames actually written is different (this update attempt will 220 raise an error if the output stream is not seekable). 221 222 223 .. method:: setcomptype(type, name) 224 225 Set the compression type and description. At the moment, only compression type 226 ``NONE`` is supported, meaning no compression. 227 228 229 .. method:: setparams(tuple) 230 231 The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype, 232 compname)``, with values valid for the ``set*()`` methods. Sets all 233 parameters. 234 235 236 .. method:: tell() 237 238 Return current position in the file, with the same disclaimer for the 239 :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods. 240 241 242 .. method:: writeframesraw(data) 243 244 Write audio frames, without correcting *nframes*. 245 246 .. versionchanged:: 3.4 247 Any :term:`bytes-like object` is now accepted. 248 249 250 .. method:: writeframes(data) 251 252 Write audio frames and make sure *nframes* is correct. It will raise an 253 error if the output stream is not seekable and the total number of frames 254 that have been written after *data* has been written does not match the 255 previously set value for *nframes*. 256 257 .. versionchanged:: 3.4 258 Any :term:`bytes-like object` is now accepted. 259 260 Note that it is invalid to set any parameters after calling :meth:`writeframes` 261 or :meth:`writeframesraw`, and any attempt to do so will raise 262 :exc:`wave.Error`. 263