/Doc/library/wave.rst

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