Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`sunau` --- Read and write Sun AU files |
| 2 | ============================================ |
| 3 | |
| 4 | .. module:: sunau |
| 5 | :synopsis: Provide an interface to the Sun AU sound format. |
| 6 | .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> |
| 7 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 8 | **Source code:** :source:`Lib/sunau.py` |
| 9 | |
| 10 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | |
| 12 | The :mod:`sunau` module provides a convenient interface to the Sun AU sound |
| 13 | format. Note that this module is interface-compatible with the modules |
| 14 | :mod:`aifc` and :mod:`wave`. |
| 15 | |
| 16 | An audio file consists of a header followed by the data. The fields of the |
| 17 | header are: |
| 18 | |
| 19 | +---------------+-----------------------------------------------+ |
| 20 | | Field | Contents | |
| 21 | +===============+===============================================+ |
| 22 | | magic word | The four bytes ``.snd``. | |
| 23 | +---------------+-----------------------------------------------+ |
| 24 | | header size | Size of the header, including info, in bytes. | |
| 25 | +---------------+-----------------------------------------------+ |
| 26 | | data size | Physical size of the data, in bytes. | |
| 27 | +---------------+-----------------------------------------------+ |
| 28 | | encoding | Indicates how the audio samples are encoded. | |
| 29 | +---------------+-----------------------------------------------+ |
| 30 | | sample rate | The sampling rate. | |
| 31 | +---------------+-----------------------------------------------+ |
| 32 | | # of channels | The number of channels in the samples. | |
| 33 | +---------------+-----------------------------------------------+ |
| 34 | | info | ASCII string giving a description of the | |
| 35 | | | audio file (padded with null bytes). | |
| 36 | +---------------+-----------------------------------------------+ |
| 37 | |
| 38 | Apart from the info field, all header fields are 4 bytes in size. They are all |
| 39 | 32-bit unsigned integers encoded in big-endian byte order. |
| 40 | |
| 41 | The :mod:`sunau` module defines the following functions: |
| 42 | |
| 43 | |
| 44 | .. function:: open(file, mode) |
| 45 | |
| 46 | If *file* is a string, open the file by that name, otherwise treat it as a |
| 47 | seekable file-like object. *mode* can be any of |
| 48 | |
| 49 | ``'r'`` |
| 50 | Read only mode. |
| 51 | |
| 52 | ``'w'`` |
| 53 | Write only mode. |
| 54 | |
| 55 | Note that it does not allow read/write files. |
| 56 | |
| 57 | A *mode* of ``'r'`` returns a :class:`AU_read` object, while a *mode* of ``'w'`` |
| 58 | or ``'wb'`` returns a :class:`AU_write` object. |
| 59 | |
| 60 | |
| 61 | .. function:: openfp(file, mode) |
| 62 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 63 | A synonym for :func:`.open`, maintained for backwards compatibility. |
| 64 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
| 66 | The :mod:`sunau` module defines the following exception: |
| 67 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | .. exception:: Error |
| 69 | |
| 70 | An error raised when something is impossible because of Sun AU specs or |
| 71 | implementation deficiency. |
| 72 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 74 | The :mod:`sunau` module defines the following data items: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
| 76 | .. data:: AUDIO_FILE_MAGIC |
| 77 | |
| 78 | An integer every valid Sun AU file begins with, stored in big-endian form. This |
| 79 | is the string ``.snd`` interpreted as an integer. |
| 80 | |
| 81 | |
| 82 | .. data:: AUDIO_FILE_ENCODING_MULAW_8 |
| 83 | AUDIO_FILE_ENCODING_LINEAR_8 |
| 84 | AUDIO_FILE_ENCODING_LINEAR_16 |
| 85 | AUDIO_FILE_ENCODING_LINEAR_24 |
| 86 | AUDIO_FILE_ENCODING_LINEAR_32 |
| 87 | AUDIO_FILE_ENCODING_ALAW_8 |
| 88 | |
| 89 | Values of the encoding field from the AU header which are supported by this |
| 90 | module. |
| 91 | |
| 92 | |
| 93 | .. data:: AUDIO_FILE_ENCODING_FLOAT |
| 94 | AUDIO_FILE_ENCODING_DOUBLE |
| 95 | AUDIO_FILE_ENCODING_ADPCM_G721 |
| 96 | AUDIO_FILE_ENCODING_ADPCM_G722 |
| 97 | AUDIO_FILE_ENCODING_ADPCM_G723_3 |
| 98 | AUDIO_FILE_ENCODING_ADPCM_G723_5 |
| 99 | |
| 100 | Additional known values of the encoding field from the AU header, but which are |
| 101 | not supported by this module. |
| 102 | |
| 103 | |
| 104 | .. _au-read-objects: |
| 105 | |
| 106 | AU_read Objects |
| 107 | --------------- |
| 108 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 109 | AU_read objects, as returned by :func:`.open` above, have the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
| 111 | |
| 112 | .. method:: AU_read.close() |
| 113 | |
| 114 | Close the stream, and make the instance unusable. (This is called automatically |
| 115 | on deletion.) |
| 116 | |
| 117 | |
| 118 | .. method:: AU_read.getnchannels() |
| 119 | |
| 120 | Returns number of audio channels (1 for mone, 2 for stereo). |
| 121 | |
| 122 | |
| 123 | .. method:: AU_read.getsampwidth() |
| 124 | |
| 125 | Returns sample width in bytes. |
| 126 | |
| 127 | |
| 128 | .. method:: AU_read.getframerate() |
| 129 | |
| 130 | Returns sampling frequency. |
| 131 | |
| 132 | |
| 133 | .. method:: AU_read.getnframes() |
| 134 | |
| 135 | Returns number of audio frames. |
| 136 | |
| 137 | |
| 138 | .. method:: AU_read.getcomptype() |
| 139 | |
| 140 | Returns compression type. Supported compression types are ``'ULAW'``, ``'ALAW'`` |
| 141 | and ``'NONE'``. |
| 142 | |
| 143 | |
| 144 | .. method:: AU_read.getcompname() |
| 145 | |
| 146 | Human-readable version of :meth:`getcomptype`. The supported types have the |
| 147 | respective names ``'CCITT G.711 u-law'``, ``'CCITT G.711 A-law'`` and ``'not |
| 148 | compressed'``. |
| 149 | |
| 150 | |
| 151 | .. method:: AU_read.getparams() |
| 152 | |
Serhiy Storchaka | e06a896 | 2013-09-04 00:43:03 +0300 | [diff] [blame] | 153 | Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, |
| 154 | framerate, nframes, comptype, compname)``, equivalent to output of the |
| 155 | :meth:`get\*` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
| 157 | |
| 158 | .. method:: AU_read.readframes(n) |
| 159 | |
| 160 | Reads and returns at most *n* frames of audio, as a string of bytes. The data |
| 161 | will be returned in linear format. If the original data is in u-LAW format, it |
| 162 | will be converted. |
| 163 | |
| 164 | |
| 165 | .. method:: AU_read.rewind() |
| 166 | |
| 167 | Rewind the file pointer to the beginning of the audio stream. |
| 168 | |
| 169 | The following two methods define a term "position" which is compatible between |
| 170 | them, and is otherwise implementation dependent. |
| 171 | |
| 172 | |
| 173 | .. method:: AU_read.setpos(pos) |
| 174 | |
| 175 | Set the file pointer to the specified position. Only values returned from |
| 176 | :meth:`tell` should be used for *pos*. |
| 177 | |
| 178 | |
| 179 | .. method:: AU_read.tell() |
| 180 | |
| 181 | Return current file pointer position. Note that the returned value has nothing |
| 182 | to do with the actual position in the file. |
| 183 | |
| 184 | The following two functions are defined for compatibility with the :mod:`aifc`, |
| 185 | and don't do anything interesting. |
| 186 | |
| 187 | |
| 188 | .. method:: AU_read.getmarkers() |
| 189 | |
| 190 | Returns ``None``. |
| 191 | |
| 192 | |
| 193 | .. method:: AU_read.getmark(id) |
| 194 | |
| 195 | Raise an error. |
| 196 | |
| 197 | |
| 198 | .. _au-write-objects: |
| 199 | |
| 200 | AU_write Objects |
| 201 | ---------------- |
| 202 | |
Georg Brandl | 502d9a5 | 2009-07-26 15:02:41 +0000 | [diff] [blame] | 203 | AU_write objects, as returned by :func:`.open` above, have the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 204 | |
| 205 | |
| 206 | .. method:: AU_write.setnchannels(n) |
| 207 | |
| 208 | Set the number of channels. |
| 209 | |
| 210 | |
| 211 | .. method:: AU_write.setsampwidth(n) |
| 212 | |
| 213 | Set the sample width (in bytes.) |
| 214 | |
Serhiy Storchaka | 81895f8 | 2013-11-10 21:02:53 +0200 | [diff] [blame] | 215 | .. versionchanged:: 3.4 |
| 216 | Added support for 24-bit samples. |
| 217 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 218 | |
| 219 | .. method:: AU_write.setframerate(n) |
| 220 | |
| 221 | Set the frame rate. |
| 222 | |
| 223 | |
| 224 | .. method:: AU_write.setnframes(n) |
| 225 | |
| 226 | Set the number of frames. This can be later changed, when and if more frames |
| 227 | are written. |
| 228 | |
| 229 | |
| 230 | .. method:: AU_write.setcomptype(type, name) |
| 231 | |
| 232 | Set the compression type and description. Only ``'NONE'`` and ``'ULAW'`` are |
| 233 | supported on output. |
| 234 | |
| 235 | |
| 236 | .. method:: AU_write.setparams(tuple) |
| 237 | |
| 238 | The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype, |
| 239 | compname)``, with values valid for the :meth:`set\*` methods. Set all |
| 240 | parameters. |
| 241 | |
| 242 | |
| 243 | .. method:: AU_write.tell() |
| 244 | |
| 245 | Return current position in the file, with the same disclaimer for the |
| 246 | :meth:`AU_read.tell` and :meth:`AU_read.setpos` methods. |
| 247 | |
| 248 | |
| 249 | .. method:: AU_write.writeframesraw(data) |
| 250 | |
| 251 | Write audio frames, without correcting *nframes*. |
| 252 | |
Serhiy Storchaka | 452bab4 | 2013-11-16 14:01:31 +0200 | [diff] [blame] | 253 | .. versionchanged:: 3.4 |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 254 | Any :term:`bytes-like object` is now accepted. |
Serhiy Storchaka | 452bab4 | 2013-11-16 14:01:31 +0200 | [diff] [blame] | 255 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 256 | |
| 257 | .. method:: AU_write.writeframes(data) |
| 258 | |
| 259 | Write audio frames and make sure *nframes* is correct. |
| 260 | |
Serhiy Storchaka | 452bab4 | 2013-11-16 14:01:31 +0200 | [diff] [blame] | 261 | .. versionchanged:: 3.4 |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 262 | Any :term:`bytes-like object` is now accepted. |
Serhiy Storchaka | 452bab4 | 2013-11-16 14:01:31 +0200 | [diff] [blame] | 263 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 264 | |
| 265 | .. method:: AU_write.close() |
| 266 | |
| 267 | Make sure *nframes* is correct, and close the file. |
| 268 | |
| 269 | This method is called upon deletion. |
| 270 | |
| 271 | Note that it is invalid to set any parameters after calling :meth:`writeframes` |
| 272 | or :meth:`writeframesraw`. |
| 273 | |