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 :ref:`MusicBrainz <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.

.. _uslt:

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.