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 (a] zadka.site.co.il> 8 9 **Source code:** :source:`Lib/sunau.py` 10 11 -------------- 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 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 62 .. function:: openfp(file, mode) 63 64 A synonym for :func:`.open`, maintained for backwards compatibility. 65 66 .. deprecated-removed:: 3.7 3.9 67 68 69 The :mod:`sunau` module defines the following exception: 70 71 .. exception:: Error 72 73 An error raised when something is impossible because of Sun AU specs or 74 implementation deficiency. 75 76 77 The :mod:`sunau` module defines the following data items: 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 112 AU_read objects, as returned by :func:`.open` above, have the following methods: 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 123 Returns number of audio channels (1 for mono, 2 for stereo). 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 156 Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, 157 framerate, nframes, comptype, compname)``, equivalent to output of the 158 :meth:`get\*` methods. 159 160 161 .. method:: AU_read.readframes(n) 162 163 Reads and returns at most *n* frames of audio, as a :class:`bytes` object. The data 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 206 AU_write objects, as returned by :func:`.open` above, have the following methods: 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 218 .. versionchanged:: 3.4 219 Added support for 24-bit samples. 220 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 256 .. versionchanged:: 3.4 257 Any :term:`bytes-like object` is now accepted. 258 259 260 .. method:: AU_write.writeframes(data) 261 262 Write audio frames and make sure *nframes* is correct. 263 264 .. versionchanged:: 3.4 265 Any :term:`bytes-like object` is now accepted. 266 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 277
