eyeD3/tag.py

   1 ###############################################################################
   2 #
   3 #  Copyright (C) 2002-2005  Travis Shirk <travis@pobox.com>
   4 #
   5 #  This program is free software; you can redistribute it and/or modify
   6 #  it under the terms of the GNU General Public License as published by
   7 #  the Free Software Foundation; either version 2 of the License, or
   8 #  (at your option) any later version.
   9 #
  10 #  This program is distributed in the hope that it will be useful,
  11 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 #  GNU General Public License for more details.
  14 #
  15 #  You should have received a copy of the GNU General Public License
  16 #  along with this program; if not, write to the Free Software
  17 #  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 #
  19 ################################################################################
  20 import re, os, string, stat, shutil, tempfile, binascii;
  21 import mimetypes;
  22 from stat import *;
  23 from eyeD3 import *;
  24 import eyeD3.utils;
  25 import eyeD3.mp3;
  26 from frames import *;
  27 from binfuncs import *;
  28 import math;
  29
  30 ID3_V1_COMMENT_DESC = "ID3 v1 Comment";
  31
  32 ################################################################################
  33 class TagException(Exception):
  34    '''error reading tag'''
  35
  36 ################################################################################
  37 class TagHeader:
  38    SIZE = 10;
  39
  40    version = None;
  41    majorVersion = None;
  42    minorVersion = None;
  43    revVersion = None;
  44
  45    # Flag bits
  46    unsync = 0;
  47    extended = 0;
  48    experimental = 0;
  49    # v2.4 addition
  50    footer = 0;
  51
  52    # The size in the most recently parsed header.
  53    tagSize = 0;
  54
  55    # Constructor
  56    def __init__(self):
  57       self.clear();
  58
  59    def clear(self):
  60       self.setVersion(None);
  61       self.unsync = 0;
  62       self.extended = 0;
  63       self.experimental = 0;
  64       self.tagSize = 0;
  65
  66    def setVersion(self, v):
  67       if v == None:
  68          self.version = None;
  69          self.majorVersion = None;
  70          self.minorVersion = None;
  71          self.revVersion = None;
  72          return;
  73
  74       if v == ID3_CURRENT_VERSION:
  75          if self.majorVersion == None or self.minorVersion == None:
  76             v = ID3_DEFAULT_VERSION;
  77          else:
  78             return;
  79       elif v == ID3_ANY_VERSION:
  80          v = ID3_DEFAULT_VERSION;
  81
  82       # Handle 3-element lists or tuples.
  83       if isinstance(v, tuple) or isinstance(v, list):
  84          self.version = eyeD3.utils.versionsToConstant(v);
  85          (self.majorVersion,
  86           self.minorVersion,
  87           self.revVersion) = v;
  88       # Handle int constants.
  89       elif isinstance(v, int):
  90          (self.majorVersion,
  91           self.minorVersion,
  92           self.revVersion) = eyeD3.utils.constantToVersions(v);
  93          self.version = v;
  94       else:
  95          raise TypeError("Wrong type: %s" % str(type(v)));
  96
  97    # Given a file handle this method attempts to identify and then parse
  98    # a ID3 v2 header.  If successful, the parsed values are stored in
  99    # the instance variable.  If the files does not contain an ID3v2 tag
 100    # false is returned. A TagException is thrown if a tag is found, but is
 101    # not valid or corrupt.
 102    def parse(self, f):
 103       self.clear();
 104
 105       # The first three bytes of a v2 header is "ID3".
 106       if f.read(3) != "ID3":
 107          return 0;
 108       TRACE_MSG("Located ID3 v2 tag");
 109
 110       # The next 2 bytes are the minor and revision versions.
 111       version = f.read(2);
 112       major = 2;
 113       minor = ord(version[0]);
 114       rev = ord(version[1]);
 115       TRACE_MSG("TagHeader [major]: " + str(major));
 116       TRACE_MSG("TagHeader [minor]: " + str(minor));
 117       TRACE_MSG("TagHeader [revis]: " + str(rev));
 118       if not (major == 2 and (minor >= 2 and minor <= 4)):
 119          raise TagException("ID3 v" + str(major) + "." + str(minor) +\
 120                             " is not supported.");
 121       # Get all the version madness in sync.
 122       self.setVersion([major, minor, rev]);
 123
 124       # The first 4 bits of the next byte are flags.
 125       (self.unsync,
 126        self.extended,
 127        self.experimental,
 128        self.footer) = bytes2bin(f.read(1))[0:4];
 129       TRACE_MSG("TagHeader [flags]: unsync(%d) extended(%d) "\
 130                 "experimental(%d) footer(%d)" % (self.unsync, self.extended,
 131                                                  self.experimental,
 132                                                  self.footer));
 133
 134       # The size of the optional extended header, frames, and padding
 135       # afer unsynchronization.  This is a sync safe integer, so only the
 136       # bottom 7 bits of each byte are used.
 137       tagSizeStr = f.read(4);
 138       TRACE_MSG("TagHeader [size string]: 0x%02x%02x%02x%02x" %\
 139                 (ord(tagSizeStr[0]), ord(tagSizeStr[1]),
 140                  ord(tagSizeStr[2]), ord(tagSizeStr[3])));
 141       self.tagSize = bin2dec(bytes2bin(tagSizeStr, 7));
 142       TRACE_MSG("TagHeader [size]: %d (0x%x)" % (self.tagSize, self.tagSize));
 143
 144       return 1;
 145
 146    def render(self, tagLen = None):
 147       if tagLen != None:
 148          self.tagSize = tagLen;
 149
 150       data = "ID3";
 151       data += chr(self.minorVersion) + chr(self.revVersion);
 152       # not not the values so we only get 1's and 0's.
 153       data += bin2bytes([not not self.unsync,
 154                          not not self.extended,
 155                          not not self.experimental,
 156                          not not self.footer,
 157                          0, 0, 0, 0]);
 158       TRACE_MSG("Setting tag size to %d" % tagLen);
 159       szBytes = bin2bytes(bin2synchsafe(dec2bin(tagLen, 32)));
 160       data += szBytes;
 161       TRACE_MSG("TagHeader Rendered");
 162       return data;
 163
 164 ################################################################################
 165 class ExtendedTagHeader:
 166    size = 0;
 167    flags = 0;
 168    crc = 0;
 169    restrictions = 0;
 170
 171    def isUpdate(self):
 172        return self.flags & 0x40;
 173    def hasCRC(self):
 174        return self.flags & 0x20;
 175    def hasRestrictions(self, minor_version = None):
 176        return self.flags & 0x10;
 177
 178    def setSizeRestrictions(self, v):
 179       assert(v >= 0 and v <= 3);
 180       self.restrictions = (v << 6) | (self.restrictions & 0x3f);
 181    def getSizeRestrictions(self):
 182       return self.restrictions >> 6;
 183    def getSizeRestrictionsString(self):
 184       val = self.getSizeRestrictions();
 185       if val == 0x00:
 186          return "No more than 128 frames and 1 MB total tag size.";
 187       elif val == 0x01:
 188          return "No more than 64 frames and 128 KB total tag size.";
 189       elif val == 0x02:
 190          return "No more than 32 frames and 40 KB total tag size.";
 191       elif val == 0x03:
 192          return "No more than 32 frames and 4 KB total tag size.";
 193
 194    def setTextEncodingRestrictions(self, v):
 195       assert(v == 0 or v == 1);
 196       self.restrictions ^= 0x20;
 197    def getTextEncodingRestrictions(self):
 198       return self.restrictions & 0x20;
 199    def getTextEncodingRestrictionsString(self):
 200       if self.getTextEncodingRestrictions():
 201          return "Strings are only encoded with ISO-8859-1 [ISO-8859-1] or "\
 202                 "UTF-8 [UTF-8].";
 203       else:
 204          return "None";
 205
 206    def setTextFieldSizeRestrictions(self, v):
 207       assert(v >= 0 and v <= 3);
 208       self.restrictions = (v << 3) | (self.restrictions & 0xe7);
 209    def getTextFieldSizeRestrictions(self):
 210       return (self.restrictions >> 3) & 0x03;
 211    def getTextFieldSizeRestrictionsString(self):
 212       val = self.getTextFieldSizeRestrictions();
 213       if val == 0x00:
 214          return "None";
 215       elif val == 0x01:
 216          return "No string is longer than 1024 characters.";
 217       elif val == 0x02:
 218          return "No string is longer than 128 characters.";
 219       elif val == 0x03:
 220          return "No string is longer than 30 characters.";
 221
 222    def setImageEncodingRestrictions(self, v):
 223       assert(v == 0 or v == 1);
 224       self.restrictions ^= 0x04;
 225    def getImageEncodingRestrictions(self):
 226       return self.restrictions & 0x04;
 227    def getImageEncodingRestrictionsString(self):
 228       if self.getImageEncodingRestrictions():
 229          return "Images are encoded only with PNG [PNG] or JPEG [JFIF].";
 230       else:
 231          return "None";
 232
 233    def setImageSizeRestrictions(self, v):
 234       assert(v >= 0 and v <= 3);
 235       self.restrictions = v | (self.restrictions & 0xfc);
 236    def getImageSizeRestrictions(self):
 237       return self.restrictions & 0x03;
 238    def getImageSizeRestrictionsString(self):
 239       val = self.getImageSizeRestrictions();
 240       if val == 0x00:
 241          return "None";
 242       elif val == 0x01:
 243          return "All images are 256x256 pixels or smaller.";
 244       elif val == 0x02:
 245          return "All images are 64x64 pixels or smaller.";
 246       elif val == 0x03:
 247          return "All images are exactly 64x64 pixels, unless required "\
 248                 "otherwise.";
 249
 250    def _syncsafeCRC(self):
 251        bites = ""
 252        bites += chr((self.crc >> 28) & 0x7f);
 253        bites += chr((self.crc >> 21) & 0x7f);
 254        bites += chr((self.crc >> 14) & 0x7f);
 255        bites += chr((self.crc >>  7) & 0x7f);
 256        bites += chr((self.crc >>  0) & 0x7f);
 257        return bites;
 258
 259
 260    def render(self, header, frameData, padding = 0):
 261       assert(header.majorVersion == 2);
 262
 263       data = "";
 264       crc = None;
 265       if header.minorVersion == 4:
 266          # Version 2.4
 267          size = 6;
 268          # Extended flags.
 269          if self.isUpdate():
 270             data += "\x00";
 271          if self.hasCRC():
 272             data += "\x05";
 273             # XXX: Using the absolute value of the CRC.  The spec is unclear
 274             # about the type of this data.
 275             self.crc = int(math.fabs(binascii.crc32(frameData +\
 276                                                     ("\x00" * padding))));
 277             crc_data = self._syncsafeCRC();
 278             if len(crc_data) < 5:
 279                 crc_data = ("\x00" * (5 - len(crc_data))) + crc_data
 280             assert(len(crc_data) == 5)
 281             data += crc_data
 282          if self.hasRestrictions():
 283             data += "\x01";
 284             assert(len(self.restrictions) == 1);
 285             data += self.restrictions;
 286          TRACE_MSG("Rendered extended header data (%d bytes)" % len(data));
 287
 288          # Extended header size.
 289          size = bin2bytes(bin2synchsafe(dec2bin(len(data) + 6, 32)))
 290          assert(len(size) == 4);
 291
 292          data = size + "\x01" + bin2bytes(dec2bin(self.flags)) + data;
 293          TRACE_MSG("Rendered extended header of size %d" % len(data));
 294       else:
 295          # Version 2.3
 296          size = 10;
 297          # Extended flags.
 298          f = [0] * 16;
 299          if self.hasCRC():
 300             f[0] = 1;
 301             # XXX: Using the absolute value of the CRC.  The spec is unclear
 302             # about the type of this type.
 303             self.crc = int(math.fabs(binascii.crc32(frameData +\
 304                                                     ("\x00" * padding))));
 305             crc = bin2bytes(dec2bin(self.crc));
 306             assert(len(crc) == 4);
 307             size += 4;
 308          flags = bin2bytes(f);
 309          assert(len(flags) == 2);
 310          # Extended header size.
 311          size = bin2bytes(dec2bin(size, 32))
 312          assert(len(size) == 4);
 313          # Padding size
 314          paddingSize = bin2bytes(dec2bin(padding, 32));
 315
 316          data = size + flags + paddingSize;
 317          if crc:
 318             data += crc;
 319       return data;
 320
 321    # Only call this when you *know* there is an extened header.
 322    def parse(self, fp, header):
 323       assert(header.majorVersion == 2);
 324
 325       TRACE_MSG("Parsing extended header @ 0x%x" % fp.tell());
 326       # First 4 bytes is the size of the extended header.
 327       data = fp.read(4);
 328       if header.minorVersion == 4:
 329          # sync-safe
 330          sz = bin2dec(bytes2bin(data, 7));
 331          TRACE_MSG("Extended header size (not including 4 byte size): %d" %\
 332                    (sz - 4));
 333          data = fp.read(sz - 4);
 334
 335          if ord(data[0]) != 1 or (ord(data[1]) & 0x8f):
 336             # As of 2.4 the first byte is 1 and the second can only have
 337             # bits 6, 5, and 4 set.
 338             raise TagException("Invalid Extended Header");
 339
 340          offset = 2;
 341          self.flags = ord(data[1]);
 342          TRACE_MSG("Extended header flags: %x" % self.flags);
 343
 344          if self.isUpdate():
 345             TRACE_MSG("Extended header has update bit set");
 346             assert(ord(data[offset]) == 0);
 347             offset += 1;
 348          if self.hasCRC():
 349             TRACE_MSG("Extended header has CRC bit set");
 350             assert(ord(data[offset]) == 5);
 351             offset += 1;
 352             crcData = data[offset:offset + 5];
 353             # This is sync-safe.
 354             self.crc = bin2dec(bytes2bin(crcData, 7));
 355             TRACE_MSG("Extended header CRC: %d" % self.crc);
 356             offset += 5;
 357          if self.hasRestrictions():
 358             TRACE_MSG("Extended header has restrictions bit set");
 359             assert(ord(data[offset]) == 5);
 360             offset += 1;
 361             self.restrictions = ord(data[offset]);
 362             offset += 1;
 363       else:
 364          # v2.3 is totally different... *sigh*
 365          sz = bin2dec(bytes2bin(data));
 366          TRACE_MSG("Extended header size (not including 4 bytes size): %d" %\
 367                    sz);
 368          tmpFlags = fp.read(2);
 369          # Read the padding size, but it'll be computed during the parse.
 370          ps = fp.read(4);
 371          TRACE_MSG("Extended header says there is %d bytes of padding" %\
 372                    bin2dec(bytes2bin(ps)));
 373          # Make this look like a v2.4 mask.
 374          self.flags = ord(tmpFlags[0]) >> 2;
 375          if self.hasCRC():
 376             TRACE_MSG("Extended header has CRC bit set");
 377             crcData = fp.read(4);
 378             self.crc = bin2dec(bytes2bin(crcData));
 379             TRACE_MSG("Extended header CRC: %d" % self.crc);
 380
 381
 382 ################################################################################
 383 # ID3 tag class.  The class is capable of reading v1 and v2 tags.  ID3 v1.x
 384 # are converted to v2 frames.
 385 class Tag:
 386    # Latin1 is the default (0x00)
 387    encoding = DEFAULT_ENCODING;
 388
 389    # ID3v1 tags do not contain a header.  The only ID3v1 values stored
 390    # in this header are the major/minor version.
 391    header = TagHeader();
 392
 393    # Optional in v2 tags.
 394    extendedHeader = ExtendedTagHeader();
 395
 396    # Contains the tag's frames.  ID3v1 fields are read and converted
 397    # the the corresponding v2 frame.
 398    frames = None;
 399
 400    # Used internally for iterating over frames.
 401    iterIndex = None;
 402
 403    # If this value is None the tag is not linked to any particular file..
 404    linkedFile = None;
 405
 406    # Constructor.  An empty tag is created and the link method is used
 407    # to read an mp3 file's v1.x or v2.x tag.  You can optionally set a
 408    # file name, but it will not be read, but may be written to.
 409    def __init__(self, fileName = None):
 410       if fileName:
 411          self.linkedFile = LinkedFile(fileName);
 412       self.clear();
 413
 414    def clear(self):
 415       self.header = TagHeader();
 416       self.frames = FrameSet(self.header);
 417       self.iterIndex = None;
 418
 419    # Returns an read-only iterator for all frames.
 420    def __iter__(self):
 421       if len(self.frames):
 422          self.iterIndex = 0;
 423       else:
 424          self.iterIndex = None;
 425       return self;
 426
 427    def next(self):
 428       if self.iterIndex == None or self.iterIndex == len(self.frames):
 429          raise StopIteration;
 430       frm = self.frames[self.iterIndex];
 431       self.iterIndex += 1;
 432       return frm;
 433
 434    # Returns true when an ID3 tag is read from f which may be a file name
 435    # or an aleady opened file object.  In the latter case, the file object
 436    # is not closed when this method returns.
 437    #
 438    # By default, both ID3 v2 and v1 tags are parsed in that order.
 439    # If a v2 tag is found then a v1 parse is not performed.  This behavior
 440    # can be refined by passing ID3_V1 or ID3_V2 as the second argument
 441    # instead of the default ID3_ANY_VERSION.
 442    #
 443    # Converts all ID3v1 data into ID3v2 frames internally.
 444    # May throw IOError, or TagException if parsing fails.
 445    def link(self, f, v = ID3_ANY_VERSION):
 446       self.linkedFile = None;
 447       self.clear();
 448
 449       fileName = "";
 450       if isinstance(f, file):
 451          fileName = f.name;
 452       elif isinstance(f, str) or isinstance(f, unicode):
 453          fileName = f;
 454       else:
 455          raise TagException("Invalid type passed to Tag.link: " +
 456                             str(type(f)));
 457
 458       if v != ID3_V1 and v != ID3_V2 and v != ID3_ANY_VERSION:
 459          raise TagException("Invalid version: " + hex(v));
 460
 461       tagFound = 0;
 462       padding = 0;
 463       TRACE_MSG("Linking File: " + fileName);
 464       if v == ID3_V1:
 465          if self.__loadV1Tag(f):
 466             tagFound = 1;
 467       elif v == ID3_V2:
 468          padding = self.__loadV2Tag(f);
 469          if padding >= 0:
 470             tagFound = 1;
 471       elif v == ID3_ANY_VERSION:
 472          padding = self.__loadV2Tag(f);
 473          if padding >= 0:
 474             tagFound = 1;
 475          else:
 476             padding = 0;
 477             if self.__loadV1Tag(f):
 478                tagFound = 1;
 479
 480       self.linkedFile = LinkedFile(fileName);
 481       if tagFound:
 482          # In the case of a v1.x tag this is zero.
 483          self.linkedFile.tagSize = self.header.tagSize;
 484          self.linkedFile.tagPadding = padding;
 485       else:
 486          self.linkedFile.tagSize = 0;
 487          self.linkedFile.tagPadding = 0;
 488       return tagFound;
 489
 490    # Write the current tag state to the linked file.
 491    # The version of the ID3 file format that should be written can
 492    # be passed as an argument; the default is ID3_CURRENT_VERSION.
 493    def update(self, version = ID3_CURRENT_VERSION, backup = 0):
 494       if not self.linkedFile:
 495          raise TagException("The Tag is not linked to a file.");
 496
 497       if backup:
 498          shutil.copyfile(self.linkedFile.name, self.linkedFile.name + ".orig");
 499
 500       self.setVersion(version);
 501       version = self.getVersion();
 502       if version == ID3_V2_2:
 503           raise TagException("Unable to write ID3 v2.2");
 504       # If v1.0 is being requested explicitly then so be it, if not and there is
 505       # a track number then bumping to v1.1 is /probably/ best.
 506       if self.header.majorVersion == 1 and self.header.minorVersion == 0 and\
 507          self.getTrackNum()[0] != None and version != ID3_V1_0:
 508          version = ID3_V1_1;
 509          self.setVersion(version);
 510
 511       # If there are no frames then simply remove the current tag.
 512       if len(self.frames) == 0:
 513          self.remove(version);
 514          self.header = TagHeader();
 515          self.frames.setTagHeader(self.header);
 516          self.linkedFile.tagPadding = 0;
 517          self.linkedFile.tagSize = 0;
 518          return;
 519
 520       if version & ID3_V1:
 521          self.__saveV1Tag(version);
 522          return 1;
 523       elif version & ID3_V2:
 524          self.__saveV2Tag(version);
 525          return 1;
 526       else:
 527          raise TagException("Invalid version: %s" % hex(version));
 528       return 0;
 529
 530    # Remove the tag.  The version argument can selectively remove specific
 531    # ID3 tag versions; the default is ID3_CURRENT_VERSION meaning the version
 532    # of the current tag.  A value of ID3_ANY_VERSION causes all tags to be
 533    # removed.
 534    def remove(self, version = ID3_CURRENT_VERSION):
 535       if not self.linkedFile:
 536          raise TagException("The Tag is not linked to a file; nothing to "\
 537                             "remove.");
 538
 539       if version == ID3_CURRENT_VERSION:
 540          version = self.getVersion();
 541
 542       retval = 0;
 543       if version & ID3_V1 or version == ID3_ANY_VERSION:
 544          tagFile = file(self.linkedFile.name, "r+b");
 545          tagFile.seek(-128, 2);
 546          if tagFile.read(3) == "TAG":
 547             TRACE_MSG("Removing ID3 v1.x Tag");
 548             tagFile.seek(-3, 1);
 549             tagFile.truncate();
 550             retval |= 1;
 551          tagFile.close();
 552
 553       if ((version & ID3_V2) or (version == ID3_ANY_VERSION)) and\
 554           self.header.tagSize:
 555          tagFile = file(self.linkedFile.name, "r+b");
 556          if tagFile.read(3) == "ID3":
 557             TRACE_MSG("Removing ID3 v2.x Tag");
 558             tagSize = self.header.tagSize + self.header.SIZE;
 559             tagFile.seek(tagSize);
 560             data = tagFile.read();
 561             tagFile.seek(0);
 562             tagFile.write(data);
 563             tagFile.truncate();
 564             tagFile.close();
 565             retval |= 1;
 566
 567       return retval;
 568
 569
 570
 571    # Get artist.  There are a few frames that can contain this information,
 572    # and they are subtley different.
 573    #   eyeD3.frames.ARTIST_FID - Lead performer(s)/Soloist(s)
 574    #   eyeD3.frames.BAND_FID - Band/orchestra/accompaniment
 575    #   eyeD3.frames.CONDUCTOR_FID - Conductor/performer refinement
 576    #   eyeD3.frames.REMIXER_FID - Interpreted, remixed, or otherwise modified by
 577    #
 578    # Any of these values can be passed as an argument to select the artist
 579    # of interest.  By default, the first one found (searched in the above order)
 580    # is the value returned.  Most tags only have the ARTIST_FID, btw.
 581    #
 582    # When no artist is found, an empty string is returned.
 583    #
 584    def getArtist(self, artistID = ARTIST_FIDS):
 585       if isinstance(artistID, list):
 586          frameIDs = artistID;
 587       else:
 588          frameIDs = [artistID];
 589
 590       for fid in frameIDs:
 591          f = self.frames[fid];
 592          if f:
 593              return f[0].text;
 594       return u"";
 595
 596    def getAlbum(self):
 597       f = self.frames[ALBUM_FID];
 598       if f:
 599          return f[0].text;
 600       else:
 601          return u"";
 602
 603    # Get the track title.  By default the main title is returned.  Optionally,
 604    # you can pass:
 605    #   eyeD3.frames.TITLE_FID - The title; the default.
 606    #   eyeD3.frames.SUBTITLE_FID - The subtitle.
 607    #   eyeD3.frames.CONTENT_TITLE_FID - Conten group description???? Rare.
 608    # An empty string is returned when no title exists.
 609    def getTitle(self, titleID = TITLE_FID):
 610       f = self.frames[titleID];
 611       if f:
 612          return f[0].text;
 613       else:
 614          return u"";
 615
 616    def getDate(self, fid = None):
 617        if not fid:
 618            for fid in DATE_FIDS:
 619                if self.frames[fid]:
 620                    return self.frames[fid];
 621            return None;
 622        return self.frames[fid];
 623
 624    def getYear(self, fid = None):
 625        dateFrame = self.getDate(fid);
 626        if dateFrame:
 627            return dateFrame[0].getYear();
 628        else:
 629            return None;
 630
 631    # Throws GenreException when the tag contains an unrecognized genre format.
 632    # Note this method returns a eyeD3.Genre object, not a raw string.
 633    def getGenre(self):
 634       f = self.frames[GENRE_FID];
 635       if f and f[0].text:
 636          g = Genre();
 637          g.parse(f[0].text);
 638          return g;
 639       else:
 640          return None;
 641
 642    def _getNum(self, fid):
 643       tn = None
 644       tt = None
 645       f = self.frames[fid];
 646       if f:
 647          n = f[0].text.split('/')
 648          if len(n) == 1:
 649             tn = self.toInt(n[0])
 650          elif len(n) == 2:
 651             tn = self.toInt(n[0])
 652             tt = self.toInt(n[1])
 653       return (tn, tt)
 654
 655    # Returns a tuple with the first value containing the track number and the
 656    # second the total number of tracks.  One or both of these values may be
 657    # None depending on what is available in the tag.
 658    def getTrackNum(self):
 659       return self._getNum(TRACKNUM_FID)
 660
 661    # Like TrackNum, except for DiscNum--that is, position in a set. Most
 662    # songs won't have this or it will be 1/1.
 663    def getDiscNum(self):
 664       return self._getNum(DISCNUM_FID)
 665
 666    # Since multiple comment frames are allowed this returns a list with 0
 667    # or more elements.  The elements are not the comment strings, they are
 668    # eyeD3.frames.CommentFrame objects.
 669    def getComments(self):
 670       return self.frames[COMMENT_FID];
 671
 672    # Returns a list (possibly empty) of eyeD3.frames.ImageFrame objects.
 673    def getImages(self):
 674       return self.frames[IMAGE_FID];
 675
 676    # Returns a list (possibly empty) of eyeD3.frames.URLFrame objects.
 677    # Both URLFrame and UserURLFrame objects are returned.  UserURLFrames
 678    # add a description and encoding, and have a different frame ID.
 679    def getURLs(self):
 680       urls = list();
 681       for fid in URL_FIDS:
 682          urls.extend(self.frames[fid]);
 683       urls.extend(self.frames[USERURL_FID]);
 684       return urls;
 685
 686    def getUserTextFrames(self):
 687       return self.frames[USERTEXT_FID];
 688
 689    def getCDID(self):
 690       return self.frames[CDID_FID];
 691
 692    def getVersion(self):
 693       return self.header.version;
 694
 695    def getVersionStr(self):
 696       return versionToString(self.header.version);
 697
 698    def strToUnicode(self, s):
 699        t = type(s);
 700        if t != unicode and t == str:
 701            s = unicode(s, eyeD3.LOCAL_ENCODING);
 702        elif t != unicode and t != str:
 703            raise TagException("Wrong type passed to strToUnicode: %s" % str(t));
 704        return s;
 705
 706    # Set the artist name.  Arguments equal to None or "" cause the frame to
 707    # be removed. An optional second argument can be passed to select the
 708    # actual artist frame that should be set.  By default, the main artist frame
 709    # (TPE1) is the value used.
 710    def setArtist(self, a, id = ARTIST_FID):
 711        self.setTextFrame(id, self.strToUnicode(a));
 712
 713    def setAlbum(self, a):
 714        self.setTextFrame(ALBUM_FID, self.strToUnicode(a));
 715
 716    def setTitle(self, t, titleID = TITLE_FID):
 717        self.setTextFrame(titleID, self.strToUnicode(t));
 718
 719    def setDate(self, year, month = None, dayOfMonth = None,
 720                hour = None, minute = None, second = None, fid = None):
 721       if not year and not fid:
 722           dateFrames = self.getDate();
 723           if dateFrames:
 724               self.frames.removeFramesByID(dateFrames[0].header.id);
 725           return;
 726       elif not year:
 727           self.frames.removeFramesByID(fid);
 728
 729       dateStr = self.strToUnicode(str(year));
 730       if len(dateStr) != 4:
 731          raise TagException("Invalid Year field: " + dateStr);
 732       if month:
 733          dateStr += "-" + self.__padDateField(month);
 734          if dayOfMonth:
 735             dateStr += "-" + self.__padDateField(dayOfMonth);
 736             if hour:
 737                dateStr += "T" + self.__padDateField(hour);
 738                if minute:
 739                   dateStr += ":" + self.__padDateField(minute);
 740                   if second:
 741                      dateStr += ":" + self.__padDateField(second);
 742
 743       if not fid:
 744           fid = "TDRL";
 745       dateFrame = self.frames[fid];
 746       try:
 747          if dateFrame:
 748             dateFrame[0].setDate(self.encoding + dateStr);
 749          else:
 750             header = FrameHeader(self.header);
 751             header.id = fid;
 752             dateFrame = DateFrame(header, encoding = self.encoding,
 753                                   date_str = self.strToUnicode(dateStr));
 754             self.frames.addFrame(dateFrame);
 755       except FrameException, ex:
 756          raise TagException(str(ex));
 757
 758    # Three types are accepted for the genre parameter.  A Genre object, an
 759    # acceptable (see Genre.parse) genre string, or an integer genre id.
 760    # Arguments equal to None or "" cause the frame to be removed.
 761    def setGenre(self, g):
 762       if g == None or g == "":
 763           self.frames.removeFramesByID(GENRE_FID);
 764           return;
 765
 766       if isinstance(g, Genre):
 767           self.frames.setTextFrame(GENRE_FID, self.strToUnicode(str(g)),
 768                                    self.encoding);
 769       elif isinstance(g, str):
 770           gObj = Genre();
 771           gObj.parse(g);
 772           self.frames.setTextFrame(GENRE_FID, self.strToUnicode(str(gObj)),
 773                                    self.encoding);
 774       elif isinstance(g, int):
 775           gObj = Genre();
 776           gObj.id = g;
 777           self.frames.setTextFrame(GENRE_FID, self.strToUnicode(str(gObj)),
 778                                    self.encoding);
 779       else:
 780           raise TagException("Invalid type passed to setGenre: %s" +
 781                              str(type(g)));
 782
 783    # Accepts a tuple with the first value containing the track number and the
 784    # second the total number of tracks.  One or both of these values may be
 785    # None.  If both values are None, the frame is removed.
 786    def setTrackNum(self, n):
 787       self.setNum(TRACKNUM_FID, n)
 788
 789    def setDiscNum(self, n):
 790       self.setNum(DISCNUM_FID, n)
 791
 792    def setNum(self, fid, n):
 793       if n[0] == None and n[1] == None:
 794          self.frames.removeFramesByID(fid);
 795          return;
 796
 797       totalStr = "";
 798       zPadding = 1;
 799       if n[1] != None:
 800          if n[1] >= 0 and n[1] <= 9:
 801             totalStr = "0" + str(n[1]);
 802          else:
 803             totalStr = str(n[1]);
 804          zPadding = len(totalStr) - 1;
 805
 806       t = n[0];
 807       if t == None:
 808          t = 0;
 809
 810       # Pad with zeros according to how large the total count is.
 811       trackStr = str(t);
 812       if len(trackStr) == 1:
 813          trackStr = "0" + trackStr;
 814       if len(trackStr) < len(totalStr):
 815          trackStr = ("0" * (len(totalStr) - len(trackStr))) + trackStr;
 816
 817       s = "";
 818       if trackStr and totalStr:
 819          s = trackStr + "/" + totalStr;
 820       elif trackStr and not totalStr:
 821          s = trackStr;
 822
 823       self.frames.setTextFrame(fid, self.strToUnicode(s),
 824                                self.encoding);
 825
 826
 827    # Add a comment.  This adds a comment unless one is already present with
 828    # the same language and description in which case the current value is
 829    # either changed (cmt != "") or removed (cmt equals "" or None).
 830    def addComment(self, cmt, desc = u"", lang = DEFAULT_LANG):
 831       if not cmt:
 832          # A little more then a call to removeFramesByID is involved since we
 833          # need to look at more than the frame ID.
 834          comments = self.frames[COMMENT_FID];
 835          for c in comments:
 836             if c.lang == lang and c.description == desc:
 837                self.frames.remove(c);
 838                break;
 839       else:
 840          self.frames.setCommentFrame(self.strToUnicode(cmt),
 841                                      self.strToUnicode(desc),
 842                                      lang, self.encoding);
 843
 844    # Semantics similar to addComment
 845    def addUserTextFrame(self, desc, text):
 846       if not text:
 847          u_frames = self.frames[USERTEXT_FID];
 848          for u in u_frames:
 849             if u.description == desc:
 850                self.frames.remove(u);
 851                break;
 852       else:
 853          self.frames.setUserTextFrame(self.strToUnicode(text),
 854                                       self.strToUnicode(desc), self.encoding);
 855
 856    def removeComments(self):
 857        return self.frames.removeFramesByID(COMMENT_FID);
 858
 859    def addImage(self, type, image_file_path, desc = u""):
 860        if image_file_path:
 861            image_frame = ImageFrame.create(type, image_file_path, desc);
 862            self.frames.addFrame(image_frame);
 863        else:
 864            image_frames = self.frames[IMAGE_FID];
 865            for i in image_frames:
 866                if i.pictureType == type:
 867                    self.frames.remove(i);
 868                    break;
 869
 870    def getPlayCount(self):
 871        if self.frames[PLAYCOUNT_FID]:
 872            pc = self.frames[PLAYCOUNT_FID][0];
 873            assert(isinstance(pc, PlayCountFrame));
 874            return pc.count;
 875        else:
 876            return None;
 877
 878    def setPlayCount(self, count):
 879        assert(count >= 0);
 880        if self.frames[PLAYCOUNT_FID]:
 881            pc = self.frames[PLAYCOUNT_FID][0];
 882            assert(isinstance(pc, PlayCountFrame));
 883            pc.count = count;
 884        else:
 885            frameHeader = FrameHeader(self.header);
 886            frameHeader.id = PLAYCOUNT_FID;
 887            pc = PlayCountFrame(frameHeader, count = count);
 888            self.frames.addFrame(pc);
 889
 890    def incrementPlayCount(self, n = 1):
 891        pc = self.getPlayCount();
 892        if pc != None:
 893            self.setPlayCount(pc + n);
 894        else:
 895            self.setPlayCount(n);
 896
 897    def getUniqueFileIDs(self):
 898        return self.frames[UNIQUE_FILE_ID_FID];
 899
 900    def addUniqueFileID(self, owner_id, id):
 901       if not id:
 902          ufids = self.frames[UNIQUE_FILE_ID_FID];
 903          for ufid in ufids:
 904              if ufid.owner_id == owner_id:
 905                  self.frames.remove(ufid);
 906                  break;
 907       else:
 908          self.frames.setUniqueFileIDFrame(owner_id, id);
 909
 910    def getBPM(self):
 911       bpm = self.frames[BPM_FID];
 912       if bpm:
 913           return int(bpm[0].text);
 914       else:
 915           return None;
 916
 917    def setBPM(self, bpm):
 918        self.setTextFrame(BPM_FID, self.strToUnicode(str(bpm)));
 919
 920    def getPublisher(self):
 921       pub = self.frames[PUBLISHER_FID];
 922       if pub:
 923           return pub[0].text or None;
 924
 925    def setPublisher(self, p):
 926        self.setTextFrame(PUBLISHER_FID, self.strToUnicode(str(p)));
 927
 928    # Test ID3 major version.
 929    def isV1(self):
 930       return self.header.majorVersion == 1;
 931    def isV2(self):
 932       return self.header.majorVersion == 2;
 933
 934    def setVersion(self, v):
 935       if v == ID3_V1:
 936          v = ID3_V1_1;
 937       elif v == ID3_V2:
 938          v = ID3_DEFAULT_VERSION;
 939
 940       if v != ID3_CURRENT_VERSION:
 941          self.header.setVersion(v);
 942          self.frames.setTagHeader(self.header);
 943
 944    def setTextFrame(self, fid, txt):
 945        if not txt:
 946           self.frames.removeFramesByID(fid);
 947        else:
 948           self.frames.setTextFrame(fid, self.strToUnicode(txt), self.encoding);
 949
 950    def setTextEncoding(self, enc):
 951        if enc != LATIN1_ENCODING and enc != UTF_16_ENCODING and\
 952           enc != UTF_16BE_ENCODING and enc != UTF_8_ENCODING:
 953            raise TagException("Invalid encoding");
 954        elif self.getVersion() & ID3_V1 and enc != LATIN1_ENCODING:
 955            raise TagException("ID3 v1.x supports ISO-8859 encoding only");
 956        elif self.getVersion() <= ID3_V2_3 and enc == UTF_8_ENCODING:
 957            # This is unfortunate.
 958            raise TagException("UTF-8 is not supported by ID3 v2.3");
 959
 960        self.encoding = enc;
 961        for f in self.frames:
 962            f.encoding = enc;
 963
 964    def tagToString(self, pattern):
 965        # %A - artist
 966        # %a - album
 967        # %t - title
 968        # %n - track number
 969        # %N - track total
 970        s = self._subst(pattern, "%A", self.getArtist());
 971        s = self._subst(s, "%a", self.getAlbum());
 972        s = self._subst(s, "%t", self.getTitle());
 973        s = self._subst(s, "%n", self._prettyTrack(self.getTrackNum()[0]));
 974        s = self._subst(s, "%N", self._prettyTrack(self.getTrackNum()[1]));
 975        return s;
 976
 977    def _prettyTrack(self, track):
 978        if not track:
 979            return None;
 980        track_str = str(track);
 981        if len(track_str) == 1:
 982            track_str = "0" + track_str;
 983        return track_str;
 984
 985    def _subst(self, name, pattern, repl):
 986        regex = re.compile(pattern);
 987        if regex.search(name) and repl:
 988            # No '/' characters allowed
 989            (repl, subs) = re.compile("/").subn("-", repl);
 990            (name, subs) = regex.subn(repl, name)
 991        return name;
 992
 993    def __saveV1Tag(self, version):
 994       assert(version & ID3_V1);
 995
 996       # Build tag buffer.
 997       tag = "TAG";
 998       tag += self._fixToWidth(self.getTitle().encode("latin_1"), 30);
 999       tag += self._fixToWidth(self.getArtist().encode("latin_1"), 30);
