| \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()}. |