beets-plugins/README.md

Beets Plugins

A collection of iTunes-centric beets plugins.

cleantags

The cleantags plugin allows you to remove existing tags from files before importing. You can configure the plugin as follows:

cleantags:
    clean: yes
    keep: space seperated string of tags
    discard: space separated string of tags

• clean enables or disables the cleantags plugin. The default is yes (the plugin is enabled).
• keep contains a space separated string of tag names that should be retained when importing files. All tags not in this list will be discarded. The default is unsepcified.
• discard can be specified as an alternative to keep. Any tag specified in this list will be discarded. Other tags will be retained.
• If both keep and discard are specified keep will take precedence and discard is ignored. If neither is specified, tags are left unchanged.

retag

The retag plugin allows you to specify a list of tags that will be ignored, even if you re-import an existing item into the library. By default some things like the acoustid fingerprint are not re-calculated. You can configure the plugin as follows:

retag:
    clear: space separated string of tags

• Specify a space separated string of tags as clear. Each of the tags will be cleared before (re-)importing an item.

sources

The sources plugin allows you to prioritize different metadata sources. Through this plugin you can give certain sources a higher priority than others while still preferring close matches. The plugin can be configured as follows. Note that the settings do not reside in a sources mapping:

preferred_sources: space separated list of sources

• An expmple might be iTunes MusicBrainz. In this setup the iTunes source would be preferred.
• Instead of source names you can also specify regular expressions to prioritize multiple sources equally.
• There is the special value * which accepts any source (equivalent to the regular expression .*). Use this to match any source.

itunes

This plugin is very much in beta and not production ready.

The itunes plugin adds the iTunes store as a metadata source. This works in two ways:

• Files are scanned for a specific iTunes ID that is present in files bought from the iTunes store and files downloaded from iTunes match.
• If the ID is present, the plugin tries to look up the track directly on the store.
• Otherwise (or if the lookup does not return any results) the track’s name is looked up on the iTunes store.

The plugin can be configured as follows (the specified values are the defaults):

itunes:
    method: lookup
    search_countries: US
    lookup_countries: US DE AU GB FR IT JP
    search_limit: 5
    sanitize_searches: yes
    artwork: no
    censored_names: no

• method lets you specify how tracks are looked up. Possible values are:
  • lookup: Tracks will be looked up via their iTunes Match ID. It no ID exists tracks are not processed.
  • lookup (search fallback): Like lookup but tracks are searched if the lookup does not return any results (or a track does not contain an ID).
  • search: Tracks are searched on the iTunes Store by name only.
  • both: Tracks are both looked up and searched, regardeless of the lookup result.
• search_countries: A space separated list of countries that will be queried for a search.
• lookup_countries: A space separated list of countries taht will be queried for lookups. If a lookup is found the remaining countries will not be queried.
• search_limit: The amount of tracks to return from searches.
• sanitize_searches: Whether to remove some special characters from seraches (such as parentheses). This has shown to improve the search accuracy.
• artwork: Whether to set the song’s artwork from the iTunes store. If you use plugins like fetchart you should disable this option.
• censored_names: Whether to use censored names or explicit names.

Note that for searches and lookups each country requires a separate request so a large number of countries may considerably slow down the autotagger. Note also that the iTunes API does employ some rate limits as well.