# ID3

ID3v2 reading and writing.

This is based off of the following references:

- http://id3.org/id3v2.4.0-structure

- http://id3.org/id3v2.4.0-frames

- http://id3.org/id3v2.3.0

- http://id3.org/id3v2-00

- http://id3.org/ID3v1

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.

## ID3 Frames

class mutagen.id3.ID3v1SaveOptions
  REMOVE = <ID3v1SaveOptions.REMOVE: 0>

    ID3v1 tags will be removed

  UPDATE = <ID3v1SaveOptions.UPDATE: 1>

    ID3v1 tags will be updated but not added

  CREATE = <ID3v1SaveOptions.CREATE: 2>

    ID3v1 tags will be created and/or updated

class mutagen.id3.PictureType

  Enumeration of image types defined by the ID3 standard for the APIC frame, but also reused in WMA/FLAC/VorbisComment.

  OTHER = <PictureType.OTHER: 0>

    Other

  FILE_ICON = <PictureType.FILE_ICON: 1>

    32x32 pixels ‘file icon’ (PNG only)

  OTHER_FILE_ICON = <PictureType.OTHER_FILE_ICON: 2>

    Other file icon

  COVER_FRONT = <PictureType.COVER_FRONT: 3>

    Cover (front)

  COVER_BACK = <PictureType.COVER_BACK: 4>

    Cover (back)

  LEAFLET_PAGE = <PictureType.LEAFLET_PAGE: 5>

    Leaflet page

  MEDIA = <PictureType.MEDIA: 6>

    Media (e.g. label side of CD)

  LEAD_ARTIST = <PictureType.LEAD_ARTIST: 7>

    Lead artist/lead performer/soloist

  ARTIST = <PictureType.ARTIST: 8>

    Artist/performer

  CONDUCTOR = <PictureType.CONDUCTOR: 9>

    Conductor

  BAND = <PictureType.BAND: 10>

    Band/Orchestra

  COMPOSER = <PictureType.COMPOSER: 11>

    Composer

  LYRICIST = <PictureType.LYRICIST: 12>

    Lyricist/text writer

  RECORDING_LOCATION = <PictureType.RECORDING_LOCATION: 13>

    Recording Location

  DURING_RECORDING = <PictureType.DURING_RECORDING: 14>

    During recording

  DURING_PERFORMANCE = <PictureType.DURING_PERFORMANCE: 15>

    During performance

  SCREEN_CAPTURE = <PictureType.SCREEN_CAPTURE: 16>

    Movie/video screen capture

  FISH = <PictureType.FISH: 17>

    A bright coloured fish

  ILLUSTRATION = <PictureType.ILLUSTRATION: 18>

    Illustration

  BAND_LOGOTYPE = <PictureType.BAND_LOGOTYPE: 19>

    Band/artist logotype

  PUBLISHER_LOGOTYPE = <PictureType.PUBLISHER_LOGOTYPE: 20>

    Publisher/Studio logotype

class mutagen.id3.Encoding

  Text Encoding

  LATIN1 = <Encoding.LATIN1: 0>

    ISO-8859-1

  UTF16 = <Encoding.UTF16: 1>

    UTF-16 with BOM

  UTF16BE = <Encoding.UTF16BE: 2>

    UTF-16BE without BOM

  UTF8 = <Encoding.UTF8: 3>

    UTF-8

class mutagen.id3.CTOCFlags
  TOP_LEVEL = <CTOCFlags.TOP_LEVEL: 2>

    Identifies the CTOC root frame

  ORDERED = <CTOCFlags.ORDERED: 1>

    Child elements are ordered

## ID3

class mutagen.id3.ID3Tags(*args, **kwargs)

  Bases: `DictProxy`, `Tags`

  add(frame)

    Add a frame to the tag.

  delall(key)

    Delete all tags of a given kind; see getall.

    Parameters:

      key (text) – key for frames to delete

  getall(key)

    Return all frames with a given name (the list may be empty).

    Parameters:

      key (text) – key for frames to get

    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:')`.

  pprint()
    Returns:

      tags in a human-readable format.

    Return type:

      text

    “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`

  setall(key, values)

    Delete frames of the given type and add frames in ‘values’.

    Parameters:

      - key (text) – key for frames to delete

      - values (list[Frame]) – frames to add

  update_to_v23()

    Convert older (and newer) tags into an ID3v2.3 tag.

    This updates incompatible ID3v2 frames to ID3v2.3 ones. If you intend to save tags as ID3v2.3, you must call this function at some point.

    If you want to to go off spec and include some v2.4 frames in v2.3, remove them before calling this and add them back afterwards.

  update_to_v24()

    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.

class mutagen.id3.ID3(filething=None)

  Bases: `ID3Tags`, `Metadata`

  A file with an ID3v2 tag.

  If any arguments are given, the `load()` is called with them. If no arguments are given then an empty `ID3` object is created.

      ID3("foo.mp3")
      # same as
      t = ID3()
      t.load("foo.mp3")

  Parameters:

    filething (filething) – or `None`

  version

    ID3 tag version as a tuple

    Type:

      tuple[int]

  unknown_frames

    raw frame data of any unknown frames found

    Type:

      list[bytes]

  size

    the total size of the ID3 tag, including the header

    Type:

      int

  delete(filething=None, delete_v1=True, delete_v2=True)

    Remove tags from a file.

    Parameters:

      - filething (filething) – A filename or `None` to use the one used when loading.

      - delete_v1 (bool) – delete any ID3v1 tag

      - delete_v2 (bool) – delete any ID3v2 tag

    If no filename is given, the one most recently loaded is used.

  load(filething, known_frames=None, translate=True, v2_version=4, load_v1=True)

    Load tags from a filename.

    Parameters:

      - filename (filething) – filename or file object to load tag data from

      - known_frames (Dict[`mutagen.text`, `Frame`]) – dict mapping frame IDs to Frame objects

      - translate (bool) – Update all tags to ID3v2.3/4 internally. If you intend to save, this must be true or you have to call update_to_v23() / update_to_v24() manually.

      - v2_version (int) – if update_to_v23 or update_to_v24 get called (3 or 4)

      - load_v1 (bool) –

        Load tags from ID3v1 header if present. If both ID3v1 and ID3v2 headers are present, combine the tags from the two, with ID3v2 having precedence.

        Added in version 1.42.

    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)

  save(filething=None, v1=1, v2_version=4, v23_sep='/', padding=None)

    Save changes to a file.

    Parameters:

      - filething (filething) – Filename to save the tag to. If no filename is given, the one most recently loaded is used.

      - v1 (ID3v1SaveOptions) – 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

      - v2_version (int) – version of ID3v2 tags (3 or 4).

      - v23_sep (text) – the separator used to join multiple text values if v2_version == 3. Defaults to ‘/’ but if it’s None will be the ID3v2v2.4 null separator.

      - padding (`mutagen.PaddingFunction`)

    Raises:

      mutagen.MutagenError –

    By default Mutagen saves ID3v2.4 tags. If you want to save ID3v2.3 tags, you must call method update_to_v23 before saving the file.

    The lack of a way to update only an ID3v1 tag is intentional.

class mutagen.id3.ID3FileType(filething, ID3=None, **kwargs)

  An unknown type of file with ID3 tags.

  Parameters:

    - filething (filething) – A filename or file-like object

    - ID3 (ID3) – An ID3 subclass to use for tags.

  Raises:

    mutagen.MutagenError – In case loading the file failed

  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.

  add_tags(ID3=None)

    Add an empty ID3 tag to the file.

    Parameters:

      ID3 (ID3) – An ID3 subclass to use or `None` to use the one that used when loading.

    A custom tag reader may be used in instead of the default `ID3` object, e.g. an `mutagen.easyid3.EasyID3` reader.

  static score(filename, fileobj, header_data)

    Returns a score for how likely the file can be parsed by this type.

    Parameters:

      - filename (fspath) – a file path

      - fileobj (fileobj) – a file object open in rb mode. Position is undefined

      - header (bytes) – data of undefined length, starts with the start of the file.

    Returns:

      negative if definitely not a matching type, otherwise a score,

        the bigger the more certain that the file can be loaded.

    Return type:

      int

## EasyID3

Easier access to ID3 tags.

EasyID3 is a wrapper around mutagen.id3.ID3 to make ID3 tags appear more like Vorbis or APEv2 tags.

class mutagen.easyid3.EasyID3(filething=None)

  Bases: `DictMixin`, `Metadata`

  A file with an ID3 tag.

  Like Vorbis comments, EasyID3 keys are case-insensitive ASCII strings. Only a subset of ID3 frames are supported by default. Use EasyID3.RegisterKey and its wrappers to support more.

  You can also set the GetFallback, SetFallback, and DeleteFallback to generic key getter/setter/deleter functions, which are called if no specific handler is registered for a key. Additionally, ListFallback can be used to supply an arbitrary list of extra keys. These can be set on EasyID3 or on individual instances after creation.

  To use an EasyID3 class with mutagen.mp3.MP3:

      from mutagen.mp3 import EasyMP3 as MP3
      MP3(filename)

  Because many of the attributes are constructed on the fly, things like the following will not work:

      ezid3["performer"].append("Joe")

  Instead, you must do:

      values = ezid3["performer"]
      values.append("Joe")
      ezid3["performer"] = values

  classmethod RegisterKey(key, getter=None, setter=None, deleter=None, lister=None)

    Register a new key mapping.

    A key mapping is four functions, a getter, setter, deleter, and lister. The key may be either a string or a glob pattern.

    The getter, deleted, and lister receive an ID3 instance and the requested key name. The setter also receives the desired value, which will be a list of strings.

    The getter, setter, and deleter are used to implement __getitem__, __setitem__, and __delitem__.

    The lister is used to implement keys(). It should return a list of keys that are actually in the ID3 instance, provided by its associated getter.

  classmethod RegisterTextKey(key, frameid)

    Register a text key.

    If the key you need to register is a simple one-to-one mapping of ID3 frame name to EasyID3 key, then you can use this function:

        EasyID3.RegisterTextKey("title", "TIT2")

  classmethod RegisterTXXXKey(key, desc)

    Register a user-defined text frame key.

    Some ID3 tags are stored in TXXX frames, which allow a freeform ‘description’ which acts as a subkey, e.g. TXXX:BARCODE.:

        EasyID3.RegisterTXXXKey('barcode', 'BARCODE').

  save(filething=None, v1=1, v2_version=4, v23_sep='/', padding=None)

    Save changes to a file. See `mutagen.id3.ID3.save()` for more info.

  property delete

    Remove tags from a file.

    In most cases this means any traces of the tag will be removed from the file.

    Parameters:

      filething (filething) – or `None`

    Raises:

      MutagenError – if deleting wasn’t possible

  pprint()

    Print tag key=value pairs.

class mutagen.easyid3.EasyID3FileType(filething=None)

  Bases: `ID3FileType`

  Like ID3FileType, but uses EasyID3 for tags.

  Parameters:

    filething (filething)

  tags
    Type:

      `EasyID3`