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