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
   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
  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
  47 Wave_read Objects
  48 -----------------
  49
  50 Wave_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
 105 The following two methods are defined for compatibility with the :mod:`aifc`
 106 module, 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
 118 The following two methods define a term "position" which is compatible between
 119 them, 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
 134 Wave_write Objects
 135 ------------------
 136
 137 Wave_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
 195 Note that it is invalid to set any parameters after calling :meth:`writeframes`
 196 or :meth:`writeframesraw`, and any attempt to do so will raise
 197 :exc:`wave.Error`.
 198