Using Tag Sources¶
puddletag supports tagging your audio files using web based Tag Sources.
Included with puddletag are tag sources supporting lookups from Amazon, Discogs, FreeDB and MusicBrainz and AcoustID. The metadata returned by each tag source is detailed at the bottom of this page.
The Tag Sources window¶
Refer to the screenshot below for a quick explanation of the Tag Sources windows’ controls:
Selects a tag source.
Is the Search Box. Enter any text here to do a textual search. You cannot do a file-based and textual searches at the same time.
Lists the retrieved albums. Click on an album to retrieve metadata. Lookups are done by album, but you can select metadata by track too. Hover over an album/track to see an overview of the metadata that’ll get written.
After an album is selected, puddletag will enter Preview Mode. Click on Write to write the previews, or use Write from the Preview Mode menu menu. Clear preview does as it says and exits preview mode.
Enter a list of comma-separated fields to write here, eg. artist, album, will update only the artist and album fields when you select an album. If left empty all the retrieved fields will be written. Starting the list with the tilde (~) character will write all but the fields you specify. eg. ~year,mbrainz_track_id will write all the fields (artist, album, etc) but the year and mbrainz_track_id fields from the tag source.
Check this box and only fields that aren’t already in the file will get updated.
If checked, the album that best matches the retrieved albums will be automatically retrieved. See Automatic Retrieval options.
How to Search¶
Make sure the Tag Sources window is visible (Windows->Tag Sources).
Choose a tag source.
Select all the files in an album you want to tag.
Click on Search.
The album’s tag’s will then be used to poll the tag sources.
When results are returned, select an appropriate album.
That album’s metadata will then be retrieved and the retrieved tags will be applied to the selected files. These changes aren’t written as puddletag will be in Preview Mode.
Write the changes to the files using the Write button (feel free to make any changes yourself beforehand).
Textual searches are also supported. If the Search Box has any text, it’ll be used to search with instead of the selected files. See the Search Box’s tooltip (or read the rest of this document) for details on how each tag source does textual searches.
Note
For a more detailed explanation see the Tag Sources tutorial.
Using AcoustID¶
AcoustID is a music fingerprinting service provided by Lukas Lalinsky. It works by calculating a unique fingerprint for your audio files and trying to match it to data in the AcoustID database. This allows you to find information for tracks that have no metadata!
Note
In order to use the library you need to have chromaprint (specifically the fpcalc binary) installed.
AcoustID returns the same data as the MusicBrainz tag source, including the following fields.
acoustid_id: The AcoustID identifier for a track as returned by the AcoustID webservice.
acoustid_fingerprint: The calculated AcoustID fingerprint. Can be a very large value.
Using Amazon¶
The Amazon tag source polls Amazon.com’s XML service to retrieve album art. Basic track information is also retrieved.
Be sure to configure the tag source to retrieve the optimum size cover art. It defaults to medium.
Amazon does textual search too. The rules are:
To search for a specific artist, album pair enter the search string as artist;album, ie. artist and album separated by a semi-colon.
Searching for the albums of a specific artist is done by leaving of the album part as in artist;
For an album only leave off the artist part, ala ;artist
Type anything not matching the above to do a keyword search.
Fields returned by the Amazon tag source are:
__image: Cover art.
album: The release’s (album’s) name.
artist: The track’s artist.
asin: Amazon’s unique identifier for the album.
label: The record label responsible for releasing the album.
title: The track’s title.
year: The album’s release date.
Using Discogs¶
The Discogs.com tag source uses Discogs.com’s XML service to retrieve album information.
Be sure to configure the tag source to retrieve the optimum size cover art. It defaults to Large.
Note
Discogs doesn’t allow lookups without a user agent any more. If you get Client Refused errors this is the reason. To rectify, set the user agent in Edit->Preferences->Tag Sources to puddletag/0.9.11 or any other valid user agent.
Textual searches are supported. Rules are as follows:
To search for a specific artist, album pair enter the search string as artist;album, ie. artist and album separated by a semi-colon.
Searching for the albums of a specific artist is done by leaving of the album part as in artist;
For an album only leave off the artist part, ala ;artist
Retrieving an album using it’s Discogs Release ID is possible by using :r release_id where release_id is the Discogs Release ID.
Type anything not matching the above to do a keyword search.
Fields returned this tag source are:
__image: Cover art. Usually more than one image.
album: The release’s (album’s) name.
artist: The track’s artist.
country: The album’s release country
discogs_catno: Discogs catalog number.
discogs_format: The album’s release media (eg. Vinyl, CD, etc.)
discogs_format_desc: The format description (eg. Album, Single, etc.)
discogs_notes: Notes associated with the album.
discogs_r_id: Discogs Release ID.
discogs_summary: The album’s summary according to Discogs.
discogs_uri: The album’s discogs URI.
discnumber: Disc number.
discs: Number of discs in the album.
genre: Genres associated with the album.
involvedpeople_album: People involved with the album’s creation. Taken from the extraartists node for the album. (Eg. Young Churf;Harpsichord)
involvedpeople_track: People involved with the relevant track. Taken from the track’s extraartists node. (Eg. Young Churf;Harpsichord)
label: The record label responsible for releasing the album.
style: Discogs styles.
track: Track number.
year: The album’s release date.
Using FreeDB¶
FreeDB creates a (semi-)unique DiscID by using the number of tracks, their order and lengths of a particular CD. The DiscID is then referenced to the FreeDB database and any matching albums are returned.
So all you need to do in order to do a FreeDB lookup is select all the files belonging to specific album and click on Search. It’s doesn’t work all the time, but it does most of the time.
album: The release’s (album’s) name.
artist: The track’s artist.
freedb_disc_id: The album’s FreeDB DiscID.
freedb_category: The FreeDB category the album’s listed under.
genre: The album’s genre.
title: The track’s title.
track: The track number.
year: The earliest date that the album was released. Not available for every album.
Using MusicBrainz¶
Note
python-musicbrainz2 ≥ 0.6.0 is required to enable MusicBrainz support.
In addition to normal file lookups MusicBrainz also supports textual searches. The rules are as follows.
To search for a specific artist, album pair enter the search string as artist;album, ie. artist and album separated by a semi-colon.
Searching for the albums of a specific artist is done by leaving of the album part as in artist;
For an album only leave off the artist part, ala ;artist
Retrieving the albums of an artist corresponding to a specific MusicBrainz Artist ID is done by starting your search string with :a as in :a f59c5520-5f46-4d2c-b2c4-822eabf53419
Also retrieving a specific album using it’s MusicBrainz Album ID can be done by starting your search string with :b eg. :b 34bb630-8061-454c-b35d-8f7131f4ff08
The fields returned by the MusicBrainz tag source are (not all fields are available for all albums):
album: The release’s (album’s) name.
artist: The track’s artist.
asin: Amazon identifier.
barcode: The album’s barcode.
catalog: Catalog numbers of the album.
country: Album’s release country.
discs: Number of discs in the album.
involvedpeople_album: People involved with the album’s creation. Taken from the extraartists node for the album. (Eg. Young Churf;Harpsichord)
involvedpeople_track: People involved with the relevant track. Taken from the track’s extraartists node. (Eg. Young Churf;Harpsichord)
isrc: ISRC’s associated with the album.
label: Label responsible for album’s release.
mbrainz_album_id: MusicBrainz’s unique identifier for the album.
mbrainz_artist_id: The unique MusicBrainz identifier for the artist.
mbrainz_label_id: The unique MusicBrainz identifier for the recording label.
musicip_puid: PUID’s associated with the track. PUID retrieval requires polling MusicBrainz for each track therefore it’s disabled by default.
mbrainz_rating: The album’s rating according to MusicBrainz.
mbrainz_track_id: MusicBrainz’s unique ID for the track.
title: The track’s title.
track: The track number.
year: The earliest date that the album was released. Not available for every album.
Using Mp3tag’s Tag Sources¶
If you don’t know what they are, visit the Mp3tag website for details.
puddletag supports using Mp3tag’s tag sources. To use them create the directory ~/.puddletag/mp3tag_sources and place any tag sources in there. If everything went okay, they’ll be loaded when you start puddletag. In the Tag Sources window they’ll be listed with ‘[M]’ appended to the filename.
You can search as you do using Mp3tag by using the Search box. See the tooltip for the field used to do the search. Selecting files and searching works too.
Caveats¶
The sources I’ve tested work like Mp3tag’s. They also bomb on the same pages. However, unlike Mp3tag, puddletag doesn’t ‘detect’ when retrieval has gone awry. So sometimes you might get nothing in Mp3tag, while getting jibberish in puddletag.
I won’t be supporting the creation of Mp3tag tag source nor does puddletag have any useful debugging facilities for them. However, if a tag source works fine with Mp3tag, but doesn’t with puddletag, create an issue with a link to the tag source and some example searches and I’ll fix ‘em.
Be sure to set ‘debug off’ or remove it alltogether unless you’re in the mood for having your filesystem being littered with junk files.