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