Tag Reference
=============

Default fields
--------------

The following fields are common to almost all music files.

.. describe:: __app

    The application name: puddletag v0.10.4 depending on version number.

.. describe:: __bitrate

    The bitrate of the file in kb/s. Note that it's a string with kb/s appended as in '213 kb/s' and not '213'. For Lossless formats this is always '0 kb/s'

.. describe:: __created

    The creation date of the file in YYYY-MM-DD HH:MM:SS format.

.. describe:: __dirpath

    The path of the directory the file resides in. /media/Multimedia/Music/myfile.mp3 has __dirpath /media/Multimedia/Music/

.. describe:: __ext

    Extension of the file. /media/Multimedia/Music/myfile.mp3 has extension mp3

.. describe:: __file_accessed_date

    The date the file was accessed in YYYY-MM-DD format

.. describe:: __file_accessed_datetime

    The date including the time the file was accessed in YYYY-MM-DD HH:MM:SS format

.. describe:: __file_accessed_datetime_raw

    UNIX time of the file's last access eg. 1234567890.

.. describe:: __file_create_date

    Creation date of the file in YYYY-MM-DD format.

.. describe:: __file_create_datetime

    File's creation date in YYYY-MM-DD HH:MM:SS format.

.. describe:: __file_create_datetime_raw

    UNIX time of file creation date eg. 1234567890.

.. describe:: __file_mod_date

    Date the file was last modified in YYYY-MM-DD format.

.. describe:: __file_mod_datetime

    Time the file was last modified in YYYY-MM-DD HH:MM:SS format.

.. describe:: __file_mod_datetime_raw

    UNIX time of file's last modification date.

.. describe:: __file_size

    The file's size in human-readable format.

.. describe:: __file_size_bytes

    The file's size in bytes.

.. describe:: __file_size_kb

    The file's size in KB.

.. describe:: __file_size_mb

    The file's size in MB (to two decimal places).

.. describe:: __filename

    The filename of the file with the folder stripped. e.g. the __filename of  /media/Multimedia/Music/myfile.mp3 is myfile.mp3

.. describe:: __filename_no_ext

    The file's filename without extension.

.. describe:: __filetype

    The format of the file. Currently the info is very sparse.

.. describe:: __frequency

    The sample rate of the file in kHz. Note that it's a string with kHz appended as in '213 kHz' and not '213'

.. describe:: __image

    Refers to the album art present in the file.

.. describe:: __image_mimetype

    MimeType of the first cover image in the file.

.. describe:: __image_size

    Size in bytes of the first cover image in the file.

.. describe:: __length

    The length of the file in "minutes: seconds" format.

.. describe:: __length_seconds

    Length of the file in seconds.

.. describe:: __mode

    One of, Mono, Stereo, Joint-Stereo or Dual Channel.

.. describe:: __modified

    The last time the file was modified in YYYY-MM-DD HH:MM:SS format .

.. describe:: __num_images

    Number of cover images found in the file.

.. describe:: __parent_dir

    The name of the parent directory of the directory the file's contained in. Cannot be written to.

.. describe:: __path

    The absolute filename of a file including directories. e.g /media/Multimedia/Music/myfile.mp3

.. describe:: __size

    The size of the file in bytes.

.. describe:: __tag

    Comma-Separated list of tags found in file. Eg. VorbisComment, ID3v2.4, ID3v1.1

.. describe:: __tag_read

    The tag that'll get written to in the file.

.. describe:: __total

    If the track field is of track/numtracks format, returns numtracks. Can also be written to.


Functions Only
--------------

Only available for Functions is:

.. describe:: __selected

    Having __selected as the field will apply the selected function to the selected cells. So if you have the album field selected in one file and artist in another. The function'll be applied to the album field of the first file and artist of the other respectively.


Cover Art
---------

Cover art can be accessed using the **__image** field. Use it only in Function like :ref:`Remove Fields <remove_fields>` as album cannot be displayed anywhere other than the :ref:`Artwork window <artwork_window>` and :ref:`Extended Tags <extended_tags_menu>` dialog.

* For ID3 tag cover art, writing multiple pictures per file is supported, but a different description is required for each.
* MP4 tags also support multiple pictures per file, but not setting descriptions.
* APEv2 tags can store at most two pictures per file. Moreover, these pictures need to have different cover types, limited to **Cover (front)** and **Cover (back)**.
* VorbisComment tags support multiple pictures per file with no limit on the descriptions or cover types.


Tags
----

The table below lists ID3v2.4 frames and MP4 Atoms with their respective puddletag fields. :doc:`This <id3>` page lists ID3 Frames and the various ways to edit them in puddletag.

Any MP4 atoms not in this list will be assumed to be freeform frames, written using ':com.apple.iTunes:**fieldname**' as the atom. ID3 frames not found will be written as TXXX frames of the form **TXXX:fieldname** frame.

===========================      =============      ========
puddletag field                  ID3v2.4 Frame      MP4 Atom
===========================      =============      ========
**album**                        TALB               alb
**albumartist**                  TPE2               
**albumsortorder**               TSOA               soal
**arranger**                     TPE4
**artist**                       TPE1               ART
**audiodelay**                   TDLY
**audiolength**                  TLEN
**audiosize**                    TSIZ
**author**                       TOLY
**bpm**                          TBPM               tmpo
**comment**                      COMM               cmt
**composer**                     TCOM               wrt
**conductor**                    TPE3
**copyright**                    TCOP               cprt
**date**                         TDAT
**discnumber**                   TPOS
**encodedby**                    TENC               too
**encodingsettings**             TSSE
**encodingtime**                 TDEN
**filename**                     TOFN
**fileowner**                    TOWN
**filetype**                     TFLT
**genre**                        TCON               gen
**grouping**                     TIT1               grp
**initialkey**                   TKEY
**involvedpeople**               TIPL
**isrc**                         TSRC
**itunesalbumsortorder**         TSO2
**itunescompilationflag**        TCMP
**itunescomposersortorder**      TSOC
**language**                     TLAN
**lyricist**                     TEXT
**mediatype**                    TMED
**mood**                         TMOO
**musiciancredits**              TMCL
**organization**                 TPUB
**originalalbum**                TOAL
**originalartist**               TOPE
**originalreleasetime**          TDOR
**originalyear**                 TORY
**performersortorder**           TSOP
**popularimeter**                POPM
**producednotice**               TPRO
**radioowner**                   TRSO
**radiostationname**             TRSN
**recordingdates**               TRDA
**releasetime**                  TDRL
**setsubtitle**                  TSST
**taggingtime**                  TDTG
**time**                         TIME
**title**                        TIT2               nam
**titlesortorder**               TSOT               sonm
**track**                        TRCK
**unsyncedlyrics**               USLT
**ufid**                         UFID
**version**                      TIT3
**wwwartist**                    WOAR
**wwwcommercialinfo**            WCOM
**wwwcopyright**                 WCOP
**wwwfileinfo**                  WOAF
**wwwpayment**                   WPAY
**wwwpublisher**                 WPUB
**wwwradio**                     WORS
**wwwsource**                    WOAS
**year**                         TDRC               day 
===========================      =============      ========