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

```yaml
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:

```yaml
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:

```yaml
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):

```yaml
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.