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