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 8**Source code:** :source:`Lib/sunau.py` 9 10-------------- 11 12The :mod:`sunau` module provides a convenient interface to the Sun AU sound 13format. Note that this module is interface-compatible with the modules 14:mod:`aifc` and :mod:`wave`. 15 16An audio file consists of a header followed by the data. The fields of the 17header 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 38Apart from the info field, all header fields are 4 bytes in size. They are all 3932-bit unsigned integers encoded in big-endian byte order. 40 41The :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 an :class:`AU_read` object, while a *mode* of ``'w'`` 58 or ``'wb'`` returns an :class:`AU_write` object. 59 60 61.. function:: openfp(file, mode) 62 63 A synonym for :func:`.open`, maintained for backwards compatibility. 64 65 66The :mod:`sunau` module defines the following exception: 67 68.. exception:: Error 69 70 An error raised when something is impossible because of Sun AU specs or 71 implementation deficiency. 72 73 74The :mod:`sunau` module defines the following data items: 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 106AU_read Objects 107--------------- 108 109AU_read objects, as returned by :func:`.open` above, have the following methods: 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 153 Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype, 154 compname)``, equivalent to output of the :meth:`get\*` methods. 155 156 157.. method:: AU_read.readframes(n) 158 159 Reads and returns at most *n* frames of audio, as a string of bytes. The data 160 will be returned in linear format. If the original data is in u-LAW format, it 161 will be converted. 162 163 164.. method:: AU_read.rewind() 165 166 Rewind the file pointer to the beginning of the audio stream. 167 168The following two methods define a term "position" which is compatible between 169them, and is otherwise implementation dependent. 170 171 172.. method:: AU_read.setpos(pos) 173 174 Set the file pointer to the specified position. Only values returned from 175 :meth:`tell` should be used for *pos*. 176 177 178.. method:: AU_read.tell() 179 180 Return current file pointer position. Note that the returned value has nothing 181 to do with the actual position in the file. 182 183The following two functions are defined for compatibility with the :mod:`aifc`, 184and don't do anything interesting. 185 186 187.. method:: AU_read.getmarkers() 188 189 Returns ``None``. 190 191 192.. method:: AU_read.getmark(id) 193 194 Raise an error. 195 196 197.. _au-write-objects: 198 199AU_write Objects 200---------------- 201 202AU_write objects, as returned by :func:`.open` above, have the following methods: 203 204 205.. method:: AU_write.setnchannels(n) 206 207 Set the number of channels. 208 209 210.. method:: AU_write.setsampwidth(n) 211 212 Set the sample width (in bytes.) 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 250.. method:: AU_write.writeframes(data) 251 252 Write audio frames and make sure *nframes* is correct. 253 254 255.. method:: AU_write.close() 256 257 Make sure *nframes* is correct, and close the file. 258 259 This method is called upon deletion. 260 261Note that it is invalid to set any parameters after calling :meth:`writeframes` 262or :meth:`writeframesraw`. 263 264