Lib/sunau.py

   1 """Stuff to parse Sun and NeXT audio files.
   2
   3 An audio file consists of a header followed by the data.  The structure
   4 of the header is as follows.
   5
   6         +---------------+
   7         | magic word    |
   8         +---------------+
   9         | header size   |
  10         +---------------+
  11         | data size     |
  12         +---------------+
  13         | encoding      |
  14         +---------------+
  15         | sample rate   |
  16         +---------------+
  17         | # of channels |
  18         +---------------+
  19         | info          |
  20         |               |
  21         +---------------+
  22
  23 The magic word consists of the 4 characters '.snd'.  Apart from the
  24 info field, all header fields are 4 bytes in size.  They are all
  25 32-bit unsigned integers encoded in big-endian byte order.
  26
  27 The header size really gives the start of the data.
  28 The data size is the physical size of the data.  From the other
  29 parameters the number of frames can be calculated.
  30 The encoding gives the way in which audio samples are encoded.
  31 Possible values are listed below.
  32 The info field currently consists of an ASCII string giving a
  33 human-readable description of the audio file.  The info field is
  34 padded with NUL bytes to the header size.
  35
  36 Usage.
  37
  38 Reading audio files:
  39         f = sunau.open(file, 'r')
  40 where file is either the name of a file or an open file pointer.
  41 The open file pointer must have methods read(), seek(), and close().
  42 When the setpos() and rewind() methods are not used, the seek()
  43 method is not  necessary.
  44
  45 This returns an instance of a class with the following public methods:
  46         getnchannels()  -- returns number of audio channels (1 for
  47                            mono, 2 for stereo)
  48         getsampwidth()  -- returns sample width in bytes
  49         getframerate()  -- returns sampling frequency
  50         getnframes()    -- returns number of audio frames
  51         getcomptype()   -- returns compression type ('NONE' or 'ULAW')
  52         getcompname()   -- returns human-readable version of
  53                            compression type ('not compressed' matches 'NONE')
  54         getparams()     -- returns a tuple consisting of all of the
  55                            above in the above order
  56         getmarkers()    -- returns None (for compatibility with the
  57                            aifc module)
  58         getmark(id)     -- raises an error since the mark does not
  59                            exist (for compatibility with the aifc module)
  60         readframes(n)   -- returns at most n frames of audio
  61         rewind()        -- rewind to the beginning of the audio stream
  62         setpos(pos)     -- seek to the specified position
  63         tell()          -- return the current position
  64         close()         -- close the instance (make it unusable)
  65 The position returned by tell() and the position given to setpos()
  66 are compatible and have nothing to do with the actual position in the
  67 file.
  68 The close() method is called automatically when the class instance
  69 is destroyed.
  70
  71 Writing audio files:
  72         f = sunau.open(file, 'w')
  73 where file is either the name of a file or an open file pointer.
  74 The open file pointer must have methods write(), tell(), seek(), and
  75 close().
  76
  77 This returns an instance of a class with the following public methods:
  78         setnchannels(n) -- set the number of channels
  79         setsampwidth(n) -- set the sample width
  80         setframerate(n) -- set the frame rate
  81         setnframes(n)   -- set the number of frames
  82         setcomptype(type, name)
  83                         -- set the compression type and the
  84                            human-readable compression type
  85         setparams(tuple)-- set all parameters at once
  86         tell()          -- return current position in output file
  87         writeframesraw(data)
  88                         -- write audio frames without pathing up the
  89                            file header
  90         writeframes(data)
  91                         -- write audio frames and patch up the file header
  92         close()         -- patch up the file header and close the
  93                            output file
  94 You should set the parameters before the first writeframesraw or
  95 writeframes.  The total number of frames does not need to be set,
  96 but when it is set to the correct value, the header does not have to
  97 be patched up.
  98 It is best to first set all parameters, perhaps possibly the
  99 compression type, and then write audio frames using writeframesraw.
 100 When all frames have been written, either call writeframes('') or
 101 close() to patch up the sizes in the header.
 102 The close() method is called automatically when the class instance
 103 is destroyed.
 104 """
 105
 106 # from <multimedia/audio_filehdr.h>
 107 AUDIO_FILE_MAGIC = 0x2e736e64
 108 AUDIO_FILE_ENCODING_MULAW_8 = 1
 109 AUDIO_FILE_ENCODING_LINEAR_8 = 2
 110 AUDIO_FILE_ENCODING_LINEAR_16 = 3
 111 AUDIO_FILE_ENCODING_LINEAR_24 = 4
 112 AUDIO_FILE_ENCODING_LINEAR_32 = 5
 113 AUDIO_FILE_ENCODING_FLOAT = 6
 114 AUDIO_FILE_ENCODING_DOUBLE = 7
 115 AUDIO_FILE_ENCODING_ADPCM_G721 = 23
 116 AUDIO_FILE_ENCODING_ADPCM_G722 = 24
 117 AUDIO_FILE_ENCODING_ADPCM_G723_3 = 25
 118 AUDIO_FILE_ENCODING_ADPCM_G723_5 = 26
 119 AUDIO_FILE_ENCODING_ALAW_8 = 27
 120
 121 # from <multimedia/audio_hdr.h>
 122 AUDIO_UNKNOWN_SIZE = 0xFFFFFFFFL        # ((unsigned)(~0))
 123
 124 _simple_encodings = [AUDIO_FILE_ENCODING_MULAW_8,
 125                      AUDIO_FILE_ENCODING_LINEAR_8,
 126                      AUDIO_FILE_ENCODING_LINEAR_16,
 127                      AUDIO_FILE_ENCODING_LINEAR_24,
 128                      AUDIO_FILE_ENCODING_LINEAR_32,
 129                      AUDIO_FILE_ENCODING_ALAW_8]
 130
 131 class Error(Exception):
 132     pass
 133
 134 def _read_u32(file):
 135     x = 0L
 136     for i in range(4):
 137         byte = file.read(1)
 138         if byte == '':
 139             raise EOFError
 140         x = x*256 + ord(byte)
 141     return x
 142
 143 def _write_u32(file, x):
 144     data = []
 145     for i in range(4):
 146         d, m = divmod(x, 256)
 147         data.insert(0, m)
 148         x = d
 149     for i in range(4):
 150         file.write(chr(int(data[i])))
 151
 152 class Au_read:
 153
 154     def __init__(self, f):
 155         if type(f) == type(''):
 156             import __builtin__
 157             f = __builtin__.open(f, 'rb')
 158         self.initfp(f)
 159
 160     def __del__(self):
 161         if self._file:
 162             self.close()
 163
 164     def initfp(self, file):
 165         self._file = file
 166         self._soundpos = 0
 167         magic = int(_read_u32(file))
 168         if magic != AUDIO_FILE_MAGIC:
 169             raise Error, 'bad magic number'
 170         self._hdr_size = int(_read_u32(file))
 171         if self._hdr_size < 24:
 172             raise Error, 'header size too small'
 173         if self._hdr_size > 100:
 174             raise Error, 'header size ridiculously large'
 175         self._data_size = _read_u32(file)
 176         if self._data_size != AUDIO_UNKNOWN_SIZE:
 177             self._data_size = int(self._data_size)
 178         self._encoding = int(_read_u32(file))
 179         if self._encoding not in _simple_encodings:
 180             raise Error, 'encoding not (yet) supported'
 181         if self._encoding in (AUDIO_FILE_ENCODING_MULAW_8,
 182                   AUDIO_FILE_ENCODING_ALAW_8):
 183             self._sampwidth = 2
 184             self._framesize = 1
 185         elif self._encoding == AUDIO_FILE_ENCODING_LINEAR_8:
 186             self._framesize = self._sampwidth = 1
 187         elif self._encoding == AUDIO_FILE_ENCODING_LINEAR_16:
 188             self._framesize = self._sampwidth = 2
 189         elif self._encoding == AUDIO_FILE_ENCODING_LINEAR_24:
 190             self._framesize = self._sampwidth = 3
 191         elif self._encoding == AUDIO_FILE_ENCODING_LINEAR_32:
 192             self._framesize = self._sampwidth = 4
 193         else:
 194             raise Error, 'unknown encoding'
 195         self._framerate = int(_read_u32(file))
 196         self._nchannels = int(_read_u32(file))
 197         self._framesize = self._framesize * self._nchannels
 198         if self._hdr_size > 24:
 199             self._info = file.read(self._hdr_size - 24)
 200             for i in range(len(self._info)):
 201                 if self._info[i] == '\0':
 202                     self._info = self._info[:i]
 203                     break
 204         else:
 205             self._info = ''
 206
 207     def getfp(self):
 208         return self._file
 209
 210     def getnchannels(self):
 211         return self._nchannels
 212
 213     def getsampwidth(self):
 214         return self._sampwidth
 215
 216     def getframerate(self):
 217         return self._framerate
 218
 219     def getnframes(self):
 220         if self._data_size == AUDIO_UNKNOWN_SIZE:
 221             return AUDIO_UNKNOWN_SIZE
 222         if self._encoding in _simple_encodings:
 223             return self._data_size / self._framesize
 224         return 0                # XXX--must do some arithmetic here
 225
 226     def getcomptype(self):
 227         if self._encoding == AUDIO_FILE_ENCODING_MULAW_8:
 228             return 'ULAW'
 229         elif self._encoding == AUDIO_FILE_ENCODING_ALAW_8:
 230             return 'ALAW'
 231         else:
 232             return 'NONE'
 233
 234     def getcompname(self):
 235         if self._encoding == AUDIO_FILE_ENCODING_MULAW_8:
 236             return 'CCITT G.711 u-law'
 237         elif self._encoding == AUDIO_FILE_ENCODING_ALAW_8:
 238             return 'CCITT G.711 A-law'
 239         else:
 240             return 'not compressed'
 241
 242     def getparams(self):
 243         return self.getnchannels(), self.getsampwidth(), \
 244                   self.getframerate(), self.getnframes(), \
 245                   self.getcomptype(), self.getcompname()
 246
 247     def getmarkers(self):
 248         return None
 249
 250     def getmark(self, id):
 251         raise Error, 'no marks'
 252
 253     def readframes(self, nframes):
 254         if self._encoding in _simple_encodings:
 255             if nframes == AUDIO_UNKNOWN_SIZE:
 256                 data = self._file.read()
 257             else:
 258                 data = self._file.read(nframes * self._framesize * self._nchannels)
 259             if self._encoding == AUDIO_FILE_ENCODING_MULAW_8:
 260                 import audioop
 261                 data = audioop.ulaw2lin(data, self._sampwidth)
 262             return data
 263         return None             # XXX--not implemented yet
 264
 265     def rewind(self):
 266         self._soundpos = 0
 267         self._file.seek(self._hdr_size)
 268
 269     def tell(self):
 270         return self._soundpos
 271
 272     def setpos(self, pos):
 273         if pos < 0 or pos > self.getnframes():
 274             raise Error, 'position not in range'
 275         self._file.seek(pos * self._framesize + self._hdr_size)
 276         self._soundpos = pos
 277
 278     def close(self):
 279         self._file = None
 280
 281 class Au_write:
 282
 283     def __init__(self, f):
 284         if type(f) == type(''):
 285             import __builtin__
 286             f = __builtin__.open(f, 'wb')
 287         self.initfp(f)
 288
 289     def __del__(self):
 290         if self._file:
 291             self.close()
 292
 293     def initfp(self, file):
 294         self._file = file
 295         self._framerate = 0
 296         self._nchannels = 0
 297         self._sampwidth = 0
 298         self._framesize = 0
 299         self._nframes = AUDIO_UNKNOWN_SIZE
 300         self._nframeswritten = 0
 301         self._datawritten = 0
 302         self._datalength = 0
 303         self._info = ''
 304         self._comptype = 'ULAW' # default is U-law
 305
 306     def setnchannels(self, nchannels):
 307         if self._nframeswritten:
 308             raise Error, 'cannot change parameters after starting to write'
 309         if nchannels not in (1, 2, 4):
 310             raise Error, 'only 1, 2, or 4 channels supported'
 311         self._nchannels = nchannels
 312
 313     def getnchannels(self):
 314         if not self._nchannels:
 315             raise Error, 'number of channels not set'
 316         return self._nchannels
 317
 318     def setsampwidth(self, sampwidth):
 319         if self._nframeswritten:
 320             raise Error, 'cannot change parameters after starting to write'
 321         if sampwidth not in (1, 2, 4):
 322             raise Error, 'bad sample width'
 323         self._sampwidth = sampwidth
 324
 325     def getsampwidth(self):
 326         if not self._framerate:
 327             raise Error, 'sample width not specified'
 328         return self._sampwidth
 329
 330     def setframerate(self, framerate):
 331         if self._nframeswritten:
 332             raise Error, 'cannot change parameters after starting to write'
 333         self._framerate = framerate
 334
 335     def getframerate(self):
 336         if not self._framerate:
 337             raise Error, 'frame rate not set'
 338         return self._framerate
 339
 340     def setnframes(self, nframes):
 341         if self._nframeswritten:
 342             raise Error, 'cannot change parameters after starting to write'
 343         if nframes < 0:
 344             raise Error, '# of frames cannot be negative'
 345         self._nframes = nframes
 346
 347     def getnframes(self):
 348         return self._nframeswritten
 349
 350     def setcomptype(self, type, name):
 351         if type in ('NONE', 'ULAW'):
 352             self._comptype = type
 353         else:
 354             raise Error, 'unknown compression type'
 355
 356     def getcomptype(self):
 357         return self._comptype
 358
 359     def getcompname(self):
 360         if self._comptype == 'ULAW':
 361             return 'CCITT G.711 u-law'
 362         elif self._comptype == 'ALAW':
 363             return 'CCITT G.711 A-law'
 364         else:
 365             return 'not compressed'
 366
 367     def setparams(self, (nchannels, sampwidth, framerate, nframes, comptype, compname)):
 368         self.setnchannels(nchannels)
 369         self.setsampwidth(sampwidth)
 370         self.setframerate(framerate)
 371         self.setnframes(nframes)
 372         self.setcomptype(comptype, compname)
 373
 374     def getparams(self):
 375         return self.getnchannels(), self.getsampwidth(), \
 376                   self.getframerate(), self.getnframes(), \
 377                   self.getcomptype(), self.getcompname()
 378
 379     def tell(self):
 380         return self._nframeswritten
 381
 382     def writeframesraw(self, data):
 383         self._ensure_header_written()
 384         nframes = len(data) / self._framesize
 385         if self._comptype == 'ULAW':
 386             import audioop
 387             data = audioop.lin2ulaw(data, self._sampwidth)
 388         self._file.write(data)
 389         self._nframeswritten = self._nframeswritten + nframes
 390         self._datawritten = self._datawritten + len(data)
 391
 392     def writeframes(self, data):
 393         self.writeframesraw(data)
 394         if self._nframeswritten != self._nframes or \
 395                   self._datalength != self._datawritten:
 396             self._patchheader()
 397
 398     def close(self):
 399         self._ensure_header_written()
 400         if self._nframeswritten != self._nframes or \
 401                   self._datalength != self._datawritten:
 402             self._patchheader()
 403         self._file.flush()
 404         self._file = None
 405
 406     #
 407     # private methods
 408     #
 409
 410     def _ensure_header_written(self):
 411         if not self._nframeswritten:
 412             if not self._nchannels:
 413                 raise Error, '# of channels not specified'
 414             if not self._sampwidth:
 415                 raise Error, 'sample width not specified'
 416             if not self._framerate:
 417                 raise Error, 'frame rate not specified'
 418             self._write_header()
 419
 420     def _write_header(self):
 421         if self._comptype == 'NONE':
 422             if self._sampwidth == 1:
 423                 encoding = AUDIO_FILE_ENCODING_LINEAR_8
 424                 self._framesize = 1
 425             elif self._sampwidth == 2:
 426                 encoding = AUDIO_FILE_ENCODING_LINEAR_16
 427                 self._framesize = 2
 428             elif self._sampwidth == 4:
 429                 encoding = AUDIO_FILE_ENCODING_LINEAR_32
 430                 self._framesize = 4
 431             else:
 432                 raise Error, 'internal error'
 433         elif self._comptype == 'ULAW':
 434             encoding = AUDIO_FILE_ENCODING_MULAW_8
 435             self._framesize = 1
 436         else:
 437             raise Error, 'internal error'
 438         self._framesize = self._framesize * self._nchannels
 439         _write_u32(self._file, AUDIO_FILE_MAGIC)
 440         header_size = 25 + len(self._info)
 441         header_size = (header_size + 7) & ~7
 442         _write_u32(self._file, header_size)
 443         if self._nframes == AUDIO_UNKNOWN_SIZE:
 444             length = AUDIO_UNKNOWN_SIZE
 445         else:
 446             length = self._nframes * self._framesize
 447         _write_u32(self._file, length)
 448         self._datalength = length
 449         _write_u32(self._file, encoding)
 450         _write_u32(self._file, self._framerate)
 451         _write_u32(self._file, self._nchannels)
 452         self._file.write(self._info)
 453         self._file.write('\0'*(header_size - len(self._info) - 24))
 454
 455     def _patchheader(self):
 456         self._file.seek(8)
 457         _write_u32(self._file, self._datawritten)
 458         self._datalength = self._datawritten
 459         self._file.seek(0, 2)
 460
 461 def open(f, mode=None):
 462     if mode is None:
 463         if hasattr(f, 'mode'):
 464             mode = f.mode
 465         else:
 466             mode = 'rb'
 467     if mode in ('r', 'rb'):
 468         return Au_read(f)
 469     elif mode in ('w', 'wb'):
 470         return Au_write(f)
 471     else:
 472         raise Error, "mode must be 'r', 'rb', 'w', or 'wb'"
 473
 474 openfp = open