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