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