Two more from Moshe!

1 files changed, 174 insertions, 0 deletions

diff --git a/Doc/lib/libsunau.tex b/Doc/lib/libsunau.tex
new file mode 100644
index 0000000..3850ce9
--- /dev/null
+++ b/Doc/lib/libsunau.tex
@@ -0,0 +1,174 @@
+\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()}.