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