Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Raymond Hettinger | ead4975 | 2011-01-24 16:28:06 +0000 | [diff] [blame] | 13 | **Source code:** :source:`Lib/aifc.py` |
| 14 | |
| 15 | -------------- |
| 16 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | e720c0a | 2009-04-27 16:20:50 +0000 | [diff] [blame] | 22 | .. note:: |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 23 | |
Guido van Rossum | da27fd2 | 2007-08-17 00:24:54 +0000 | [diff] [blame] | 24 | Some operations may only work under IRIX; these will raise :exc:`ImportError` |
Georg Brandl | e720c0a | 2009-04-27 16:20:50 +0000 | [diff] [blame] | 25 | when attempting to import the :mod:`cl` module, which is only available on |
| 26 | IRIX. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | 1a51b55 | 2013-10-21 09:07:31 +0200 | [diff] [blame^] | 33 | ``nchannels * samplesize`` bytes, and a second's worth of audio consists of |
| 34 | ``nchannels * samplesize * framerate`` bytes. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Georg Brandl | b868a66 | 2009-04-02 02:56:10 +0000 | [diff] [blame] | 44 | .. function:: open(file, mode=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | |
| 46 | Open an AIFF or AIFF-C file and return an object instance with methods that are |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 47 | described below. The argument *file* is either a string naming a file or a |
| 48 | :term:`file object`. *mode* must be ``'r'`` or ``'rb'`` when the file must be |
| 49 | opened for reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing. |
| 50 | If omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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`. |
R David Murray | c91d5ee | 2013-07-31 13:46:08 -0400 | [diff] [blame] | 54 | The :func:`.open` function may be used in a :keyword:`with` statement. When |
| 55 | the :keyword:`with` block completes, the :meth:`~aifc.close` method is called. |
Serhiy Storchaka | 44c66c7 | 2012-12-29 22:54:49 +0200 | [diff] [blame] | 56 | |
| 57 | .. versionchanged:: 3.4 |
| 58 | Support for the :keyword:`with` statement was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 60 | Objects returned by :func:`.open` when a file is opened for reading have the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | following methods: |
| 62 | |
| 63 | |
| 64 | .. method:: aifc.getnchannels() |
| 65 | |
| 66 | Return the number of audio channels (1 for mono, 2 for stereo). |
| 67 | |
| 68 | |
| 69 | .. method:: aifc.getsampwidth() |
| 70 | |
| 71 | Return the size in bytes of individual samples. |
| 72 | |
| 73 | |
| 74 | .. method:: aifc.getframerate() |
| 75 | |
| 76 | Return the sampling rate (number of audio frames per second). |
| 77 | |
| 78 | |
| 79 | .. method:: aifc.getnframes() |
| 80 | |
| 81 | Return the number of audio frames in the file. |
| 82 | |
| 83 | |
| 84 | .. method:: aifc.getcomptype() |
| 85 | |
R. David Murray | e08a66a | 2009-04-29 21:50:39 +0000 | [diff] [blame] | 86 | Return a bytes array of length 4 describing the type of compression |
| 87 | used in the audio file. For AIFF files, the returned value is |
| 88 | ``b'NONE'``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | |
| 90 | |
| 91 | .. method:: aifc.getcompname() |
| 92 | |
R. David Murray | e08a66a | 2009-04-29 21:50:39 +0000 | [diff] [blame] | 93 | Return a bytes array convertible to a human-readable description |
| 94 | of the type of compression used in the audio file. For AIFF files, |
| 95 | the returned value is ``b'not compressed'``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
| 97 | |
| 98 | .. method:: aifc.getparams() |
| 99 | |
R David Murray | 4d35e75 | 2013-07-25 16:12:01 -0400 | [diff] [blame] | 100 | Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, |
| 101 | framerate, nframes, comptype, compname)``, equivalent to output of the |
| 102 | :meth:`get\*` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 103 | |
| 104 | |
| 105 | .. method:: aifc.getmarkers() |
| 106 | |
| 107 | Return a list of markers in the audio file. A marker consists of a tuple of |
| 108 | three elements. The first is the mark ID (an integer), the second is the mark |
| 109 | position in frames from the beginning of the data (an integer), the third is the |
| 110 | name of the mark (a string). |
| 111 | |
| 112 | |
| 113 | .. method:: aifc.getmark(id) |
| 114 | |
| 115 | Return the tuple as described in :meth:`getmarkers` for the mark with the given |
| 116 | *id*. |
| 117 | |
| 118 | |
| 119 | .. method:: aifc.readframes(nframes) |
| 120 | |
| 121 | Read and return the next *nframes* frames from the audio file. The returned |
| 122 | data is a string containing for each frame the uncompressed samples of all |
| 123 | channels. |
| 124 | |
| 125 | |
| 126 | .. method:: aifc.rewind() |
| 127 | |
| 128 | Rewind the read pointer. The next :meth:`readframes` will start from the |
| 129 | beginning. |
| 130 | |
| 131 | |
| 132 | .. method:: aifc.setpos(pos) |
| 133 | |
| 134 | Seek to the specified frame number. |
| 135 | |
| 136 | |
| 137 | .. method:: aifc.tell() |
| 138 | |
| 139 | Return the current frame number. |
| 140 | |
| 141 | |
| 142 | .. method:: aifc.close() |
| 143 | |
| 144 | Close the AIFF file. After calling this method, the object can no longer be |
| 145 | used. |
| 146 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 147 | Objects returned by :func:`.open` when a file is opened for writing have all the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 148 | above methods, except for :meth:`readframes` and :meth:`setpos`. In addition |
| 149 | the following methods exist. The :meth:`get\*` methods can only be called after |
| 150 | the corresponding :meth:`set\*` methods have been called. Before the first |
| 151 | :meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the |
| 152 | number of frames must be filled in. |
| 153 | |
| 154 | |
| 155 | .. method:: aifc.aiff() |
| 156 | |
| 157 | Create an AIFF file. The default is that an AIFF-C file is created, unless the |
| 158 | name of the file ends in ``'.aiff'`` in which case the default is an AIFF file. |
| 159 | |
| 160 | |
| 161 | .. method:: aifc.aifc() |
| 162 | |
| 163 | Create an AIFF-C file. The default is that an AIFF-C file is created, unless |
| 164 | the name of the file ends in ``'.aiff'`` in which case the default is an AIFF |
| 165 | file. |
| 166 | |
| 167 | |
| 168 | .. method:: aifc.setnchannels(nchannels) |
| 169 | |
| 170 | Specify the number of channels in the audio file. |
| 171 | |
| 172 | |
| 173 | .. method:: aifc.setsampwidth(width) |
| 174 | |
| 175 | Specify the size in bytes of audio samples. |
| 176 | |
| 177 | |
| 178 | .. method:: aifc.setframerate(rate) |
| 179 | |
| 180 | Specify the sampling frequency in frames per second. |
| 181 | |
| 182 | |
| 183 | .. method:: aifc.setnframes(nframes) |
| 184 | |
| 185 | Specify the number of frames that are to be written to the audio file. If this |
| 186 | parameter is not set, or not set correctly, the file needs to support seeking. |
| 187 | |
| 188 | |
| 189 | .. method:: aifc.setcomptype(type, name) |
| 190 | |
| 191 | .. index:: |
| 192 | single: u-LAW |
| 193 | single: A-LAW |
| 194 | single: G.722 |
| 195 | |
R. David Murray | e08a66a | 2009-04-29 21:50:39 +0000 | [diff] [blame] | 196 | Specify the compression type. If not specified, the audio data will |
| 197 | not be compressed. In AIFF files, compression is not possible. |
| 198 | The name parameter should be a human-readable description of the |
| 199 | compression type as a bytes array, the type parameter should be a |
| 200 | bytes array of length 4. Currently the following compression types |
| 201 | are supported: ``b'NONE'``, ``b'ULAW'``, ``b'ALAW'``, ``b'G722'``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 202 | |
| 203 | |
| 204 | .. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname) |
| 205 | |
| 206 | Set all the above parameters at once. The argument is a tuple consisting of the |
| 207 | various parameters. This means that it is possible to use the result of a |
| 208 | :meth:`getparams` call as argument to :meth:`setparams`. |
| 209 | |
| 210 | |
| 211 | .. method:: aifc.setmark(id, pos, name) |
| 212 | |
| 213 | Add a mark with the given id (larger than 0), and the given name at the given |
| 214 | position. This method can be called at any time before :meth:`close`. |
| 215 | |
| 216 | |
| 217 | .. method:: aifc.tell() |
| 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 | |
| 229 | .. method:: aifc.writeframesraw(data) |
| 230 | |
| 231 | Like :meth:`writeframes`, except that the header of the audio file is not |
| 232 | updated. |
| 233 | |
| 234 | |
| 235 | .. method:: aifc.close() |
| 236 | |
| 237 | Close the AIFF file. The header of the file is updated to reflect the actual |
| 238 | size of the audio data. After calling this method, the object can no longer be |
| 239 | used. |
| 240 | |