Doc/lib/libsunau.tex

   1 \section{\module{sunau} ---
   2          Read and write Sun AU files}
   3
   4 \declaremodule{standard}{sunau}
   5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   6 \modulesynopsis{Provide an interface to the Sun AU sound format.}
   7
   8 The \module{sunau} module provides a convenient interface to the Sun
   9 AU sound format.  Note that this module is interface-compatible with
  10 the modules \refmodule{aifc} and \refmodule{wave}.
  11
  12 An audio file consists of a header followed by the data.  The fields
  13 of the header are:
  14
  15 \begin{tableii}{l|l}{textrm}{Field}{Contents}
  16   \lineii{magic word}{The four bytes \samp{.snd}.}
  17   \lineii{header size}{Size of the header, including info, in bytes.}
  18   \lineii{data size}{Physical size of the data, in bytes.}
  19   \lineii{encoding}{Indicates how the audio samples are encoded.}
  20   \lineii{sample rate}{The sampling rate.}
  21   \lineii{\# of channels}{The number of channels in the samples.}
  22   \lineii{info}{\ASCII{} string giving a description of the audio
  23                 file (padded with null bytes).}
  24 \end{tableii}
  25
  26 Apart from the info field, all header fields are 4 bytes in size.
  27 They are all 32-bit unsigned integers encoded in big-endian byte
  28 order.
  29
  30
  31 The \module{sunau} module defines the following functions:
  32
  33 \begin{funcdesc}{open}{file, mode}
  34 If \var{file} is a string, open the file by that name, otherwise treat it
  35 as a seekable file-like object. \var{mode} can be any of
  36 \begin{description}
  37         \item[\code{'r'}] Read only mode.
  38         \item[\code{'w'}] Write only mode.
  39 \end{description}
  40 Note that it does not allow read/write files.
  41
  42 A \var{mode} of \code{'r'} returns a \class{AU_read}
  43 object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
  44 a \class{AU_write} object.
  45 \end{funcdesc}
  46
  47 \begin{funcdesc}{openfp}{file, mode}
  48 A synonym for \function{open}, maintained for backwards compatibility.
  49 \end{funcdesc}
  50
  51 The \module{sunau} module defines the following exception:
  52
  53 \begin{excdesc}{Error}
  54 An error raised when something is impossible because of Sun AU specs or
  55 implementation deficiency.
  56 \end{excdesc}
  57
  58 The \module{sunau} module defines the following data items:
  59
  60 \begin{datadesc}{AUDIO_FILE_MAGIC}
  61 An integer every valid Sun AU file begins with, stored in big-endian
  62 form.  This is the string \samp{.snd} interpreted as an integer.
  63 \end{datadesc}
  64
  65 \begin{datadesc}{AUDIO_FILE_ENCODING_MULAW_8}
  66 \dataline{AUDIO_FILE_ENCODING_LINEAR_8}
  67 \dataline{AUDIO_FILE_ENCODING_LINEAR_16}
  68 \dataline{AUDIO_FILE_ENCODING_LINEAR_24}
  69 \dataline{AUDIO_FILE_ENCODING_LINEAR_32}
  70 \dataline{AUDIO_FILE_ENCODING_ALAW_8}
  71 Values of the encoding field from the AU header which are supported by
  72 this module.
  73 \end{datadesc}
  74
  75 \begin{datadesc}{AUDIO_FILE_ENCODING_FLOAT}
  76 \dataline{AUDIO_FILE_ENCODING_DOUBLE}
  77 \dataline{AUDIO_FILE_ENCODING_ADPCM_G721}
  78 \dataline{AUDIO_FILE_ENCODING_ADPCM_G722}
  79 \dataline{AUDIO_FILE_ENCODING_ADPCM_G723_3}
  80 \dataline{AUDIO_FILE_ENCODING_ADPCM_G723_5}
  81 Additional known values of the encoding field from the AU header, but
  82 which are not supported by this module.
  83 \end{datadesc}
  84
  85
  86 \subsection{AU_read Objects \label{au-read-objects}}
  87
  88 AU_read objects, as returned by \function{open()} above, have the
  89 following methods:
  90
  91 \begin{methoddesc}[AU_read]{close}{}
  92 Close the stream, and make the instance unusable. (This is
  93 called automatically on deletion.)
  94 \end{methoddesc}
  95
  96 \begin{methoddesc}[AU_read]{getnchannels}{}
  97 Returns number of audio channels (1 for mone, 2 for stereo).
  98 \end{methoddesc}
  99
 100 \begin{methoddesc}[AU_read]{getsampwidth}{}
 101 Returns sample width in bytes.
 102 \end{methoddesc}
 103
 104 \begin{methoddesc}[AU_read]{getframerate}{}
 105 Returns sampling frequency.
 106 \end{methoddesc}
 107
 108 \begin{methoddesc}[AU_read]{getnframes}{}
 109 Returns number of audio frames.
 110 \end{methoddesc}
 111
 112 \begin{methoddesc}[AU_read]{getcomptype}{}
 113 Returns compression type.
 114 Supported compression types are \code{'ULAW'}, \code{'ALAW'} and \code{'NONE'}.
 115 \end{methoddesc}
 116
 117 \begin{methoddesc}[AU_read]{getcompname}{}
 118 Human-readable version of \method{getcomptype()}.
 119 The supported types have the respective names \code{'CCITT G.711
 120 u-law'}, \code{'CCITT G.711 A-law'} and \code{'not compressed'}.
 121 \end{methoddesc}
 122
 123 \begin{methoddesc}[AU_read]{getparams}{}
 124 Returns a tuple \code{(\var{nchannels}, \var{sampwidth},
 125 \var{framerate}, \var{nframes}, \var{comptype}, \var{compname})},
 126 equivalent to output of the \method{get*()} methods.
 127 \end{methoddesc}
 128
 129 \begin{methoddesc}[AU_read]{readframes}{n}
 130 Reads and returns at most \var{n} frames of audio, as a string of
 131 bytes.  The data will be returned in linear format.  If the original
 132 data is in u-LAW format, it will be converted.
 133 \end{methoddesc}
 134
 135 \begin{methoddesc}[AU_read]{rewind}{}
 136 Rewind the file pointer to the beginning of the audio stream.
 137 \end{methoddesc}
 138
 139 The following two methods define a term ``position'' which is compatible
 140 between them, and is otherwise implementation dependent.
 141
 142 \begin{methoddesc}[AU_read]{setpos}{pos}
 143 Set the file pointer to the specified position.  Only values returned
 144 from \method{tell()} should be used for \var{pos}.
 145 \end{methoddesc}
 146
 147 \begin{methoddesc}[AU_read]{tell}{}
 148 Return current file pointer position.  Note that the returned value
 149 has nothing to do with the actual position in the file.
 150 \end{methoddesc}
 151
 152 The following two functions are defined for compatibility with the
 153 \refmodule{aifc}, and don't do anything interesting.
 154
 155 \begin{methoddesc}[AU_read]{getmarkers}{}
 156 Returns \code{None}.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}[AU_read]{getmark}{id}
 160 Raise an error.
 161 \end{methoddesc}
 162
 163
 164 \subsection{AU_write Objects \label{au-write-objects}}
 165
 166 AU_write objects, as returned by \function{open()} above, have the
 167 following methods:
 168
 169 \begin{methoddesc}[AU_write]{setnchannels}{n}
 170 Set the number of channels.
 171 \end{methoddesc}
 172
 173 \begin{methoddesc}[AU_write]{setsampwidth}{n}
 174 Set the sample width (in bytes.)
 175 \end{methoddesc}
 176
 177 \begin{methoddesc}[AU_write]{setframerate}{n}
 178 Set the frame rate.
 179 \end{methoddesc}
 180
 181 \begin{methoddesc}[AU_write]{setnframes}{n}
 182 Set the number of frames. This can be later changed, when and if more
 183 frames are written.
 184 \end{methoddesc}
 185
 186
 187 \begin{methoddesc}[AU_write]{setcomptype}{type, name}
 188 Set the compression type and description.
 189 Only \code{'NONE'} and \code{'ULAW'} are supported on output.
 190 \end{methoddesc}
 191
 192 \begin{methoddesc}[AU_write]{setparams}{tuple}
 193 The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
 194 \var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
 195 values valid for the \method{set*()} methods.  Set all parameters.
 196 \end{methoddesc}
 197
 198 \begin{methoddesc}[AU_write]{tell}{}
 199 Return current position in the file, with the same disclaimer for
 200 the \method{AU_read.tell()} and \method{AU_read.setpos()} methods.
 201 \end{methoddesc}
 202
 203 \begin{methoddesc}[AU_write]{writeframesraw}{data}
 204 Write audio frames, without correcting \var{nframes}.
 205 \end{methoddesc}
 206
 207 \begin{methoddesc}[AU_write]{writeframes}{data}
 208 Write audio frames and make sure \var{nframes} is correct.
 209 \end{methoddesc}
 210
 211 \begin{methoddesc}[AU_write]{close}{}
 212 Make sure \var{nframes} is correct, and close the file.
 213
 214 This method is called upon deletion.
 215 \end{methoddesc}
 216
 217 Note that it is invalid to set any parameters after calling
 218 \method{writeframes()} or \method{writeframesraw()}.