\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-Cfiles.  AIFF is Audio Interchange File Format, a format for storingdigital audio samples in a file.  AIFF-C is a newer version of theformat 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 willraise \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 thesound is sampled.  The number of channels indicate if the audio ismono, stereo, or quadro.  Each frame consists of one sample perchannel.  The sample size is the size in bytes of each sample.  Thus aframe consists of \var{nchannels}*\var{samplesize} bytes, and asecond'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 (16bits), uses two channels (stereo) and has a frame rate of 44,100frames/second.  This gives a frame size of 4 bytes (2*2), and asecond'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 withmethods that are described below.  The argument \var{file} is either astring 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'} isused.  When used for writing, the file object should be seekable,unless you know ahead of time how many samples you are going to writein total and use \method{writeframesraw()} and \method{setnframes()}.\end{funcdesc} Objects returned by \function{open()} when a file is opened forreading 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 usedin 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 inthe audio file.  For AIFF files, the returned value is \code{'notcompressed'}.\end{methoddesc} \begin{methoddesc}[aifc]{getparams}{}Return a tuple consisting of all of the above values in the aboveorder.\end{methoddesc} \begin{methoddesc}[aifc]{getmarkers}{}Return a list of markers in the audio file.  A marker consists of atuple of three elements.  The first is the mark ID (an integer), thesecond is the mark position in frames from the beginning of the data(an integer), the third is the name of the mark (a string).\end{methoddesc} \begin{methoddesc}[aifc]{getmark}{id}Return the tuple as described in \method{getmarkers()} for the markwith the given \var{id}.\end{methoddesc} \begin{methoddesc}[aifc]{readframes}{nframes}Read and return the next \var{nframes} frames from the audio file.  Thereturned data is a string containing for each frame the uncompressedsamples of all channels.\end{methoddesc} \begin{methoddesc}[aifc]{rewind}{}Rewind the read pointer.  The next \method{readframes()} will start fromthe beginning.\end{methoddesc} \begin{methoddesc}[aifc]{setpos}{pos}Seek to the specified frame number.\end{methoddesc} \begin{methoddesc}[aifc]{tell}{}Return the current frame number.\end{methoddesc} \begin{methoddesc}[aifc]{close}{}Close the AIFF file.  After calling this method, the object can nolonger be used.\end{methoddesc} Objects returned by \function{open()} when a file is opened forwriting have all the above methods, except for \method{readframes()} and\method{setpos()}.  In addition the following methods exist.  The\method{get*()} methods can only be called after the corresponding\method{set*()} methods have been called.  Before the first\method{writeframes()} or \method{writeframesraw()}, all parametersexcept for the number of frames must be filled in. \begin{methoddesc}[aifc]{aiff}{}Create an AIFF file.  The default is that an AIFF-C file is created,unless the name of the file ends in \code{'.aiff'} in which case thedefault is an AIFF file.\end{methoddesc} \begin{methoddesc}[aifc]{aifc}{}Create an AIFF-C file.  The default is that an AIFF-C file is created,unless the name of the file ends in \code{'.aiff'} in which case thedefault is an AIFF file.\end{methoddesc} \begin{methoddesc}[aifc]{setnchannels}{nchannels}Specify the number of channels in the audio file.\end{methoddesc} \begin{methoddesc}[aifc]{setsampwidth}{width}Specify the size in bytes of audio samples.\end{methoddesc} \begin{methoddesc}[aifc]{setframerate}{rate}Specify the sampling frequency in frames per second.\end{methoddesc} \begin{methoddesc}[aifc]{setnframes}{nframes}Specify the number of frames that are to be written to the audio file.If this parameter is not set, or not set correctly, the file needs tosupport seeking.\end{methoddesc} \begin{methoddesc}[aifc]{setcomptype}{type, name}Specify the compression type.  If not specified, the audio data willnot be compressed.  In AIFF files, compression is not possible.  Thename parameter should be a human-readable description of thecompression type, the type parameter should be a four-characterstring.  Currently the following compression types are supported:NONE, ULAW, ALAW, G722.\index{u-LAW}\index{A-LAW}\index{G.722}\end{methoddesc} \begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname}Set all the above parameters at once.  The argument is a tupleconsisting of the various parameters.  This means that it is possibleto use the result of a \method{getparams()} call as argument to\method{setparams()}.\end{methoddesc} \begin{methoddesc}[aifc]{setmark}{id, pos, name}Add a mark with the given id (larger than 0), and the given name atthe given position.  This method can be called at any time before\method{close()}.\end{methoddesc} \begin{methoddesc}[aifc]{tell}{}Return the current write position in the output file.  Useful incombination with \method{setmark()}.\end{methoddesc} \begin{methoddesc}[aifc]{writeframes}{data}Write data to the output file.  This method can only be called afterthe audio file parameters have been set.\end{methoddesc} \begin{methoddesc}[aifc]{writeframesraw}{data}Like \method{writeframes()}, except that the header of the audio fileis not updated.\end{methoddesc} \begin{methoddesc}[aifc]{close}{}Close the AIFF file.  The header of the file is updated to reflect theactual size of the audio data. After calling this method, the objectcan no longer be used.\end{methoddesc}