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 = 0xFFFFFFFF        # ((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 = 0
 136     for i in range(4):
 137         byte = file.read(1)
 138         if not 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, int(m))
 148         x = d
 149     file.write(bytes(data))
 150
 151 class Au_read:
 152
 153     def __init__(self, f):
 154         if type(f) == type(''):
 155             import builtins
 156             f = builtins.open(f, 'rb')
 157         self.initfp(f)
 158
 159     def __del__(self):
 160         if self._file:
 161             self.close()
 162
 163     def initfp(self, file):
 164         self._file = file
 165         self._soundpos = 0
 166         magic = int(_read_u32(file))
 167         if magic != AUDIO_FILE_MAGIC:
 168             raise Error('bad magic number')
 169         self._hdr_size = int(_read_u32(file))
 170         if self._hdr_size < 24:
 171             raise Error('header size too small')
 172         if self._hdr_size > 100:
 173             raise Error('header size ridiculously large')
 174         self._data_size = _read_u32(file)
 175         if self._data_size != AUDIO_UNKNOWN_SIZE:
 176             self._data_size = int(self._data_size)
 177         self._encoding = int(_read_u32(file))
 178         if self._encoding not in _simple_encodings:
 179             raise Error('encoding not (yet) supported')
 180         if self._encoding in (AUDIO_FILE_ENCODING_MULAW_8,
 181                   AUDIO_FILE_ENCODING_ALAW_8):
 182             self._sampwidth = 2
 183             self._framesize = 1
 184         elif self._encoding == AUDIO_FILE_ENCODING_LINEAR_8:
 185             self._framesize = self._sampwidth = 1
 186         elif self._encoding == AUDIO_FILE_ENCODING_LINEAR_16:
 187             self._framesize = self._sampwidth = 2
 188         elif self._encoding == AUDIO_FILE_ENCODING_LINEAR_24:
 189             self._framesize = self._sampwidth = 3
 190         elif self._encoding == AUDIO_FILE_ENCODING_LINEAR_32:
 191             self._framesize = self._sampwidth = 4
 192         else:
 193             raise Error('unknown encoding')
 194         self._framerate = int(_read_u32(file))
 195         self._nchannels = int(_read_u32(file))
 196         self._framesize = self._framesize * self._nchannels
 197         if self._hdr_size > 24:
 198             self._info = file.read(self._hdr_size - 24)
 199             for i in range(len(self._info)):
 200                 if self._info[i] == b'\0':
 201                     self._info = self._info[:i]
 202                     break
 203         else:
 204             self._info = ''
 205
 206     def getfp(self):
 207         return self._file
 208
 209     def getnchannels(self):
 210         return self._nchannels
 211
 212     def getsampwidth(self):
 213         return self._sampwidth
 214
 215     def getframerate(self):
 216         return self._framerate
 217
 218     def getnframes(self):
 219         if self._data_size == AUDIO_UNKNOWN_SIZE:
 220             return AUDIO_UNKNOWN_SIZE
 221         if self._encoding in _simple_encodings:
 222             return self._data_size / self._framesize
 223         return 0                # XXX--must do some arithmetic here
 224
 225     def getcomptype(self):
 226         if self._encoding == AUDIO_FILE_ENCODING_MULAW_8:
 227             return 'ULAW'
 228         elif self._encoding == AUDIO_FILE_ENCODING_ALAW_8:
 229             return 'ALAW'
 230         else:
 231             return 'NONE'
 232
 233     def getcompname(self):
 234         if self._encoding == AUDIO_FILE_ENCODING_MULAW_8:
 235             return 'CCITT G.711 u-law'
 236         elif self._encoding == AUDIO_FILE_ENCODING_ALAW_8:
 237             return 'CCITT G.711 A-law'
 238         else:
 239             return 'not compressed'
 240
 241     def getparams(self):
 242         return self.getnchannels(), self.getsampwidth(), \
 243                   self.getframerate(), self.getnframes(), \
 244                   self.getcomptype(), self.getcompname()
 245
 246     def getmarkers(self):
 247         return None
 248
 249     def getmark(self, id):
 250         raise Error('no marks')
 251
 252     def readframes(self, nframes):
 253         if self._encoding in _simple_encodings:
 254             if nframes == AUDIO_UNKNOWN_SIZE:
 255                 data = self._file.read()
 256             else:
 257                 data = self._file.read(nframes * self._framesize * self._nchannels)
 258             if self._encoding == AUDIO_FILE_ENCODING_MULAW_8:
 259                 import audioop
 260                 data = audioop.ulaw2lin(data, self._sampwidth)
 261             return data
 262         return None             # XXX--not implemented yet
 263
 264     def rewind(self):
 265         self._soundpos = 0
 266         self._file.seek(self._hdr_size)
 267
 268     def tell(self):
 269         return self._soundpos
 270
 271     def setpos(self, pos):
 272         if pos < 0 or pos > self.getnframes():
 273             raise Error('position not in range')
 274         self._file.seek(pos * self._framesize + self._hdr_size)
 275         self._soundpos = pos
 276
 277     def close(self):
 278         self._file = None
 279
 280 class Au_write:
 281
 282     def __init__(self, f):
 283         if type(f) == type(''):
 284             import builtins
 285             f = builtins.open(f, 'wb')
 286         self.initfp(f)
 287
 288     def __del__(self):
 289         if self._file:
 290             self.close()
 291
 292     def initfp(self, file):
 293         self._file = file
 294         self._framerate = 0
 295         self._nchannels = 0
 296         self._sampwidth = 0
 297         self._framesize = 0
 298         self._nframes = AUDIO_UNKNOWN_SIZE
 299         self._nframeswritten = 0
 300         self._datawritten = 0
 301         self._datalength = 0
 302         self._info = ''
 303         self._comptype = 'ULAW' # default is U-law
 304
 305     def setnchannels(self, nchannels):
 306         if self._nframeswritten:
 307             raise Error('cannot change parameters after starting to write')
 308         if nchannels not in (1, 2, 4):
 309             raise Error('only 1, 2, or 4 channels supported')
 310         self._nchannels = nchannels
 311
 312     def getnchannels(self):
 313         if not self._nchannels:
 314             raise Error('number of channels not set')
 315         return self._nchannels
 316
 317     def setsampwidth(self, sampwidth):
 318         if self._nframeswritten:
 319             raise Error('cannot change parameters after starting to write')
 320         if sampwidth not in (1, 2, 4):
 321             raise Error('bad sample width')
 322         self._sampwidth = sampwidth
 323
 324     def getsampwidth(self):
 325         if not self._framerate:
 326             raise Error('sample width not specified')
 327         return self._sampwidth
 328
 329     def setframerate(self, framerate):
 330         if self._nframeswritten:
 331             raise Error('cannot change parameters after starting to write')
 332         self._framerate = framerate
 333
 334     def getframerate(self):
 335         if not self._framerate:
 336             raise Error('frame rate not set')
 337         return self._framerate
 338
 339     def setnframes(self, nframes):
 340         if self._nframeswritten:
 341             raise Error('cannot change parameters after starting to write')
 342         if nframes < 0:
 343             raise Error('# of frames cannot be negative')
 344         self._nframes = nframes
 345
 346     def getnframes(self):
 347         return self._nframeswritten
 348
 349     def setcomptype(self, type, name):
 350         if type in ('NONE', 'ULAW'):
 351             self._comptype = type
 352         else:
 353             raise Error('unknown compression type')
 354
 355     def getcomptype(self):
 356         return self._comptype
 357
 358     def getcompname(self):
 359         if self._comptype == 'ULAW':
 360             return 'CCITT G.711 u-law'
 361         elif self._comptype == 'ALAW':
 362             return 'CCITT G.711 A-law'
 363         else:
 364             return 'not compressed'
 365
 366     def setparams(self, params):
 367         nchannels, sampwidth, framerate, nframes, comptype, compname = params
 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(b'\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