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