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='')

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

class mutagen.id3.TimeStampTextFrame(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

A list of time stamps.

The ‘text’ attribute in this frame is a list of ID3TimeStamp objects, not a list of strings.

class mutagen.id3.UrlFrameU(url='')

Bases: UrlFrame

property HashKey: An internal key used to ensure frame uniqueness in a tag

ID3v2.3/4 Frames

class mutagen.id3.AENC(owner='', preview_start=0, preview_length=0, data='')

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=u'', type=<PictureType.COVER_FRONT: 3>, desc=u'', data='')

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=u'', text=[])

Bases: TextFrame

User comment.

User comment frames have a descrption, 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=u'', valid_until='19700101', contact=u'', format=0, seller=u'', desc=u'')

Bases: Frame

Commercial frame.

property HashKey: An internal key used to ensure frame uniqueness in a tag

class mutagen.id3.CTOC(element_id=u'', 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='')

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.ETCO(format=1, events=[])

Bases: Frame

Event timing codes.

class mutagen.id3.GEOB(encoding=<Encoding.UTF16: 1>, mime=u'', filename=u'', desc=u'', data='')

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='')

Bases: Frame

Group identification registration.

property HashKey: An internal key used to ensure frame uniqueness in a tag

class mutagen.id3.GRP1(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

iTunes Grouping

class mutagen.id3.IPLS(encoding=<Encoding.UTF16: 1>, people=[])

Bases: TIPL

Involved People List

class mutagen.id3.LINK(frameid='XXXX', url='', data='')

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='')

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='')

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=u'', date='19700101', seller=u'')

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.PCST(value=0)

Bases: Frame

iTunes Podcast Flag

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='')

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.RVAD(adjustments=[0, 0])

Bases: Frame

Relative volume adjustment

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='')

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=u'', text=u'')

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='')

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.TALB(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Album

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.TCOM(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Composer

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.TCOP(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Copyright (c)

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.TENC(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Encoder

class mutagen.id3.TEXT(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Lyricist

class mutagen.id3.TFLT(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

File type

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.TIT2(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Title

class mutagen.id3.TIT3(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Subtitle/Description refinement

class mutagen.id3.TKEY(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Starting Key

class mutagen.id3.TKWD(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

iTunes Podcast Keywords

class mutagen.id3.TLAN(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Audio Languages

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.TMED(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Source Media Type

class mutagen.id3.TMOO(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Mood

class mutagen.id3.TOAL(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Original Album

class mutagen.id3.TOFN(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Original Filename

class mutagen.id3.TOLY(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Original Lyricist

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.TOWN(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Owner/Licensee

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.TPE3(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Conductor

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.TPRO(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Produced (P)

class mutagen.id3.TPUB(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Publisher

class mutagen.id3.TRCK(encoding=<Encoding.UTF16: 1>, text=[])

Bases: NumericPartTextFrame

Track Number

class mutagen.id3.TRDA(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Recording Dates

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

Perfomer 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.TSSE(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Encoder settings

class mutagen.id3.TSST(encoding=<Encoding.UTF16: 1>, text=[])

Bases: TextFrame

Set Subtitle

class mutagen.id3.TXXX(encoding=<Encoding.UTF16: 1>, desc=u'', 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='')

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=u'')

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=u'', text=u'')

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

class mutagen.id3.WCOM(url='')

Bases: UrlFrameU

Commercial Information

class mutagen.id3.WCOP(url='')

Bases: UrlFrame

Copyright Information

class mutagen.id3.WFED(url='')

Bases: UrlFrame

iTunes Podcast Feed

class mutagen.id3.WOAF(url='')

Bases: UrlFrame

Official File Information

class mutagen.id3.WOAR(url='')

Bases: UrlFrameU

Official Artist/Performer Information

class mutagen.id3.WOAS(url='')

Bases: UrlFrame

Official Source Information

class mutagen.id3.WORS(url='')

Bases: UrlFrame

Official Internet Radio Information

class mutagen.id3.WPAY(url='')

Bases: UrlFrame

Payment Information

class mutagen.id3.WPUB(url='')

Bases: UrlFrame

Official Publisher Information

class mutagen.id3.WXXX(encoding=<Encoding.UTF16: 1>, desc=u'', url=u'')

Bases: UrlFrame

User-defined URL data.

Like TXXX, this has a freeform description associated with it.

property HashKey: An internal key used to ensure frame uniqueness in a tag