Masstagging Tutorial
====================

If you haven't got a handle on using **Tag Sources**, see the :doc:`tut4`.

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
------------

#. 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.
#. A :ref:`File->Tag <filename_to_tag>` operation will be applied to each file. Any fields that aren't present in the file will be filled using those results.
#. For each group of files, the Tag Sources will be polled in the order listed in the current **Masstagging Profile**.
    #. Each Tag Source listed will be polled and checked for a matching album within the bounds specified.
    #. 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.
    #. Fields/Values from each tag source will be combined using your preferences.
    #. When done and if matches were found, the metadata will be applied to the files and puddletag will be in :ref:`Preview Mode <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.

.. image:: masstag_images/choose_profile.png
   :alt: Masstagging Profile choosing dialog.
   :align: center

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

.. image:: masstag_images/configure_profile.png
   :alt: Masstagging Profile Configuration dialog.
   :align: center

Inputs required are:

.. describe:: Name

    The name of the profile.

.. describe:: Description

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

.. describe:: Tag Sources

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

    See :ref:`masstag_tagsources`.

.. describe:: Pattern to match filenames against.

    A :ref:`File->Tag <filename_to_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.

.. _tag_source_auto_options:

.. describe:: 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.

.. describe:: 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

.. describe:: 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.

.. describe:: 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.

.. describe:: Brute force unmatched files.

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

.. _masstag_tagsources:

Configuring a Tag Source
^^^^^^^^^^^^^^^^^^^^^^^^

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

.. image:: masstag_images/configure_tagsource.png
   :alt: Masstagging Tag Source Configuration dialog.
   :align: center

.. describe:: Fields

    The list of fields to retrieve from the tag source. Rules are as described in :ref:`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**

.. describe:: 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.

.. describe:: Source

    The tag source to use. See :doc:`tagsources`.

.. describe:: 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.