New module documentation sections from Moshe Zadka <moshez@math.huji.ac.il>!

Doc/lib/libwave.tex

@@ -0,0 +1,165 @@
+% Documentations stolen and LaTeX'ed from comments in file.
+\section{\module{wave} ---
+         Read and write .WAV files}
+
+\declaremodule{standard}{wave}
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+\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:
+
+\begin{funcdesc}{open}{file, 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.
+\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()} above, have the
+following methods:
+
+\begin{methoddesc}[Wave_read]{getnchannels}{}
+Returns number of audio channels (1 for mone, 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{(nchannels, sampwidth, framerate, nframes, comptype, compname)},
+equivalent to output of the \code{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 functions 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 dependant.
+
+\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}
+
+\begin{methoddesc}[Wave_read]{close}{}
+Close the stream, and make the instance unusable. (This is
+called automatically on deletion.
+\end{methoddesc}
+
+
+\subsection{Wave_write Objects \label{Wave-write-objects}}
+
+Wave_write objects, as returned by \function{open()} above, have the
+following methods:
+
+\begin{methoddesc}[Wave_write]{setnchannels}{n}
+Set the number of channels.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{setsampwidth}{n}
+Set the sample width (in bytes.)
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{setframerate}{n}
+Set the frame rate.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{setnframes}{n}
+Set the number of frames. This can be later changed, when and 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 \code{set} methods.  Set 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}
+
+\begin{methoddesc}[Wave_write]{close}{}
+Make sure \var{nframes} is correct, and close the file.
+
+This method is called upon deletion.
+\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 an error.