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.
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.Metadata
A file with an ID3v2 tag.
Attributes:
Deprecated. Doesn’t have any effect
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.
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.
ID3 tag version as a tuple (of the loaded file)
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:
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
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:
Average Bitrate (a variant of VBR)
Constant Bitrate
Probably a CBR file, but not sure
Variable Bitrate
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: |
|
---|
AIFF audio stream information and tags.
Bases: mutagen.FileType
An AIFF audio file.
Variables: |
|
---|
Add an empty ID3 tag to the file.
Load stream and tag information from a file.
AIFF audio stream information.
Information is parsed from the COMM chunk of the AIFF file
Useful attributes: