NAME
beetsconfig - beets configuration file- •
- On Unix-like OSes, write ~/.config/beets/config.yaml.
- •
- On Windows, use %APPDATA%\beets\config.yaml. This is usually in a directory like C:\Users\You\AppData\Roaming.
- •
- On OS X, you can use either the Unix location or ~/Library/Application Support/beets/config.yaml.
option: value
another_option: foo
bigger_option:
key: value
foo: bar
- •
- Global Options
- •
- library
- •
- directory
- •
- plugins
- •
- include
- •
- pluginpath
- •
- ignore
- •
- ignore_hidden
- •
- replace
- •
- path_sep_replace
- •
- asciify_paths
- •
- art_filename
- •
- threaded
- •
- format_item
- •
- format_album
- •
- sort_item
- •
- sort_album
- •
- sort_case_insensitive
- •
- original_date
- •
- artist_credit
- •
- per_disc_numbering
- •
- aunique
- •
- terminal_encoding
- •
- clutter
- •
- max_filename_length
- •
- id3v23
- •
- va_name
- •
- UI Options
- •
- color
- •
- colors
- •
- Importer Options
- •
- write
- •
- copy
- •
- move
- •
- link
- •
- hardlink
- •
- reflink
- •
- resume
- •
- incremental
- •
- incremental_skip_later
- •
- from_scratch
- •
- quiet
- •
- quiet_fallback
- •
- none_rec_action
- •
- timid
- •
- log
- •
- default_action
- •
- languages
- •
- detail
- •
- group_albums
- •
- autotag
- •
- duplicate_action
- •
- bell
- •
- set_fields
- •
- MusicBrainz Options
- •
- searchlimit
- •
- extra_tags
- •
- genres
- •
- Autotagger Matching Options
- •
- max_rec
- •
- preferred
- •
- ignored
- •
- required
- •
- ignored_media
- •
- ignore_data_tracks
- •
- ignore_video_tracks
- •
- Path Format Configuration
- •
- Configuration Location
- •
- Environment Variable
- •
- Command-Line Option
- •
- Default Location
- •
- Example
GLOBAL OPTIONS
These options control beets’ global operation.library
Path to the beets library file. By default, beets will use a file called library.db alongside your configuration file.directory
The directory to which files will be copied/moved when adding them to the library. Defaults to a folder called Music in your home directory.plugins
A space-separated list of plugin module names to load. See using-plugins.include
A space-separated list of extra configuration files to include. Filenames are relative to the directory containing config.yaml.pluginpath
Directories to search for plugins. Each Python file or directory in a plugin path represents a plugin and should define a subclass of BeetsPlugin. A plugin can then be loaded by adding the filename to the plugins configuration. The plugin path can either be a single string or a list of strings—so, if you have multiple paths, format them as a YAML list like so:
pluginpath:
- /path/one
- /path/two
ignore
A list of glob patterns specifying file and directory names to be ignored when importing. By default, this consists of .*, *~, System Volume Information, lost+found (i.e., beets ignores Unix-style hidden files, backup files, and directories that appears at the root of some Linux and Windows filesystems).ignore_hidden
Either yes or no; whether to ignore hidden files when importing. On Windows, the “Hidden” property of files is used to detect whether or not a file is hidden. On OS X, the file’s “IsHidden” flag is used to detect whether or not a file is hidden. On both OS X and other platforms (excluding Windows), files (and directories) starting with a dot are detected as hidden files.replace
A set of regular expression/replacement pairs to be applied to all filenames created by beets. Typically, these replacements are used to avoid confusing problems or errors with the filesystem (for example, leading dots, which hide files on Unix, and trailing whitespace, which is illegal on Windows). To override these substitutions, specify a mapping from regular expression to replacement strings. For example, [xy]: z will make beets replace all instances of the characters x or y with the character z.
replace:
'[\\/]': _
'^\.': _
'[\x00-\x1f]': _
'[<>:"\?\*\|]': _
'\.$': _
'\s+$': ''
'^\s+': ''
'^-': _
path_sep_replace
A string that replaces the path separator (for example, the forward slash / on Linux and MacOS, and the backward slash \\ on Windows) when generating filenames with beets. This option is related to replace, but is distict from it for technical reasons.Changing this option is potentially dangerous.
For example, setting it to the actual path separator could create directories
in unexpected locations. Use caution when changing it and always try it out on
a small number of files before applying it to your whole library.
asciify_paths
Convert all non-ASCII characters in paths to ASCII equivalents.art_filename
When importing album art, the name of the file (without extension) where the cover art image should be placed. This is a template string, so you can use any of the syntax available to /reference/pathformat. Defaults to cover (i.e., images will be named cover.jpg or cover.png and placed in the album’s directory).threaded
Either yes or no, indicating whether the autotagger should use multiple threads. This makes things substantially faster by overlapping work: for example, it can copy files for one album in parallel with looking up data in MusicBrainz for a different album. You may want to disable this when debugging problems with the autotagger. Defaults to yes.format_item
Format to use when listing individual items with the list-cmd command and other commands that need to print out items. Defaults to $artist - $album - $title. The -f command-line option overrides this setting.format_album
Format to use when listing albums with list-cmd and other commands. Defaults to $albumartist - $album. The -f command-line option overrides this setting.sort_item
Default sort order to use when fetching items from the database. Defaults to artist+ album+ disc+ track+. Explicit sort orders override this default.sort_album
Default sort order to use when fetching albums from the database. Defaults to albumartist+ album+. Explicit sort orders override this default.sort_case_insensitive
Either yes or no, indicating whether the case should be ignored when sorting lexicographic fields. When set to no, lower-case values will be placed after upper-case values (e.g., Bar Qux foo), while yes would result in the more expected Bar foo Qux. Default: yes.original_date
Either yes or no, indicating whether matched albums should have their year, month, and day fields set to the release date of the original version of an album rather than the selected version of the release. That is, if this option is turned on, then year will always equal original_year and so on. Default: no.artist_credit
Either yes or no, indicating whether matched tracks and albums should use the artist credit, rather than the artist. That is, if this option is turned on, then artist will contain the artist as credited on the release.per_disc_numbering
A boolean controlling the track numbering style on multi-disc releases. By default ( per_disc_numbering: no), tracks are numbered per-release, so the first track on the second disc has track number N+1 where N is the number of tracks on the first disc. If this per_disc_numbering is enabled, then the first (non-pregap) track on each disc always has track number 1.
paths:
default: $albumartist/$album%aunique{}/$disc-$track $title
aunique
These options are used to generate a string that is guaranteed to be unique among all albums in the library who share the same set of keys.
aunique:
keys: albumartist album
disambiguators: albumtype year label catalognum albumdisambig releasegroupdisambig
bracket: '[]'
terminal_encoding
The text encoding, as known to Python, to use for messages printed to the standard output. It’s also used to read messages from the standard input. By default, this is determined automatically from the locale environment variables.clutter
When beets imports all the files in a directory, it tries to remove the directory if it’s empty. A directory is considered empty if it only contains files whose names match the glob patterns in clutter, which should be a list of strings. The default list consists of “Thumbs.DB” and “.DS_Store”.max_filename_length
Set the maximum number of characters in a filename, after which names will be truncated. By default, beets tries to ask the filesystem for the correct maximum.id3v23
By default, beets writes MP3 tags using the ID3v2.4 standard, the latest version of ID3. Enable this option to instead use the older ID3v2.3 standard, which is preferred by certain older software such as Windows Media Player.va_name
Sets the albumartist for various-artist compilations. Defaults to 'Various Artists' (the MusicBrainz standard). Affects other sources, such as /plugins/discogs, too.UI OPTIONS
The options that allow for customization of the visual appearance of the console interface.color
Either yes or no; whether to use color in console output (currently only in the import command). Turn this off if your terminal doesn’t support ANSI colors.The color option was previously a
top-level configuration. This is still respected, but a deprecation message
will be shown until your top-level color configuration has been nested
under ui.
colors
The colors that are used throughout the user interface. These are only used if the color option is set to yes. For example, you might have a section in your configuration file that looks like this:
ui:
color: yes
colors:
text_success: green
text_warning: yellow
text_error: red
text_highlight: red
text_highlight_minor: lightgray
action_default: turquoise
action: blue
IMPORTER OPTIONS
The options that control the import-cmd command are indented under the import: key. For example, you might have a section in your configuration file that looks like this:
import:
write: yes
copy: yes
resume: no
write
Either yes or no, controlling whether metadata (e.g., ID3) tags are written to files when using beet import. Defaults to yes. The -w and -W command-line options override this setting.copy
Either yes or no, indicating whether to copy files into the library directory when using beet import. Defaults to yes. Can be overridden with the -c and -C command-line options.move
Either yes or no, indicating whether to move files into the library directory when using beet import. Defaults to no.link
Either yes or no, indicating whether to use symbolic links instead of moving or copying files. (It conflicts with the move, copy and hardlink options.) Defaults to no.hardlink
Either yes or no, indicating whether to use hard links instead of moving, copying, or symlinking files. (It conflicts with the move, copy, and link options.) Defaults to no.reflink
Either yes, no, or auto, indicating whether to use copy-on-write file clones (a.k.a. “reflinks”) instead of copying or moving files. The auto option uses reflinks when possible and falls back to plain copying when necessary. Defaults to no.resume
Either yes, no, or ask. Controls whether interrupted imports should be resumed. “Yes” means that imports are always resumed when possible; “no” means resuming is disabled entirely; “ask” (the default) means that the user should be prompted when resuming is possible. The -p and -P flags correspond to the “yes” and “no” settings and override this option.incremental
Either yes or no, controlling whether imported directories are recorded and whether these recorded directories are skipped. This corresponds to the -i flag to beet import.incremental_skip_later
Either yes or no, controlling whether skipped directories are recorded in the incremental list. When set to yes, skipped directories won’t be recorded, and beets will try to import them again later. When set to no, skipped directories will be recorded, and skipped later. Defaults to no.from_scratch
Either yes or no (default), controlling whether existing metadata is discarded when a match is applied. This corresponds to the --from_scratch flag to beet import.quiet
Either yes or no (default), controlling whether to ask for a manual decision from the user when the importer is unsure how to proceed. This corresponds to the --quiet flag to beet import.quiet_fallback
Either skip (default) or asis, specifying what should happen in quiet mode (see the -q flag to import, above) when there is no strong recommendation.none_rec_action
Either ask (default), asis or skip. Specifies what should happen during an interactive import session when there is no recommendation. Useful when you are only interested in processing medium and strong recommendations interactively.timid
Either yes or no, controlling whether the importer runs in timid mode, in which it asks for confirmation on every autotagging match, even the ones that seem very close. Defaults to no. The -t command-line flag controls the same setting.log
Specifies a filename where the importer’s log should be kept. By default, no log is written. This can be overridden with the -l flag to import.default_action
One of apply, skip, asis, or none, indicating which option should be the default when selecting an action for a given match. This is the action that will be taken when you type return without an option letter. The default is apply.languages
A list of locale names to search for preferred aliases. For example, setting this to en uses the transliterated artist name “Pyotr Ilyich Tchaikovsky” instead of the Cyrillic script for the composer’s name when tagging from MusicBrainz. You can use a space-separated list of language abbreviations, like en jp es, to specify a preference order. Defaults to an empty list, meaning that no language is preferred.detail
Whether the importer UI should show detailed information about each match it finds. When enabled, this mode prints out the title of every track, regardless of whether it matches the original metadata. (The default behavior only shows changes.) Default: no.group_albums
By default, the beets importer groups tracks into albums based on the directories they reside in. This option instead uses files’ metadata to partition albums. Enable this option if you have directories that contain tracks from many albums mixed together.autotag
By default, the beets importer always attempts to autotag new music. If most of your collection consists of obscure music, you may be interested in disabling autotagging by setting this option to no. (You can re-enable it with the -a flag to the import-cmd command.)duplicate_action
Either skip, keep, remove, merge or ask. Controls how duplicates are treated in import task. “skip” means that new item(album or track) will be skipped; “keep” means keep both old and new items; “remove” means remove old item; “merge” means merge into one album; “ask” means the user should be prompted for the action each time. The default is ask.bell
Ring the terminal bell to get your attention when the importer needs your input.set_fields
A dictionary indicating fields to set to values for newly imported music. Here’s an example:
set_fields:
genre: 'To Listen'
collection: 'Unordered'
MUSICBRAINZ OPTIONS
You can instruct beets to use your own MusicBrainz database instead of the main server. Use the host, https and ratelimit options under a musicbrainz: header, like so:
musicbrainz:
host: localhost:5000
https: no
ratelimit: 100
searchlimit
The number of matches returned when sending search queries to the MusicBrainz server.extra_tags
By default, beets will use only the artist, album, and track count to query MusicBrainz. Additional tags to be queried can be supplied with the extra_tags setting. For example:
musicbrainz:
extra_tags: [year, catalognum, country, media, label]
genres
Use MusicBrainz genre tags to populate (and replace if it’s already set) the genre tag. This will make it a list of all the genres tagged for the release and the release-group on MusicBrainz, separated by “; ” and sorted by the total number of votes. Default: noAUTOTAGGER MATCHING OPTIONS
You can configure some aspects of the logic beets uses when automatically matching MusicBrainz results under the match: section. To control how tolerant the autotagger is of differences, use the strong_rec_thresh option, which reflects the distance threshold below which beets will make a “strong recommendation” that the metadata be used. Strong recommendations are accepted automatically (except in “timid” mode), so you can use this to make beets ask your opinion more or less often.
match:
strong_rec_thresh: 0.10
max_rec
As mentioned above, autotagger matches have recommendations that control how the UI behaves for a certain quality of match. The recommendation for a certain match is based on the overall distance calculation. But you can also control the recommendation when a specific distance penalty is applied by defining maximum recommendations for each field:
match:
max_rec:
missing_tracks: medium
unmatched_tracks: medium
- •
- source
- •
- artist
- •
- album
- •
- media
- •
- mediums
- •
- year
- •
- country
- •
- label
- •
- catalognum
- •
- albumdisambig
- •
- album_id
- •
- tracks
- •
- missing_tracks
- •
- unmatched_tracks
- •
- track_title
- •
- track_artist
- •
- track_index
- •
- track_length
- •
- track_id
preferred
In addition to comparing the tagged metadata with the match metadata for similarity, you can also specify an ordered list of preferred countries and media types.
match:
preferred:
countries: ['US', 'GB|UK']
media: ['CD', 'Digital Media|File']
original_year: yes
ignored
You can completely avoid matches that have certain penalties applied by adding the penalty name to the ignored setting:
match:
ignored: missing_tracks unmatched_tracks
required
You can avoid matches that lack certain required information. Add the tags you want to enforce to the required setting:
match:
required: year label catalognum country
ignored_media
A list of media (i.e., formats) in metadata databases to ignore when matching music. You can use this to ignore all media that usually contain video instead of audio, for example:
match:
ignored_media: ['Data CD', 'DVD', 'DVD-Video', 'Blu-ray', 'HD-DVD',
'VCD', 'SVCD', 'UMD', 'VHS']
ignore_data_tracks
By default, audio files contained in data tracks within a release are included in the album’s tracklist. If you want them to be included, set it no.ignore_video_tracks
By default, video tracks within a release will be ignored. If you want them to be included (for example if you would like to track the audio-only versions of the video tracks), set it to no.PATH FORMAT CONFIGURATION
You can also configure the directory hierarchy beets uses to store music. These settings appear under the paths: key. Each string is a template string that can refer to metadata fields like $artist or $title. The filename extension is added automatically. At the moment, you can specify three special paths: default for most releases, comp for “various artist” releases with no dominant artist, and singleton for non-album tracks. The defaults look like this:
paths:
default: $albumartist/$album%aunique{}/$track $title
singleton: Non-Album/$artist/$title
comp: Compilations/$album%aunique{}/$track $title
paths:
albumtype:soundtrack: Soundtracks/$album/$track $title
CONFIGURATION LOCATION
The beets configuration file is usually located in a standard location that depends on your OS, but there are a couple of ways you can tell beets where to look.Environment Variable
First, you can set the BEETSDIR environment variable to a directory containing a config.yaml file. This replaces your configuration in the default location. This also affects where auxiliary files, like the library database, are stored by default (that’s where relative paths are resolved to). This environment variable is useful if you need to manage multiple beets libraries with separate configurations.Command-Line Option
Alternatively, you can use the --config command-line option to indicate a YAML file containing options that will then be merged with your existing options (from BEETSDIR or the default locations). This is useful if you want to keep your configuration mostly the same but modify a few options as a batch. For example, you might have different strategies for importing files, each with a different set of importer options.Default Location
In the absence of a BEETSDIR variable, beets searches a few places for your configuration, depending on the platform:- •
- On Unix platforms, including OS X:~/.config/beets and then $XDG_CONFIG_DIR/beets, if the environment variable is set.
- •
- On OS X, we also search ~/Library/Application Support/beets before the Unixy locations.
- •
- On Windows: ~\AppData\Roaming\beets, and then %APPDATA%\beets, if the environment variable is set.
EXAMPLE
Here’s an example file:
directory: /var/mp3
import:
copy: yes
write: yes
log: beetslog.txt
art_filename: albumart
plugins: bpd
pluginpath: ~/beets/myplugins
ui:
color: yes
paths:
default: $genre/$albumartist/$album/$track $title
singleton: Singletons/$artist - $title
comp: $genre/$album/$track $title
albumtype:soundtrack: Soundtracks/$album/$track $title
SEE ALSO
https://beets.readthedocs.org/AUTHOR
Adrian SampsonCOPYRIGHT
2016, Adrian Sampson| November 27, 2021 | 1.6 |