Doc/lib/libaifc.tex

   1 \section{\module{aifc} ---
   2          Read and write AIFF and AIFC files}
   3
   4 \declaremodule{standard}{aifc}
   5 \modulesynopsis{Read and write audio files in AIFF or AIFC format.}
   6
   7
   8 This module provides support for reading and writing AIFF and AIFF-C
   9 files.  AIFF is Audio Interchange File Format, a format for storing
  10 digital audio samples in a file.  AIFF-C is a newer version of the
  11 format that includes the ability to compress the audio data.
  12 \index{Audio Interchange File Format}
  13 \index{AIFF}
  14 \index{AIFF-C}
  15
  16 \strong{Caveat:}  Some operations may only work under IRIX; these will
  17 raise \exception{ImportError} when attempting to import the
  18 \module{cl} module, which is only available on IRIX.
  19
  20 Audio files have a number of parameters that describe the audio data.
  21 The sampling rate or frame rate is the number of times per second the
  22 sound is sampled.  The number of channels indicate if the audio is
  23 mono, stereo, or quadro.  Each frame consists of one sample per
  24 channel.  The sample size is the size in bytes of each sample.  Thus a
  25 frame consists of \var{nchannels}*\var{samplesize} bytes, and a
  26 second's worth of audio consists of
  27 \var{nchannels}*\var{samplesize}*\var{framerate} bytes.
  28
  29 For example, CD quality audio has a sample size of two bytes (16
  30 bits), uses two channels (stereo) and has a frame rate of 44,100
  31 frames/second.  This gives a frame size of 4 bytes (2*2), and a
  32 second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes.
  33
  34 Module \module{aifc} defines the following function:
  35
  36 \begin{funcdesc}{open}{file\optional{, mode}}
  37 Open an AIFF or AIFF-C file and return an object instance with
  38 methods that are described below.  The argument \var{file} is either a
  39 string naming a file or a file object.  \var{mode} must be \code{'r'}
  40 or \code{'rb'} when the file must be opened for reading, or \code{'w'}
  41 or \code{'wb'} when the file must be opened for writing.  If omitted,
  42 \code{\var{file}.mode} is used if it exists, otherwise \code{'rb'} is
  43 used.  When used for writing, the file object should be seekable,
  44 unless you know ahead of time how many samples you are going to write
  45 in total and use \method{writeframesraw()} and \method{setnframes()}.
  46 \end{funcdesc}
  47
  48 Objects returned by \function{open()} when a file is opened for
  49 reading have the following methods:
  50
  51 \begin{methoddesc}[aifc]{getnchannels}{}
  52 Return the number of audio channels (1 for mono, 2 for stereo).
  53 \end{methoddesc}
  54
  55 \begin{methoddesc}[aifc]{getsampwidth}{}
  56 Return the size in bytes of individual samples.
  57 \end{methoddesc}
  58
  59 \begin{methoddesc}[aifc]{getframerate}{}
  60 Return the sampling rate (number of audio frames per second).
  61 \end{methoddesc}
  62
  63 \begin{methoddesc}[aifc]{getnframes}{}
  64 Return the number of audio frames in the file.
  65 \end{methoddesc}
  66
  67 \begin{methoddesc}[aifc]{getcomptype}{}
  68 Return a four-character string describing the type of compression used
  69 in the audio file.  For AIFF files, the returned value is
  70 \code{'NONE'}.
  71 \end{methoddesc}
  72
  73 \begin{methoddesc}[aifc]{getcompname}{}
  74 Return a human-readable description of the type of compression used in
  75 the audio file.  For AIFF files, the returned value is \code{'not
  76 compressed'}.
  77 \end{methoddesc}
  78
  79 \begin{methoddesc}[aifc]{getparams}{}
  80 Return a tuple consisting of all of the above values in the above
  81 order.
  82 \end{methoddesc}
  83
  84 \begin{methoddesc}[aifc]{getmarkers}{}
  85 Return a list of markers in the audio file.  A marker consists of a
  86 tuple of three elements.  The first is the mark ID (an integer), the
  87 second is the mark position in frames from the beginning of the data
  88 (an integer), the third is the name of the mark (a string).
  89 \end{methoddesc}
  90
  91 \begin{methoddesc}[aifc]{getmark}{id}
  92 Return the tuple as described in \method{getmarkers()} for the mark
  93 with the given \var{id}.
  94 \end{methoddesc}
  95
  96 \begin{methoddesc}[aifc]{readframes}{nframes}
  97 Read and return the next \var{nframes} frames from the audio file.  The
  98 returned data is a string containing for each frame the uncompressed
  99 samples of all channels.
 100 \end{methoddesc}
 101
 102 \begin{methoddesc}[aifc]{rewind}{}
 103 Rewind the read pointer.  The next \method{readframes()} will start from
 104 the beginning.
 105 \end{methoddesc}
 106
 107 \begin{methoddesc}[aifc]{setpos}{pos}
 108 Seek to the specified frame number.
 109 \end{methoddesc}
 110
 111 \begin{methoddesc}[aifc]{tell}{}
 112 Return the current frame number.
 113 \end{methoddesc}
 114
 115 \begin{methoddesc}[aifc]{close}{}
 116 Close the AIFF file.  After calling this method, the object can no
 117 longer be used.
 118 \end{methoddesc}
 119
 120 Objects returned by \function{open()} when a file is opened for
 121 writing have all the above methods, except for \method{readframes()} and
 122 \method{setpos()}.  In addition the following methods exist.  The
 123 \method{get*()} methods can only be called after the corresponding
 124 \method{set*()} methods have been called.  Before the first
 125 \method{writeframes()} or \method{writeframesraw()}, all parameters
 126 except for the number of frames must be filled in.
 127
 128 \begin{methoddesc}[aifc]{aiff}{}
 129 Create an AIFF file.  The default is that an AIFF-C file is created,
 130 unless the name of the file ends in \code{'.aiff'} in which case the
 131 default is an AIFF file.
 132 \end{methoddesc}
 133
 134 \begin{methoddesc}[aifc]{aifc}{}
 135 Create an AIFF-C file.  The default is that an AIFF-C file is created,
 136 unless the name of the file ends in \code{'.aiff'} in which case the
 137 default is an AIFF file.
 138 \end{methoddesc}
 139
 140 \begin{methoddesc}[aifc]{setnchannels}{nchannels}
 141 Specify the number of channels in the audio file.
 142 \end{methoddesc}
 143
 144 \begin{methoddesc}[aifc]{setsampwidth}{width}
 145 Specify the size in bytes of audio samples.
 146 \end{methoddesc}
 147
 148 \begin{methoddesc}[aifc]{setframerate}{rate}
 149 Specify the sampling frequency in frames per second.
 150 \end{methoddesc}
 151
 152 \begin{methoddesc}[aifc]{setnframes}{nframes}
 153 Specify the number of frames that are to be written to the audio file.
 154 If this parameter is not set, or not set correctly, the file needs to
 155 support seeking.
 156 \end{methoddesc}
 157
 158 \begin{methoddesc}[aifc]{setcomptype}{type, name}
 159 Specify the compression type.  If not specified, the audio data will
 160 not be compressed.  In AIFF files, compression is not possible.  The
 161 name parameter should be a human-readable description of the
 162 compression type, the type parameter should be a four-character
 163 string.  Currently the following compression types are supported:
 164 NONE, ULAW, ALAW, G722.
 165 \index{u-LAW}
 166 \index{A-LAW}
 167 \index{G.722}
 168 \end{methoddesc}
 169
 170 \begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname}
 171 Set all the above parameters at once.  The argument is a tuple
 172 consisting of the various parameters.  This means that it is possible
 173 to use the result of a \method{getparams()} call as argument to
 174 \method{setparams()}.
 175 \end{methoddesc}
 176
 177 \begin{methoddesc}[aifc]{setmark}{id, pos, name}
 178 Add a mark with the given id (larger than 0), and the given name at
 179 the given position.  This method can be called at any time before
 180 \method{close()}.
 181 \end{methoddesc}
 182
 183 \begin{methoddesc}[aifc]{tell}{}
 184 Return the current write position in the output file.  Useful in
 185 combination with \method{setmark()}.
 186 \end{methoddesc}
 187
 188 \begin{methoddesc}[aifc]{writeframes}{data}
 189 Write data to the output file.  This method can only be called after
 190 the audio file parameters have been set.
 191 \end{methoddesc}
 192
 193 \begin{methoddesc}[aifc]{writeframesraw}{data}
 194 Like \method{writeframes()}, except that the header of the audio file
 195 is not updated.
 196 \end{methoddesc}
 197
 198 \begin{methoddesc}[aifc]{close}{}
 199 Close the AIFF file.  The header of the file is updated to reflect the
 200 actual size of the audio data. After calling this method, the object
 201 can no longer be used.
 202 \end{methoddesc}