81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
# 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.
|
||
|