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