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