BEETSCONFIG(5) beets BEETSCONFIG(5)NAMEbeetsconfig - beets configuration file
Beets has an extensive configuration system that lets you customize
nearly every aspect of its operation. To configure beets, you create a
file called config.yaml. The location of the file depend on your plat‐
form (type beet config -p to see the path on your system):
· 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/Applica‐
tion Support/beets/config.yaml.
You can launch your text editor to create or update your configuration
by typing beet config -e. (See the config-cmd command for details.) It
is also possible to customize the location of the configuration file
and even use multiple layers of configuration. See Configuration Loca‐
tion, below.
The config file uses YAML syntax. You can use the full power of YAML,
but most configuration options are simple key/value pairs. This means
your config file will look like this:
option: value
another_option: foo
bigger_option:
key: value
foo: bar
In YAML, you will need to use spaces (not tabs!) to indent some lines.
If you have questions about more sophisticated syntax, take a look at
the YAML documentation.
The rest of this page enumerates the dizzying litany of configuration
options available in beets. You might also want to see an example.
· Global Options
· library
· directory
· plugins
· include
· pluginpath
· ignore
· replace
· asciify_paths
· art_filename
· threaded
· format_item
· format_album
· sort_item
· sort_album
· sort_case_insensitive
· original_date
· per_disc_numbering
· terminal_encoding
· clutter
· max_filename_length
· id3v23
· UI Options
· color
· colors
· Importer Options
· write
· copy
· move
· link
· resume
· incremental
· quiet_fallback
· none_rec_action
· timid
· log
· default_action
· languages
· detail
· group_albums
· autotag
· MusicBrainz Options
· searchlimit
· Autotagger Matching Options
· max_rec
· preferred
· ignored
· required
· 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-plug‐
ins.
include
A space-separated list of extra configuration files to include. File‐
names 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 Beet‐
sPlugin. 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 .*, *~, and Sys‐
tem Volume Information (i.e., beets ignores Unix-style hidden files,
backup files, and a directory that appears at the root of some Windows
filesystems).
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 map‐
ping 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.
If you do change this value, be certain that you include at least
enough substitutions to avoid causing errors on your operating system.
Here are the default substitutions used by beets, which are sufficient
to avoid unexpected behavior on all popular platforms:
replace:
'[\\/]': _
'^\.': _
'[\x00-\x1f]': _
'[<>:"\?\*\|]': _
'\.$': _
'\s+$': ''
'^\s+': ''
These substitutions remove forward and back slashes, leading dots, and
control characters—all of which is a good idea on any OS. The fourth
line removes the Windows "reserved characters" (useful even on Unix for
for compatibility with Windows-influenced network filesystems like
Samba). Trailing dots and trailing whitespace, which can cause prob‐
lems on Windows clients, are also removed.
When replacements other than the defaults are used, it is possible that
they will increase the length of the path. In the scenario where this
leads to a conflict with the maximum filename length, the default
replacements will be used to resolve the conflict and beets will dis‐
play a warning.
Note that paths might contain special characters such as typographical
quotes (“”). With the configuration above, those will not be replaced
as they don't match the typewriter quote ("). To also strip these spe‐
cial characters, you can either add them to the replacement list or use
the asciify_paths configuration option below.
asciify_paths
Convert all non-ASCII characters in paths to ASCII equivalents.
For example, if your path template for singletons is singletons/$title
and the title of a track is "Café", then the track will be saved as
singletons/Cafe.mp3. The changes take place before applying the
replace configuration and are roughly equivalent to wrapping all your
path templates in the %asciify{} template function.
Default: no.
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.
It used to be named list_format_item.
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.
It used to be named list_format_album.
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 items 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 orig‐
inal_year and so on. Default: no.
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.
If you enable per_disc_numbering, you will likely want to change your
Path Format Configuration also to include $disc before $track to make
filenames sort correctly in album directories. For example, you might
want to use a path format like this:
paths:
default: $albumartist/$album%aunique{}/$disc-$track $title
When this option is off (the default), even "pregap" hidden tracks are
numbered from one, not zero, so other track numbers may appear to be
bumped up by one. When it is on, the pregap track for each disc can be
numbered zero.
terminal_encoding
The text encoding, as known to Python, to use for messages printed to
the standard output. 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".
The importer only removes recursively searched subdirectories---the
top-level directory you specify on the command line is never deleted.
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 lat‐
est 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.
UI OPTIONS
The options that allow for customization of the visual appearance of
the console interface.
These options are available in this section:
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.
NOTE:
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
Available colors: black, darkred, darkgreen, brown (darkyellow), dark‐
blue, purple (darkmagenta), teal (darkcyan), lightgray, darkgray, red,
green, yellow, blue, fuchsia (magenta), turquoise (cyan), white
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 configura‐
tion file that looks like this:
import:
write: yes
copy: yes
resume: no
These options are available in this section:
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.
The option is ignored if move is enabled (i.e., beets can move or copy
files but it doesn't make sense to do both).
move
Either yes or no, indicating whether to move files into the library
directory when using beet import. Defaults to no.
The effect is similar to the copy option but you end up with only one
copy of the imported file. ("Moving" works even across filesystems; if
necessary, beets will copy and then delete when a simple rename is
impossible.) Moving files can be risky—it's a good idea to keep a
backup in case beets doesn't do what you expect with your files.
This option overrides copy, so enabling it will always move (and not
copy) files. The -c switch to the beet import command, however, still
takes precedence.
link
Either yes or no, indicating whether to use symbolic links instead of
moving or copying files. (It conflicts with the move and copy options.)
Defaults to no.
This option only works on platforms that support symbolic links: i.e.,
Unixes. It will fail on Windows.
It's likely that you'll also want to set write to no if you use this
option to preserve the metadata on the linked files.
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.
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 recom‐
mendation.
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 recommen‐
dations 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 let‐
ter. 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. 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 con‐
tain tracks from many albums mixed together.
The --group-albums or -g option to the import-cmd command is equiva‐
lent, and the G interactive option invokes the same workflow.
Default: no.
autotag
By default, the beets importer always attempts to autotag new music. If
most of your collection consists of obscure music, you may be inter‐
ested in disabling autotagging by setting this option to no. (You can
re-enable it with the -a flag to the import-cmd command.)
Default: yes.
MUSICBRAINZ OPTIONS
If you run your own MusicBrainz server, you can instruct beets to use
it instead of the main server. Use the host and ratelimit options under
a musicbrainz: header, like so:
musicbrainz:
host: localhost:5000
ratelimit: 100
The host key, of course, controls the Web server hostname (and port,
optionally) that will be contacted by beets (default: musicbrainz.org).
The ratelimit option, an integer, controls the number of Web service
requests per second (default: 1). Do not change the rate limit setting
if you're using the main MusicBrainz server---on this public server,
you're limited to one request per second.
searchlimit
The number of matches returned when sending search queries to the
MusicBrainz server.
Default: 5.
AUTOTAGGER MATCHING OPTIONS
You can configure some aspects of the logic beets uses when automati‐
cally 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.
The threshold is a distance value between 0.0 and 1.0, so you can think
of it as the opposite of a similarity value. For example, if you want
to automatically accept any matches above 90% similarity, use:
match:
strong_rec_thresh: 0.10
The default strong recommendation threshold is 0.04.
The medium_rec_thresh and rec_gap_thresh options work similarly. When a
match is above the medium recommendation threshold or the distance
between it and the next-best match is above the gap threshold, the
importer will suggest that match but not automatically confirm it. Oth‐
erwise, you'll see a list of options to choose from.
max_rec
As mentioned above, autotagger matches have recommendations that con‐
trol how the UI behaves for a certain quality of match. The recommenda‐
tion 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:
To define maxima, use keys under max_rec: in the match section. The
defaults are "medium" for missing and unmatched tracks and "strong"
(i.e., no maximum) for everything else:
match:
max_rec:
missing_tracks: medium
unmatched_tracks: medium
If a recommendation is higher than the configured maximum and the indi‐
cated penalty is applied, the recommendation is downgraded. The setting
for each field can be one of none, low, medium or strong. When the max‐
imum recommendation is strong, no "downgrading" occurs. The available
penalty names here are:
· 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 coun‐
tries and media types.
A distance penalty will be applied if the country or media type from
the match metadata doesn't match. The specified values are preferred in
descending order (i.e., the first item will be most preferred). Each
item may be a regular expression, and will be matched case insensi‐
tively. The number of media will be stripped when matching preferred
media (e.g. "2x" in "2xCD").
You can also tell the autotagger to prefer matches that have a release
year closest to the original year for an album.
Here's an example:
match:
preferred:
countries: ['US', 'GB|UK']
media: ['CD', 'Digital Media|File']
original_year: yes
By default, none of these options are enabled.
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
The available penalties are the same as those for the max_rec setting.
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
No tags are required by default.
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
Note the use of $albumartist instead of $artist; this ensure that
albums will be well-organized. For more about these format strings, see
pathformat. The aunique{} function ensures that identically-named
albums are placed in different directories; see aunique for details.
In addition to default, comp, and singleton, you can condition path
queries based on beets queries (see /reference/query). This means that
a config file like this:
paths:
albumtype:soundtrack: Soundtracks/$album/$track $title
will place soundtrack albums in a separate directory. The queries are
tested in the order they appear in the configuration file, meaning that
if an item matches multiple queries, beets will use the path format for
the first matching query.
Note that the special singleton and comp path format conditions are, in
fact, just shorthand for the explicit queries singleton:true and
comp:true. In contrast, default is special and has no query equivalent:
the default format is only used if no queries match.
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 use‐
ful if you want to keep your configuration mostly the same but modify a
few options as a batch. For example, you might have different strate‐
gies 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_CON‐
FIG_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.
Beets uses the first directory in your platform's list that contains
config.yaml. If no config file exists, the last path in the list is
used.
EXAMPLE
Here's an example file:
library: /var/music.blb
directory: /var/mp3
import:
copy: yes
write: yes
resume: ask
quiet_fallback: skip
timid: no
log: beetslog.txt
ignore: .AppleDouble ._* *~ .DS_Store
art_filename: albumart
plugins: bpd
pluginpath: ~/beets/myplugins
threaded: yes
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
http://beets.readthedocs.org/
beet(1)AUTHOR
Adrian Sampson
COPYRIGHT
2012, Adrian Sampson
1.3 October 17, 2015 BEETSCONFIG(5)
