1:mod:`aifc` --- Read and write AIFF and AIFC files
2==================================================
3
4.. module:: aifc
5   :synopsis: Read and write audio files in AIFF or AIFC format.
6
7
8.. index::
9   single: Audio Interchange File Format
10   single: AIFF
11   single: AIFF-C
12
13**Source code:** :source:`Lib/aifc.py`
14
15--------------
16
17This module provides support for reading and writing AIFF and AIFF-C files.
18AIFF is Audio Interchange File Format, a format for storing digital audio
19samples in a file.  AIFF-C is a newer version of the format that includes the
20ability to compress the audio data.
21
22.. note::
23
24   Some operations may only work under IRIX; these will raise :exc:`ImportError`
25   when attempting to import the :mod:`cl` module, which is only available on
26   IRIX.
27
28Audio files have a number of parameters that describe the audio data. The
29sampling rate or frame rate is the number of times per second the sound is
30sampled.  The number of channels indicate if the audio is mono, stereo, or
31quadro.  Each frame consists of one sample per channel.  The sample size is the
32size in bytes of each sample.  Thus a frame consists of
33*nchannels*\*\ *samplesize* bytes, and a second's worth of audio consists of
34*nchannels*\*\ *samplesize*\*\ *framerate* bytes.
35
36For example, CD quality audio has a sample size of two bytes (16 bits), uses two
37channels (stereo) and has a frame rate of 44,100 frames/second.  This gives a
38frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes
39(176,400 bytes).
40
41Module :mod:`aifc` defines the following function:
42
43
44.. function:: open(file[, mode])
45
46   Open an AIFF or AIFF-C file and return an object instance with methods that are
47   described below.  The argument *file* is either a string naming a file or a file
48   object.  *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
49   reading, or ``'w'``  or ``'wb'`` when the file must be opened for writing.  If
50   omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used.  When
51   used for writing, the file object should be seekable, unless you know ahead of
52   time how many samples you are going to write in total and use
53   :meth:`writeframesraw` and :meth:`setnframes`.
54
55Objects returned by :func:`.open` when a file is opened for reading have the
56following methods:
57
58
59.. method:: aifc.getnchannels()
60
61   Return the number of audio channels (1 for mono, 2 for stereo).
62
63
64.. method:: aifc.getsampwidth()
65
66   Return the size in bytes of individual samples.
67
68
69.. method:: aifc.getframerate()
70
71   Return the sampling rate (number of audio frames per second).
72
73
74.. method:: aifc.getnframes()
75
76   Return the number of audio frames in the file.
77
78
79.. method:: aifc.getcomptype()
80
81   Return a four-character string describing the type of compression used in the
82   audio file.  For AIFF files, the returned value is ``'NONE'``.
83
84
85.. method:: aifc.getcompname()
86
87   Return a human-readable description of the type of compression used in the audio
88   file.  For AIFF files, the returned value is ``'not compressed'``.
89
90
91.. method:: aifc.getparams()
92
93   Return a tuple consisting of all of the above values in the above order.
94
95
96.. method:: aifc.getmarkers()
97
98   Return a list of markers in the audio file.  A marker consists of a tuple of
99   three elements.  The first is the mark ID (an integer), the second is the mark
100   position in frames from the beginning of the data (an integer), the third is the
101   name of the mark (a string).
102
103
104.. method:: aifc.getmark(id)
105
106   Return the tuple as described in :meth:`getmarkers` for the mark with the given
107   *id*.
108
109
110.. method:: aifc.readframes(nframes)
111
112   Read and return the next *nframes* frames from the audio file.  The returned
113   data is a string containing for each frame the uncompressed samples of all
114   channels.
115
116
117.. method:: aifc.rewind()
118
119   Rewind the read pointer.  The next :meth:`readframes` will start from the
120   beginning.
121
122
123.. method:: aifc.setpos(pos)
124
125   Seek to the specified frame number.
126
127
128.. method:: aifc.tell()
129
130   Return the current frame number.
131
132
133.. method:: aifc.close()
134
135   Close the AIFF file.  After calling this method, the object can no longer be
136   used.
137
138Objects returned by :func:`.open` when a file is opened for writing have all the
139above methods, except for :meth:`readframes` and :meth:`setpos`.  In addition
140the following methods exist.  The :meth:`get\*` methods can only be called after
141the corresponding :meth:`set\*` methods have been called.  Before the first
142:meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the
143number of frames must be filled in.
144
145
146.. method:: aifc.aiff()
147
148   Create an AIFF file.  The default is that an AIFF-C file is created, unless the
149   name of the file ends in ``'.aiff'`` in which case the default is an AIFF file.
150
151
152.. method:: aifc.aifc()
153
154   Create an AIFF-C file.  The default is that an AIFF-C file is created, unless
155   the name of the file ends in ``'.aiff'`` in which case the default is an AIFF
156   file.
157
158
159.. method:: aifc.setnchannels(nchannels)
160
161   Specify the number of channels in the audio file.
162
163
164.. method:: aifc.setsampwidth(width)
165
166   Specify the size in bytes of audio samples.
167
168
169.. method:: aifc.setframerate(rate)
170
171   Specify the sampling frequency in frames per second.
172
173
174.. method:: aifc.setnframes(nframes)
175
176   Specify the number of frames that are to be written to the audio file. If this
177   parameter is not set, or not set correctly, the file needs to support seeking.
178
179
180.. method:: aifc.setcomptype(type, name)
181
182   .. index::
183      single: u-LAW
184      single: A-LAW
185      single: G.722
186
187   Specify the compression type.  If not specified, the audio data will not be
188   compressed.  In AIFF files, compression is not possible.  The name parameter
189   should be a human-readable description of the compression type, the type
190   parameter should be a four-character string.  Currently the following
191   compression types are supported: NONE, ULAW, ALAW, G722.
192
193
194.. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)
195
196   Set all the above parameters at once.  The argument is a tuple consisting of the
197   various parameters.  This means that it is possible to use the result of a
198   :meth:`getparams` call as argument to :meth:`setparams`.
199
200
201.. method:: aifc.setmark(id, pos, name)
202
203   Add a mark with the given id (larger than 0), and the given name at the given
204   position.  This method can be called at any time before :meth:`close`.
205
206
207.. method:: aifc.tell()
208
209   Return the current write position in the output file.  Useful in combination
210   with :meth:`setmark`.
211
212
213.. method:: aifc.writeframes(data)
214
215   Write data to the output file.  This method can only be called after the audio
216   file parameters have been set.
217
218
219.. method:: aifc.writeframesraw(data)
220
221   Like :meth:`writeframes`, except that the header of the audio file is not
222   updated.
223
224
225.. method:: aifc.close()
226
227   Close the AIFF file.  The header of the file is updated to reflect the actual
228   size of the audio data. After calling this method, the object can no longer be
229   used.
230
231