ID3 Frames

Below is the list of ID3 frames supported by puddletag descriptions of their usage in puddletag. These can be accessed available via the Extended Tags Dialog (Edit -> Extended Tags). puddletag writes only UTF-8 encoded ID3v2.4 and ID3v2.3 (with the option of including ID3v1) tags.

Text Frames

Text frames can store any text. Multiple values are allowed per field.

Comment frames are written to the COMM frame. Multiple values are allowed per comment field, but storing different comment frames requires a different description for each frame. This is denoted by any text following the comment: identifier. Eg. comment:numbertwo (no spaces allowed) will have description numbertwo. The first COMM frame encountered without a description will be used as the comment field. Likewise creating a comment field will write to a description-less COMM frame.

Any unknown field is assumed to be a user-defined field. Therefore writing to the field ‘mytag’ will write to the ID3 tag frame TXXX:mytag.

The list of ID3 text frames as supported by puddletag is shown below. Multiple values per field are allowed. The iTunes frames are only supported by Mutagen 1.17 and above.

puddletag field

ID3v2.4 Frame

album

TALB

albumartist

TPE2

albumsortorder

TSOA

arranger

TPE4

artist

TPE1

audiodelay

TDLY

audiolength

TLEN

audiosize

TSIZ

author

TOLY

bpm

TBPM

composer

TCOM

conductor

TPE3

copyright

TCOP

date

TDAT

discnumber

TPOS

encodedby

TENC

encodingsettings

TSSE

filename

TOFN

fileowner

TOWN

filetype

TFLT

genre

TCON

grouping

TIT1

initialkey

TKEY

isrc

TSRC

itunesalbumsortorder

TSO2

itunescompilationflag

TCMP

itunescomposersortorder

TSOC

language

TLAN

lyricist

TEXT

mediatype

TMED

mood

TMOO

organization

TPUB

originalalbum

TOAL

originalartist

TOPE

originalyear

TORY

performersortorder

TSOP

producednotice

TPRO

radioowner

TRSO

radiostationname

TRSN

recordingdates

TRDA

setsubtitle

TSST

time

TIME

title

TIT2

titlesortorder

TSOT

track

TRCK

version

TIT3

year

TYER

Time Frames

[From the mutagen docs] Time fields take the form of YYYY-MM-DD HH:MM:SS Or some partial form (YYYY-MM-DD HH, YYYY, etc.). puddletag supports reading from and writing to:

puddletag field

ID3v2.4 Frame

encodingtime

TDEN

originalreleasetime

TDOR

releasetime

TDRL

taggingtime

TDTG

year

TDRC

URL Frames

URL link frames act like text frames, but with two caveats. Only ASCII is allowed and only one value per field is allowed (So even if you try to write multiple values, only the first one will get written).

wwwartist and wwwcommercialinfo are the only URL link frames that allow multiple values per field. Each will be written to a different frame as per the ID3v2.4 standard.

Starting a field name with www: will denote it to be a user-defined URL field. All text following www: will form the description. Eg. from www:homepage homepage will be the description written to the WXXX frame.

puddletag field

ID3v2.4 Frame

wwwartist

WOAR

wwwcommercialinfo

WCOM

wwwcopyright

WCOP

wwwfileinfo

WOAF

wwwpayment

WPAY

wwwpublisher

WPUB

wwwradio

WORS

wwwsource

WOAS

Paired Frames

The following are called paired frames due to their values being represented as paired items. Eg. the involvedpeople tag could list the people involved in the band of whatever song you’re trying to tag, like Billy Taylor:Piano;Chester Bennington:Vocals;Ratatat:Instruments (note that spaces are significant). Items in a pair are separated with a colon (:), with pairs separated by a semi-colon(;) (like I just did). Although Mp3tag allows the writing of multiple paired frames, the ID3 standard doesn’t allow it, therefore mutagen doesn’t, hence puddletag refrains from writing multiple paired frames. So erm…store all your stuff in one frame if you don’t mind. Thanks.

Here are the puddletag supported frames:

puddletag field

ID3v2.4 Frame

involvedpeople

TIPL

musiciancredits

TMCL

Misc Frames

These frames are handled differently from those previously discussed, so I’ve put them all in misc.

field: playcount, frame: PCNT

The PCNT frame stores the number of times the file has been played. This frame is usually only used by media players. Although it’s been superseded by:

field: popularimeter, frame: POPM

This frame stores three values: an email, rating and playcount separated by a colon as in cpuddle@unregistered.com:12:3. If playcount isn’t found in an existing field it’ll be added.

field: ufid, frame: UFID

UFID stands for Unique File Identifier. It’s a single-valued field shown in puddletag as ufid:owner eg. ufid:musicbrainz.org (the MusicBrainz tag source writes the MusicBrainz Track ID to this field). Only values that can be decoded to UTF-8 will be editable.

field: rgain, frame: RVA2

Replaygain, also know as Relative Volume Adjustment info is stored in the RVA2 Frame. The field name in puddletag will take the rgain:description. You’re likely to encounter either rgain:track or rgain:album as these are used by media players to store Replaygain info. Values are of the forme channel:gain:peak where peak is a floating point number between 0 and 1.

field: unsyncedlyrics, frame: USLT

Unsynced Lyrics frames store lyrics. Values should take the form Language|Description|Lyrics, where Language corresponds to three-letter language abbreviation as listed in ISO-639-2. If only text is entered, the language XXX will be used. If only one ‘|’ is found in the text, it’ll be assumed that the Language and Lyrics were entered.