Doc/lib/libwave.tex

   1 % Documentations stolen and LaTeX'ed from comments in file.
   2 \section{\module{wave} ---
   3          Read and write WAV files}
   4
   5 \declaremodule{standard}{wave}
   6 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   7 \modulesynopsis{Provide an interface to the WAV sound format.}
   8
   9 The \module{wave} module provides a convenient interface to the WAV sound
  10 format. It does not support compression/decompression, but it does support
  11 mono/stereo.
  12
  13 The \module{wave} module defines the following function and exception:
  14
  15 \begin{funcdesc}{open}{file\optional{, mode}}
  16 If \var{file} is a string, open the file by that name, other treat it
  17 as a seekable file-like object. \var{mode} can be any of
  18 \begin{description}
  19         \item[\code{'r'}, \code{'rb'}] Read only mode.
  20         \item[\code{'w'}, \code{'wb'}] Write only mode.
  21 \end{description}
  22 Note that it does not allow read/write WAV files.
  23
  24 A \var{mode} of \code{'r'} or \code{'rb'} returns a \class{Wave_read}
  25 object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
  26 a \class{Wave_write} object.  If \var{mode} is omitted and a file-like
  27 object is passed as \var{file}, \code{\var{file}.mode} is used as the
  28 default value for \var{mode} (the \character{b} flag is still added if
  29 necessary).
  30 \end{funcdesc}
  31
  32 \begin{funcdesc}{openfp}{file, mode}
  33 A synonym for \function{open()}, maintained for backwards compatibility.
  34 \end{funcdesc}
  35
  36 \begin{excdesc}{Error}
  37 An error raised when something is impossible because it violates the
  38 WAV specification or hits an implementation deficiency.
  39 \end{excdesc}
  40
  41
  42 \subsection{Wave_read Objects \label{Wave-read-objects}}
  43
  44 Wave_read objects, as returned by \function{open()}, have the
  45 following methods:
  46
  47 \begin{methoddesc}[Wave_read]{close}{}
  48 Close the stream, and make the instance unusable. This is
  49 called automatically on object collection.
  50 \end{methoddesc}
  51
  52 \begin{methoddesc}[Wave_read]{getnchannels}{}
  53 Returns number of audio channels (\code{1} for mono, \code{2} for
  54 stereo).
  55 \end{methoddesc}
  56
  57 \begin{methoddesc}[Wave_read]{getsampwidth}{}
  58 Returns sample width in bytes.
  59 \end{methoddesc}
  60
  61 \begin{methoddesc}[Wave_read]{getframerate}{}
  62 Returns sampling frequency.
  63 \end{methoddesc}
  64
  65 \begin{methoddesc}[Wave_read]{getnframes}{}
  66 Returns number of audio frames.
  67 \end{methoddesc}
  68
  69 \begin{methoddesc}[Wave_read]{getcomptype}{}
  70 Returns compression type (\code{'NONE'} is the only supported type).
  71 \end{methoddesc}
  72
  73 \begin{methoddesc}[Wave_read]{getcompname}{}
  74 Human-readable version of \method{getcomptype()}.
  75 Usually \code{'not compressed'} parallels \code{'NONE'}.
  76 \end{methoddesc}
  77
  78 \begin{methoddesc}[Wave_read]{getparams}{}
  79 Returns a tuple
  80 \code{(\var{nchannels}, \var{sampwidth}, \var{framerate},
  81 \var{nframes}, \var{comptype}, \var{compname})}, equivalent to output
  82 of the \method{get*()} methods.
  83 \end{methoddesc}
  84
  85 \begin{methoddesc}[Wave_read]{readframes}{n}
  86 Reads and returns at most \var{n} frames of audio, as a string of bytes.
  87 \end{methoddesc}
  88
  89 \begin{methoddesc}[Wave_read]{rewind}{}
  90 Rewind the file pointer to the beginning of the audio stream.
  91 \end{methoddesc}
  92
  93 The following two methods are defined for compatibility with the
  94 \refmodule{aifc} module, and don't do anything interesting.
  95
  96 \begin{methoddesc}[Wave_read]{getmarkers}{}
  97 Returns \code{None}.
  98 \end{methoddesc}
  99
 100 \begin{methoddesc}[Wave_read]{getmark}{id}
 101 Raise an error.
 102 \end{methoddesc}
 103
 104 The following two methods define a term ``position'' which is compatible
 105 between them, and is otherwise implementation dependent.
 106
 107 \begin{methoddesc}[Wave_read]{setpos}{pos}
 108 Set the file pointer to the specified position.
 109 \end{methoddesc}
 110
 111 \begin{methoddesc}[Wave_read]{tell}{}
 112 Return current file pointer position.
 113 \end{methoddesc}
 114
 115
 116 \subsection{Wave_write Objects \label{Wave-write-objects}}
 117
 118 Wave_write objects, as returned by \function{open()}, have the
 119 following methods:
 120
 121 \begin{methoddesc}[Wave_write]{close}{}
 122 Make sure \var{nframes} is correct, and close the file.
 123 This method is called upon deletion.
 124 \end{methoddesc}
 125
 126 \begin{methoddesc}[Wave_write]{setnchannels}{n}
 127 Set the number of channels.
 128 \end{methoddesc}
 129
 130 \begin{methoddesc}[Wave_write]{setsampwidth}{n}
 131 Set the sample width to \var{n} bytes.
 132 \end{methoddesc}
 133
 134 \begin{methoddesc}[Wave_write]{setframerate}{n}
 135 Set the frame rate to \var{n}.
 136 \end{methoddesc}
 137
 138 \begin{methoddesc}[Wave_write]{setnframes}{n}
 139 Set the number of frames to \var{n}. This will be changed later if
 140 more frames are written.
 141 \end{methoddesc}
 142
 143 \begin{methoddesc}[Wave_write]{setcomptype}{type, name}
 144 Set the compression type and description.
 145 \end{methoddesc}
 146
 147 \begin{methoddesc}[Wave_write]{setparams}{tuple}
 148 The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
 149 \var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
 150 values valid for the \method{set*()} methods.  Sets all parameters.
 151 \end{methoddesc}
 152
 153 \begin{methoddesc}[Wave_write]{tell}{}
 154 Return current position in the file, with the same disclaimer for
 155 the \method{Wave_read.tell()} and \method{Wave_read.setpos()}
 156 methods.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}[Wave_write]{writeframesraw}{data}
 160 Write audio frames, without correcting \var{nframes}.
 161 \end{methoddesc}
 162
 163 \begin{methoddesc}[Wave_write]{writeframes}{data}
 164 Write audio frames and make sure \var{nframes} is correct.
 165 \end{methoddesc}
 166
 167 Note that it is invalid to set any parameters after calling
 168 \method{writeframes()} or \method{writeframesraw()}, and any attempt
 169 to do so will raise \exception{wave.Error}.