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