Tag Sources Tutorial
====================

Introduction
------------

With puddletag you can tag your audio files using metadata from external **Tag Sources**.

The following Tag Sources are distributed with puddletag:

* Amazon.com's album art
* Discogs.com XML service
* FreeDB
* Musicbrainz

Tag Sources are album based and enable tagging individual albums using metadata from the Tag Source(s) of your choosing. For each of the Tag Sources puddletag will by default retrieve the full complement of metadata provided by the Tag Source. You do, however, have the option of choosing only specific fields or writing all fields provided by a Tag Source except those you specifically exclude.

.. _deciding_what_to_retrieve:

Deciding what to retrieve
-------------------------

You can specify or omit fields from a tagging operation by specifying the following in the **Fields** input area (leave it blank to retrieve all fields provided by a Tag Source):

* Leave it empty and all metadata from the Tag Source will be retrieved.
* Enter a comma separated list of fields to retrieve only those field. Eg. **artist, title, album, genre**
* Alternatively, use the tilde character ("~") followed by a comma delimited list of fields you'd like to exclude. All fields except thouse you specify will get written to files. Eg. if you entered **~genre,album** and the Tag Source returned a tag with **artist, title, album, track, genre** fields. Only the **artist, title, track** fields would be written to the files.

.. image:: images/tagsource_dialog_tut4.png
   :alt: Field descriptions
   :align: center

How you do it
-------------

1. Sort tracks by ascending track number if possible.
2. Select all tracks in an album you want to tag.
3. Make sure that the Tag Sources dialog is visible (use **Windows->Tag** Sources menu to show it).
4. Select a Tag Source.
5. Click on Search and wait...
6. Click on **Search**.
7. Select the correct (or any really) album from the Tag Sources dialog. Retrieved metadata now be matched to the selected files.
8. Remember I said sort files in ascending order? The matching process will "connect" each file to a retrieved track. Going from track 1 to the end.
9. puddletag will now be in **Preview Mode**. You can make changes if you wish as they'll be stored in memory.
10. Don't despair if you encounter a situation where the version/ release of the album you have is different to that retrieved via the Tag Source and/or the track sequence or number of tracks differ. You can tag individual tracks by selecting the track in the File-View and then clicking on the corresponding track in the Tag Source's track list. Similarly, selecting a sequence of tracks will do the same for the selected files.
11. Use **Write** on the Tag Sources dialog or **Write Previews** from the Preview Mode menu to save the changes to file.

Things to be aware of
---------------------

There are a couple of things you need to know to able to use puddletag's tagging abilities effectively:

* Limiting the fields retrieved can be done by editing the **Fields** text box, see :ref:`above <deciding_what_to_retrieve>`.
* You can configure the Tag Source's behaviour (if not previously configured to your liking). This is done by clicking on the Configuration icon.
* If you want to prevent existing values from being overwritten ensure **Update empty fields only** is checked.
* Tag Sources are album based, not track based (although you can choose individual tracks from an album).
* Tracks/files need to be selected in order for metadata relating to those tracks to be taken into account.
* Not selecting all files in an album may yield incorrect results when doing a lookup.
* (Ctrl-N is your friend...it selects all audio tracks located in the folder in which the currently highlighted file resides).
* You can map the field names for retrieved Tag Sources metadata to field names of your choosing (via Edit->Preferences->Mappings, see the tooltip for info.)
* While in Preview Mode, you can edit fields as normal (via the main view window, Tag Panel or Extended Tags view) before committing any changes. This makes it simple to tweak retrieved metadata to your specific needs before writing changes to your tracks.
* You're also able to clear the previews of individual files or cells while in **Preview Mode**.
* puddletag will not write *any* metadata retrieved from tag source until you tell it to.


Textual searches
----------------

For all Tag Sources, but FreeDB you can also do textual searching. If the **Search text box** contains *any* text whatsoever, puddletag will do a textual search when you click on **Search**. After which you can perform the same procedure as from **9** above.

* Searching for something like 'Nomvula' will assume you mean the album **Nomvula**.
* Searching for a specific artist/album combination can accomplished by separating the artist and album using a semi-colon as in "Jethro Tull; Aqualung". To specify an album name only, start with the semi-colon as in ";Aqualung". In the same way ending with a semi-colon eg. "Jethro Tull;" will only search for the specific artist.
* Each Tag Source can have unique means of doing searches (e.g. the Musicbrainz Tag Source supports searching via Musicbrainz Album Id). See the Search box's tooltip for details or go :ref:`here <amazon>`.