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 (a] zadka.site.co.il> 7 .. Documentations stolen from comments in file. 8 9 **Source code:** :source:`Lib/wave.py` 10 11 -------------- 12 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 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 56 Wave_read Objects 57 ----------------- 58 59 Wave_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 114 The following two methods are defined for compatibility with the :mod:`aifc` 115 module, 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 127 The following two methods define a term "position" which is compatible between 128 them, 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 143 Wave_write Objects 144 ------------------ 145 146 Wave_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 205 Note that it is invalid to set any parameters after calling :meth:`writeframes` 206 or :meth:`writeframesraw`, and any attempt to do so will raise 207 :exc:`wave.Error`. 208 209
