Doc/libaifc.tex

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