\section{\module{sunau} --- Read and write Sun AU files}\declaremodule{standard}{sunau}\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}\modulesynopsis{Provide an interface to the Sun AU sound format.}The \module{sunau} module provides a convenient interface to the SunAU sound format. Note that this module is interface-compatible withthe modules \refmodule{aifc} and \refmodule{wave}.An audio file consists of a header followed by the data. The fieldsof the header are:\begin{tableii}{l|l}{textrm}{Field}{Contents} \lineii{magic word}{The four bytes \samp{.snd}.} \lineii{header size}{Size of the header, including info, in bytes.} \lineii{data size}{Physical size of the data, in bytes.} \lineii{encoding}{Indicates how the audio samples are encoded.} \lineii{sample rate}{The sampling rate.} \lineii{\# of channels}{The number of channels in the samples.} \lineii{info}{\ASCII{} string giving a description of the audio file (padded with null bytes).}\end{tableii}Apart from the info field, all header fields are 4 bytes in size.They are all 32-bit unsigned integers encoded in big-endian byteorder.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 itas 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'} returnsa \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 items:\begin{datadesc}{AUDIO_FILE_MAGIC}An integer every valid Sun AU file begins with, stored in big-endianform. This is the string \samp{.snd} interpreted as an integer.\end{datadesc}\begin{datadesc}{AUDIO_FILE_ENCODING_MULAW_8}\dataline{AUDIO_FILE_ENCODING_LINEAR_8}\dataline{AUDIO_FILE_ENCODING_LINEAR_16}\dataline{AUDIO_FILE_ENCODING_LINEAR_24}\dataline{AUDIO_FILE_ENCODING_LINEAR_32}\dataline{AUDIO_FILE_ENCODING_ALAW_8}Values of the encoding field from the AU header which are supported bythis module.\end{datadesc}\begin{datadesc}{AUDIO_FILE_ENCODING_FLOAT}\dataline{AUDIO_FILE_ENCODING_DOUBLE}\dataline{AUDIO_FILE_ENCODING_ADPCM_G721}\dataline{AUDIO_FILE_ENCODING_ADPCM_G722}\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_3}\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_5}Additional known values of the encoding field from the AU header, butwhich are not supported by this module.\end{datadesc}\subsection{AU_read Objects \label{au-read-objects}}AU_read objects, as returned by \function{open()} above, have thefollowing 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.711u-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 ofbytes. The data will be returned in linear format. If the originaldata is in u-LAW format, it will be converted.\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 compatiblebetween them, and is otherwise implementation dependent.\begin{methoddesc}[AU_read]{setpos}{pos}Set the file pointer to the specified position. Only values returnedfrom \method{tell()} should be used for \var{pos}.\end{methoddesc}\begin{methoddesc}[AU_read]{tell}{}Return current file pointer position. Note that the returned valuehas nothing to do with the actual position in the file.\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 thefollowing 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})}, withvalues 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 forthe \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()}.
\section{\module{sunau} ---
Read and write Sun AU files}
\declaremodule{standard}{sunau}
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
\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}.
An audio file consists of a header followed by the data. The fields
of the header are:
\begin{tableii}{l|l}{textrm}{Field}{Contents}
\lineii{magic word}{The four bytes \samp{.snd}.}
\lineii{header size}{Size of the header, including info, in bytes.}
\lineii{data size}{Physical size of the data, in bytes.}
\lineii{encoding}{Indicates how the audio samples are encoded.}
\lineii{sample rate}{The sampling rate.}
\lineii{\# of channels}{The number of channels in the samples.}
\lineii{info}{\ASCII{} string giving a description of the audio
file (padded with null bytes).}
\end{tableii}
Apart from the info field, all header fields are 4 bytes in size.
They are all 32-bit unsigned integers encoded in big-endian byte
order.
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 items:
\begin{datadesc}{AUDIO_FILE_MAGIC}
An integer every valid Sun AU file begins with, stored in big-endian
form. This is the string \samp{.snd} interpreted as an integer.
\end{datadesc}
\begin{datadesc}{AUDIO_FILE_ENCODING_MULAW_8}
\dataline{AUDIO_FILE_ENCODING_LINEAR_8}
\dataline{AUDIO_FILE_ENCODING_LINEAR_16}
\dataline{AUDIO_FILE_ENCODING_LINEAR_24}
\dataline{AUDIO_FILE_ENCODING_LINEAR_32}
\dataline{AUDIO_FILE_ENCODING_ALAW_8}
Values of the encoding field from the AU header which are supported by
this module.
\end{datadesc}
\begin{datadesc}{AUDIO_FILE_ENCODING_FLOAT}
\dataline{AUDIO_FILE_ENCODING_DOUBLE}
\dataline{AUDIO_FILE_ENCODING_ADPCM_G721}
\dataline{AUDIO_FILE_ENCODING_ADPCM_G722}
\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_3}
\dataline{AUDIO_FILE_ENCODING_ADPCM_G723_5}
Additional known values of the encoding field from the AU header, but
which are not supported by this module.
\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. The data will be returned in linear format. If the original
data is in u-LAW format, it will be converted.
\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 dependent.
\begin{methoddesc}[AU_read]{setpos}{pos}
Set the file pointer to the specified position. Only values returned
from \method{tell()} should be used for \var{pos}.
\end{methoddesc}
\begin{methoddesc}[AU_read]{tell}{}
Return current file pointer position. Note that the returned value
has nothing to do with the actual position in the file.
\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()}.