# puddletag

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

# Tag Reference

## Default fields

The following fields are common to almost all music files.

`__app`

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

`__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’

`__created`

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

`__dirpath`

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

`__ext`

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

`__file_accessed_date`

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

`__file_accessed_datetime`

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

`__file_accessed_datetime_raw`

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

`__file_create_date`

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

`__file_create_datetime`

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

`__file_create_datetime_raw`

  UNIX time of file creation date eg. 1234567890.

`__file_mod_date`

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

`__file_mod_datetime`

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

`__file_mod_datetime_raw`

  UNIX time of file’s last modification date.

`__file_size`

  The file’s size in human-readable format.

`__file_size_bytes`

  The file’s size in bytes.

`__file_size_kb`

  The file’s size in KB.

`__file_size_mb`

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

`__filename`

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

`__filename_no_ext`

  The file’s filename without extension.

`__filetype`

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

`__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’

`__image`

  Refers to the album art present in the file.

`__image_mimetype`

  MimeType of the first cover image in the file.

`__image_size`

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

`__length`

  The length of the file in “minutes: seconds” format.

`__length_seconds`

  Length of the file in seconds.

`__mode`

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

`__modified`

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

`__num_images`

  Number of cover images found in the file.

`__parent_dir`

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

`__path`

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

`__size`

  The size of the file in bytes.

`__tag`

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

`__tag_read`

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

`__total`

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

## Functions Only

Only available for Functions is:

`__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 Remove Fields as album cannot be displayed anywhere other than the Artwork window and Extended Tags 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. This 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