# puddletag

## - A tag editor for GNU/Linux (Documentation).

# 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.