12.3. Standard Module `aifc`

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.

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 nchannels*samplesize bytes, and a second's worth of audio consists of nchannels*samplesize*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, i.e. 176,400 bytes.

Module aifc defines the following function:

open (file, mode) -- function of module aifc: Open an AIFF or AIFF-C file and return an object instance with methods that are described below. The argument file is either a string naming a file or a file object. The mode is either the string 'r' when the file must be opened for reading, or 'w' when the file must be opened for writing. 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 writeframesraw() and setnframes().

Objects returned by aifc.open() when a file is opened for reading have the following methods:

getnchannels () -- Method on aifc object: Return the number of audio channels (1 for mono, 2 for stereo).

getsampwidth () -- Method on aifc object: Return the size in bytes of individual samples.

getframerate () -- Method on aifc object: Return the sampling rate (number of audio frames per second).

getnframes () -- Method on aifc object: Return the number of audio frames in the file.

getcomptype () -- Method on aifc object: Return a four-character string describing the type of compression used in the audio file. For AIFF files, the returned value is 'NONE'.

getcompname () -- Method on aifc object: Return a human-readable description of the type of compression used in the audio file. For AIFF files, the returned value is 'not compressed'.

getparams () -- Method on aifc object: Return a tuple consisting of all of the above values in the above order.

getmarkers () -- Method on aifc object: Return a list of markers in the audio file. A marker consists of a tuple of three elements. The first is the mark ID (an integer), the second is the mark position in frames from the beginning of the data (an integer), the third is the name of the mark (a string).

getmark (id) -- Method on aifc object: Return the tuple as described in getmarkers for the mark with the given id.

readframes (nframes) -- Method on aifc object: Read and return the next nframes frames from the audio file. The returned data is a string containing for each frame the uncompressed samples of all channels.

rewind () -- Method on aifc object: Rewind the read pointer. The next readframes will start from the beginning.

setpos (pos) -- Method on aifc object: Seek to the specified frame number.

tell () -- Method on aifc object: Return the current frame number.

close () -- Method on aifc object: Close the AIFF file. After calling this method, the object can no longer be used.

Objects returned by aifc.open() when a file is opened for writing have all the above methods, except for readframes and setpos. In addition the following methods exist. The get methods can only be called after the corresponding set methods have been called. Before the first writeframes or writeframesraw, all parameters except for the number of frames must be filled in.

aiff () -- Method on aifc object: Create an AIFF file. The default is that an AIFF-C file is created, unless the name of the file ends in '.aiff' in which case the default is an AIFF file.

aifc () -- Method on aifc object: Create an AIFF-C file. The default is that an AIFF-C file is created, unless the name of the file ends in '.aiff' in which case the default is an AIFF file.

setnchannels (nchannels) -- Method on aifc object: Specify the number of channels in the audio file.

setsampwidth (width) -- Method on aifc object: Specify the size in bytes of audio samples.

setframerate (rate) -- Method on aifc object: Specify the sampling frequency in frames per second.

setnframes (nframes) -- Method on aifc object: 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 to support seeking.

setcomptype (type, name) -- Method on aifc object: Specify the compression type. If not specified, the audio data will not be compressed. In AIFF files, compression is not possible. The name parameter should be a human-readable description of the compression type, the type parameter should be a four-character string. Currently the following compression types are supported: NONE, ULAW, ALAW, G722.

setparams (nchannels, sampwidth, framerate, comptype, compname) -- Method on aifc object: Set all the above parameters at once. The argument is a tuple consisting of the various parameters. This means that it is possible to use the result of a getparams call as argument to setparams.

setmark (id, pos, name) -- Method on aifc object: Add a mark with the given id (larger than 0), and the given name at the given position. This method can be called at any time before close.

tell () -- Method on aifc object: Return the current write position in the output file. Useful in combination with setmark.

writeframes (data) -- Method on aifc object: Write data to the output file. This method can only be called after the audio file parameters have been set.

writeframesraw (data) -- Method on aifc object: Like writeframes, except that the header of the audio file is not updated.

close () -- Method on aifc object: Close the AIFF file. The header of the file is updated to reflect the actual size of the audio data. After calling this method, the object can no longer be used.

Next: jpeg Prev: imageop Up: Multimedia Services Top: Top

12.3. Standard Module aifc

12.3. Standard Module `aifc`