source: trunk/essentials/dev-lang/python/Doc/lib/libwave.tex@ 3368

% Documentations stolen and LaTeX'ed from comments in file.
\section{\module{wave} ---
         Read and write WAV files}

\declaremodule{standard}{wave}
\sectionauthor{Moshe Zadka}{[email protected]}
\modulesynopsis{Provide an interface to the WAV sound format.}

The \module{wave} module provides a convenient interface to the WAV sound
format. It does not support compression/decompression, but it does support
mono/stereo.

The \module{wave} module defines the following function and exception:

\begin{funcdesc}{open}{file\optional{, mode}}
If \var{file} is a string, open the file by that name, other treat it
as a seekable file-like object. \var{mode} can be any of
\begin{description}
        \item[\code{'r'}, \code{'rb'}] Read only mode.
        \item[\code{'w'}, \code{'wb'}] Write only mode.
\end{description}
Note that it does not allow read/write WAV files.

A \var{mode} of \code{'r'} or \code{'rb'} returns a \class{Wave_read}
object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
a \class{Wave_write} object.  If \var{mode} is omitted and a file-like 
object is passed as \var{file}, \code{\var{file}.mode} is used as the
default value for \var{mode} (the \character{b} flag is still added if 
necessary).
\end{funcdesc}

\begin{funcdesc}{openfp}{file, mode}
A synonym for \function{open()}, maintained for backwards compatibility.
\end{funcdesc}

\begin{excdesc}{Error}
An error raised when something is impossible because it violates the
WAV specification or hits an implementation deficiency.
\end{excdesc}


\subsection{Wave_read Objects \label{Wave-read-objects}}

Wave_read objects, as returned by \function{open()}, have the
following methods:

\begin{methoddesc}[Wave_read]{close}{}
Close the stream, and make the instance unusable. This is
called automatically on object collection.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getnchannels}{}
Returns number of audio channels (\code{1} for mono, \code{2} for
stereo).
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getsampwidth}{}
Returns sample width in bytes.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getframerate}{}
Returns sampling frequency.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getnframes}{}
Returns number of audio frames.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getcomptype}{}
Returns compression type (\code{'NONE'} is the only supported type).
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getcompname}{}
Human-readable version of \method{getcomptype()}.
Usually \code{'not compressed'} parallels \code{'NONE'}.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getparams}{}
Returns a tuple
\code{(\var{nchannels}, \var{sampwidth}, \var{framerate},
\var{nframes}, \var{comptype}, \var{compname})}, equivalent to output
of the \method{get*()} methods.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{readframes}{n}
Reads and returns at most \var{n} frames of audio, as a string of bytes.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{rewind}{}
Rewind the file pointer to the beginning of the audio stream.
\end{methoddesc}

The following two methods are defined for compatibility with the
\refmodule{aifc} module, and don't do anything interesting.

\begin{methoddesc}[Wave_read]{getmarkers}{}
Returns \code{None}.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{getmark}{id}
Raise an error.
\end{methoddesc}

The following two methods define a term ``position'' which is compatible
between them, and is otherwise implementation dependent.

\begin{methoddesc}[Wave_read]{setpos}{pos}
Set the file pointer to the specified position.
\end{methoddesc}

\begin{methoddesc}[Wave_read]{tell}{}
Return current file pointer position.
\end{methoddesc}


\subsection{Wave_write Objects \label{Wave-write-objects}}

Wave_write objects, as returned by \function{open()}, have the
following methods:

\begin{methoddesc}[Wave_write]{close}{}
Make sure \var{nframes} is correct, and close the file.
This method is called upon deletion.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setnchannels}{n}
Set the number of channels.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setsampwidth}{n}
Set the sample width to \var{n} bytes.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setframerate}{n}
Set the frame rate to \var{n}.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setnframes}{n}
Set the number of frames to \var{n}. This will be changed later if
more frames are written.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setcomptype}{type, name}
Set the compression type and description.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{setparams}{tuple}
The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
values valid for the \method{set*()} methods.  Sets all parameters.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{tell}{}
Return current position in the file, with the same disclaimer for
the \method{Wave_read.tell()} and \method{Wave_read.setpos()}
methods.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{writeframesraw}{data}
Write audio frames, without correcting \var{nframes}.
\end{methoddesc}

\begin{methoddesc}[Wave_write]{writeframes}{data}
Write audio frames and make sure \var{nframes} is correct.
\end{methoddesc}

Note that it is invalid to set any parameters after calling
\method{writeframes()} or \method{writeframesraw()}, and any attempt
to do so will raise \exception{wave.Error}.