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