Unlike Vorbis, FLAC, and APEv2 comments, ID3 data is highly structured. Because of this, the interface for ID3 tags is very different from the APEv2 or Vorbis/FLAC interface. For example, to set the title of an ID3 tag, you need to do the following:
from mutagen.id3 import ID3, TIT2 audio = ID3("example.mp3") audio.add(TIT2(encoding=3, text=u"An example")) audio.save()
If you use the ID3 module, you should familiarize yourself with how ID3v2 tags are stored, by reading the details of the ID3v2 standard at http://id3.org/id3v2.4.0-structure.
ID3 Dict Interface¶
>>> mutagen.File("01. On The Road Again.mp3").keys() [u'TXXX:replaygain_album_peak', u'RVA2:track', u'APIC:picture', u'UFID:http://musicbrainz.org', 'TDRC', u'TXXX:replaygain_track_peak', 'TIT2', u'RVA2:album', u'TXXX:replaygain_track_gain', u'TXXX:MusicBrainz Album Id', 'TRCK', 'TPE1', 'TALB', u'TXXX:MusicBrainz Album Artist Id', u'TXXX:replaygain_album_gain'] >>>
On the first look the key format in the ID3 dict seem a bit confusing, this is
because they are the frame hashes of the corresponding dict values
Frame.HashKey). For example the ID3 specification states that there
can’t be two APIC frames with the same description, so the frame hash contains
the description and adding a new frame with the same description will replace
the old one. Only the first four letters always represent the frame type name.
In many cases you don’t care about the hash and just want to look up all
frames of one type. For this use the
>>> for frame in mutagen.File("01. On The Road Again.mp3").tags.getall("TXXX"): ... frame ... TXXX(encoding=<Encoding.LATIN1: 0>, desc=u'replaygain_album_peak', text=[u'1.00000000047']) TXXX(encoding=<Encoding.LATIN1: 0>, desc=u'replaygain_track_peak', text=[u'1.00000000047']) TXXX(encoding=<Encoding.LATIN1: 0>, desc=u'replaygain_track_gain', text=[u'-7.429688 dB']) TXXX(encoding=<Encoding.LATIN1: 0>, desc=u'MusicBrainz Album Id', text=[u'be6fb9b0-5073-4633-aefa-c559554f28e5']) TXXX(encoding=<Encoding.LATIN1: 0>, desc=u'MusicBrainz Album Artist Id', text=[u'815a0279-558c-4522-ac3b-6a1e259e95b5']) TXXX(encoding=<Encoding.LATIN1: 0>, desc=u'replaygain_album_gain', text=[u'-7.429688 dB'])
For adding new frames you can use the
ID3Tags.add() method, which will
use the frame hash as key. For example the ID3 spec only allows one TALB
frame, so passing a TALB frame to add() will replace the old frame:
>>> tags.getall("TALB") [TALB(encoding=<Encoding.UTF8: 3>, text=[u'The Very Best of Canned Heat'])] >>> tags.add(TALB(text=[u"new value"])) >>> tags.getall("TALB") [TALB(encoding=<Encoding.UTF16: 1>, text=[u'new value'])] >>>
There is also a corresponding
ID3Tags.delall() method for deleting all
frames of one type.
Mutagen’s ID3 API is primary targeted at id3v2.4, so by default any id3 tags will be upgraded to 2.4 and saving a file will make it 2.4 as well. Saving as 2.3 is possible but needs some extra steps.
By default mutagen will:
- Load the file
- Upgrade any ID3v2.2 frames to their ID3v2.3/4 counterparts
- Upgrade 2.3 only frames to their 2.4 counterparts or throw them away in case there exists no sane upgrade path.
In code it comes down to this:
from mutagen.id3 import ID3 audio = ID3("example.mp3") audio.save()
ID3.version attribute contains the id3 version the loaded file
For more control the following functions are important:
ID3()which loads the tags and if
translate=True(default) calls either
ID3Tags.update_to_v23()depending on the
v2_versionargument (defaults to
ID3Tags.update_to_v24()which upgrades v2.2/3 frames to v2.4
ID3Tags.update_to_v23()which downgrades v2.4 and upgrades v2.2 frames to v2.3
ID3.save()which will save as v2.3 if
4) and also allows specifying a separator for joining multiple text values into one (defaults to
To load any ID3 tag and save it as v2.3 do the following:
from mutagen.id3 import ID3 audio = ID3("example.mp3", v2_version=3) audio.save(v2_version=3)
You may notice that if you load a v2.4 file this way, the text frames will
still have multiple values or are defined to be saved using UTF-8, both of
which isn’t valid in v2.3. But the resulting file will still be valid because
the following will happen in
- Frames that use UTF-8 as text encoding will be saved as UTF-16 instead.
- Multiple values in text frames will be joined with
v23_sepas passed to
Nonstandard ID3v2.3 Tricks¶
- Saving v2.4 frames in v2.3 tags
While not standard conform, you can exclude certain v2.4 frames from being thrown out by
ID3Tags.update_to_v23()by removing them temporarily:
audio = ID3("example.mp3", translate=False) keep_these = audio.getall("TSOP") audio.update_to_v23() audio.setall("TSOP", keep_these) audio.save(v2_version=3)
- Saving Multiple Text Values in v2.3 Tags
The v2.3 standard states that after a text termination “all the following information should be ignored and not be displayed”. So, saving multiple values separated by the text terminator should allow v2.3 only readers to read the first value while providing a way to read all values back.
But editing these files will probably throw out all the other values and some implementations might get confused about the extra non-NULL data, so this isn’t recommended.
To use the terminator as value separator pass
audio = ID3("example.mp3", v2_version=3) audio.save(v2_version=3, v23_sep=None)
Mutagen itself disregards the v2.3 spec in this case and will read them back as multiple values.
Since reading standards is hard, Mutagen also provides a simpler ID3 interface.
from mutagen.easyid3 import EasyID3 audio = EasyID3("example.mp3") audio["title"] = u"An example" audio.save()
Because of the simpler interface, only a few keys can be edited by EasyID3; to see them, use:
from mutagen.easyid3 import EasyID3 print(EasyID3.valid_keys.keys())
By default, mutagen.mp3.MP3 uses the real ID3 class. You can make it use EasyID3 as follows:
from mutagen.easyid3 import EasyID3 from mutagen.mp3 import MP3 audio = MP3("example.mp3", ID3=EasyID3) audio.pprint()
The following code adds two chapters to a file:
from mutagen.id3 import ID3, CTOC, CHAP, TIT2, CTOCFlags audio = ID3("example.mp3") audio.add( CTOC(element_id=u"toc", flags=CTOCFlags.TOP_LEVEL | CTOCFlags.ORDERED, child_element_ids=[u"chp1", "chp2"], sub_frames=[ TIT2(text=[u"I'm a TOC"]), ])) audio.add( CHAP(element_id=u"chp1", start_time=0, end_time=42000, sub_frames=[ TIT2(text=[u"I'm the first chapter"]), ])) audio.add( CHAP(element_id=u"chp2", start_time=42000, end_time=84000, sub_frames=[ TIT2(text=[u"I'm the second chapter"]), ])) audio.save()
Dealing with Frame Uniqueness of ID3 Frames¶
The ID3 spec defines for each frame type which combination of the contained
data needs to be unique in the whole tag and acts as an identifier for that
frame. This manifests itself in mutagen in that adding a frame using
ID3Tags.add(), which has the same key as an existing frame, will replace
the old one.
One frame type where this commonly leads to confusing results is the APIC frame, which requires that only the description field needs to be unique in the whole tag and not the description and picture type.
If you want to add a new frame without replacing an existing one, check the HashKey property and adjust your new frame until it no longer matches any existing frame.
tag = ID3() new = APIC() while new.HashKey in tag: new.desc += u"x" tag.add(new)
Compatibility / Bugs¶
- Mutagen writes ID3v2.4 tags which id3lib cannot read. If you enable ID3v1 tag saving (pass v1=2 to ID3.save), id3lib will read those.
- iTunes has a bug in its handling of very large ID3 tags (such as tags that contain an attached picture). Mutagen can read tags from iTunes, but iTunes may not be able to read tags written by Quod Libet.
- Mutagen has had several bugs in correct sync-safe parsing and writing of data length flags in ID3 tags. This will only affect files with very large or compressed ID3 frames (e.g. APIC). As of 1.10 we believe them all to be fixed.
- Mutagen 1.18 moved EasyID3FileType to mutagen.easyid3, rather than mutagen.id3, which was used in 1.17. Keeping in mutagen.id3 caused circular import problems.
- Mutagen 1.19 made it possible for POPM to have no ‘count’ attribute. Previously, files that generated POPM frames of this type would fail to load at all.
- When given date frames less than four characters long (which are already outside the ID3v2 specification), Mutagen 1.20 and earlier would write invalid ID3v1 tags that were too short. Mutagen 1.21 will parse these and fix them if it finds them while saving.