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