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