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.
ID3v1 tags will be removed
ID3v1 tags will be updated but not added
ID3v1 tags will be created and/or updated
Enumeration of image types defined by the ID3 standard for the APIC frame, but also reused in WMA/FLAC/VorbisComment.
Other
32x32 pixels ‘file icon’ (PNG only)
Other file icon
Cover (front)
Cover (back)
Leaflet page
Media (e.g. label side of CD)
Lead artist/lead performer/soloist
Artist/performer
Conductor
Band/Orchestra
Composer
Lyricist/text writer
Recording Location
During recording
During performance
Movie/video screen capture
A bright coloured fish
Illustration
Band/artist logotype
Publisher/Studio logotype
Bases: mutagen._util.DictProxy, mutagen.Tags
Add a frame to the tag.
Delete all tags of a given kind; see getall.
Parameters: | key (text) – key for frames to delete |
---|
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:').
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
Delete frames of the given type and add frames in ‘values’.
Parameters: |
|
---|
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.
Bases: mutagen.id3.ID3Tags, mutagen.Metadata
ID3(filething=None)
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 |
---|
Tuple[int]
ID3 tag version as a tuple
List[bytes]
raw frame data of any unknown frames found
int
the total size of the ID3 tag, including the header
Remove tags from a file.
Parameters: |
|
---|
If no filename is given, the one most recently loaded is used.
Load tags from a filename.
Parameters: |
|
---|
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 changes to a file.
Parameters: |
|
---|---|
Raises : |
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.
tuple: ID3 tag version as a tuple (of the loaded file)
ID3FileType(filething, ID3=None, **kwargs)
An unknown type of file with ID3 tags.
Parameters: |
|
---|---|
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 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.
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
EasyID3(filething=None)
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 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")
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 changes to a file. See mutagen.id3.ID3.save() for more info.
Print tag key=value pairs.
Bases: mutagen.id3.ID3FileType
EasyID3FileType(filething=None)
Like ID3FileType, but uses EasyID3 for tags.
Parameters: | (filething) (filething) – |
---|