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 17 This module provides support for reading and writing AIFF and AIFF-C files. 18 AIFF is Audio Interchange File Format, a format for storing digital audio 19 samples in a file. AIFF-C is a newer version of the format that includes the 20 ability 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 28 Audio files have a number of parameters that describe the audio data. The 29 sampling rate or frame rate is the number of times per second the sound is 30 sampled. The number of channels indicate if the audio is mono, stereo, or 31 quadro. Each frame consists of one sample per channel. The sample size is the 32 size 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 36 For example, CD quality audio has a sample size of two bytes (16 bits), uses two 37 channels (stereo) and has a frame rate of 44,100 frames/second. This gives a 38 frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes 39 (176,400 bytes). 40 41 Module :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 55 Objects returned by :func:`.open` when a file is opened for reading have the 56 following 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 138 Objects returned by :func:`.open` when a file is opened for writing have all the 139 above methods, except for :meth:`readframes` and :meth:`setpos`. In addition 140 the following methods exist. The :meth:`get\*` methods can only be called after 141 the corresponding :meth:`set\*` methods have been called. Before the first 142 :meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the 143 number 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
