Doc/lib/libsunau.tex

\section{\module{sunau} ---
         Read and write Sun AU files}

\declaremodule{standard}{sunau}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
\modulesynopsis{Provide an interface to the Sun AU sound format.}

The \module{sunau} module provides a convenient interface to the Sun AU sound
format. Note that this module is interface-compatible with the modules
\refmodule{aifc} and \refmodule{wave}.

The \module{sunau} module defines the following functions:

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

A \var{mode} of \code{'r'} returns a \class{AU_read}
object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
a \class{AU_write} object.
\end{funcdesc}

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

The \module{sunau} module defines the following exception:

\begin{excdesc}{Error}
An error raised when something is impossible because of Sun AU specs or 
implementation deficiency.
\end{excdesc}

The \module{sunau} module defines the following data item:

\begin{datadesc}{AUDIO_FILE_MAGIC}
An integer every valid Sun AU file begins with a big-endian encoding of.
\end{datadesc}


\subsection{AU_read Objects \label{au-read-objects}}

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

\begin{methoddesc}[AU_read]{close}{}
Close the stream, and make the instance unusable. (This is 
called automatically on deletion.)
\end{methoddesc}

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

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

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

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

\begin{methoddesc}[AU_read]{getcomptype}{}
Returns compression type.
Supported compression types are \code{'ULAW'}, \code{'ALAW'} and \code{'NONE'}.
\end{methoddesc}

\begin{methoddesc}[AU_read]{getcompname}{}
Human-readable version of \method{getcomptype()}. 
The supported types have the respective names \code{'CCITT G.711
u-law'}, \code{'CCITT G.711 A-law'} and \code{'not compressed'}.
\end{methoddesc}

\begin{methoddesc}[AU_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}[AU_read]{readframes}{n}
Reads and returns at most \var{n} frames of audio, as a string of bytes.
\end{methoddesc}

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

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

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

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

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

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

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


\subsection{AU_write Objects \label{au-write-objects}}

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

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

\begin{methoddesc}[AU_write]{setsampwidth}{n}
Set the sample width (in bytes.)
\end{methoddesc}

\begin{methoddesc}[AU_write]{setframerate}{n}
Set the frame rate.
\end{methoddesc}

\begin{methoddesc}[AU_write]{setnframes}{n}
Set the number of frames. This can be later changed, when and if more 
frames are written.
\end{methoddesc}


\begin{methoddesc}[AU_write]{setcomptype}{type, name}
Set the compression type and description.
Only \code{'NONE'} and \code{'ULAW'} are supported on output.
\end{methoddesc}

\begin{methoddesc}[AU_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.  Set all parameters.
\end{methoddesc}

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

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

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

\begin{methoddesc}[AU_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()}.