# puddletag

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

# Masstagging Tutorial

If you haven’t got a handle on using Tag Sources, see the Tag Sources Tutorial.

## Introduction

If you’re wanting to automatically tag multiple albums in unattended batch mode, then Masstagging may be just what you’re looking for. puddletag will take the files you selected, separate them into directories and sequentially process each directory.

## How it works

1. First off, puddletag will separate the selected files into directories. Furthermore, if the album field differs between each files in a directory, they’ll be split again using files will be grouped according the album field.

2. A File->Tag operation will be applied to each file. Any fields that aren’t present in the file will be filled using those results.

3. For each group of files, the Tag Sources will be polled in the order listed in the current Masstagging Profile.
     1. Each Tag Source listed will be polled and checked for a matching album within the bounds specified.
     2. If a match wasn’t found for one Tag Source, but for another the Tag Source will be polled again using the data retrieved from the matching source.
     3. Fields/Values from each tag source will be combined using your preferences.
     4. When done and if matches were found, the metadata will be applied to the files and puddletag will be in Preview Mode

## How to use it

- Select a profile from the Masstagging Window.
- Select files.
- Click on start.
- Wait until it’s done.
- Make modifications.
- Write changes.

## Configuring Profiles

The best way to explain this I think is by creating a new Profile.

Click Configure Profiles on the Masstagging window to bring up the Profile configuration dialog.

Now add a new profile by clicking on the Add Profile (“+”) button. You should get this dialog.

Inputs required are:

`Name`

  The name of the profile.

`Description`

  Any description you’d like. Will be shown as a tooltip for the

`Tag Sources`

  Each tag source will be polled in the order listed here.

  See Configuring a Tag Source.

`Pattern to match filenames against.`

  A File->Tag operation will be performed on each file using the pattern defined here. Any fields found from this operation not aren’t already present in the file will be replaced.

  Eg. For a with with path /music/Bongo Maffin - Bongolution/02 - Way Kungakhona, that has the tag, artist=Bongo Maffin, album=Bonglut, genre=Kwaito.

  Using the pattern %artist - %album%/%track% - %title% will retrieve the following tag artist=Bongo Maffin, album=Bongolution, track=02, title=Way Kungakhona. The file doesn’t contain the track and title fields, so it’ll be updated with these fields.

  The tag used to poll Tag Sources will then be artist=Bongo Maffin, album=Bonglut, genre=Kwaito, track=02, title=Way Kungokhona.

  Note

  All these changes are kept in memory and nothing is written to the file.

`Minimum percentage required for album matches.`

  An album will be considered a match if the percentage by which the album name and artist differ for the album is less than what’s specified here.

`Match tracks using fields:`

  For a matching album, each retrieved track will be checked against the files. For each file, puddletag cycle through the list of retrieved tracks and do the following.

  - Check if all the fields listed are present in the retrieved track.
  - If so, each field will be compared in the file vs each track and the field with the lowest match percentage will be used to assess the track match the file.

  puddletag will compare all retrieved tracks against the files and choose the one with the highest Matching Percentage as a match if and only if the Match Percentage is higher than

`Minimum percentage required for track match.`

  If a track has a Match Percentage higher or equal to this when compared to a file, then that track will be considered a match.

`Tag Sources`

  Check to enable brute force matching.

  If no matches were found for some files, then the files will be sorted by track (if it’s not present, __filename). The retrieved data will also be sorted using track. Each retrieved track will then be paired with a file (in order) provided that file hasn’t been matched previously.

`Brute force unmatched files.`

  If checked, only fields that don’t already have values will be updated with retrieved data.

### Configuring a Tag Source

Clicking on the Add Tag Source (“+”) button should bring up this dialog:

`Fields`

  The list of fields to retrieve from the tag source. Rules are as described in Deciding what to retrieve.

  Fields from different tag sources will be combined into multiple values where they differ. Eg. If one tag source retrieved genre=Rock and another genre=Alternative, the value that puddletag will write to the files will the values Rock\\Alternative. Values will only be combined if they differ.

  The way they’re combined depends on the position the tag source is listed. The tag source polled last takes precedence. Say you polled FreeDB first and Discogs second.

  FreeDB returned artist=TKZee, title=Felakai, genre=Dance.

  Discogs gave artist=TKZee, title=Felakai, genre=Kwaito\\Rap.

  Since Discogs was polled last it’s values will be listed first, giving the final tag.

  artist=TKZee, title=Felakai, genre=Kwaito\\Rap\\Dance

`Fields to replace`

  A comma-separated list of fields that takes precedence. Any listed here will replace any previous results retrieved. Eg. say you polled FreeDB, Discogs and MusicBrainz in order.

  MusicBrainz has Field to replace set to artist.

  FreeDB returned artist=TKZee, title=Felakai, genre=Dance.

  Discogs gave artist=TKZee, title=Felakai, genre=Kwaito\\Rap.

  MusicBrainz: artist=TKZ, title=Felakai

  Instead of the artist field being combined in the final tag to TKZ\\TKZee, only the value from MusicBrainz will be used. Giving as the final tag.

  artist=TKZ, title=Felakai, genre=Kwaito\\Rap\\Dance

  Note

  If a later tag source replaces the same fields as any previous tag source, that tag source’s field will be used.

`Source`

  The tag source to use. See Using Tag Sources.

`If no results found:`

  If no matching album was found for this tag source, you can choose to either Continue with the other tag sources in the list or Stop the lookup and use any previously retrieved results.