Load last folder at startup

If checked, the last folder that was loaded upon closing puddletag will be re-opened when puddletag is started.


If checked, Subfolders of directories selected for import will be checked for supported files (which’ll then be loaded). Otherwise, just files residing in the selected directories will be loaded.

Show gridlines

Shows/Hides the gridlines in the file view depending on whether it checked/unchecked.

Show tooltips in file-view.

By default tooltips will be shown in the file view showing the value of a cell on which the mouse is hovered. When in Preview Mode the tooltip will show both the Preview and value as stored in the file. Uncheck this box to disable it.

Show row numbers.

Check to show row numbers in the file view.

Automatically resize columns to contents

If checked, the columns will be resized to the so that all text is visible upon loading folders. They will not be resize during editing.

Program to play files with:

Enter the command of the program puddletag should use to play files with. The list of selected files will be appended to the argument list.

Edit sort options

With Sort Options you can sort the file-view using a list of predefined fields. The window brough up by clicking this button is pretty self explanatory. Any field-lists you add will create a menu item in the Tools->Sort By menu.

Provided a single file (or none at all) is selected, clicking on a menu item will sort the file-view in order of the fields defined. So track/__dirpath/album will sort the file-view by track first, then __dirpath then album. It’s equivalent to clicking the relevant headers in order in the file-view.

Click on it again and the sort order will be reversed like album/__dirpath/track.

This sort order will be used when loading dirs unless changed (by clicking a header or using another Sort Option.) It is saved across sessions.

If you have more than one file selected, only the selected files will be sorted using those fields. All other files will remain as is.


Confirmations let you know that you’re about to do something that can’t be reversed. Turn off the ones that you find grating.


With mappings you can ‘rename’ puddletag fields.

For instance if you want the performer to be shown as albumartist for ID3 files. You’d set up a mapping with ID3 as the Tag, performer as the Original Field and albumartist as the Target.

Now any files that contained the performer field before the mapping will instead show it as albumartist.

The mapping doesn’t work in reverse, albumartist won’t be show as performer. You’ll need to set up another mapping for that.

  • Tag can be one one of ID3, MP4, APEv2 (for Musepack, WavPack, etc.) or VorbisComment (for FLAC and Ogg Vorbis). Note that these are case-sensitive.

  • You can also set mappings for Tag Sources using the exact Tag Source’s name. eg. MusicBrainz.

  • Mapping default fields like “__filename, __dirpath, __image, etc”. will cause undesired behaviour.


Write extended info:

When enabled the pattern you will be used to write extended info for M3U playlists.

Filename pattern:

Then default filename pattern to use when saving playlists.


Defines the background colours to used in various puddletag dialogs. Use it when needed (you’ll need to if you’re using a dark theme).


The list of genres as used in the Tag Panel. Edit to your hearts content. If you want to reset it to the default values remove ~/.puddletag/genres.


Restrict incoming files to (eg. “*.mp3; *.ogg; *.aac”)

Enter a “;”-separated list of texts to restrict the filenames puddletag loads to. “*.mp3; *.ogg; *.aac” will only load filenames beginning ending with ‘.ogg’, ‘.mp3’ or ‘.aac’. By default puddletag checks every file for a valid tag.


puddletag supports writing UTF8-encoded ID3v2.4 and ID3v2.3 with the option of including ID3v1.1. Choose whichever option you want to use.


Plugins are a means with which to extend puddletag. If you want to install one drop it into “~/.puddletag/plugins”. Enable it, then restart.

Plugins are executable code akin to installing a program on you PC. Do not use any that aren’t from trustworthy sources.


With this panel you can edit the keyboard shortcuts of any menu item in puddletag. Just double-click on the desired shortcut in the shortcut column and enter the desired shortcut.

Tag Panel

This is where you can edit Tag Panel settings. puddletag will show the Title above a combo box that’ll be populated using the field you specify in the Field column.

Use & in your Title to create an accelerator eg. ‘&Artist’ will allow you to set focus to the relevant combo box by pressing ‘Alt+A’

Row refers to the row number in which to show the field. If more than one row contains the same number, the fields will be listed on one row.

Tag Sources

Display format for individual tracks:

Enter a pattern to be used to display the metadata for individual tracks in the Tag Sources dialog’s album list.

Display format for retrieved albums:

As above but for the album. You can use the field %__numtracks% to get the number of tracks in an album.

Sort retrieved albums using order

Will sort the retrieved album by the order listed. Use the dialog brought up by clicking ‘Edit’ to bring up an editor for the sort options. You can change the order dynamically by right clicking on the header of the Tag Sources dialog’s album list and choosing from the sort options you defined.


If you use a Tag Sources to scrape a website, using anything other than the default User-Agent is a good idea.

Automatic Retrieval options

If automatic retrieval of albums is enabled in the Tag Sources dialog, then the options you specify here will be used to determine which album best matches. Options are as used in Masstagging.


Modify the patterns listed in the pattern combo here.


In this panel you can modify the columns listed in the file-view.

  • Any unchecked columns will not be shown.

  • Title is the title that’ll be displayed on the file-view’s header.

  • Data will be retrieved from the Field you specify.