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. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 8 | .. Documentations stolen from comments in file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 9 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 10 | **Source code:** :source:`Lib/wave.py` |
| 11 | |
| 12 | -------------- |
| 13 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 7f01a13 | 2009-09-16 15:58:14 +0000 | [diff] [blame] | 20 | .. function:: open(file, mode=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 21 | |
Georg Brandl | d97b7b5 | 2011-01-08 09:45:43 +0000 | [diff] [blame] | 22 | 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] | 23 | file-like object. *mode* can be: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
R David Murray | 536ffe1 | 2013-07-31 20:48:26 -0400 | [diff] [blame] | 25 | ``'rb'`` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | Read only mode. |
| 27 | |
R David Murray | 536ffe1 | 2013-07-31 20:48:26 -0400 | [diff] [blame] | 28 | ``'wb'`` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | Write only mode. |
| 30 | |
| 31 | Note that it does not allow read/write WAV files. |
| 32 | |
R David Murray | 536ffe1 | 2013-07-31 20:48:26 -0400 | [diff] [blame] | 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*. |
Georg Brandl | d97b7b5 | 2011-01-08 09:45:43 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | |
R David Murray | c91d5ee | 2013-07-31 13:46:08 -0400 | [diff] [blame] | 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 | |
Serhiy Storchaka | 7714ebb | 2013-11-16 13:04:00 +0200 | [diff] [blame] | 47 | .. versionchanged:: 3.4 |
| 48 | Added support for unseekable files. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 49 | |
| 50 | .. function:: openfp(file, mode) |
| 51 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 52 | A synonym for :func:`.open`, maintained for backwards compatibility. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
Brian Curtin | 9f914a0 | 2017-11-10 11:38:25 -0500 | [diff] [blame] | 54 | .. deprecated-removed:: 3.7 3.9 |
| 55 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 68 | Wave_read objects, as returned by :func:`.open`, have the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
| 70 | |
| 71 | .. method:: Wave_read.close() |
| 72 | |
Georg Brandl | d97b7b5 | 2011-01-08 09:45:43 +0000 | [diff] [blame] | 73 | Close the stream if it was opened by :mod:`wave`, and make the instance |
| 74 | unusable. This is called automatically on object collection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
R David Murray | 671cd32 | 2013-04-10 12:31:43 -0400 | [diff] [blame] | 110 | Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, |
| 111 | framerate, nframes, comptype, compname)``, equivalent to output of the |
| 112 | :meth:`get\*` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | |
| 114 | |
| 115 | .. method:: Wave_read.readframes(n) |
| 116 | |
R David Murray | 48de282 | 2016-08-23 20:43:56 -0400 | [diff] [blame] | 117 | Reads and returns at most *n* frames of audio, as a :class:`bytes` object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
R David Murray | 5d6240e | 2014-03-08 11:14:29 -0500 | [diff] [blame] | 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 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 168 | Wave_write objects, as returned by :func:`.open`, have the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | |
R David Murray | 5d6240e | 2014-03-08 11:14:29 -0500 | [diff] [blame] | 170 | .. versionchanged:: 3.4 |
| 171 | Added support for unseekable files. |
| 172 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 173 | |
| 174 | .. method:: Wave_write.close() |
| 175 | |
Georg Brandl | d97b7b5 | 2011-01-08 09:45:43 +0000 | [diff] [blame] | 176 | Make sure *nframes* is correct, and close the file if it was opened by |
R David Murray | 5d6240e | 2014-03-08 11:14:29 -0500 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Mark Dickinson | 64a38c0 | 2010-08-28 17:22:16 +0000 | [diff] [blame] | 196 | .. versionchanged:: 3.2 |
| 197 | A non-integral input to this method is rounded to the nearest |
| 198 | integer. |
| 199 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 200 | |
| 201 | .. method:: Wave_write.setnframes(n) |
| 202 | |
R David Murray | 5d6240e | 2014-03-08 11:14:29 -0500 | [diff] [blame] | 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). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Serhiy Storchaka | 452bab4 | 2013-11-16 14:01:31 +0200 | [diff] [blame] | 231 | .. versionchanged:: 3.4 |
R David Murray | cbf479a | 2014-03-08 11:46:05 -0500 | [diff] [blame] | 232 | Any :term:`bytes-like object` is now accepted. |
Serhiy Storchaka | 452bab4 | 2013-11-16 14:01:31 +0200 | [diff] [blame] | 233 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 234 | |
| 235 | .. method:: Wave_write.writeframes(data) |
| 236 | |
R David Murray | 5d6240e | 2014-03-08 11:14:29 -0500 | [diff] [blame] | 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*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 241 | |
Serhiy Storchaka | 452bab4 | 2013-11-16 14:01:31 +0200 | [diff] [blame] | 242 | .. versionchanged:: 3.4 |
R David Murray | cbf479a | 2014-03-08 11:46:05 -0500 | [diff] [blame] | 243 | Any :term:`bytes-like object` is now accepted. |
Serhiy Storchaka | 452bab4 | 2013-11-16 14:01:31 +0200 | [diff] [blame] | 244 | |
Georg Brandl | d97b7b5 | 2011-01-08 09:45:43 +0000 | [diff] [blame] | 245 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |