ID3v2

ID3v2 reading and writing.

This is based off of the following references:

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

class mutagen.id3.ID3

Bases: mutagen._util.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
add(frame)

Add a frame to the tag.

delall(key)

Delete all tags of a given kind; see getall.

delete(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
getall(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:').

load(filename, known_frames=None, translate=True, v2_version=4)

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.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 – if update_to_v23 or update_to_v24 get called (3 or 4)

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)
pprint()

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
save(filename=None, v1=1, v2_version=4, v23_sep='/')

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

v2 – version of ID3v2 tags (3 or 4).

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.

v23_sep – 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.

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

setall(key, values)

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

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.ID3FileType(filename, ID3=None)

An unknown type of file with ID3 tags.

add_tags(ID3=None)

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.

load(filename, ID3=None, **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.

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(filename=None)

Bases: mutagen._util.DictMixin, mutagen.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 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').
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")
pprint()

Print tag key=value pairs.

class mutagen.easyid3.EasyID3FileType(filename=None, *args, **kwargs)

Bases: mutagen.id3.ID3FileType

Like ID3FileType, but uses EasyID3 for tags.

MP3

MPEG audio stream information and tags.

class mutagen.mp3.MP3(filename, ID3=None)

Bases: mutagen.id3.ID3FileType

An MPEG audio (usually MPEG-1 Layer 3) file.

Variables:
class mutagen.mp3.MPEGInfo

MPEG audio stream information

Parse information about an MPEG audio file. This also reads the Xing VBR header format.

This code was implemented based on the format documentation at http://mpgedit.org/mpgedit/mpeg_format/mpeghdr.htm.

Useful attributes:

  • length – audio length, in seconds
  • bitrate – audio bitrate, in bits per second
  • sketchy – if true, the file may not be valid MPEG audio

Useless attributes:

  • version – MPEG version (1, 2, 2.5)
  • layer – 1, 2, or 3
  • mode – One of STEREO, JOINTSTEREO, DUALCHANNEL, or MONO (0-3)
  • protected – whether or not the file is “protected”
  • padding – whether or not audio frames are padded
  • sample_rate – audio sample rate, in Hz
class mutagen.mp3.EasyMP3(filename, ID3=None)

Bases: mutagen.mp3.MP3

Like MP3, but uses EasyID3 for tags.

Variables:

TrueAudio

True Audio audio stream information and tags.

True Audio is a lossless format designed for real-time encoding and decoding. This module is based on the documentation at http://www.true-audio.com/TTA_Lossless_Audio_Codec_-_Format_Description

True Audio files use ID3 tags.

class mutagen.trueaudio.TrueAudio(filename, ID3=None)

Bases: mutagen.id3.ID3FileType

A True Audio file.

Variables:
class mutagen.trueaudio.TrueAudioInfo

True Audio stream information.

Attributes:

  • length - audio length, in seconds
  • sample_rate - audio sample rate, in Hz
class mutagen.trueaudio.EasyTrueAudio(filename, ID3=None)

Bases: mutagen.trueaudio.TrueAudio

Like MP3, but uses EasyID3 for tags.

Variables:

AIFF

AIFF audio stream information and tags.

class mutagen.aiff.AIFF(filename)

Bases: mutagen.FileType

An AIFF audio file.

Variables:
add_tags()

Add an empty ID3 tag to the file.

load(filename, **kwargs)

Load stream and tag information from a file.

class mutagen.aiff.AIFFInfo

AIFF audio stream information.

Information is parsed from the COMM chunk of the AIFF file

Useful attributes:

  • length – audio length, in seconds
  • bitrate – audio bitrate, in bits per second
  • channels – The number of audio channels
  • sample_rate – audio sample rate, in Hz
  • sample_size – The audio sample size

Table Of Contents

Previous topic

Main Module

Next topic

Frame Base Classes

This Page