ID3

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

New 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