Lib/sunau.py

   1 # Stuff to parse Sun and NeXT audio files.
   2 #
   3 # An audio 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 # parameter 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 postion 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 # from <multimedia/audio_filehdr.h>
 106 AUDIO_FILE_MAGIC = 0x2e736e64
 107 AUDIO_FILE_ENCODING_MULAW_8 = 1
 108 AUDIO_FILE_ENCODING_LINEAR_8 = 2
 109 AUDIO_FILE_ENCODING_LINEAR_16 = 3
 110 AUDIO_FILE_ENCODING_LINEAR_24 = 4
 111 AUDIO_FILE_ENCODING_LINEAR_32 = 5
 112 AUDIO_FILE_ENCODING_FLOAT = 6
 113 AUDIO_FILE_ENCODING_DOUBLE = 7
 114 AUDIO_FILE_ENCODING_ADPCM_G721 = 23
 115 AUDIO_FILE_ENCODING_ADPCM_G722 = 24
 116 AUDIO_FILE_ENCODING_ADPCM_G723_3 = 25
 117 AUDIO_FILE_ENCODING_ADPCM_G723_5 = 26
 118 AUDIO_FILE_ENCODING_ALAW_8 = 27
 119
 120 # from <multimedia/audio_hdr.h>
 121 AUDIO_UNKNOWN_SIZE = 0xFFFFFFFFL        # ((unsigned)(~0))
 122
 123 _simple_encodings = [AUDIO_FILE_ENCODING_MULAW_8,
 124                      AUDIO_FILE_ENCODING_LINEAR_8,
 125                      AUDIO_FILE_ENCODING_LINEAR_16,
 126                      AUDIO_FILE_ENCODING_LINEAR_24,
 127                      AUDIO_FILE_ENCODING_LINEAR_32,
 128                      AUDIO_FILE_ENCODING_ALAW_8]
 129
 130 Error = 'sunau.Error'
 131
 132 def _read_u32(file):
 133         x = 0L
 134         for i in range(4):
 135                 byte = file.read(1)
 136                 if byte == '':
 137                         raise EOFError
 138                 x = x*256 + ord(byte)
 139         return x
 140
 141 def _write_u32(file, x):
 142         data = []
 143         for i in range(4):
 144                 d, m = divmod(x, 256)
 145                 data.insert(0, m)
 146                 x = d
 147         for i in range(4):
 148                 file.write(chr(int(data[i])))
 149
 150 class Au_read:
 151 ##      access _file, _soundpos, _hdr_size, _data_size, _encoding, \
 152 ##                _sampwidth, _framesize, _framerate, _nchannels, \
 153 ##                _info: private
 154
 155         def __init__(self, f):
 156                 if type(f) == type(''):
 157                         import __builtin__
 158                         f = __builtin__.open(f, 'r')
 159                 self.initfp(f)
 160
 161         def __del__(self):
 162                 if self._file:
 163                         self.close()
 164
 165         def initfp(self, file):
 166                 self._file = file
 167                 self._soundpos = 0
 168                 magic = int(_read_u32(file))
 169                 if magic != AUDIO_FILE_MAGIC:
 170                         raise Error, 'bad magic number'
 171                 self._hdr_size = int(_read_u32(file))
 172                 if self._hdr_size < 24:
 173                         raise Error, 'header size too small'
 174                 if self._hdr_size > 100:
 175                         raise Error, 'header size rediculously large'
 176                 self._data_size = _read_u32(file)
 177                 if self._data_size != AUDIO_UNKNOWN_SIZE:
 178                         self._data_size = int(self._data_size)
 179                 self._encoding = int(_read_u32(file))
 180                 if self._encoding not in _simple_encodings:
 181                         raise Error, 'encoding not (yet) supported'
 182                 if self._encoding in (AUDIO_FILE_ENCODING_MULAW_8,
 183                           AUDIO_FILE_ENCODING_LINEAR_8,
 184                           AUDIO_FILE_ENCODING_ALAW_8):
 185                         self._sampwidth = 2
 186                         self._framesize = 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 ##      access _file, _framerate, _nchannels, _sampwidth, _framesize, \
 283 ##                _nframes, _nframeswritten, _datawritten, _info, \
 284 ##                _comptype: private
 285
 286         def __init__(self, f):
 287                 if type(f) == type(''):
 288                         import __builtin__
 289                         f = __builtin__.open(f, 'w')
 290                 self.initfp(f)
 291
 292         def __del__(self):
 293                 if self._file:
 294                         self.close()
 295
 296         def initfp(self, file):
 297                 self._file = file
 298                 self._framerate = 0
 299                 self._nchannels = 0
 300                 self._sampwidth = 0
 301                 self._framesize = 0
 302                 self._nframes = AUDIO_UNKNOWN_SIZE
 303                 self._nframeswritten = 0
 304                 self._datawritten = 0
 305                 self._datalength = 0
 306                 self._info = ''
 307                 self._comptype = 'ULAW' # default is U-law
 308
 309         def setnchannels(self, nchannels):
 310                 if self._nframeswritten:
 311                         raise Error, 'cannot change parameters after starting to write'
 312                 if nchannels not in (1, 2, 4):
 313                         raise Error, 'only 1, 2, or 4 channels supported'
 314                 self._nchannels = nchannels
 315
 316         def getnchannels(self):
 317                 if not self._nchannels:
 318                         raise Error, 'number of channels not set'
 319                 return self._nchannels
 320
 321         def setsampwidth(self, sampwidth):
 322                 if self._nframeswritten:
 323                         raise Error, 'cannot change parameters after starting to write'
 324                 if sampwidth not in (1, 2, 4):
 325                         raise Error, 'bad sample width'
 326                 self._sampwidth = sampwidth
 327
 328         def getsampwidth(self):
 329                 if not self._framerate:
 330                         raise Error, 'sample width not specified'
 331                 return self._sampwidth
 332
 333         def setframerate(self, framerate):
 334                 if self._nframeswritten:
 335                         raise Error, 'cannot change parameters after starting to write'
 336                 self._framerate = framerate
 337
 338         def getframerate(self):
 339                 if not self._framerate:
 340                         raise Error, 'frame rate not set'
 341                 return self._framerate
 342
 343         def setnframes(self, nframes):
 344                 if self._nframeswritten:
 345                         raise Error, 'cannot change parameters after starting to write'
 346                 if nframes < 0:
 347                         raise Error, '# of frames cannot be negative'
 348                 self._nframes = nframes
 349
 350         def getnframes(self):
 351                 return self._nframeswritten
 352
 353         def setcomptype(self, type, name):
 354                 if type in ('NONE', 'ULAW'):
 355                         self._comptype = type
 356                 else:
 357                         raise Error, 'unknown compression type'
 358
 359         def getcomptype(self):
 360                 return self._comptype
 361
 362         def getcompname(self):
 363                 if self._comptype == 'ULAW':
 364                         return 'CCITT G.711 u-law'
 365                 elif self._comptype == 'ALAW':
 366                         return 'CCITT G.711 A-law'
 367                 else:
 368                         return 'not compressed'
 369
 370         def setparams(self, (nchannels, sampwidth, framerate, nframes, comptype, compname)):
 371                 self.setnchannels(nchannels)
 372                 self.setsampwidth(sampwidth)
 373                 self.setframerate(framerate)
 374                 self.setnframes(nframes)
 375                 self.setcomptype(comptype, compname)
 376
 377         def getparams(self):
 378                 return self.getnchannels(), self.getsampwidth(), \
 379                           self.getframerate(), self.getnframes(), \
 380                           self.getcomptype(), self.getcompname()
 381
 382         def tell(self):
 383                 return self._nframeswritten
 384
 385         def writeframesraw(self, data):
 386                 self._ensure_header_written()
 387                 nframes = len(data) / self._framesize
 388                 if self._comptype == 'ULAW':
 389                         import audioop
 390                         data = audioop.lin2ulaw(data, self._sampwidth)
 391                 self._file.write(data)
 392                 self._nframeswritten = self._nframeswritten + nframes
 393                 self._datawritten = self._datawritten + len(data)
 394
 395         def writeframes(self, data):
 396                 self.writeframesraw(data)
 397                 if self._nframeswritten != self._nframes or \
 398                           self._datalength != self._datawritten:
 399                         self._patchheader()
 400
 401         def close(self):
 402                 self._ensure_header_written()
 403                 if self._nframeswritten != self._nframes or \
 404                           self._datalength != self._datawritten:
 405                         self._patchheader()
 406                 self._file.flush()
 407                 self._file = None
 408
 409         #
 410         # private methods
 411         #
 412 ##      if 0: access *: private
 413
 414         def _ensure_header_written(self):
 415                 if not self._nframeswritten:
 416                         if not self._nchannels:
 417                                 raise Error, '# of channels not specified'
 418                         if not self._sampwidth:
 419                                 raise Error, 'sample width not specified'
 420                         if not self._framerate:
 421                                 raise Error, 'frame rate not specified'
 422                         self._write_header()
 423
 424         def _write_header(self):
 425                 if self._comptype == 'NONE':
 426                         if self._sampwidth == 1:
 427                                 encoding = AUDIO_FILE_ENCODING_LINEAR_8
 428                                 self._framesize = 1
 429                         elif self._sampwidth == 2:
 430                                 encoding = AUDIO_FILE_ENCODING_LINEAR_16
 431                                 self._framesize = 2
 432                         elif self._sampwidth == 4:
 433                                 encoding = AUDIO_FILE_ENCODING_LINEAR_32
 434                                 self._framesize = 4
 435                         else:
 436                                 raise Error, 'internal error'
 437                 elif self._comptype == 'ULAW':
 438                         encoding = AUDIO_FILE_ENCODING_MULAW_8
 439                         self._framesize = 1
 440                 else:
 441                         raise Error, 'internal error'
 442                 self._framesize = self._framesize * self._nchannels
 443                 _write_u32(self._file, AUDIO_FILE_MAGIC)
 444                 header_size = 25 + len(self._info)
 445                 header_size = (header_size + 7) & ~7
 446                 _write_u32(self._file, header_size)
 447                 if self._nframes == AUDIO_UNKNOWN_SIZE:
 448                         length = AUDIO_UNKNOWN_SIZE
 449                 else:
 450                         length = self._nframes * self._framesize
 451                 _write_u32(self._file, length)
 452                 self._datalength = length
 453                 _write_u32(self._file, encoding)
 454                 _write_u32(self._file, self._framerate)
 455                 _write_u32(self._file, self._nchannels)
 456                 self._file.write(self._info)
 457                 self._file.write('\0'*(header_size - len(self._info) - 24))
 458
 459         def _patchheader(self):
 460                 self._file.seek(8)
 461                 _write_u32(self._file, self._datawritten)
 462                 self._datalength = self._datawritten
 463                 self._file.seek(0, 2)
 464
 465 def open(f, mode):
 466         if mode == 'r':
 467                 return Au_read(f)
 468         elif mode == 'w':
 469                 return Au_write(f)
 470         else:
 471                 raise Error, "mode must be 'r' or 'w'"
 472
 473 openfp = open