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.