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 | |
| 9 | The :mod:`wave` module provides a convenient interface to the WAV sound format. |
| 10 | It does not support compression/decompression, but it does support mono/stereo. |
| 11 | |
| 12 | The :mod:`wave` module defines the following function and exception: |
| 13 | |
| 14 | |
Georg Brandl | b044b2a | 2009-09-16 16:05:59 +0000 | [diff] [blame] | 15 | .. function:: open(file, mode=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Georg Brandl | ec78b8b | 2011-01-09 07:59:02 +0000 | [diff] [blame] | 17 | If *file* is a string, open the file by that name, otherwise treat it as a |
| 18 | seekable file-like object. *mode* can be any of |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | |
| 20 | ``'r'``, ``'rb'`` |
| 21 | Read only mode. |
| 22 | |
| 23 | ``'w'``, ``'wb'`` |
| 24 | Write only mode. |
| 25 | |
| 26 | Note that it does not allow read/write WAV files. |
| 27 | |
| 28 | A *mode* of ``'r'`` or ``'rb'`` returns a :class:`Wave_read` object, while a |
Georg Brandl | ec78b8b | 2011-01-09 07:59:02 +0000 | [diff] [blame] | 29 | *mode* of ``'w'`` or ``'wb'`` returns a :class:`Wave_write` object. If |
| 30 | *mode* is omitted and a file-like object is passed as *file*, ``file.mode`` |
| 31 | is used as the default value for *mode* (the ``'b'`` flag is still added if |
| 32 | necessary). |
| 33 | |
| 34 | If you pass in a file-like object, the wave object will not close it when its |
| 35 | :meth:`close` method is called; it is the caller's responsibility to close |
| 36 | the file object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 37 | |
| 38 | |
| 39 | .. function:: openfp(file, mode) |
| 40 | |
Georg Brandl | c5605df | 2009-08-13 08:26:44 +0000 | [diff] [blame] | 41 | A synonym for :func:`.open`, maintained for backwards compatibility. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | |
| 43 | |
| 44 | .. exception:: Error |
| 45 | |
| 46 | An error raised when something is impossible because it violates the WAV |
| 47 | specification or hits an implementation deficiency. |
| 48 | |
| 49 | |
| 50 | .. _wave-read-objects: |
| 51 | |
| 52 | Wave_read Objects |
| 53 | ----------------- |
| 54 | |
Georg Brandl | c5605df | 2009-08-13 08:26:44 +0000 | [diff] [blame] | 55 | Wave_read objects, as returned by :func:`.open`, have the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
| 57 | |
| 58 | .. method:: Wave_read.close() |
| 59 | |
Georg Brandl | ec78b8b | 2011-01-09 07:59:02 +0000 | [diff] [blame] | 60 | Close the stream if it was opened by :mod:`wave`, and make the instance |
| 61 | unusable. This is called automatically on object collection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | |
| 63 | |
| 64 | .. method:: Wave_read.getnchannels() |
| 65 | |
| 66 | Returns number of audio channels (``1`` for mono, ``2`` for stereo). |
| 67 | |
| 68 | |
| 69 | .. method:: Wave_read.getsampwidth() |
| 70 | |
| 71 | Returns sample width in bytes. |
| 72 | |
| 73 | |
| 74 | .. method:: Wave_read.getframerate() |
| 75 | |
| 76 | Returns sampling frequency. |
| 77 | |
| 78 | |
| 79 | .. method:: Wave_read.getnframes() |
| 80 | |
| 81 | Returns number of audio frames. |
| 82 | |
| 83 | |
| 84 | .. method:: Wave_read.getcomptype() |
| 85 | |
| 86 | Returns compression type (``'NONE'`` is the only supported type). |
| 87 | |
| 88 | |
| 89 | .. method:: Wave_read.getcompname() |
| 90 | |
| 91 | Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'`` |
| 92 | parallels ``'NONE'``. |
| 93 | |
| 94 | |
| 95 | .. method:: Wave_read.getparams() |
| 96 | |
| 97 | Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype, |
| 98 | compname)``, equivalent to output of the :meth:`get\*` methods. |
| 99 | |
| 100 | |
| 101 | .. method:: Wave_read.readframes(n) |
| 102 | |
| 103 | Reads and returns at most *n* frames of audio, as a string of bytes. |
| 104 | |
| 105 | |
| 106 | .. method:: Wave_read.rewind() |
| 107 | |
| 108 | Rewind the file pointer to the beginning of the audio stream. |
| 109 | |
| 110 | The following two methods are defined for compatibility with the :mod:`aifc` |
| 111 | module, and don't do anything interesting. |
| 112 | |
| 113 | |
| 114 | .. method:: Wave_read.getmarkers() |
| 115 | |
| 116 | Returns ``None``. |
| 117 | |
| 118 | |
| 119 | .. method:: Wave_read.getmark(id) |
| 120 | |
| 121 | Raise an error. |
| 122 | |
| 123 | The following two methods define a term "position" which is compatible between |
| 124 | them, and is otherwise implementation dependent. |
| 125 | |
| 126 | |
| 127 | .. method:: Wave_read.setpos(pos) |
| 128 | |
| 129 | Set the file pointer to the specified position. |
| 130 | |
| 131 | |
| 132 | .. method:: Wave_read.tell() |
| 133 | |
| 134 | Return current file pointer position. |
| 135 | |
| 136 | |
| 137 | .. _wave-write-objects: |
| 138 | |
| 139 | Wave_write Objects |
| 140 | ------------------ |
| 141 | |
Georg Brandl | c5605df | 2009-08-13 08:26:44 +0000 | [diff] [blame] | 142 | Wave_write objects, as returned by :func:`.open`, have the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
| 144 | |
| 145 | .. method:: Wave_write.close() |
| 146 | |
Georg Brandl | ec78b8b | 2011-01-09 07:59:02 +0000 | [diff] [blame] | 147 | Make sure *nframes* is correct, and close the file if it was opened by |
| 148 | :mod:`wave`. This method is called upon object collection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 149 | |
| 150 | |
| 151 | .. method:: Wave_write.setnchannels(n) |
| 152 | |
| 153 | Set the number of channels. |
| 154 | |
| 155 | |
| 156 | .. method:: Wave_write.setsampwidth(n) |
| 157 | |
| 158 | Set the sample width to *n* bytes. |
| 159 | |
| 160 | |
| 161 | .. method:: Wave_write.setframerate(n) |
| 162 | |
| 163 | Set the frame rate to *n*. |
| 164 | |
| 165 | |
| 166 | .. method:: Wave_write.setnframes(n) |
| 167 | |
| 168 | Set the number of frames to *n*. This will be changed later if more frames are |
| 169 | written. |
| 170 | |
| 171 | |
| 172 | .. method:: Wave_write.setcomptype(type, name) |
| 173 | |
| 174 | Set the compression type and description. At the moment, only compression type |
| 175 | ``NONE`` is supported, meaning no compression. |
| 176 | |
| 177 | |
| 178 | .. method:: Wave_write.setparams(tuple) |
| 179 | |
| 180 | The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype, |
| 181 | compname)``, with values valid for the :meth:`set\*` methods. Sets all |
| 182 | parameters. |
| 183 | |
| 184 | |
| 185 | .. method:: Wave_write.tell() |
| 186 | |
| 187 | Return current position in the file, with the same disclaimer for the |
| 188 | :meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods. |
| 189 | |
| 190 | |
| 191 | .. method:: Wave_write.writeframesraw(data) |
| 192 | |
| 193 | Write audio frames, without correcting *nframes*. |
| 194 | |
| 195 | |
| 196 | .. method:: Wave_write.writeframes(data) |
| 197 | |
| 198 | Write audio frames and make sure *nframes* is correct. |
| 199 | |
Georg Brandl | ec78b8b | 2011-01-09 07:59:02 +0000 | [diff] [blame] | 200 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 201 | Note that it is invalid to set any parameters after calling :meth:`writeframes` |
| 202 | or :meth:`writeframesraw`, and any attempt to do so will raise |
| 203 | :exc:`wave.Error`. |
| 204 | |