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.
Bases: mutagen._util.DictProxy, mutagen.Metadata
A file with an ID3v2 tag.
Attributes:
Add a frame to the tag.
Delete all tags of a given kind; see getall.
Remove tags from a file.
If no filename is given, the one most recently loaded is used.
Keyword arguments:
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 tags from a filename.
Keyword arguments:
filename – filename to load tag data from
known_frames – dict mapping frame IDs to Frame objects
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)
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 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.
The lack of a way to update only an ID3v1 tag is intentional.
Delete frames of the given type and add frames in ‘values’.
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.
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.
An unknown type of file with ID3 tags.
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 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.
Easier access to ID3 tags.
EasyID3 is a wrapper around mutagen.id3.ID3 to make ID3 tags appear more like Vorbis or APEv2 tags.
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
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.
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').
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")
Print tag key=value pairs.
Bases: mutagen.id3.ID3FileType
Like ID3FileType, but uses EasyID3 for tags.
MPEG audio stream information and tags.
Bases: mutagen.id3.ID3FileType
An MPEG audio (usually MPEG-1 Layer 3) file.
Variables: |
---|
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:
Useless attributes:
Bases: mutagen.mp3.MP3
Like MP3, but uses EasyID3 for tags.
Variables: |
---|
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.
Bases: mutagen.id3.ID3FileType
A True Audio file.
Variables: |
|
---|
True Audio stream information.
Attributes:
Bases: mutagen.trueaudio.TrueAudio
Like MP3, but uses EasyID3 for tags.
Variables: |
|
---|