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