source: trunk/essentials/dev-lang/python/Doc/lib/libaifc.tex@ 3226

\section{\module{aifc} ---
         Read and write AIFF and AIFC files}

\declaremodule{standard}{aifc}
\modulesynopsis{Read and write audio files in AIFF or AIFC format.}


This module provides support for reading and writing AIFF and AIFF-C
files.  AIFF is Audio Interchange File Format, a format for storing
digital audio samples in a file.  AIFF-C is a newer version of the
format that includes the ability to compress the audio data.
\index{Audio Interchange File Format}
\index{AIFF}
\index{AIFF-C}

\strong{Caveat:}  Some operations may only work under IRIX; these will
raise \exception{ImportError} when attempting to import the
\module{cl} module, which is only available on IRIX.

Audio files have a number of parameters that describe the audio data.
The sampling rate or frame rate is the number of times per second the
sound is sampled.  The number of channels indicate if the audio is
mono, stereo, or quadro.  Each frame consists of one sample per
channel.  The sample size is the size in bytes of each sample.  Thus a
frame consists of \var{nchannels}*\var{samplesize} bytes, and a
second's worth of audio consists of
\var{nchannels}*\var{samplesize}*\var{framerate} bytes.

For example, CD quality audio has a sample size of two bytes (16
bits), uses two channels (stereo) and has a frame rate of 44,100
frames/second.  This gives a frame size of 4 bytes (2*2), and a
second's worth occupies 2*2*44100 bytes (176,400 bytes).

Module \module{aifc} defines the following function:

\begin{funcdesc}{open}{file\optional{, mode}}
Open an AIFF or AIFF-C file and return an object instance with
methods that are described below.  The argument \var{file} is either a
string naming a file or a file object.  \var{mode} must be \code{'r'}
or \code{'rb'} when the file must be opened for reading, or \code{'w'} 
or \code{'wb'} when the file must be opened for writing.  If omitted,
\code{\var{file}.mode} is used if it exists, otherwise \code{'rb'} is
used.  When used for writing, the file object should be seekable,
unless you know ahead of time how many samples you are going to write
in total and use \method{writeframesraw()} and \method{setnframes()}.
\end{funcdesc}

Objects returned by \function{open()} when a file is opened for
reading have the following methods:

\begin{methoddesc}[aifc]{getnchannels}{}
Return the number of audio channels (1 for mono, 2 for stereo).
\end{methoddesc}

\begin{methoddesc}[aifc]{getsampwidth}{}
Return the size in bytes of individual samples.
\end{methoddesc}

\begin{methoddesc}[aifc]{getframerate}{}
Return the sampling rate (number of audio frames per second).
\end{methoddesc}

\begin{methoddesc}[aifc]{getnframes}{}
Return the number of audio frames in the file.
\end{methoddesc}

\begin{methoddesc}[aifc]{getcomptype}{}
Return a four-character string describing the type of compression used
in the audio file.  For AIFF files, the returned value is
\code{'NONE'}.
\end{methoddesc}

\begin{methoddesc}[aifc]{getcompname}{}
Return a human-readable description of the type of compression used in
the audio file.  For AIFF files, the returned value is \code{'not
compressed'}.
\end{methoddesc}

\begin{methoddesc}[aifc]{getparams}{}
Return a tuple consisting of all of the above values in the above
order.