/Doc/library/aifc.rst

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