Doc/lib/libsunau.tex

   1 \section{\module{sunau} ---
   2          Read and write Sun AU files}
   3
   4 \declaremodule{standard}{sunau}
   5 \sectionauthor{Moshe Zadka}{mzadka@geocities.com}
   6 \modulesynopsis{Provide an interface to the Sun AU sound format.}
   7
   8 The \module{sunau} module provides a convenient interface to the Sun AU sound
   9 format. Note that this module is interface-compatible with the modules
  10 \refmodule{aifc} and \refmodule{wave}.
  11
  12 The \module{sunau} module defines the following functions:
  13
  14 \begin{funcdesc}{open}{file, mode}
  15 If \var{file} is a string, open the file by that name, otherwise treat it
  16 as a seekable file-like object. \var{mode} can be any of
  17 \begin{description}
  18         \item[\code{'r'}] Read only mode.
  19         \item[\code{'w'}] Write only mode.
  20 \end{description}
  21 Note that it does not allow read/write files.
  22
  23 A \var{mode} of \code{'r'} returns a \class{AU_read}
  24 object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
  25 a \class{AU_write} object.
  26 \end{funcdesc}
  27
  28 \begin{funcdesc}{openfp}{file, mode}
  29 A synonym for \function{open}, maintained for backwards compatibility.
  30 \end{funcdesc}
  31
  32 The \module{sunau} module defines the following exception:
  33
  34 \begin{excdesc}{Error}
  35 An error raised when something is impossible because of Sun AU specs or
  36 implementation deficiency.
  37 \end{excdesc}
  38
  39 The \module{sunau} module defines the following data item:
  40
  41 \begin{datadesc}{AUDIO_FILE_MAGIC}
  42 An integer every valid Sun AU file begins with a big-endian encoding of.
  43 \end{datadesc}
  44
  45
  46 \subsection{AU_read Objects \label{au-read-objects}}
  47
  48 AU_read objects, as returned by \function{open()} above, have the
  49 following methods:
  50
  51 \begin{methoddesc}[AU_read]{close}{}
  52 Close the stream, and make the instance unusable. (This is
  53 called automatically on deletion.)
  54 \end{methoddesc}
  55
  56 \begin{methoddesc}[AU_read]{getnchannels}{}
  57 Returns number of audio channels (1 for mone, 2 for stereo).
  58 \end{methoddesc}
  59
  60 \begin{methoddesc}[AU_read]{getsampwidth}{}
  61 Returns sample width in bytes.
  62 \end{methoddesc}
  63
  64 \begin{methoddesc}[AU_read]{getframerate}{}
  65 Returns sampling frequency.
  66 \end{methoddesc}
  67
  68 \begin{methoddesc}[AU_read]{getnframes}{}
  69 Returns number of audio frames.
  70 \end{methoddesc}
  71
  72 \begin{methoddesc}[AU_read]{getcomptype}{}
  73 Returns compression type.
  74 Supported compression types are \code{'ULAW'}, \code{'ALAW'} and \code{'NONE'}.
  75 \end{methoddesc}
  76
  77 \begin{methoddesc}[AU_read]{getcompname}{}
  78 Human-readable version of \method{getcomptype()}.
  79 The supported types have the respective names \code{'CCITT G.711
  80 u-law'}, \code{'CCITT G.711 A-law'} and \code{'not compressed'}.
  81 \end{methoddesc}
  82
  83 \begin{methoddesc}[AU_read]{getparams}{}
  84 Returns a tuple \code{(\var{nchannels}, \var{sampwidth},
  85 \var{framerate}, \var{nframes}, \var{comptype}, \var{compname})},
  86 equivalent to output of the \method{get*()} methods.
  87 \end{methoddesc}
  88
  89 \begin{methoddesc}[AU_read]{readframes}{n}
  90 Reads and returns at most \var{n} frames of audio, as a string of bytes.
  91 \end{methoddesc}
  92
  93 \begin{methoddesc}[AU_read]{rewind}{}
  94 Rewind the file pointer to the beginning of the audio stream.
  95 \end{methoddesc}
  96
  97 The following two methods define a term ``position'' which is compatible
  98 between them, and is otherwise implementation dependent.
  99
 100 \begin{methoddesc}[AU_read]{setpos}{pos}
 101 Set the file pointer to the specified position.
 102 \end{methoddesc}
 103
 104 \begin{methoddesc}[AU_read]{tell}{}
 105 Return current file pointer position.
 106 \end{methoddesc}
 107
 108 The following two functions are defined for compatibility with the
 109 \refmodule{aifc}, and don't do anything interesting.
 110
 111 \begin{methoddesc}[AU_read]{getmarkers}{}
 112 Returns \code{None}.
 113 \end{methoddesc}
 114
 115 \begin{methoddesc}[AU_read]{getmark}{id}
 116 Raise an error.
 117 \end{methoddesc}
 118
 119
 120 \subsection{AU_write Objects \label{au-write-objects}}
 121
 122 AU_write objects, as returned by \function{open()} above, have the
 123 following methods:
 124
 125 \begin{methoddesc}[AU_write]{setnchannels}{n}
 126 Set the number of channels.
 127 \end{methoddesc}
 128
 129 \begin{methoddesc}[AU_write]{setsampwidth}{n}
 130 Set the sample width (in bytes.)
 131 \end{methoddesc}
 132
 133 \begin{methoddesc}[AU_write]{setframerate}{n}
 134 Set the frame rate.
 135 \end{methoddesc}
 136
 137 \begin{methoddesc}[AU_write]{setnframes}{n}
 138 Set the number of frames. This can be later changed, when and if more
 139 frames are written.
 140 \end{methoddesc}
 141
 142
 143 \begin{methoddesc}[AU_write]{setcomptype}{type, name}
 144 Set the compression type and description.
 145 Only \code{'NONE'} and \code{'ULAW'} are supported on output.
 146 \end{methoddesc}
 147
 148 \begin{methoddesc}[AU_write]{setparams}{tuple}
 149 The \var{tuple} should be \code{(\var{nchannels}, \var{sampwidth},
 150 \var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, with
 151 values valid for the \method{set*()} methods.  Set all parameters.
 152 \end{methoddesc}
 153
 154 \begin{methoddesc}[AU_write]{tell}{}
 155 Return current position in the file, with the same disclaimer for
 156 the \method{AU_read.tell()} and \method{AU_read.setpos()} methods.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}[AU_write]{writeframesraw}{data}
 160 Write audio frames, without correcting \var{nframes}.
 161 \end{methoddesc}
 162
 163 \begin{methoddesc}[AU_write]{writeframes}{data}
 164 Write audio frames and make sure \var{nframes} is correct.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}[AU_write]{close}{}
 168 Make sure \var{nframes} is correct, and close the file.
 169
 170 This method is called upon deletion.
 171 \end{methoddesc}
 172
 173 Note that it is invalid to set any parameters after calling
 174 \method{writeframes()} or \method{writeframesraw()}.