1000       tag += self._fixToWidth(self.getAlbum().encode("latin_1"), 30);
1001       y = self.getYear();
1002       if y is None:
1003           y = "";
1004       tag += self._fixToWidth(y.encode("latin_1"), 4);
1005
1006       cmt = "";
1007       for c in self.getComments():
1008          if c.description == ID3_V1_COMMENT_DESC:
1009             cmt = c.comment;
1010             # We prefer this one over "";
1011             break;
1012          elif c.description == "":
1013             cmt = c.comment;
1014             # Keep searching in case we find the description eyeD3 uses.
1015       cmt = self._fixToWidth(cmt, 30);
1016       if version != ID3_V1_0:
1017          track = self.getTrackNum()[0];
1018          if track != None:
1019             cmt = cmt[0:28] + "\x00" + chr(int(track) & 0xff);
1020       tag += cmt;
1021
1022       if not self.getGenre():
1023          genre = 0;
1024       else:
1025          genre = self.getGenre().getId();
1026       tag += chr(genre & 0xff);
1027
1028       assert(len(tag) == 128);
1029
1030       tagFile = file(self.linkedFile.name, "r+b");
1031       # Write the tag over top an original or append it.
1032       try:
1033          tagFile.seek(-128, 2);
1034          if tagFile.read(3) == "TAG":
1035             tagFile.seek(-128, 2);
1036          else:
1037             tagFile.seek(0, 2);
1038       except IOError:
1039          # File is smaller than 128 bytes.
1040          tagFile.seek(0, 2);
1041
1042       tagFile.write(tag);
1043       tagFile.flush();
1044       tagFile.close();
1045
1046    def _fixToWidth(self, s, n):
1047       retval = str(s);
1048       retval = retval[0:n];
1049       retval = retval + ("\x00" * (n - len(retval)));
1050       return retval;
1051
1052    # Returns false when an ID3 v1 tag is not present, or contains no data.
1053    def __loadV1Tag(self, f):
1054       if isinstance(f, str) or isinstance(f, unicode):
1055          fp = file(f, "rb")
1056          closeFile = 1;
1057       else:
1058          fp = f;
1059          closeFile = 0;
1060
1061       # Seek to the end of the file where all ID3v1 tags are written.
1062       fp.seek(0, 2);
1063       strip_chars = string.whitespace + "\x00";
1064       if fp.tell() > 127:
1065          fp.seek(-128, 2);
1066          id3tag = fp.read(128);
1067          if id3tag[0:3] == "TAG":
1068             TRACE_MSG("Located ID3 v1 tag");
1069             # 1.0 is implied until a 1.1 feature is recognized.
1070             self.setVersion(ID3_V1_0);
1071
1072             title = re.sub("\x00+$", "", id3tag[3:33].strip(strip_chars));
1073             TRACE_MSG("Tite: " + title);
1074             if title:
1075                self.setTitle(unicode(title, "latin1"));
1076
1077             artist = re.sub("\x00+$", "", id3tag[33:63].strip(strip_chars));
1078             TRACE_MSG("Artist: " + artist);
1079             if artist:
1080                self.setArtist(unicode(artist, "latin1"));
1081
1082             album = re.sub("\x00+$", "", id3tag[63:93].strip(strip_chars));
1083             TRACE_MSG("Album: " + album);
1084             if album:
1085                self.setAlbum(unicode(album, "latin1"));
1086
1087             year = re.sub("\x00+$", "", id3tag[93:97].strip(strip_chars));
1088             TRACE_MSG("Year: " + year);
1089             try:
1090                if year and int(year):
1091                   self.setDate(year);
1092             except ValueError:
1093                # Bogus year strings.
1094                pass;
1095
1096             if re.sub("\x00+$", "", id3tag[97:127]):
1097                comment = id3tag[97:127];
1098                TRACE_MSG("Comment: " + comment);
1099                if comment[-2] == "\x00" and comment[-1] != "\x00":
1100                   # Parse track number (added to ID3v1.1) if present.
1101                   TRACE_MSG("Comment contains track number per v1.1 spec");
1102                   track = ord(comment[-1]);
1103                   self.setTrackNum((track, None));
1104                   TRACE_MSG("Track: " + str(track));
1105                   TRACE_MSG("Track Num found, setting version to v1.1s");
1106                   self.setVersion(ID3_V1_1);
1107                   comment = comment[:-2];
1108                else:
1109                   track = None
1110                comment = re.sub("\x00+$", "", comment).rstrip();
1111                TRACE_MSG("Comment: " + comment);
1112                if comment:
1113                   self.addComment(unicode(comment, 'latin1'),
1114                                   ID3_V1_COMMENT_DESC);
1115
1116             genre = ord(id3tag[127:128])
1117             TRACE_MSG("Genre ID: " + str(genre));
1118             self.setGenre(genre);
1119
1120       if closeFile:
1121          fp.close()
1122       return len(self.frames);
1123
1124    def __saveV2Tag(self, version):
1125       assert(version & ID3_V2);
1126       TRACE_MSG("Rendering tag version: " + versionToString(version));
1127
1128       self.setVersion(version);
1129
1130       currPadding = 0;
1131       currTagSize = 0
1132       if currTagSize == 0:
1133          # We may be converting from 1.x to 2.x so we need to find any
1134          # current v2.x tag otherwise we're gonna hork the file.
1135          tmpTag = Tag();
1136          if tmpTag.link(self.linkedFile.name, ID3_V2):
1137             TRACE_MSG("Found current v2.x tag:");
1138             currTagSize = tmpTag.linkedFile.tagSize;
1139             TRACE_MSG("Current tag size: %d" % currTagSize);
1140             currPadding = tmpTag.linkedFile.tagPadding;
1141             TRACE_MSG("Current tag padding: %d" % currPadding);
1142
1143       # Tag it!
1144       if self.header.minorVersion == 4:
1145           h = FrameHeader(self.header);
1146           h.id = "TDTG";
1147           t = time.strftime("%Y-%m-%dT%H:%M:%S");
1148           dateFrame = DateFrame(h, date_str = self.strToUnicode(t),
1149                                 encoding = self.encoding);
1150           self.frames.removeFramesByID("TDTG");
1151           self.frames.addFrame(dateFrame);
1152
1153       # Render all frames first so the data size is known for the tag header.
1154       frameData = "";
1155       for f in self.frames:
1156          TRACE_MSG("Rendering frame: " + f.header.id);
1157          raw_frame = f.render();
1158          TRACE_MSG("Rendered %d bytes" % len(raw_frame));
1159          frameData += raw_frame;
1160       # Handle the overall tag header unsync bit.  Frames themselves duplicate
1161       # this bit.
1162       if self.header.unsync:
1163           TRACE_MSG("Unsyncing all frames (sync-safe)");
1164           frameData = frames.unsyncData(frameData);
1165
1166       TRACE_MSG("Rendered tag size: " + str(len(frameData)));
1167
1168       rewriteFile = 0;
1169       paddingSize = 0;
1170       headerData = "";
1171       extHeaderData = "";
1172
1173       # Extended header
1174       if self.header.extended:
1175          # This is sorta lame.  We don't know the total framesize until
1176          # this is rendered, yet we can't render it witout knowing the
1177          # amount of padding.  Force it.
1178          rewriteFile = 1;
1179          paddingSize = 2048;
1180          TRACE_MSG("Rendering extended header");
1181          extHeaderData += self.extendedHeader.render(self.header, frameData,
1182                                                      paddingSize);
1183
1184       if rewriteFile or (10 + len(headerData) + len(extHeaderData) +\
1185                          len(frameData)) >= currTagSize:
1186          TRACE_MSG("File rewrite required");
1187          rewriteFile = 1;
1188          paddingSize = 2048;
1189       else:
1190          paddingSize = currTagSize - (len(headerData) + len(extHeaderData) +\
1191                                       len(frameData));
1192       frameData += ("\x00" * paddingSize);
1193
1194       # Render the tag header.
1195       TRACE_MSG("Rendering %s tag header with size %d" %\
1196                 (versionToString(self.getVersion()), len(frameData)));
1197       headerData = self.header.render(len(frameData));
1198
1199       # Assemble frame.
1200       tagData = headerData + extHeaderData + frameData;
1201
1202       # Write the tag.
1203       if not rewriteFile:
1204          tagFile = file(self.linkedFile.name, "r+b");
1205          TRACE_MSG("Writing %d bytes of tag data" % len(tagData));
1206          tagFile.write(tagData);
1207          tagFile.close();
1208       else:
1209          # Open original
1210          tagFile = file(self.linkedFile.name, "rb");
1211          # Read all audio data
1212          tagFile.seek(currTagSize);
1213          audioData = tagFile.read();
1214          tagFile.close();
1215
1216          # Open tmp file
1217          tmpName = tempfile.mktemp();
1218          tmpFile = file(tmpName, "w+b");
1219          TRACE_MSG("Writing %d bytes of tag data" % len(tagData));
1220          tmpFile.write(tagData);
1221          tmpFile.write(audioData);
1222          tmpFile.close();
1223
1224          # Move tmp to orig.
1225          shutil.copyfile(tmpName, self.linkedFile.name);
1226          os.unlink(tmpName);
1227
1228       # Update our state.
1229       TRACE_MSG("Tag write complete.  Updating state.");
1230       self.linkedFile.tagPadding = paddingSize;
1231       # XXX: getSize could cache sizes so to prevent rendering again.
1232       self.linkedFile.tagSize = self.frames.getSize();
1233
1234
1235    # Returns >= 0 to indicate the padding size of the read frame; -1 returned
1236    # when not tag was found.
1237    def __loadV2Tag(self, f):
1238       if isinstance(f, str) or isinstance(f, unicode):
1239          fp = file(f, "rb")
1240          closeFile = 1;
1241       else:
1242          fp = f;
1243          closeFile = 0;
1244
1245       padding = -1;
1246       try:
1247          # Look for a tag and if found load it.
1248          if not self.header.parse(fp):
1249             return -1;
1250
1251          # Read the extended header if present.
1252          if self.header.extended:
1253             self.extendedHeader.parse(fp, self.header);
1254
1255          # Header is definitely there so at least one frame *must* follow.
1256          self.frames.setTagHeader(self.header);
1257          padding = self.frames.parse(fp, self.header);
1258          TRACE_MSG("Tag contains %d bytes of padding." % padding);
1259       except FrameException, ex:
1260          if utils.strictID3():
1261             fp.close();
1262             raise TagException(str(ex));
1263       except TagException:
1264          fp.close();
1265          raise;
1266
1267       if closeFile:
1268          fp.close();
1269       return padding;
1270
1271    def toInt(self, s):
1272       try:
1273          return int(s);
1274       except ValueError:
1275          return None;
1276       except TypeError:
1277          return None;
1278
1279    def __padDateField(self, f):
1280       fStr = str(f);
1281       if len(fStr) == 2:
1282          pass;
1283       elif len(fStr) == 1:
1284          fStr = "0" + fStr;
1285       else:
1286          raise TagException("Invalid date field: " + fStr);
1287       return fStr;
1288
1289    # DEPRECATED
1290    # This method will return the first comment in the FrameSet
1291    # and not all of them.  Multiple COMM frames are common and useful.  Use
1292    # getComments which returns a list.
1293    def getComment(self):
1294       f = self.frames[COMMENT_FID];
1295       if f:
1296          return f[0].comment;
1297       else:
1298          return None;
1299
1300
1301 ################################################################################
1302 class GenreException(Exception):
1303    '''Problem looking up genre'''
1304
1305 ################################################################################
1306 class Genre:
1307    id = None;
1308    name = None;
1309
1310    def __init__(self, id = None, name = None):
1311       if id is not None:
1312          self.setId(id);
1313       elif name is not None:
1314          self.setName(name);
1315
1316    def getId(self):
1317       return self.id;
1318    def getName(self):
1319       return self.name;
1320
1321    # Sets the genre id.  The objects name field is set to the corresponding
1322    # value obtained from eyeD3.genres.
1323    #
1324    # Throws GenreException when name does not map to a valid ID3 v1.1. id.
1325    # This behavior can be disabled by passing 0 as the second argument.
1326    def setId(self, id):
1327       if not isinstance(id, int):
1328          raise TypeError("Invalid genre id: " + str(id));
1329
1330       try:
1331           name = genres[id];
1332       except Exception, ex:
1333           if utils.strictID3():
1334               raise GenreException("Invalid genre id: " + str(id));
1335
1336       if utils.strictID3() and not name:
1337           raise GenreException("Genre id maps to a null name: " + str(id));
1338
1339       self.id = id;
1340       self.name = name;
1341
1342    # Sets the genre name.  The objects id field is set to the corresponding
1343    # value obtained from eyeD3.genres.
1344    #
1345    # Throws GenreException when name does not map to a valid ID3 v1.1. name.
1346    # This behavior can be disabled by passing 0 as the second argument.
1347    def setName(self, name):
1348       if not isinstance(name, str):
1349          raise GenreException("Invalid genre name: " + str(name));
1350
1351       try:
1352          id = genres[name];
1353          # Get titled case.
1354          name = genres[id];
1355       except:
1356           if utils.strictID3():
1357               raise GenreException("Invalid genre name: " + name);
1358           id = None;
1359
1360       self.id = id;
1361       self.name = name;
1362
1363
1364    # Sets the genre id and name.
1365    #
1366    # Throws GenreException when eyeD3.genres[id] != name (case insensitive).
1367    # This behavior can be disabled by passing 0 as the second argument.
1368    def set(self, id, name):
1369       if not isinstance(id, int):
1370          raise GenreException("Invalid genre id: " + id);
1371       if not isinstance(name, str):
1372          raise GenreException("Invalid genre name: " + str(name));
1373
1374       if not utils.strictID3():
1375          self.id = id;
1376          self.name = name;
1377       else:
1378          try:
1379             if genres[name] != id:
1380                raise GenreException("eyeD3.genres[" + str(id) + "] " +\
1381                                     "does not match " + name);
1382             self.id = id;
1383             self.name = name;
1384          except:
1385             raise GenreException("eyeD3.genres[" + str(id) + "] " +\
1386                                  "does not match " + name);
1387
1388    # Parses genre information from genreStr.
1389    # The following formats are supported:
1390    # 01, 2, 23, 125 - ID3 v1 style.
1391    # (01), (2), (129)Hardcore, (9)Metal - ID3 v2 style with and without
1392    #                                      refinement.
1393    #
1394    # Throws GenreException when an invalid string is passed.
1395    def parse(self, genreStr):
1396       genreStr =\
1397           str(genreStr.encode('utf-8')).strip(string.whitespace + '\x00');
1398       self.id = None;
1399       self.name = None;
1400
1401       if not genreStr:
1402          return;
1403
1404       # XXX: Utf-16 conversions leave a null byte at the end of the string.
1405       while genreStr[len(genreStr) - 1] == "\x00":
1406          genreStr = genreStr[:len(genreStr) - 1];
1407          if len(genreStr) == 0:
1408             break;
1409
1410       # ID3 v1 style.
1411       # Match 03, 34, 129.
1412       regex = re.compile("[0-9][0-9]?[0-9]?$");
1413       if regex.match(genreStr):
1414          if len(genreStr) != 1 and genreStr[0] == '0':
1415             genreStr = genreStr[1:];
1416
1417          self.setId(int(genreStr));
1418          return;
1419
1420       # ID3 v2 style.
1421       # Match (03), (0)Blues, (15) Rap
1422       regex = re.compile("\(([0-9][0-9]?[0-9]?)\)(.*)$");
1423       m = regex.match(genreStr);
1424       if m:
1425          (id, name) = m.groups();
1426          if len(id) != 1 and id[0] == '0':
1427             id = id[1:];
1428
1429          if id and name:
1430             self.set(int(id), name.strip());
1431          else:
1432             self.setId(int(id));
1433          return;
1434
1435       # Non standard, but witnessed.
1436       # Match genreName alone.  e.g. Rap, Rock, blues.
1437       regex = re.compile("^[A-Z 0-9+/\-&]+\00*$", re.IGNORECASE);
1438       if regex.match(genreStr):
1439          self.setName(genreStr);
1440          return;
1441       raise GenreException("Genre string cannot be parsed with '%s': %s" %\
1442                            (regex.pattern, genreStr));
1443
1444    def __str__(self):
1445       s = "";
1446       if self.id != None:
1447          s += "(" + str(self.id) + ")"
1448       if self.name:
1449          s += self.name;
1450       return s;
1451
1452 ################################################################################
1453 class InvalidAudioFormatException(Exception):
1454    '''Problems with audio format'''
1455
1456 ################################################################################
1457 class TagFile:
1458    fileName = str("");
1459    fileSize = int(0);
1460    tag      = None;
1461    # Number of seconds required to play the audio file.
1462    play_time = int(0);
1463
1464    def __init__(self, fileName):
1465        self.fileName = fileName;
1466
1467    def getTag(self):
1468       return self.tag;
1469
1470    def getSize(self):
1471       if not self.fileSize:
1472          self.fileSize = os.stat(self.fileName)[ST_SIZE];
1473       return self.fileSize;
1474
1475    def rename(self, name, fsencoding):
1476        base = os.path.basename(self.fileName);
1477        base_ext = os.path.splitext(base)[1];
1478        dir = os.path.dirname(self.fileName);
1479        if not dir:
1480            dir = ".";
1481        new_name = dir + os.sep + name.encode(fsencoding) + base_ext;
1482        try:
1483            os.rename(self.fileName, new_name);
1484            self.fileName = new_name;
1485        except OSError, ex:
1486            raise TagException("Error renaming '%s' to '%s'" % (self.fileName,
1487                                                                new_name));
1488
1489    def getPlayTime(self):
1490       return self.play_time;
1491
1492    def getPlayTimeString(self):
1493       total = self.getPlayTime();
1494       h = total / 3600;
1495       m = (total % 3600) / 60;
1496       s = (total % 3600) % 60;
1497       if h:
1498          timeStr = "%d:%.2d:%.2d" % (h, m, s);
1499       else:
1500          timeStr = "%d:%.2d" % (m, s);
1501       return timeStr;
1502
1503
1504 ################################################################################
1505 class Mp3AudioFile(TagFile):
1506    header         = mp3.Header();
1507    xingHeader     = None;
1508    invalidFileExc = InvalidAudioFormatException("File is not mp3");
1509
1510    def __init__(self, fileName, tagVersion = ID3_ANY_VERSION):
1511       TagFile.__init__(self, fileName);
1512
1513       if not isMp3File(fileName):
1514          raise self.invalidFileExc;
1515
1516       # Parse ID3 tag.
1517       f = file(fileName, "rb");
1518       tag = Tag();
1519       hasTag = tag.link(f, tagVersion);
1520       # Find the first mp3 frame.
1521       if tag.isV1():
1522          framePos = 0;
1523       elif not hasTag:
1524          framePos = 0;
1525          tag = None;
1526       else:
1527          # XXX: Note that v2.4 allows for appended tags; account for that.
1528          framePos = tag.header.SIZE + tag.header.tagSize;
1529
1530       f.seek(framePos);
1531       bString = f.read(4);
1532       if len(bString) < 4:
1533          raise InvalidAudioFormatException("Unable to find a valid mp3 "\
1534                                            "frame");
1535       frameHead = bin2dec(bytes2bin(bString));
1536       header = mp3.Header();
1537       it_count = 0;
1538       # Keep reading until we find a valid mp3 frame header.
1539       while not header.isValid(frameHead):
1540          # Originally, the search was one byte at a time.  Occasionally a tag
1541          # was heavily, and incorrectly, padded or a corrupt mp3 would cause
1542          # a byte by byte search to take a long time.  This algorithm speeds
1543          # up this particular case.
1544          if it_count > 9:
1545              f.seek(f.tell() + 128);
1546              bString = f.read(4);
1547              if len(bString) < 4:
1548                 raise InvalidAudioFormatException("Unable to find a valid mp3 "\
1549                                                   "frame");
1550              frameHead = bin2dec(bytes2bin(bString));
1551              it_count = 0;
1552              continue;
1553
1554          frameHead <<= 8;
1555          bString = f.read(1);
1556          if len(bString) != 1:
1557             raise InvalidAudioFormatException("Unable to find a valid mp3 "\
1558                                               "frame");
1559          frameHead |= ord(bString[0]);
1560          it_count += 1;
1561       TRACE_MSG("mp3 header %x found at position: %d (0x%x)" % \
1562                 (frameHead, f.tell() - 4, f.tell() - 4));
1563
1564       # Decode the header.
1565       try:
1566          header.decode(frameHead);
1567          # Check for Xing header inforamtion which will always be in the
1568          # first "null" frame.
1569          f.seek(-4, 1);
1570          mp3Frame = f.read(header.frameLength);
1571          if mp3Frame.find("Xing") != -1:
1572             xingHeader = mp3.XingHeader();
1573             if not xingHeader.decode(mp3Frame):
1574                raise InvalidAudioFormatException("Corrupt Xing header");
1575          else:
1576             xingHeader = None;
1577       except mp3.Mp3Exception, ex:
1578          raise InvalidAudioFormatException(str(ex));
1579
1580       # Compute track play time.
1581       tpf = mp3.computeTimePerFrame(header);
1582       if xingHeader:
1583          self.play_time = int(tpf * xingHeader.numFrames);
1584       else:
1585          length = self.getSize();
1586          if tag and tag.isV2():
1587             length -= tag.header.SIZE + tag.header.tagSize;
1588             # Handle the case where there is a v2 tag and a v1 tag.
1589             f.seek(-128, 2)
1590             if f.read(3) == "TAG":
1591                length -= 128;
1592          elif tag and tag.isV1():
1593             length -= 128;
1594          self.play_time = int((length / header.frameLength) * tpf);
1595
1596       self.header = header;
1597       self.xingHeader = xingHeader;
1598       self.tag = tag;
1599       f.close();
1600
1601    # Returns a tuple.  The first value is a boolean which if true means the
1602    # bit rate returned in the second value is variable.
1603    def getBitRate(self):
1604       xHead = self.xingHeader;
1605       if xHead:
1606          tpf = eyeD3.mp3.computeTimePerFrame(self.header);
1607          br = int((xHead.numBytes * 8) / (tpf * xHead.numFrames * 1000));
1608          vbr = 1;
1609       else:
1610          br = self.header.bitRate;
1611          vbr = 0;
1612       return (vbr, br);
1613
1614    def getBitRateString(self):
1615       (vbr, bitRate) = self.getBitRate();
1616       brs = "%d kb/s" % bitRate;
1617       if vbr:
1618          brs = "~" + brs;
1619       return brs;
1620    def getSampleFreq(self):
1621       return self.header.sampleFreq;
1622
1623 ################################################################################
1624 def isMp3File(fileName):
1625     (type, enc) = mimetypes.guess_type(fileName);
1626     return type == "audio/mpeg";
1627
1628 ################################################################################
1629 class GenreMap(list):
1630    # None value are set in the ctor
1631    GENRE_MIN = 0;
1632    GENRE_MAX = None;
1633    ID3_GENRE_MIN = 0;
1634    ID3_GENRE_MAX = 79;
1635    WINAMP_GENRE_MIN = 80;
1636    WINAMP_GENRE_MAX = 147;
1637    EYED3_GENRE_MIN = None;
1638    EYED3_GENRE_MAX = None;
1639
1640    # Accepts both int and string keys. Throws IndexError and TypeError.
1641    def __getitem__(self, key):
1642       if isinstance(key, int):
1643          if key >= 0 and key < len(self):
1644             v = list.__getitem__(self, key);
1645             if v:
1646                return v;
1647             else:
1648                return None;
1649          else:
1650             raise IndexError("genre index out of range");
1651       elif isinstance(key, str):
1652          if self.reverseDict.has_key(key.lower()):
1653             return self.reverseDict[key.lower()];
1654          else:
1655             raise IndexError(key + " genre not found");
1656       else:
1657          raise TypeError("genre key must be type int or string");
1658
1659    def __init__(self):
1660       self.data = []
1661       self.reverseDict = {}
1662       # ID3 genres as defined by the v1.1 spec with WinAmp extensions.
1663       self.append('Blues');
1664       self.append('Classic Rock');
1665       self.append('Country');
1666       self.append('Dance');
1667       self.append('Disco');
1668       self.append('Funk');
1669       self.append('Grunge');
1670       self.append('Hip-Hop');
1671       self.append('Jazz');
1672       self.append('Metal');
1673       self.append('New Age');
1674       self.append('Oldies');
1675       self.append('Other');
1676       self.append('Pop');
1677       self.append('R&B');
1678       self.append('Rap');
1679       self.append('Reggae');
1680       self.append('Rock');
1681       self.append('Techno');
1682       self.append('Industrial');
1683       self.append('Alternative');
1684       self.append('Ska');
1685       self.append('Death Metal');
1686       self.append('Pranks');
1687       self.append('Soundtrack');
1688       self.append('Euro-Techno');
1689       self.append('Ambient');
1690       self.append('Trip-Hop');
1691       self.append('Vocal');
1692       self.append('Jazz+Funk');
1693       self.append('Fusion');
1694       self.append('Trance');
1695       self.append('Classical');
1696       self.append('Instrumental');
1697       self.append('Acid');
1698       self.append('House');
1699       self.append('Game');
1700       self.append('Sound Clip');
1701       self.append('Gospel');
1702       self.append('Noise');
1703       self.append('AlternRock');
1704       self.append('Bass');
1705       self.append('Soul');
1706       self.append('Punk');
1707       self.append('Space');
1708       self.append('Meditative');
1709       self.append('Instrumental Pop');
1710       self.append('Instrumental Rock');
1711       self.append('Ethnic');
1712       self.append('Gothic');
1713       self.append('Darkwave');
1714       self.append('Techno-Industrial');
1715       self.append('Electronic');
1716       self.append('Pop-Folk');
1717       self.append('Eurodance');
1718       self.append('Dream');
1719       self.append('Southern Rock');
1720       self.append('Comedy');
1721       self.append('Cult');
1722       self.append('Gangsta Rap');
1723       self.append('Top 40');
1724       self.append('Christian Rap');
1725       self.append('Pop / Funk');
1726       self.append('Jungle');
1727       self.append('Native American');
1728       self.append('Cabaret');
1729       self.append('New Wave');
1730       self.append('Psychedelic');
1731       self.append('Rave');
1732       self.append('Showtunes');
1733       self.append('Trailer');
1734       self.append('Lo-Fi');
1735       self.append('Tribal');
1736       self.append('Acid Punk');
1737       self.append('Acid Jazz');
1738       self.append('Polka');
1739       self.append('Retro');
1740       self.append('Musical');
1741       self.append('Rock & Roll');
1742       self.append('Hard Rock');
1743       self.append('Folk');
1744       self.append('Folk-Rock');
1745       self.append('National Folk');
1746       self.append('Swing');
1747       self.append('Fast  Fusion');
1748       self.append('Bebob');
1749       self.append('Latin');
1750       self.append('Revival');
1751       self.append('Celtic');
1752       self.append('Bluegrass');
1753       self.append('Avantgarde');
1754       self.append('Gothic Rock');
1755       self.append('Progressive Rock');
1756       self.append('Psychedelic Rock');
1757       self.append('Symphonic Rock');
1758       self.append('Slow Rock');
1759       self.append('Big Band');
1760       self.append('Chorus');
1761       self.append('Easy Listening');
1762       self.append('Acoustic');
1763       self.append('Humour');
1764       self.append('Speech');
1765       self.append('Chanson');
1766       self.append('Opera');
1767       self.append('Chamber Music');
1768       self.append('Sonata');
1769       self.append('Symphony');
1770       self.append('Booty Bass');
1771       self.append('Primus');
1772       self.append('Porn Groove');
1773       self.append('Satire');
1774       self.append('Slow Jam');
1775       self.append('Club');
1776       self.append('Tango');
1777       self.append('Samba');
1778       self.append('Folklore');
1779       self.append('Ballad');
1780       self.append('Power Ballad');
1781       self.append('Rhythmic Soul');
1782       self.append('Freestyle');
1783       self.append('Duet');
1784       self.append('Punk Rock');
1785       self.append('Drum Solo');
1786       self.append('A Cappella');
1787       self.append('Euro-House');
1788       self.append('Dance Hall');
1789       self.append('Goa');
1790       self.append('Drum & Bass');
1791       self.append('Club-House');
1792       self.append('Hardcore');
1793       self.append('Terror');
1794       self.append('Indie');
1795       self.append('BritPop');
1796       self.append('Negerpunk');
1797       self.append('Polsk Punk');
1798       self.append('Beat');
1799       self.append('Christian Gangsta Rap');
1800       self.append('Heavy Metal');
1801       self.append('Black Metal');
1802       self.append('Crossover');
1803       self.append('Contemporary Christian');
1804       self.append('Christian Rock');
1805       self.append('Merengue');
1806       self.append('Salsa');
1807       self.append('Thrash Metal');
1808       self.append('Anime');
1809       self.append('JPop');
1810       self.append('Synthpop');
1811       # The follow genres I've encountered in the wild.
1812       self.append('Rock/Pop');
1813       self.EYED3_GENRE_MIN = len(self) - 1;
1814       # New genres go here
1815
1816       self.EYED3_GENRE_MAX = len(self) - 1;
1817       self.GENRE_MAX = len(self) - 1;
1818
1819       # Pad up to 255 with "Unknown"
1820       count = len(self);
1821       while count < 256:
1822          self.append("Unknown");
1823          count += 1;
1824
1825       for index in range(len(self)):
1826          if self[index]:
1827             self.reverseDict[string.lower(self[index])] = index
1828 class LinkedFile:
1829    name = "";
1830    tagPadding = 0;
1831    tagSize = 0;  # This includes the padding byte count.
1832
1833    def __init__(self, fileName):
1834        if isinstance(fileName, str):
1835            self.name = unicode(fileName, sys.getfilesystemencoding());
1836        else:
1837            self.name = fileName;
1838
1839 def tagToUserTune(tag):
1840     audio_file = None;
1841     if isinstance(tag, Mp3AudioFile):
1842         audio_file = tag;
1843         tag = audio_file.getTag();
1844
1845     tune =  u"<tune xmlns='http://jabber.org/protocol/tune'>\n";
1846     if tag.getArtist():
1847         tune += "  <artist>" + tag.getArtist() + "</artist>\n";
1848     if tag.getTitle():
1849         tune += "  <title>" + tag.getTitle() + "</title>\n";
1850     if tag.getAlbum():
1851         tune += "  <source>" + tag.getAlbum() + "</source>\n";
1852     tune += "  <track>" +\
1853             "file://" + unicode(os.path.abspath(tag.linkedFile.name)) +\
1854             "</track>\n";
1855     if audio_file:
1856         tune += "  <length>" + unicode(audio_file.getPlayTime()) +\
1857                 "</length>\n";
1858     tune += "</tune>\n";
1859     return tune;
1860
1861 #
1862 # Module level globals.
1863 #
1864 genres = GenreMap();
1865