Frame Base Classes
- class mutagen.id3.Frame
Bases:
object
Fundamental unit of ID3 data.
ID3 tags are split into frames. Each frame has a potentially different structure, and so this base class is not very featureful.
- property FrameID
ID3v2 three or four character frame ID
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- pprint()
Return a human-readable representation of the frame.
- class mutagen.id3.BinaryFrame(data=b'')
Bases:
Frame
Binary data
The ‘data’ attribute contains the raw byte string.
- class mutagen.id3.PairedTextFrame(encoding=<Encoding.UTF16: 1>, people=[])
Bases:
Frame
Paired text strings.
Some ID3 frames pair text strings, to associate names with a more specific involvement in the song. The ‘people’ attribute of these frames contains a list of pairs:
[['trumpet', 'Miles Davis'], ['bass', 'Paul Chambers']]
Like text frames, these frames also have an encoding attribute.
- class mutagen.id3.TextFrame(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
Frame
Text strings.
Text frames support casts to unicode or str objects, as well as list-like indexing, extend, and append.
Iterating over a TextFrame iterates over its strings, not its characters.
Text frames have a ‘text’ attribute which is the list of strings, and an ‘encoding’ attribute; 0 for ISO-8859 1, 1 UTF-16, 2 for UTF-16BE, and 3 for UTF-8. If you don’t want to worry about encodings, just set it to 3.
- append(value)
Append a string.
- extend(value)
Extend the list by appending all strings from the given list.
- class mutagen.id3.UrlFrame(url='')
Bases:
Frame
A frame containing a URL string.
The ID3 specification is silent about IRIs and normalized URL forms. Mutagen assumes all URLs in files are encoded as Latin 1, but string conversion of this frame returns a UTF-8 representation for compatibility with other string conversions.
The only sane way to handle URLs in MP3s is to restrict them to ASCII.
- class mutagen.id3.NumericPartTextFrame(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Multivalue numerical text strings.
These strings indicate ‘part (e.g. track) X of Y’, and unary plus returns the first value:
frame = TRCK('4/15') track = +frame # track == 4
- class mutagen.id3.NumericTextFrame(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Numerical text strings.
The numeric value of these frames can be gotten with unary plus, e.g.:
frame = TLEN('12345') length = +frame
ID3v2.3/4 Frames
- class mutagen.id3.AENC(owner='', preview_start=0, preview_length=0, data=b'')
Bases:
Frame
Audio encryption.
Attributes:
owner – key identifying this encryption type
preview_start – unencrypted data block offset
preview_length – number of unencrypted blocks
data – data required for decryption (optional)
Mutagen cannot decrypt files.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.APIC(encoding=<Encoding.UTF16: 1>, mime='', type=<PictureType.COVER_FRONT: 3>, desc='', data=b'')
Bases:
Frame
Attached (or linked) Picture.
Attributes:
encoding – text encoding for the description
mime – a MIME type (e.g. image/jpeg) or ‘–>’ if the data is a URI
type – the source of the image (3 is the album front cover)
desc – a text description of the image
data – raw image data, as a byte string
Mutagen will automatically compress large images when saving tags.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.ASPI(S=0, L=0, N=0, b=0, Fi=[])
Bases:
Frame
Audio seek point index.
Attributes: S, L, N, b, and Fi. For the meaning of these, see the ID3v2.4 specification. Fi is a list of integers.
- class mutagen.id3.CHAP(element_id='', start_time=0, end_time=0, start_offset=4294967295, end_offset=4294967295, sub_frames={})
Bases:
Frame
Chapter
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.COMM(encoding=<Encoding.UTF16: 1>, lang='XXX', desc='', text=[])
Bases:
TextFrame
User comment.
User comment frames have a description, like TXXX, and also a three letter ISO language code in the ‘lang’ attribute.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.COMR(encoding=<Encoding.UTF16: 1>, price='', valid_until='19700101', contact='', format=0, seller='', desc='')
Bases:
Frame
Commercial frame.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.CTOC(element_id='', flags=<0: 0>, child_element_ids=[], sub_frames={})
Bases:
Frame
Table of contents
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.ENCR(owner='', method=128, data=b'')
Bases:
Frame
Encryption method registration.
The standard does not allow multiple ENCR frames with the same owner or the same method. Mutagen only verifies that the owner is unique.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.EQU2(method=0, desc='', adjustments=[])
Bases:
Frame
Equalisation (2).
Attributes: method – interpolation method (0 = band, 1 = linear) desc – identifying description adjustments – list of (frequency, vol_adjustment) pairs
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.GEOB(encoding=<Encoding.UTF16: 1>, mime='', filename='', desc='', data=b'')
Bases:
Frame
General Encapsulated Object.
A blob of binary data, that is not a picture (those go in APIC).
Attributes:
encoding – encoding of the description
mime – MIME type of the data or ‘–>’ if the data is a URI
filename – suggested filename if extracted
desc – text description of the data
data – raw data, as a byte string
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.GRID(owner='', group=128, data=b'')
Bases:
Frame
Group identification registration.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.LINK(frameid='XXXX', url='', data=b'')
Bases:
Frame
Linked information.
Attributes:
frameid – the ID of the linked frame
url – the location of the linked frame
data – further ID information for the frame
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.MCDI(data=b'')
Bases:
BinaryFrame
Binary dump of CD’s TOC
- class mutagen.id3.MLLT(frames=0, bytes=0, milliseconds=0, bits_for_bytes=0, bits_for_milliseconds=0, data=b'')
Bases:
Frame
MPEG location lookup table.
This frame’s attributes may be changed in the future based on feedback from real-world use.
- class mutagen.id3.MVIN(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericPartTextFrame
iTunes Movement Number/Count
- class mutagen.id3.MVNM(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
iTunes Movement Name
- class mutagen.id3.OWNE(encoding=<Encoding.UTF16: 1>, price='', date='19700101', seller='')
Bases:
Frame
Ownership frame.
- class mutagen.id3.PCNT(count=0)
Bases:
Frame
Play counter.
The ‘count’ attribute contains the (recorded) number of times this file has been played.
This frame is basically obsoleted by POPM.
- class mutagen.id3.POPM(email='', rating=0)
Bases:
Frame
Popularimeter.
This frame keys a rating (out of 255) and a play count to an email address.
Attributes:
email – email this POPM frame is for
rating – rating from 0 to 255
count – number of times the files has been played (optional)
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.POSS(format=1, position=0)
Bases:
Frame
Position synchronisation frame
Attribute:
format – format of the position attribute (frames or milliseconds)
position – current position of the file
- class mutagen.id3.PRIV(owner='', data=b'')
Bases:
Frame
Private frame.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.RBUF(size=0)
Bases:
Frame
Recommended buffer size.
Attributes:
size – recommended buffer size in bytes
info – if ID3 tags may be elsewhere in the file (optional)
offset – the location of the next ID3 tag, if any
Mutagen will not find the next tag itself.
- class mutagen.id3.RVA2(desc='', channel=1, gain=1, peak=1)
Bases:
Frame
Relative volume adjustment (2).
This frame is used to implemented volume scaling, and in particular, normalization using ReplayGain.
Attributes:
desc – description or context of this adjustment
channel – audio channel to adjust (master is 1)
gain – a + or - dB gain relative to some reference level
peak – peak of the audio as a floating point number, [0, 1]
When storing ReplayGain tags, use descriptions of ‘album’ and ‘track’ on channel 1.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.RVRB(left=0, right=0, bounce_left=0, bounce_right=0, feedback_ltl=0, feedback_ltr=0, feedback_rtr=0, feedback_rtl=0, premix_ltr=0, premix_rtl=0)
Bases:
Frame
Reverb.
- class mutagen.id3.SEEK(offset=0)
Bases:
Frame
Seek frame.
Mutagen does not find tags at seek offsets.
- class mutagen.id3.SIGN(group=128, sig=b'')
Bases:
Frame
Signature frame.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.SYLT(encoding=<Encoding.UTF16: 1>, lang='XXX', format=1, type=0, desc='', text='')
Bases:
Frame
Synchronised lyrics/text.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.SYTC(format=1, data=b'')
Bases:
Frame
Synchronised tempo codes.
This frame’s attributes may be changed in the future based on feedback from real-world use.
- class mutagen.id3.TBPM(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericTextFrame
Beats per minute
- class mutagen.id3.TCAT(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
iTunes Podcast Category
- class mutagen.id3.TCMP(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericTextFrame
iTunes Compilation Flag
- class mutagen.id3.TCON(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Content type (Genre)
ID3 has several ways genres can be represented; for convenience, use the ‘genres’ property rather than the ‘text’ attribute.
- property genres
A list of genres parsed from the raw text data.
- class mutagen.id3.TDAT(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Date of recording (DDMM)
- class mutagen.id3.TDEN(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TimeStampTextFrame
Encoding Time
- class mutagen.id3.TDES(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
iTunes Podcast Description
- class mutagen.id3.TDLY(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericTextFrame
Audio Delay (ms)
- class mutagen.id3.TDOR(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TimeStampTextFrame
Original Release Time
- class mutagen.id3.TDRC(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TimeStampTextFrame
Recording Time
- class mutagen.id3.TDRL(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TimeStampTextFrame
Release Time
- class mutagen.id3.TDTG(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TimeStampTextFrame
Tagging Time
- class mutagen.id3.TGID(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
iTunes Podcast Identifier
- class mutagen.id3.TIME(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Time of recording (HHMM)
- class mutagen.id3.TIPL(encoding=<Encoding.UTF16: 1>, people=[])
Bases:
PairedTextFrame
Involved People List
- class mutagen.id3.TIT1(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Content group description
- class mutagen.id3.TIT3(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Subtitle/Description refinement
- class mutagen.id3.TKWD(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
iTunes Podcast Keywords
- class mutagen.id3.TLEN(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericTextFrame
Audio Length (ms)
- class mutagen.id3.TMCL(encoding=<Encoding.UTF16: 1>, people=[])
Bases:
PairedTextFrame
Musicians Credits List
- class mutagen.id3.TOPE(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Original Artist/Performer
- class mutagen.id3.TORY(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericTextFrame
Original Release Year
- class mutagen.id3.TPE1(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Lead Artist/Performer/Soloist/Group
- class mutagen.id3.TPE2(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Band/Orchestra/Accompaniment
- class mutagen.id3.TPE4(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Interpreter/Remixer/Modifier
- class mutagen.id3.TPOS(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericPartTextFrame
Part of set
- class mutagen.id3.TRCK(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericPartTextFrame
Track Number
- class mutagen.id3.TRSN(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Internet Radio Station Name
- class mutagen.id3.TRSO(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Internet Radio Station Owner
- class mutagen.id3.TSIZ(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericTextFrame
Size of audio data (bytes)
- class mutagen.id3.TSO2(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
iTunes Album Artist Sort
- class mutagen.id3.TSOA(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Album Sort Order key
- class mutagen.id3.TSOC(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
iTunes Composer Sort
- class mutagen.id3.TSOP(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Performer Sort Order key
- class mutagen.id3.TSOT(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
Title Sort Order key
- class mutagen.id3.TSRC(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
TextFrame
International Standard Recording Code (ISRC)
- class mutagen.id3.TXXX(encoding=<Encoding.UTF16: 1>, desc='', text=[])
Bases:
TextFrame
User-defined text data.
TXXX frames have a ‘desc’ attribute which is set to any Unicode value (though the encoding of the text and the description must be the same). Many taggers use this frame to store freeform keys.
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.TYER(encoding=<Encoding.UTF16: 1>, text=[])
Bases:
NumericTextFrame
Year of recording
- class mutagen.id3.UFID(owner='', data=b'')
Bases:
Frame
Unique file identifier.
Attributes:
owner – format/type of identifier
data – identifier
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.USER(encoding=<Encoding.UTF16: 1>, lang='XXX', text='')
Bases:
Frame
Terms of use.
Attributes:
encoding – text encoding
lang – ISO three letter language code
text – licensing terms for the audio
- property HashKey
An internal key used to ensure frame uniqueness in a tag
- class mutagen.id3.USLT(encoding=<Encoding.UTF16: 1>, lang='XXX', desc='', text='')
Bases:
Frame
Unsynchronised lyrics/text transcription.
Lyrics have a three letter ISO language code (‘lang’), a description (‘desc’), and a block of plain text (‘text’).
- property HashKey
An internal key used to ensure frame uniqueness in a tag