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 Frames

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

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
PEDANTIC = True

Deprecated. Doesn’t have any effect

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.

Args:
filename:
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 (int):
version of ID3v2 tags (3 or 4).
v23_sep (str):
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.

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.

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.

version

ID3 tag version as a tuple (of the loaded file)

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

  • channels – number of audio channels

  • bitrate – audio bitrate, in bits per second

  • sketchy – if true, the file may not be valid MPEG audio

  • encoder_info – a string containing encoder name and possibly version.

    In case a lame tag is present this will start with "LAME ", if unknown it is empty, otherwise the text format is undefined.

  • bitrate_mode – a BitrateMode

  • track_gain – replaygain track gain (89db) or None

  • track_peak – replaygain track peak or None

  • album_gain – replaygain album gain (89db) or None

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.BitrateMode
ABR = <BitrateMode.ABR: 3>

Average Bitrate (a variant of VBR)

CBR = <BitrateMode.CBR: 1>

Constant Bitrate

UNKNOWN = <BitrateMode.UNKNOWN: 0>

Probably a CBR file, but not sure

VBR = <BitrateMode.VBR: 2>

Variable Bitrate

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