-# id3 support for mutagen
-# Copyright (C) 2005 Michael Urman
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of version 2 of the GNU General Public License as
-# published by the Free Software Foundation.
-#
-# $Id: id3.py 4275 2008-06-01 06:32:37Z piman $
-
-"""ID3v2 reading and writing.
-
-This is based off of the following references:
- http://www.id3.org/id3v2.4.0-structure.txt
- http://www.id3.org/id3v2.4.0-frames.txt
- http://www.id3.org/id3v2.3.0.html
- http://www.id3.org/id3v2-00.txt
- http://www.id3.org/id3v1.html
-
-Its largest deviation from the above (versions 2.3 and 2.2) is that it
-will not interpret the / characters as a separator, and will almost
-always accept null separators to generate multi-valued text frames.
-
-Because ID3 frame structure differs between frame types, each frame is
-implemented as a different class (e.g. TIT2 as mutagen.id3.TIT2). Each
-frame's documentation contains a list of its attributes.
-
-Since this file's documentation is a little unwieldy, you are probably
-interested in the 'ID3' class to start with.
-"""
-
-__all__ = ['ID3', 'ID3FileType', 'Frames', 'Open', 'delete']
-
-import struct; from struct import unpack, pack
-from zlib import error as zlibError
-from warnings import warn
-
-import mutagen
-from mutagen._util import insert_bytes, delete_bytes, DictProxy
-
-class error(Exception): pass
-class ID3NoHeaderError(error, ValueError): pass
-class ID3BadUnsynchData(error, ValueError): pass
-class ID3BadCompressedData(error, ValueError): pass
-class ID3TagError(error, ValueError): pass
-class ID3UnsupportedVersionError(error, NotImplementedError): pass
-class ID3EncryptionUnsupportedError(error, NotImplementedError): pass
-class ID3JunkFrameError(error, ValueError): pass
-
-class ID3Warning(error, UserWarning): pass
-
-def is_valid_frame_id(frame_id):
- return frame_id.isalnum() and frame_id.isupper()
-
-class ID3(DictProxy, mutagen.Metadata):
- """A file with an ID3v2 tag.
-
- Attributes:
- version -- ID3 tag version as a tuple
- unknown_frames -- raw frame data of any unknown frames found
- size -- the total size of the ID3 tag, including the header
- """
-
- PEDANTIC = True
- version = (2, 4, 0)
-
- filename = None
- size = 0
- __flags = 0
- __readbytes = 0
- __crc = None
-
- def __init__(self, *args, **kwargs):
- self.unknown_frames = []
- super(ID3, self).__init__(*args, **kwargs)
-
- def __fullread(self, size):
- try:
- if size < 0:
- raise ValueError('Requested bytes (%s) less than zero' % size)
- if size > self.__filesize:
- raise EOFError('Requested %#x of %#x (%s)' %
- (long(size), long(self.__filesize), self.filename))
- except AttributeError: pass
- data = self.__fileobj.read(size)
- if len(data) != size: raise EOFError
- self.__readbytes += size
- return data
-
- def load(self, filename, known_frames=None, translate=True):
- """Load tags from a filename.
-
- Keyword arguments:
- filename -- filename to load tag data from
- known_frames -- dict mapping frame IDs to Frame objects
- translate -- Update all tags to ID3v2.4 internally. Mutagen is
- only capable of writing ID3v2.4 tags, so if you
- intend to save, this must be true.
-
- Example of loading a custom frame:
- my_frames = dict(mutagen.id3.Frames)
- class XMYF(Frame): ...
- my_frames["XMYF"] = XMYF
- mutagen.id3.ID3(filename, known_frames=my_frames)
- """
-
- from os.path import getsize
- self.filename = filename
- self.__known_frames = known_frames
- self.__fileobj = file(filename, 'rb')
- self.__filesize = getsize(filename)
- try:
- try:
- self.__load_header()
- except EOFError:
- self.size = 0
- raise ID3NoHeaderError("%s: too small (%d bytes)" %(
- filename, self.__filesize))
- except (ID3NoHeaderError, ID3UnsupportedVersionError), err:
- self.size = 0
- import sys
- stack = sys.exc_info()[2]
- try: self.__fileobj.seek(-128, 2)
- except EnvironmentError: raise err, None, stack
- else:
- frames = ParseID3v1(self.__fileobj.read(128))
- if frames is not None:
- self.version = (1, 1)
- map(self.add, frames.values())
- else: raise err, None, stack
- else:
- frames = self.__known_frames
- if frames is None:
- if (2,3,0) <= self.version: frames = Frames
- elif (2,2,0) <= self.version: frames = Frames_2_2
- data = self.__fullread(self.size - 10)
- for frame in self.__read_frames(data, frames=frames):
- if isinstance(frame, Frame): self.add(frame)
- else: self.unknown_frames.append(frame)
- finally:
- self.__fileobj.close()
- del self.__fileobj
- del self.__filesize
- if translate:
- self.update_to_v24()
-
- def getall(self, key):
- """Return all frames with a given name (the list may be empty).
-
- This is best explained by examples:
- id3.getall('TIT2') == [id3['TIT2']]
- id3.getall('TTTT') == []
- id3.getall('TXXX') == [TXXX(desc='woo', text='bar'),
- TXXX(desc='baz', text='quuuux'), ...]
-
- Since this is based on the frame's HashKey, which is
- colon-separated, you can use it to do things like
- getall('COMM:MusicMatch') or getall('TXXX:QuodLibet:').
- """
- if key in self: return [self[key]]
- else:
- key = key + ":"
- return [v for s,v in self.items() if s.startswith(key)]
-
- def delall(self, key):
- """Delete all tags of a given kind; see getall."""
- if key in self: del(self[key])
- else:
- key = key + ":"
- for k in filter(lambda s: s.startswith(key), self.keys()):
- del(self[k])
-
- def setall(self, key, values):
- """Delete frames of the given type and add frames in 'values'."""
- self.delall(key)
- for tag in values:
- self[tag.HashKey] = tag
-
- def pprint(self):
- """Return tags in a human-readable format.
-
- "Human-readable" is used loosely here. The format is intended
- to mirror that used for Vorbis or APEv2 output, e.g.
- TIT2=My Title
- However, ID3 frames can have multiple keys:
- POPM=user@example.org=3 128/255
- """
- return "\n".join(map(Frame.pprint, self.values()))
-
- def loaded_frame(self, tag):
- """Deprecated; use the add method."""
- # turn 2.2 into 2.3/2.4 tags
- if len(type(tag).__name__) == 3: tag = type(tag).__base__(tag)
- self[tag.HashKey] = tag
-
- # add = loaded_frame (and vice versa) break applications that
- # expect to be able to override loaded_frame (e.g. Quod Libet),
- # as does making loaded_frame call add.
- def add(self, frame):
- """Add a frame to the tag."""
- return self.loaded_frame(frame)
-
- def __load_header(self):
- fn = self.filename
- data = self.__fullread(10)
- id3, vmaj, vrev, flags, size = unpack('>3sBBB4s', data)
- self.__flags = flags
- self.size = BitPaddedInt(size) + 10
- self.version = (2, vmaj, vrev)
-
- if id3 != 'ID3':
- raise ID3NoHeaderError("'%s' doesn't start with an ID3 tag" % fn)
- if vmaj not in [2, 3, 4]:
- raise ID3UnsupportedVersionError("'%s' ID3v2.%d not supported"
- % (fn, vmaj))
-
- if self.PEDANTIC:
- if (2,4,0) <= self.version and (flags & 0x0f):
- raise ValueError("'%s' has invalid flags %#02x" % (fn, flags))
- elif (2,3,0) <= self.version and (flags & 0x1f):
- raise ValueError("'%s' has invalid flags %#02x" % (fn, flags))
-
- if self.f_extended:
- if self.version >= (2,4,0):
- # "Where the 'Extended header size' is the size of the whole
- # extended header, stored as a 32 bit synchsafe integer."
- self.__extsize = BitPaddedInt(self.__fullread(4)) - 4
- else:
- # "Where the 'Extended header size', currently 6 or 10 bytes,
- # excludes itself."
- self.__extsize = unpack('>L', self.__fullread(4))[0]
- self.__extdata = self.__fullread(self.__extsize)
-
- def __determine_bpi(self, data, frames):
- if self.version < (2,4,0): return int
- # have to special case whether to use bitpaddedints here
- # spec says to use them, but iTunes has it wrong
-
- # count number of tags found as BitPaddedInt and how far past
- o = 0
- asbpi = 0
- while o < len(data)-10:
- name, size, flags = unpack('>4sLH', data[o:o+10])
- size = BitPaddedInt(size)
- o += 10+size
- if name in frames: asbpi += 1
- bpioff = o - len(data)
-
- # count number of tags found as int and how far past
- o = 0
- asint = 0
- while o < len(data)-10:
- name, size, flags = unpack('>4sLH', data[o:o+10])
- o += 10+size
- if name in frames: asint += 1
- intoff = o - len(data)
-
- # if more tags as int, or equal and bpi is past and int is not
- if asint > asbpi or (asint == asbpi and (bpioff >= 1 and intoff <= 1)):
- return int
- return BitPaddedInt
-
- def __read_frames(self, data, frames):
- if self.version < (2,4,0) and self.f_unsynch:
- try: data = unsynch.decode(data)
- except ValueError: pass
-
- if (2,3,0) <= self.version:
- bpi = self.__determine_bpi(data, frames)
- while data:
- header = data[:10]
- try: name, size, flags = unpack('>4sLH', header)
- except struct.error: return # not enough header
- if name.strip('\x00') == '': return
- size = bpi(size)
- framedata = data[10:10+size]
- data = data[10+size:]
- if size == 0: continue # drop empty frames
- try: tag = frames[name]
- except KeyError:
- if is_valid_frame_id(name): yield header + framedata
- else:
- try: yield self.__load_framedata(tag, flags, framedata)
- except NotImplementedError: yield header + framedata
- except ID3JunkFrameError: pass
-
- elif (2,2,0) <= self.version:
- while data:
- header = data[0:6]
- try: name, size = unpack('>3s3s', header)
- except struct.error: return # not enough header
- size, = struct.unpack('>L', '\x00'+size)
- if name.strip('\x00') == '': return
- framedata = data[6:6+size]
- data = data[6+size:]
- if size == 0: continue # drop empty frames
- try: tag = frames[name]
- except KeyError:
- if is_valid_frame_id(name): yield header + framedata
- else:
- try: yield self.__load_framedata(tag, 0, framedata)
- except NotImplementedError: yield header + framedata
- except ID3JunkFrameError: pass
-
- def __load_framedata(self, tag, flags, framedata):
- return tag.fromData(self, flags, framedata)
-
- f_unsynch = property(lambda s: bool(s.__flags & 0x80))
- f_extended = property(lambda s: bool(s.__flags & 0x40))
- f_experimental = property(lambda s: bool(s.__flags & 0x20))
- f_footer = property(lambda s: bool(s.__flags & 0x10))
-
- #f_crc = property(lambda s: bool(s.__extflags & 0x8000))
-
- def save(self, filename=None, v1=1):
- """Save changes to a file.
-
- If no filename is given, the one most recently loaded is used.
-
- Keyword arguments:
- v1 -- if 0, ID3v1 tags will be removed
- if 1, ID3v1 tags will be updated but not added
- if 2, ID3v1 tags will be created and/or updated
-
- The lack of a way to update only an ID3v1 tag is intentional.
- """
-
- # Sort frames by 'importance'
- order = ["TIT2", "TPE1", "TRCK", "TALB", "TPOS", "TDRC", "TCON"]
- order = dict(zip(order, range(len(order))))
- last = len(order)
- frames = self.items()
- frames.sort(lambda a, b: cmp(order.get(a[0][:4], last),
- order.get(b[0][:4], last)))
-
- framedata = [self.__save_frame(frame) for (key, frame) in frames]
- framedata.extend([data for data in self.unknown_frames
- if len(data) > 10])
- if not framedata:
- try:
- self.delete(filename)
- except EnvironmentError, err:
- from errno import ENOENT
- if err.errno != ENOENT: raise
- return
-
- framedata = ''.join(framedata)
- framesize = len(framedata)
-
- if filename is None: filename = self.filename
- try: f = open(filename, 'rb+')
- except IOError, err:
- from errno import ENOENT
- if err.errno != ENOENT: raise
- f = open(filename, 'ab') # create, then reopen
- f = open(filename, 'rb+')
- try:
- idata = f.read(10)
- try: id3, vmaj, vrev, flags, insize = unpack('>3sBBB4s', idata)
- except struct.error: id3, insize = '', 0
- insize = BitPaddedInt(insize)
- if id3 != 'ID3': insize = -10
-
- if insize >= framesize: outsize = insize
- else: outsize = (framesize + 1023) & ~0x3FF
- framedata += '\x00' * (outsize - framesize)
-
- framesize = BitPaddedInt.to_str(outsize, width=4)
- flags = 0
- header = pack('>3sBBB4s', 'ID3', 4, 0, flags, framesize)
- data = header + framedata
-
- if (insize < outsize):
- insert_bytes(f, outsize-insize, insize+10)
- f.seek(0)
- f.write(data)
-
- try:
- f.seek(-128, 2)
- except IOError, err:
- from errno import EINVAL
- if err.errno != EINVAL: raise
- f.seek(0, 2) # ensure read won't get "TAG"
-
- if f.read(3) == "TAG":
- f.seek(-128, 2)
- if v1 > 0: f.write(MakeID3v1(self))
- else: f.truncate()
- elif v1 == 2:
- f.seek(0, 2)
- f.write(MakeID3v1(self))
-
- finally:
- f.close()
-
- def delete(self, filename=None, delete_v1=True, delete_v2=True):
- """Remove tags from a file.
-
- If no filename is given, the one most recently loaded is used.
-
- Keyword arguments:
- delete_v1 -- delete any ID3v1 tag
- delete_v2 -- delete any ID3v2 tag
- """
- if filename is None:
- filename = self.filename
- delete(filename, delete_v1, delete_v2)
- self.clear()
-
- def __save_frame(self, frame):
- flags = 0
- if self.PEDANTIC and isinstance(frame, TextFrame):
- if len(str(frame)) == 0: return ''
- framedata = frame._writeData()
- usize = len(framedata)
- if usize > 2048:
- framedata = BitPaddedInt.to_str(usize) + framedata.encode('zlib')
- flags |= Frame.FLAG24_COMPRESS | Frame.FLAG24_DATALEN
- datasize = BitPaddedInt.to_str(len(framedata), width=4)
- header = pack('>4s4sH', type(frame).__name__, datasize, flags)
- return header + framedata
-
- def update_to_v24(self):
- """Convert older tags into an ID3v2.4 tag.
-
- This updates old ID3v2 frames to ID3v2.4 ones (e.g. TYER to
- TDRC). If you intend to save tags, you must call this function
- at some point; it is called by default when loading the tag.
- """
-
- if self.version < (2,3,0): del self.unknown_frames[:]
- # unsafe to write
-
- # TDAT, TYER, and TIME have been turned into TDRC.
- try:
- if str(self.get("TYER", "")).strip("\x00"):
- date = str(self.pop("TYER"))
- if str(self.get("TDAT", "")).strip("\x00"):
- dat = str(self.pop("TDAT"))
- date = "%s-%s-%s" % (date, dat[2:], dat[:2])
- if str(self.get("TIME", "")).strip("\x00"):
- time = str(self.pop("TIME"))
- date += "T%s:%s:00" % (time[:2], time[2:])
- if "TDRC" not in self:
- self.add(TDRC(encoding=0, text=date))
- except UnicodeDecodeError:
- # Old ID3 tags have *lots* of Unicode problems, so if TYER
- # is bad, just chuck the frames.
- pass
-
- # TORY can be the first part of a TDOR.
- if "TORY" in self:
- f = self.pop("TORY")
- if "TDOR" not in self:
- try:
- self.add(TDOR(encoding=0, text=str(f)))
- except UnicodeDecodeError:
- pass
-
- # IPLS is now TIPL.
- if "IPLS" in self:
- f = self.pop("IPLS")
- if "TIPL" not in self:
- self.add(TIPL(encoding=f.encoding, people=f.people))
-
- if "TCON" in self:
- # Get rid of "(xx)Foobr" format.
- self["TCON"].genres = self["TCON"].genres
-
- if self.version < (2, 3):
- # ID3v2.2 PIC frames are slightly different.
- pics = self.getall("APIC")
- mimes = { "PNG": "image/png", "JPG": "image/jpeg" }
- self.delall("APIC")
- for pic in pics:
- newpic = APIC(
- encoding=pic.encoding, mime=mimes.get(pic.mime, pic.mime),
- type=pic.type, desc=pic.desc, data=pic.data)
- self.add(newpic)
-
- # ID3v2.2 LNK frames are just way too different to upgrade.
- self.delall("LINK")
-
- # These can't be trivially translated to any ID3v2.4 tags, or
- # should have been removed already.
- for key in ["RVAD", "EQUA", "TRDA", "TSIZ", "TDAT", "TIME", "CRM"]:
- if key in self: del(self[key])
-
-def delete(filename, delete_v1=True, delete_v2=True):
- """Remove tags from a file.
-
- Keyword arguments:
- delete_v1 -- delete any ID3v1 tag
- delete_v2 -- delete any ID3v2 tag
- """
-
- f = open(filename, 'rb+')
-
- if delete_v1:
- try:
- f.seek(-128, 2)
- except IOError: pass
- else:
- if f.read(3) == "TAG":
- f.seek(-128, 2)
- f.truncate()
-
- # technically an insize=0 tag is invalid, but we delete it anyway
- # (primarily because we used to write it)
- if delete_v2:
- f.seek(0, 0)
- idata = f.read(10)
- try: id3, vmaj, vrev, flags, insize = unpack('>3sBBB4s', idata)
- except struct.error: id3, insize = '', -1
- insize = BitPaddedInt(insize)
- if id3 == 'ID3' and insize >= 0:
- delete_bytes(f, insize + 10, 0)
-
-class BitPaddedInt(int):
- def __new__(cls, value, bits=7, bigendian=True):
- "Strips 8-bits bits out of every byte"
- mask = (1<<(bits))-1
- if isinstance(value, (int, long)):
- bytes = []
- while value:
- bytes.append(value & ((1<<bits)-1))
- value = value >> 8
- if isinstance(value, str):
- bytes = [ord(byte) & mask for byte in value]
- if bigendian: bytes.reverse()
- numeric_value = 0
- for shift, byte in zip(range(0, len(bytes)*bits, bits), bytes):
- numeric_value += byte << shift
- if isinstance(numeric_value, long):
- self = long.__new__(BitPaddedLong, numeric_value)
- else:
- self = int.__new__(BitPaddedInt, numeric_value)
- self.bits = bits
- self.bigendian = bigendian
- return self
-
- def as_str(value, bits=7, bigendian=True, width=4):
- bits = getattr(value, 'bits', bits)
- bigendian = getattr(value, 'bigendian', bigendian)
- value = int(value)
- mask = (1<<bits)-1
- bytes = []
- while value:
- bytes.append(value & mask)
- value = value >> bits
- # PCNT and POPM use growing integers of at least 4 bytes as counters.
- if width == -1: width = max(4, len(bytes))
- if len(bytes) > width:
- raise ValueError, 'Value too wide (%d bytes)' % len(bytes)
- else: bytes.extend([0] * (width-len(bytes)))
- if bigendian: bytes.reverse()
- return ''.join(map(chr, bytes))
- to_str = staticmethod(as_str)
-
-class BitPaddedLong(long):
- def as_str(value, bits=7, bigendian=True, width=4):
- return BitPaddedInt.to_str(value, bits, bigendian, width)
- to_str = staticmethod(as_str)
-
-class unsynch(object):
- def decode(value):
- output = []
- safe = True
- append = output.append
- for val in value:
- if safe:
- append(val)
- safe = val != '\xFF'
- else:
- if val >= '\xE0': raise ValueError('invalid sync-safe string')
- elif val != '\x00': append(val)
- safe = True
- if not safe: raise ValueError('string ended unsafe')
- return ''.join(output)
- decode = staticmethod(decode)
-
- def encode(value):
- output = []
- safe = True
- append = output.append
- for val in value:
- if safe:
- append(val)
- if val == '\xFF': safe = False
- elif val == '\x00' or val >= '\xE0':
- append('\x00')
- append(val)
- safe = val != '\xFF'
- else:
- append(val)
- safe = True
- if not safe: append('\x00')
- return ''.join(output)
- encode = staticmethod(encode)
-
-class Spec(object):
- def __init__(self, name): self.name = name
- def __hash__(self): raise TypeError("Spec objects are unhashable")
-
-class ByteSpec(Spec):
- def read(self, frame, data): return ord(data[0]), data[1:]
- def write(self, frame, value): return chr(value)
- def validate(self, frame, value): return value
-
-class IntegerSpec(Spec):
- def read(self, frame, data):
- return int(BitPaddedInt(data, bits=8)), ''
- def write(self, frame, value):
- return BitPaddedInt.to_str(value, bits=8, width=-1)
- def validate(self, frame, value):
- return value
-
-class SizedIntegerSpec(Spec):
- def __init__(self, name, size):
- self.name, self.__sz = name, size
- def read(self, frame, data):
- return int(BitPaddedInt(data[:self.__sz], bits=8)), data[self.__sz:]
- def write(self, frame, value):
- return BitPaddedInt.to_str(value, bits=8, width=self.__sz)
- def validate(self, frame, value):
- return value
-
-class EncodingSpec(ByteSpec):
- def read(self, frame, data):
- enc, data = super(EncodingSpec, self).read(frame, data)
- if enc < 16: return enc, data
- else: return 0, chr(enc)+data
-
- def validate(self, frame, value):
- if 0 <= value <= 3: return value
- if value is None: return None
- raise ValueError, 'Invalid Encoding: %r' % value
-
-class StringSpec(Spec):
- def __init__(self, name, length):
- super(StringSpec, self).__init__(name)
- self.len = length
- def read(s, frame, data): return data[:s.len], data[s.len:]
- def write(s, frame, value):
- if value is None: return '\x00' * s.len
- else: return (str(value) + '\x00' * s.len)[:s.len]
- def validate(s, frame, value):
- if value is None: return None
- if isinstance(value, basestring) and len(value) == s.len: return value
- raise ValueError, 'Invalid StringSpec[%d] data: %r' % (s.len, value)
-
-class BinaryDataSpec(Spec):
- def read(self, frame, data): return data, ''
- def write(self, frame, value): return str(value)
- def validate(self, frame, value): return str(value)
-
-class EncodedTextSpec(Spec):
- # Okay, seriously. This is private and defined explicitly and
- # completely by the ID3 specification. You can't just add
- # encodings here however you want.
- _encodings = ( ('latin1', '\x00'), ('utf16', '\x00\x00'),
- ('utf_16_be', '\x00\x00'), ('utf8', '\x00') )
-
- def read(self, frame, data):
- enc, term = self._encodings[frame.encoding]
- ret = ''
- if len(term) == 1:
- if term in data:
- data, ret = data.split(term, 1)
- else:
- offset = -1
- try:
- while True:
- offset = data.index(term, offset+1)
- if offset & 1: continue
- data, ret = data[0:offset], data[offset+2:]; break
- except ValueError: pass
-
- if len(data) < len(term): return u'', ret
- return data.decode(enc), ret
-
- def write(self, frame, value):
- enc, term = self._encodings[frame.encoding]
- return value.encode(enc) + term
-
- def validate(self, frame, value): return unicode(value)
-
-class MultiSpec(Spec):
- def __init__(self, name, *specs, **kw):
- super(MultiSpec, self).__init__(name)
- self.specs = specs
- self.sep = kw.get('sep')
-
- def read(self, frame, data):
- values = []
- while data:
- record = []
- for spec in self.specs:
- value, data = spec.read(frame, data)
- record.append(value)
- if len(self.specs) != 1: values.append(record)
- else: values.append(record[0])
- return values, data
-
- def write(self, frame, value):
- data = []
- if len(self.specs) == 1:
- for v in value:
- data.append(self.specs[0].write(frame, v))
- else:
- for record in value:
- for v, s in zip(record, self.specs):
- data.append(s.write(frame, v))
- return ''.join(data)
-
- def validate(self, frame, value):
- if value is None: return []
- if self.sep and isinstance(value, basestring):
- value = value.split(self.sep)
- if isinstance(value, list):
- if len(self.specs) == 1:
- return [self.specs[0].validate(frame, v) for v in value]
- else:
- return [
- [s.validate(frame, v) for (v,s) in zip(val, self.specs)]
- for val in value ]
- raise ValueError, 'Invalid MultiSpec data: %r' % value
-
-class EncodedNumericTextSpec(EncodedTextSpec): pass
-class EncodedNumericPartTextSpec(EncodedTextSpec): pass
-
-class Latin1TextSpec(EncodedTextSpec):
- def read(self, frame, data):
- if '\x00' in data: data, ret = data.split('\x00',1)
- else: ret = ''
- return data.decode('latin1'), ret
-
- def write(self, data, value):
- return value.encode('latin1') + '\x00'
-
- def validate(self, frame, value): return unicode(value)
-
-class ID3TimeStamp(object):
- """A time stamp in ID3v2 format.
-
- This is a restricted form of the ISO 8601 standard; time stamps
- take the form of:
- YYYY-MM-DD HH:MM:SS
- Or some partial form (YYYY-MM-DD HH, YYYY, etc.).
-
- The 'text' attribute contains the raw text data of the time stamp.
- """
-
- import re
- def __init__(self, text):
- if isinstance(text, ID3TimeStamp): text = text.text
- self.text = text
-
- __formats = ['%04d'] + ['%02d'] * 5
- __seps = ['-', '-', ' ', ':', ':', 'x']
- def get_text(self):
- parts = [self.year, self.month, self.day,
- self.hour, self.minute, self.second]
- pieces = []
- for i, part in enumerate(iter(iter(parts).next, None)):
- pieces.append(self.__formats[i]%part + self.__seps[i])
- return u''.join(pieces)[:-1]
-
- def set_text(self, text, splitre=re.compile('[-T:/.]|\s+')):
- year, month, day, hour, minute, second = \
- splitre.split(text + ':::::')[:6]
- for a in 'year month day hour minute second'.split():
- try: v = int(locals()[a])
- except ValueError: v = None
- setattr(self, a, v)
-
- text = property(get_text, set_text, doc="ID3v2.4 date and time.")
-
- def __str__(self): return self.text
- def __repr__(self): return repr(self.text)
- def __cmp__(self, other): return cmp(self.text, other.text)
- def encode(self, *args): return self.text.encode(*args)
-
-class TimeStampSpec(EncodedTextSpec):
- def read(self, frame, data):
- value, data = super(TimeStampSpec, self).read(frame, data)
- return self.validate(frame, value), data
-
- def write(self, frame, data):
- return super(TimeStampSpec, self).write(frame,
- data.text.replace(' ', 'T'))
-
- def validate(self, frame, value):
- try: return ID3TimeStamp(value)
- except TypeError: raise ValueError, "Invalid ID3TimeStamp: %r" % value
-
-class ChannelSpec(ByteSpec):
- (OTHER, MASTER, FRONTRIGHT, FRONTLEFT, BACKRIGHT, BACKLEFT, FRONTCENTRE,
- BACKCENTRE, SUBWOOFER) = range(9)
-
-class VolumeAdjustmentSpec(Spec):
- def read(self, frame, data):
- value, = unpack('>h', data[0:2])
- return value/512.0, data[2:]
-
- def write(self, frame, value):
- return pack('>h', int(round(value * 512)))
-
- def validate(self, frame, value): return value
-
-class VolumePeakSpec(Spec):
- def read(self, frame, data):
- # http://bugs.xmms.org/attachment.cgi?id=113&action=view
- peak = 0
- bits = ord(data[0])
- bytes = min(4, (bits + 7) >> 3)
- # not enough frame data
- if bytes + 1 > len(data): raise ID3JunkFrameError
- shift = ((8 - (bits & 7)) & 7) + (4 - bytes) * 8
- for i in range(1, bytes+1):
- peak *= 256
- peak += ord(data[i])
- peak *= 2**shift
- return (float(peak) / (2**31-1)), data[1+bytes:]
-
- def write(self, frame, value):
- # always write as 16 bits for sanity.
- return "\x10" + pack('>H', int(round(value * 32768)))
-
- def validate(self, frame, value): return value
-
-class SynchronizedTextSpec(EncodedTextSpec):
- def read(self, frame, data):
- texts = []
- encoding, term = self._encodings[frame.encoding]
- while data:
- l = len(term)
- value_idx = data.index(term)
- value = data[:value_idx].decode(encoding)
- time, = struct.unpack(">I", data[value_idx+l:value_idx+l+4])
- texts.append((value, time))
- data = data[value_idx+l+4:]
- return texts, ""
-
- def write(self, frame, value):
- data = []
- encoding, term = self._encodings[frame.encoding]
- for text, time in frame.text:
- text = text.encode(encoding) + term
- data.append(text + struct.pack(">I", time))
- return "".join(data)
-
- def validate(self, frame, value):
- return value
-
-class KeyEventSpec(Spec):
- def read(self, frame, data):
- events = []
- while len(data) >= 5:
- events.append(struct.unpack(">bI", data[:5]))
- data = data[5:]
- return events, data
-
- def write(self, frame, value):
- return "".join([struct.pack(">bI", *event) for event in value])
-
- def validate(self, frame, value):
- return value
-
-class VolumeAdjustmentsSpec(Spec):
- # Not to be confused with VolumeAdjustmentSpec.
- def read(self, frame, data):
- adjustments = {}
- while len(data) >= 4:
- freq, adj = struct.unpack(">Hh", data[:4])
- data = data[4:]
- freq /= 2.0
- adj /= 512.0
- adjustments[freq] = adj
- adjustments = adjustments.items()
- adjustments.sort()
- return adjustments, data
-
- def write(self, frame, value):
- value.sort()
- return "".join([struct.pack(">Hh", int(freq * 2), int(adj * 512))
- for (freq, adj) in value])
-
- def validate(self, frame, value):
- return value
-
-class ASPIIndexSpec(Spec):
- def read(self, frame, data):
- if frame.b == 16:
- format = "H"
- size = 2
- elif frame.b == 8:
- format = "B"
- size = 1
- else:
- warn("invalid bit count in ASPI (%d)" % frame.b, ID3Warning)
- return [], data
-
- indexes = data[:frame.N * size]
- data = data[frame.N * size:]
- return list(struct.unpack(">" + format * frame.N, indexes)), data
-
- def write(self, frame, values):
- if frame.b == 16: format = "H"
- elif frame.b == 8: format = "B"
- else: raise ValueError("frame.b must be 8 or 16")
- return struct.pack(">" + format * frame.N, *values)
-
- def validate(self, frame, values):
- return values
-
-class Frame(object):
- """Fundamental unit of ID3 data.
-
- ID3 tags are split into frames. Each frame has a potentially
- different structure, and so this base class is not very featureful.
- """
-
- FLAG23_ALTERTAG = 0x8000
- FLAG23_ALTERFILE = 0x4000
- FLAG23_READONLY = 0x2000
- FLAG23_COMPRESS = 0x0080
- FLAG23_ENCRYPT = 0x0040
- FLAG23_GROUP = 0x0020
-
- FLAG24_ALTERTAG = 0x4000
- FLAG24_ALTERFILE = 0x2000
- FLAG24_READONLY = 0x1000
- FLAG24_GROUPID = 0x0040
- FLAG24_COMPRESS = 0x0008
- FLAG24_ENCRYPT = 0x0004
- FLAG24_UNSYNCH = 0x0002
- FLAG24_DATALEN = 0x0001
-
- _framespec = []
- def __init__(self, *args, **kwargs):
- if len(args)==1 and len(kwargs)==0 and isinstance(args[0], type(self)):
- other = args[0]
- for checker in self._framespec:
- val = checker.validate(self, getattr(other, checker.name))
- setattr(self, checker.name, val)
- else:
- for checker, val in zip(self._framespec, args):
- setattr(self, checker.name, checker.validate(self, val))
- for checker in self._framespec[len(args):]:
- validated = checker.validate(
- self, kwargs.get(checker.name, None))
- setattr(self, checker.name, validated)
-
- HashKey = property(
- lambda s: s.FrameID,
- doc="an internal key used to ensure frame uniqueness in a tag")
- FrameID = property(
- lambda s: type(s).__name__,
- doc="ID3v2 three or four character frame ID")
-
- def __repr__(self):
- """Python representation of a frame.
-
- The string returned is a valid Python expression to construct
- a copy of this frame.
- """
- kw = []
- for attr in self._framespec:
- kw.append('%s=%r' % (attr.name, getattr(self, attr.name)))
- return '%s(%s)' % (type(self).__name__, ', '.join(kw))
-
- def _readData(self, data):
- odata = data
- for reader in self._framespec:
- if len(data):
- try: value, data = reader.read(self, data)
- except UnicodeDecodeError:
- raise ID3JunkFrameError
- else: raise ID3JunkFrameError
- setattr(self, reader.name, value)
- if data.strip('\x00'):
- warn('Leftover data: %s: %r (from %r)' % (
- type(self).__name__, data, odata),
- ID3Warning)
-
- def _writeData(self):
- data = []
- for writer in self._framespec:
- data.append(writer.write(self, getattr(self, writer.name)))
- return ''.join(data)
-
- def pprint(self):
- """Return a human-readable representation of the frame."""
- return "%s=%s" % (type(self).__name__, self._pprint())
-
- def _pprint(self):
- return "[unrepresentable data]"
-
- def fromData(cls, id3, tflags, data):
- """Construct this ID3 frame from raw string data."""
-
- if (2,4,0) <= id3.version:
- if tflags & (Frame.FLAG24_COMPRESS | Frame.FLAG24_DATALEN):
- # The data length int is syncsafe in 2.4 (but not 2.3).
- # However, we don't actually need the data length int,
- # except to work around a QL 0.12 bug, and in that case
- # all we need are the raw bytes.
- datalen_bytes = data[:4]
- data = data[4:]
- if tflags & Frame.FLAG24_UNSYNCH or id3.f_unsynch:
- try: data = unsynch.decode(data)
- except ValueError, err:
- if id3.PEDANTIC:
- raise ID3BadUnsynchData, '%s: %r' % (err, data)
- if tflags & Frame.FLAG24_ENCRYPT:
- raise ID3EncryptionUnsupportedError
- if tflags & Frame.FLAG24_COMPRESS:
- try: data = data.decode('zlib')
- except zlibError, err:
- # the initial mutagen that went out with QL 0.12 did not
- # write the 4 bytes of uncompressed size. Compensate.
- data = datalen_bytes + data
- try: data = data.decode('zlib')
- except zlibError, err:
- if id3.PEDANTIC:
- raise ID3BadCompressedData, '%s: %r' % (err, data)
-
- elif (2,3,0) <= id3.version:
- if tflags & Frame.FLAG23_COMPRESS:
- usize, = unpack('>L', data[:4])
- data = data[4:]
- if tflags & Frame.FLAG23_ENCRYPT:
- raise ID3EncryptionUnsupportedError
- if tflags & Frame.FLAG23_COMPRESS:
- try: data = data.decode('zlib')
- except zlibError, err:
- if id3.PEDANTIC:
- raise ID3BadCompressedData, '%s: %r' % (err, data)
-
- frame = cls()
- frame._rawdata = data
- frame._flags = tflags
- frame._readData(data)
- return frame
- fromData = classmethod(fromData)
-
- def __hash__(self):
- raise TypeError("Frame objects are unhashable")
-
-class FrameOpt(Frame):
- """A frame with optional parts.
-
- Some ID3 frames have optional data; this class extends Frame to
- provide support for those parts.
- """
- _optionalspec = []
-
- def __init__(self, *args, **kwargs):
- super(FrameOpt, self).__init__(*args, **kwargs)
- for spec in self._optionalspec:
- if spec.name in kwargs:
- validated = spec.validate(self, kwargs[spec.name])
- setattr(self, spec.name, validated)
- else: break
-
- def _readData(self, data):
- odata = data
- for reader in self._framespec:
- if len(data): value, data = reader.read(self, data)
- else: raise ID3JunkFrameError
- setattr(self, reader.name, value)
- if data:
- for reader in self._optionalspec:
- if len(data): value, data = reader.read(self, data)
- else: break
- setattr(self, reader.name, value)
- if data.strip('\x00'):
- warn('Leftover data: %s: %r (from %r)' % (
- type(self).__name__, data, odata),
- ID3Warning)
-
- def _writeData(self):
- data = []
- for writer in self._framespec:
- data.append(writer.write(self, getattr(self, writer.name)))
- for writer in self._optionalspec:
- try: data.append(writer.write(self, getattr(self, writer.name)))
- except AttributeError: break
- return ''.join(data)
-
- def __repr__(self):
- kw = []
- for attr in self._framespec:
- kw.append('%s=%r' % (attr.name, getattr(self, attr.name)))
- for attr in self._optionalspec:
- if hasattr(self, attr.name):
- kw.append('%s=%r' % (attr.name, getattr(self, attr.name)))
- return '%s(%s)' % (type(self).__name__, ', '.join(kw))
-
-
-class TextFrame(Frame):
- """Text strings.
-
- Text frames support casts to unicode or str objects, as well as
- list-like indexing, extend, and append.
-
- Iterating over a TextFrame iterates over its strings, not its
- characters.
-
- Text frames have a 'text' attribute which is the list of strings,
- and an 'encoding' attribute; 0 for ISO-8859 1, 1 UTF-16, 2 for
- UTF-16BE, and 3 for UTF-8. If you don't want to worry about
- encodings, just set it to 3.
- """
-
- _framespec = [ EncodingSpec('encoding'),
- MultiSpec('text', EncodedTextSpec('text'), sep=u'\u0000') ]
- def __str__(self): return self.__unicode__().encode('utf-8')
- def __unicode__(self): return u'\u0000'.join(self.text)
- def __eq__(self, other):
- if isinstance(other, str): return str(self) == other
- elif isinstance(other, unicode):
- return u'\u0000'.join(self.text) == other
- return self.text == other
- def __getitem__(self, item): return self.text[item]
- def __iter__(self): return iter(self.text)
- def append(self, value): return self.text.append(value)
- def extend(self, value): return self.text.extend(value)
- def _pprint(self): return " / ".join(self.text)
-
-class NumericTextFrame(TextFrame):
- """Numerical text strings.
-
- The numeric value of these frames can be gotten with unary plus, e.g.
- frame = TLEN('12345')
- length = +frame
- """
-
- _framespec = [ EncodingSpec('encoding'),
- MultiSpec('text', EncodedNumericTextSpec('text'), sep=u'\u0000') ]
-
- def __pos__(self):
- """Return the numerical value of the string."""
- return int(self.text[0])
-
-class NumericPartTextFrame(TextFrame):
- """Multivalue numerical text strings.
-
- These strings indicate 'part (e.g. track) X of Y', and unary plus
- returns the first value:
- frame = TRCK('4/15')
- track = +frame # track == 4
- """
-
- _framespec = [ EncodingSpec('encoding'),
- MultiSpec('text', EncodedNumericPartTextSpec('text'), sep=u'\u0000') ]
- def __pos__(self):
- return int(self.text[0].split("/")[0])
-
-class TimeStampTextFrame(TextFrame):
- """A list of time stamps.
-
- The 'text' attribute in this frame is a list of ID3TimeStamp
- objects, not a list of strings.
- """
-
- _framespec = [ EncodingSpec('encoding'),
- MultiSpec('text', TimeStampSpec('stamp'), sep=u',') ]
- def __str__(self): return self.__unicode__().encode('utf-8')
- def __unicode__(self): return ','.join([stamp.text for stamp in self.text])
- def _pprint(self):
- return " / ".join([stamp.text for stamp in self.text])
-
-class UrlFrame(Frame):
- """A frame containing a URL string.
-
- The ID3 specification is silent about IRIs and normalized URL
- forms. Mutagen assumes all URLs in files are encoded as Latin 1,
- but string conversion of this frame returns a UTF-8 representation
- for compatibility with other string conversions.
-
- The only sane way to handle URLs in MP3s is to restrict them to
- ASCII.
- """
-
- _framespec = [ Latin1TextSpec('url') ]
- def __str__(self): return self.url.encode('utf-8')
- def __unicode__(self): return self.url
- def __eq__(self, other): return self.url == other
- def _pprint(self): return self.url
-
-class UrlFrameU(UrlFrame):
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.url))
-
-class TALB(TextFrame): "Album"
-class TBPM(NumericTextFrame): "Beats per minute"
-class TCOM(TextFrame): "Composer"
-
-class TCON(TextFrame):
- """Content type (Genre)
-
- ID3 has several ways genres can be represented; for convenience,
- use the 'genres' property rather than the 'text' attribute.
- """
-
- from mutagen._constants import GENRES
-
- def __get_genres(self):
- genres = []
- import re
- genre_re = re.compile(r"((?:\((?P<id>[0-9]+|RX|CR)\))*)(?P<str>.+)?")
- for value in self.text:
- if value.isdigit():
- try: genres.append(self.GENRES[int(value)])
- except IndexError: genres.append(u"Unknown")
- elif value == "CR": genres.append(u"Cover")
- elif value == "RX": genres.append(u"Remix")
- elif value:
- newgenres = []
- genreid, dummy, genrename = genre_re.match(value).groups()
-
- if genreid:
- for gid in genreid[1:-1].split(")("):
- if gid.isdigit() and int(gid) < len(self.GENRES):
- gid = unicode(self.GENRES[int(gid)])
- newgenres.append(gid)
- elif gid == "CR": newgenres.append(u"Cover")
- elif gid == "RX": newgenres.append(u"Remix")
- else: newgenres.append(u"Unknown")
-
- if genrename:
- # "Unescaping" the first parenthesis
- if genrename.startswith("(("): genrename = genrename[1:]
- if genrename not in newgenres: newgenres.append(genrename)
-
- genres.extend(newgenres)
-
- return genres
-
- def __set_genres(self, genres):
- if isinstance(genres, basestring): genres = [genres]
- self.text = map(self.__decode, genres)
-
- def __decode(self, value):
- if isinstance(value, str):
- enc = EncodedTextSpec._encodings[self.encoding][0]
- return value.decode(enc)
- else: return value
-
- genres = property(__get_genres, __set_genres, None,
- "A list of genres parsed from the raw text data.")
-
- def _pprint(self):
- return " / ".join(self.genres)
-
-class TCOP(TextFrame): "Copyright (c)"
-class TCMP(NumericTextFrame): "iTunes Compilation Flag"
-class TDAT(TextFrame): "Date of recording (DDMM)"
-class TDEN(TimeStampTextFrame): "Encoding Time"
-class TDOR(TimeStampTextFrame): "Original Release Time"
-class TDLY(NumericTextFrame): "Audio Delay (ms)"
-class TDRC(TimeStampTextFrame): "Recording Time"
-class TDRL(TimeStampTextFrame): "Release Time"
-class TDTG(TimeStampTextFrame): "Tagging Time"
-class TENC(TextFrame): "Encoder"
-class TEXT(TextFrame): "Lyricist"
-class TFLT(TextFrame): "File type"
-class TIME(TextFrame): "Time of recording (HHMM)"
-class TIT1(TextFrame): "Content group description"
-class TIT2(TextFrame): "Title"
-class TIT3(TextFrame): "Subtitle/Description refinement"
-class TKEY(TextFrame): "Starting Key"
-class TLAN(TextFrame): "Audio Languages"
-class TLEN(NumericTextFrame): "Audio Length (ms)"
-class TMED(TextFrame): "Source Media Type"
-class TMOO(TextFrame): "Mood"
-class TOAL(TextFrame): "Original Album"
-class TOFN(TextFrame): "Original Filename"
-class TOLY(TextFrame): "Original Lyricist"
-class TOPE(TextFrame): "Original Artist/Performer"
-class TORY(NumericTextFrame): "Original Release Year"
-class TOWN(TextFrame): "Owner/Licensee"
-class TPE1(TextFrame): "Lead Artist/Performer/Soloist/Group"
-class TPE2(TextFrame): "Band/Orchestra/Accompaniment"
-class TPE3(TextFrame): "Conductor"
-class TPE4(TextFrame): "Interpreter/Remixer/Modifier"
-class TPOS(NumericPartTextFrame): "Part of set"
-class TPRO(TextFrame): "Produced (P)"
-class TPUB(TextFrame): "Publisher"
-class TRCK(NumericPartTextFrame): "Track Number"
-class TRDA(TextFrame): "Recording Dates"
-class TRSN(TextFrame): "Internet Radio Station Name"
-class TRSO(TextFrame): "Internet Radio Station Owner"
-class TSIZ(NumericTextFrame): "Size of audio data (bytes)"
-class TSOA(TextFrame): "Album Sort Order key"
-class TSOP(TextFrame): "Perfomer Sort Order key"
-class TSOT(TextFrame): "Title Sort Order key"
-class TSRC(TextFrame): "International Standard Recording Code (ISRC)"
-class TSSE(TextFrame): "Encoder settings"
-class TSST(TextFrame): "Set Subtitle"
-class TYER(NumericTextFrame): "Year of recording"
-
-class TXXX(TextFrame):
- """User-defined text data.
-
- TXXX frames have a 'desc' attribute which is set to any Unicode
- value (though the encoding of the text and the description must be
- the same). Many taggers use this frame to store freeform keys.
- """
- _framespec = [ EncodingSpec('encoding'), EncodedTextSpec('desc'),
- MultiSpec('text', EncodedTextSpec('text'), sep=u'\u0000') ]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.desc))
- def _pprint(self): return "%s=%s" % (self.desc, " / ".join(self.text))
-
-class WCOM(UrlFrameU): "Commercial Information"
-class WCOP(UrlFrame): "Copyright Information"
-class WOAF(UrlFrame): "Official File Information"
-class WOAR(UrlFrameU): "Official Artist/Performer Information"
-class WOAS(UrlFrame): "Official Source Information"
-class WORS(UrlFrame): "Official Internet Radio Information"
-class WPAY(UrlFrame): "Payment Information"
-class WPUB(UrlFrame): "Official Publisher Information"
-
-class WXXX(UrlFrame):
- """User-defined URL data.
-
- Like TXXX, this has a freeform description associated with it.
- """
- _framespec = [ EncodingSpec('encoding'), EncodedTextSpec('desc'),
- Latin1TextSpec('url') ]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.desc))
-
-class PairedTextFrame(Frame):
- """Paired text strings.
-
- Some ID3 frames pair text strings, to associate names with a more
- specific involvement in the song. The 'people' attribute of these
- frames contains a list of pairs:
- [['trumpet', 'Miles Davis'], ['bass', 'Paul Chambers']]
-
- Like text frames, these frames also have an encoding attribute.
- """
-
- _framespec = [ EncodingSpec('encoding'), MultiSpec('people',
- EncodedTextSpec('involvement'), EncodedTextSpec('person')) ]
- def __eq__(self, other):
- return self.people == other
-
-class TIPL(PairedTextFrame): "Involved People List"
-class TMCL(PairedTextFrame): "Musicians Credits List"
-class IPLS(TIPL): "Involved People List"
-
-class MCDI(Frame):
- """Binary dump of CD's TOC.
-
- The 'data' attribute contains the raw byte string.
- """
- _framespec = [ BinaryDataSpec('data') ]
- def __eq__(self, other): return self.data == other
-
-class ETCO(Frame):
- """Event timing codes."""
- _framespec = [ ByteSpec("format"), KeyEventSpec("events") ]
- def __eq__(self, other): return self.events == other
-
-class MLLT(Frame):
- """MPEG location lookup table.
-
- This frame's attributes may be changed in the future based on
- feedback from real-world use.
- """
- _framespec = [ SizedIntegerSpec('frames', 2),
- SizedIntegerSpec('bytes', 3),
- SizedIntegerSpec('milliseconds', 3),
- ByteSpec('bits_for_bytes'),
- ByteSpec('bits_for_milliseconds'),
- BinaryDataSpec('data') ]
- def __eq__(self, other): return self.data == other
-
-class SYTC(Frame):
- """Synchronised tempo codes.
-
- This frame's attributes may be changed in the future based on
- feedback from real-world use.
- """
- _framespec = [ ByteSpec("format"), BinaryDataSpec("data") ]
- def __eq__(self, other): return self.data == other
-
-class USLT(Frame):
- """Unsynchronised lyrics/text transcription.
-
- Lyrics have a three letter ISO language code ('lang'), a
- description ('desc'), and a block of plain text ('text').
- """
-
- _framespec = [ EncodingSpec('encoding'), StringSpec('lang', 3),
- EncodedTextSpec('desc'), EncodedTextSpec('text') ]
- HashKey = property(lambda s: '%s:%s:%r' % (s.FrameID, s.desc, s.lang))
-
- def __str__(self): return self.text.encode('utf-8')
- def __unicode__(self): return self.text
- def __eq__(self, other): return self.text == other
-
-class SYLT(Frame):
- """Synchronised lyrics/text."""
-
- _framespec = [ EncodingSpec('encoding'), StringSpec('lang', 3),
- ByteSpec('format'), ByteSpec('type'), EncodedTextSpec('desc'),
- SynchronizedTextSpec('text') ]
- HashKey = property(lambda s: '%s:%s:%r' % (s.FrameID, s.desc, s.lang))
-
- def __eq__(self, other):
- return str(self) == other
-
- def __str__(self):
- return "".join([text for (text, time) in self.text]).encode('utf-8')
-
-class COMM(TextFrame):
- """User comment.
-
- User comment frames have a descrption, like TXXX, and also a three
- letter ISO language code in the 'lang' attribute.
- """
- _framespec = [ EncodingSpec('encoding'), StringSpec('lang', 3),
- EncodedTextSpec('desc'),
- MultiSpec('text', EncodedTextSpec('text'), sep=u'\u0000') ]
- HashKey = property(lambda s: '%s:%s:%r' % (s.FrameID, s.desc, s.lang))
- def _pprint(self): return "%s=%r=%s" % (
- self.desc, self.lang, " / ".join(self.text))
-
-class RVA2(Frame):
- """Relative volume adjustment (2).
-
- This frame is used to implemented volume scaling, and in
- particular, normalization using ReplayGain.
-
- Attributes:
- desc -- description or context of this adjustment
- channel -- audio channel to adjust (master is 1)
- gain -- a + or - dB gain relative to some reference level
- peak -- peak of the audio as a floating point number, [0, 1]
-
- When storing ReplayGain tags, use descriptions of 'album' and
- 'track' on channel 1.
- """
-
- _framespec = [ Latin1TextSpec('desc'), ChannelSpec('channel'),
- VolumeAdjustmentSpec('gain'), VolumePeakSpec('peak') ]
- _channels = ["Other", "Master volume", "Front right", "Front left",
- "Back right", "Back left", "Front centre", "Back centre",
- "Subwoofer"]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.desc))
-
- def __eq__(self, other):
- return ((str(self) == other) or
- (self.desc == other.desc and
- self.channel == other.channel and
- self.gain == other.gain and
- self.peak == other.peak))
-
- def __str__(self):
- return "%s: %+0.4f dB/%0.4f" % (
- self._channels[self.channel], self.gain, self.peak)
-
-class EQU2(Frame):
- """Equalisation (2).
-
- Attributes:
- method -- interpolation method (0 = band, 1 = linear)
- desc -- identifying description
- adjustments -- list of (frequency, vol_adjustment) pairs
- """
- _framespec = [ ByteSpec("method"), Latin1TextSpec("desc"),
- VolumeAdjustmentsSpec("adjustments") ]
- def __eq__(self, other): return self.adjustments == other
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.desc))
-
-# class RVAD: unsupported
-# class EQUA: unsupported
-
-class RVRB(Frame):
- """Reverb."""
- _framespec = [ SizedIntegerSpec('left', 2), SizedIntegerSpec('right', 2),
- ByteSpec('bounce_left'), ByteSpec('bounce_right'),
- ByteSpec('feedback_ltl'), ByteSpec('feedback_ltr'),
- ByteSpec('feedback_rtr'), ByteSpec('feedback_rtl'),
- ByteSpec('premix_ltr'), ByteSpec('premix_rtl') ]
-
- def __eq__(self, other): return (self.left, self.right) == other
-
-class APIC(Frame):
- """Attached (or linked) Picture.
-
- Attributes:
- encoding -- text encoding for the description
- mime -- a MIME type (e.g. image/jpeg) or '-->' if the data is a URI
- type -- the source of the image (3 is the album front cover)
- desc -- a text description of the image
- data -- raw image data, as a byte string
-
- Mutagen will automatically compress large images when saving tags.
- """
- _framespec = [ EncodingSpec('encoding'), Latin1TextSpec('mime'),
- ByteSpec('type'), EncodedTextSpec('desc'), BinaryDataSpec('data') ]
- def __eq__(self, other): return self.data == other
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.desc))
- def _pprint(self):
- return "%s (%s, %d bytes)" % (
- self.desc, self.mime, len(self.data))
-
-class PCNT(Frame):
- """Play counter.
-
- The 'count' attribute contains the (recorded) number of times this
- file has been played.
-
- This frame is basically obsoleted by POPM.
- """
- _framespec = [ IntegerSpec('count') ]
-
- def __eq__(self, other): return self.count == other
- def __pos__(self): return self.count
- def _pprint(self): return unicode(self.count)
-
-class POPM(Frame):
- """Popularimeter.
-
- This frame keys a rating (out of 255) and a play count to an email
- address.
-
- Attributes:
- email -- email this POPM frame is for
- rating -- rating from 0 to 255
- count -- number of times the files has been played
- """
- _framespec = [ Latin1TextSpec('email'), ByteSpec('rating'),
- IntegerSpec('count') ]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.email))
-
- def __eq__(self, other): return self.rating == other
- def __pos__(self): return self.rating
- def _pprint(self): return "%s=%s %s/255" % (
- self.email, self.count, self.rating)
-
-class GEOB(Frame):
- """General Encapsulated Object.
-
- A blob of binary data, that is not a picture (those go in APIC).
-
- Attributes:
- encoding -- encoding of the description
- mime -- MIME type of the data or '-->' if the data is a URI
- filename -- suggested filename if extracted
- desc -- text description of the data
- data -- raw data, as a byte string
- """
- _framespec = [ EncodingSpec('encoding'), Latin1TextSpec('mime'),
- EncodedTextSpec('filename'), EncodedTextSpec('desc'),
- BinaryDataSpec('data') ]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.desc))
-
- def __eq__(self, other): return self.data == other
-
-class RBUF(FrameOpt):
- """Recommended buffer size.
-
- Attributes:
- size -- recommended buffer size in bytes
- info -- if ID3 tags may be elsewhere in the file (optional)
- offset -- the location of the next ID3 tag, if any
-
- Mutagen will not find the next tag itself.
- """
- _framespec = [ SizedIntegerSpec('size', 3) ]
- _optionalspec = [ ByteSpec('info'), SizedIntegerSpec('offset', 4) ]
-
- def __eq__(self, other): return self.size == other
- def __pos__(self): return self.size
-
-class AENC(FrameOpt):
- """Audio encryption.
-
- Attributes:
- owner -- key identifying this encryption type
- preview_start -- unencrypted data block offset
- preview_length -- number of unencrypted blocks
- data -- data required for decryption (optional)
-
- Mutagen cannot decrypt files.
- """
- _framespec = [ Latin1TextSpec('owner'),
- SizedIntegerSpec('preview_start', 2),
- SizedIntegerSpec('preview_length', 2) ]
- _optionalspec = [ BinaryDataSpec('data') ]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.owner))
-
- def __str__(self): return self.owner.encode('utf-8')
- def __unicode__(self): return self.owner
- def __eq__(self, other): return self.owner == other
-
-class LINK(FrameOpt):
- """Linked information.
-
- Attributes:
- frameid -- the ID of the linked frame
- url -- the location of the linked frame
- data -- further ID information for the frame
- """
-
- _framespec = [ StringSpec('frameid', 4), Latin1TextSpec('url') ]
- _optionalspec = [ BinaryDataSpec('data') ]
- def __HashKey(self):
- try:
- return "%s:%s:%s:%r" % (
- self.FrameID, self.frameid, self.url, self.data)
- except AttributeError:
- return "%s:%s:%s" % (self.FrameID, self.frameid, self.url)
- HashKey = property(__HashKey)
- def __eq__(self, other):
- try: return (self.frameid, self.url, self.data) == other
- except AttributeError: return (self.frameid, self.url) == other
-
-class POSS(Frame):
- """Position synchronisation frame
-
- Attribute:
- format -- format of the position attribute (frames or milliseconds)
- position -- current position of the file
- """
- _framespec = [ ByteSpec('format'), IntegerSpec('position') ]
-
- def __pos__(self): return self.position
- def __eq__(self, other): return self.position == other
-
-class UFID(Frame):
- """Unique file identifier.
-
- Attributes:
- owner -- format/type of identifier
- data -- identifier
- """
-
- _framespec = [ Latin1TextSpec('owner'), BinaryDataSpec('data') ]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.owner))
- def __eq__(s, o):
- if isinstance(o, UFI): return s.owner == o.owner and s.data == o.data
- else: return s.data == o
- def _pprint(self):
- isascii = ord(max(self.data)) < 128
- if isascii: return "%s=%s" % (self.owner, self.data)
- else: return "%s (%d bytes)" % (self.owner, len(self.data))
-
-class USER(Frame):
- """Terms of use.
-
- Attributes:
- encoding -- text encoding
- lang -- ISO three letter language code
- text -- licensing terms for the audio
- """
- _framespec = [ EncodingSpec('encoding'), StringSpec('lang', 3),
- EncodedTextSpec('text') ]
- HashKey = property(lambda s: '%s:%r' % (s.FrameID, s.lang))
-
- def __str__(self): return self.text.encode('utf-8')
- def __unicode__(self): return self.text
- def __eq__(self, other): return self.text == other
- def _pprint(self): return "%r=%s" % (self.lang, self.text)
-
-class OWNE(Frame):
- """Ownership frame."""
- _framespec = [ EncodingSpec('encoding'), Latin1TextSpec('price'),
- StringSpec('date', 8), EncodedTextSpec('seller') ]
-
- def __str__(self): return self.seller.encode('utf-8')
- def __unicode__(self): return self.seller
- def __eq__(self, other): return self.seller == other
-
-class COMR(FrameOpt):
- """Commercial frame."""
- _framespec = [ EncodingSpec('encoding'), Latin1TextSpec('price'),
- StringSpec('valid_until', 8), Latin1TextSpec('contact'),
- ByteSpec('format'), EncodedTextSpec('seller'),
- EncodedTextSpec('desc')]
- _optionalspec = [ Latin1TextSpec('mime'), BinaryDataSpec('logo') ]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s._writeData()))
- def __eq__(self, other): return self._writeData() == other._writeData()
-
-class ENCR(Frame):
- """Encryption method registration.
-
- The standard does not allow multiple ENCR frames with the same owner
- or the same method. Mutagen only verifies that the owner is unique.
- """
- _framespec = [ Latin1TextSpec('owner'), ByteSpec('method'),
- BinaryDataSpec('data') ]
- HashKey = property(lambda s: "%s:%s" % (s.FrameID, s.owner))
- def __str__(self): return self.data
- def __eq__(self, other): return self.data == other
-
-class GRID(FrameOpt):
- """Group identification registration."""
- _framespec = [ Latin1TextSpec('owner'), ByteSpec('group') ]
- _optionalspec = [ BinaryDataSpec('data') ]
- HashKey = property(lambda s: '%s:%s' % (s.FrameID, s.group))
- def __pos__(self): return self.group
- def __str__(self): return self.owner.encode('utf-8')
- def __unicode__(self): return self.owner
- def __eq__(self, other): return self.owner == other or self.group == other
-
-
-class PRIV(Frame):
- """Private frame."""
- _framespec = [ Latin1TextSpec('owner'), BinaryDataSpec('data') ]
- HashKey = property(lambda s: '%s:%s:%s' % (
- s.FrameID, s.owner, s.data.decode('latin1')))
- def __str__(self): return self.data
- def __eq__(self, other): return self.data == other
- def _pprint(self):
- isascii = ord(max(self.data)) < 128
- if isascii: return "%s=%s" % (self.owner, self.data)
- else: return "%s (%d bytes)" % (self.owner, len(self.data))
-
-class SIGN(Frame):
- """Signature frame."""
- _framespec = [ ByteSpec('group'), BinaryDataSpec('sig') ]
- HashKey = property(lambda s: '%s:%c:%s' % (s.FrameID, s.group, s.sig))
- def __str__(self): return self.sig
- def __eq__(self, other): return self.sig == other
-
-class SEEK(Frame):
- """Seek frame.
-
- Mutagen does not find tags at seek offsets.
- """
- _framespec = [ IntegerSpec('offset') ]
- def __pos__(self): return self.offset
- def __eq__(self, other): return self.offset == other
-
-class ASPI(Frame):
- """Audio seek point index.
-
- Attributes: S, L, N, b, and Fi. For the meaning of these, see
- the ID3v2.4 specification. Fi is a list of integers.
- """
- _framespec = [ SizedIntegerSpec("S", 4), SizedIntegerSpec("L", 4),
- SizedIntegerSpec("N", 2), ByteSpec("b"),
- ASPIIndexSpec("Fi") ]
- def __eq__(self, other): return self.Fi == other
-
-Frames = dict([(k,v) for (k,v) in globals().items()
- if len(k)==4 and isinstance(v, type) and issubclass(v, Frame)])
-"""All supported ID3v2 frames, keyed by frame name."""
-del(k); del(v)
-
-# ID3v2.2 frames
-class UFI(UFID): "Unique File Identifier"
-
-class TT1(TIT1): "Content group description"
-class TT2(TIT2): "Title"
-class TT3(TIT3): "Subtitle/Description refinement"
-class TP1(TPE1): "Lead Artist/Performer/Soloist/Group"
-class TP2(TPE2): "Band/Orchestra/Accompaniment"
-class TP3(TPE3): "Conductor"
-class TP4(TPE4): "Interpreter/Remixer/Modifier"
-class TCM(TCOM): "Composer"
-class TXT(TEXT): "Lyricist"
-class TLA(TLAN): "Audio Language(s)"
-class TCO(TCON): "Content Type (Genre)"
-class TAL(TALB): "Album"
-class TPA(TPOS): "Part of set"
-class TRK(TRCK): "Track Number"
-class TRC(TSRC): "International Standard Recording Code (ISRC)"
-class TYE(TYER): "Year of recording"
-class TDA(TDAT): "Date of recording (DDMM)"
-class TIM(TIME): "Time of recording (HHMM)"
-class TRD(TRDA): "Recording Dates"
-class TMT(TMED): "Source Media Type"
-class TFT(TFLT): "File Type"
-class TBP(TBPM): "Beats per minute"
-class TCP(TCMP): "iTunes Compilation Flag"
-class TCR(TCOP): "Copyright (C)"
-class TPB(TPUB): "Publisher"
-class TEN(TENC): "Encoder"
-class TSS(TSSE): "Encoder settings"
-class TOF(TOFN): "Original Filename"
-class TLE(TLEN): "Audio Length (ms)"
-class TSI(TSIZ): "Audio Data size (bytes)"
-class TDY(TDLY): "Audio Delay (ms)"
-class TKE(TKEY): "Starting Key"
-class TOT(TOAL): "Original Album"
-class TOA(TOPE): "Original Artist/Perfomer"
-class TOL(TOLY): "Original Lyricist"
-class TOR(TORY): "Original Release Year"
-
-class TXX(TXXX): "User-defined Text"
-
-class WAF(WOAF): "Official File Information"
-class WAR(WOAR): "Official Artist/Performer Information"
-class WAS(WOAS): "Official Source Information"
-class WCM(WCOM): "Commercial Information"
-class WCP(WCOP): "Copyright Information"
-class WPB(WPUB): "Official Publisher Information"
-
-class WXX(WXXX): "User-defined URL"
-
-class IPL(IPLS): "Involved people list"
-class MCI(MCDI): "Binary dump of CD's TOC"
-class ETC(ETCO): "Event timing codes"
-class MLL(MLLT): "MPEG location lookup table"
-class STC(SYTC): "Synced tempo codes"
-class ULT(USLT): "Unsychronised lyrics/text transcription"
-class SLT(SYLT): "Synchronised lyrics/text"
-class COM(COMM): "Comment"
-#class RVA(RVAD)
-#class EQU(EQUA)
-class REV(RVRB): "Reverb"
-class PIC(APIC):
- """Attached Picture.
-
- The 'mime' attribute of an ID3v2.2 attached picture must be either
- 'PNG' or 'JPG'.
- """
- _framespec = [ EncodingSpec('encoding'), StringSpec('mime', 3),
- ByteSpec('type'), EncodedTextSpec('desc'), BinaryDataSpec('data') ]
-class GEO(GEOB): "General Encapsulated Object"
-class CNT(PCNT): "Play counter"
-class POP(POPM): "Popularimeter"
-class BUF(RBUF): "Recommended buffer size"
-
-class CRM(Frame):
- """Encrypted meta frame"""
- _framespec = [ Latin1TextSpec('owner'), Latin1TextSpec('desc'),
- BinaryDataSpec('data') ]
- def __eq__(self, other): return self.data == other
-
-class CRA(AENC): "Audio encryption"
-
-class LNK(LINK):
- """Linked information"""
- _framespec = [ StringSpec('frameid', 3), Latin1TextSpec('url') ]
- _optionalspec = [ BinaryDataSpec('data') ]
-
-Frames_2_2 = dict([(k,v) for (k,v) in globals().items()
- if len(k)==3 and isinstance(v, type) and issubclass(v, Frame)])
-
-# support open(filename) as interface
-Open = ID3
-
-# ID3v1.1 support.
-def ParseID3v1(string):
- """Parse an ID3v1 tag, returning a list of ID3v2.4 frames."""
- from struct import error as StructError
- frames = {}
- try:
- tag, title, artist, album, year, comment, track, genre = unpack(
- "3s30s30s30s4s29sBB", string)
- except StructError: return None
-
- if tag != "TAG": return None
- def fix(string):
- return string.split("\x00")[0].strip().decode('latin1')
- title, artist, album, year, comment = map(
- fix, [title, artist, album, year, comment])
-
- if title: frames["TIT2"] = TIT2(encoding=0, text=title)
- if artist: frames["TPE1"] = TPE1(encoding=0, text=[artist])
- if album: frames["TALB"] = TALB(encoding=0, text=album)
- if year: frames["TDRC"] = TDRC(encoding=0, text=year)
- if comment: frames["COMM"] = COMM(
- encoding=0, lang="eng", desc="ID3v1 Comment", text=comment)
- # Don't read a track number if it looks like the comment was
- # padded with spaces instead of nulls (thanks, WinAmp).
- if track and (track != 32 or string[-3] == '\x00'):
- frames["TRCK"] = TRCK(encoding=0, text=str(track))
- if genre != 255: frames["TCON"] = TCON(encoding=0, text=str(genre))
- return frames
-
-def MakeID3v1(id3):
- """Return an ID3v1.1 tag string from a dict of ID3v2.4 frames."""
-
- v1 = {}
-
- for v2id, name in {"TIT2": "title", "TPE1": "artist",
- "TALB": "album"}.items():
- if v2id in id3:
- text = id3[v2id].text[0].encode('latin1', 'replace')[:30]
- else: text = ""
- v1[name] = text + ("\x00" * (30 - len(text)))
-
- if "COMM" in id3:
- cmnt = id3["COMM"].text[0].encode('latin1', 'replace')[:28]
- else: cmnt = ""
- v1["comment"] = cmnt + ("\x00" * (29 - len(cmnt)))
-
- if "TRCK" in id3:
- try: v1["track"] = chr(+id3["TRCK"])
- except ValueError: v1["track"] = "\x00"
- else: v1["track"] = "\x00"
-
- if "TCON" in id3:
- try: genre = id3["TCON"].genres[0]
- except IndexError: pass
- else:
- if genre in TCON.GENRES:
- v1["genre"] = chr(TCON.GENRES.index(genre))
- if "genre" not in v1: v1["genre"] = "\xff"
-
- if "TDRC" in id3: v1["year"] = str(id3["TDRC"])[:4]
- else: v1["year"] = "\x00\x00\x00\x00"
-
- return ("TAG%(title)s%(artist)s%(album)s%(year)s%(comment)s"
- "%(track)s%(genre)s") % v1
-
-class ID3FileType(mutagen.FileType):
- """An unknown type of file with ID3 tags."""
-
- class _Info(object):
- length = 0
- def __init__(self, fileobj, offset): pass
- pprint = staticmethod(lambda: "Unknown format with ID3 tag")
-
- def score(filename, fileobj, header):
- return header.startswith("ID3")
- score = staticmethod(score)
-
- def add_tags(self, ID3=ID3):
- """Add an empty ID3 tag to the file.
-
- A custom tag reader may be used in instead of the default
- mutagen.id3.ID3 object, e.g. an EasyID3 reader.
- """
- if self.tags is None:
- self.tags = ID3()
- else:
- raise error("an ID3 tag already exists")
-
- def load(self, filename, ID3=ID3, **kwargs):
- """Load stream and tag information from a file.
-
- A custom tag reader may be used in instead of the default
- mutagen.id3.ID3 object, e.g. an EasyID3 reader.
- """
- self.filename = filename
- try: self.tags = ID3(filename, **kwargs)
- except error: self.tags = None
- if self.tags is not None:
- try: offset = self.tags.size
- except AttributeError: offset = None
- else: offset = None
- try:
- fileobj = file(filename, "rb")
- self.info = self._Info(fileobj, offset)
- finally:
- fileobj.close()
-
fnp / wolnelektury.git / commitdiff