Ubuntu Manpage: beetsconfig - beets configuration file

NAME

beetsconfig - 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 platform (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/Application
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 Location, 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

• pluginpath

• ignore

• replace

• asciify_paths

• art_filename

• threaded

• color

• list_format_item

• list_format_album

• sort_item

• sort_album

• original_date

• per_disc_numbering

• terminal_encoding

• clutter

• max_filename_length

• id3v23

• Importer Options

• write

• copy

• move

• resume

• incremental

• quiet_fallback

• none_rec_action

• timid

• log

• default_action

• languages

• detail

• group_albums

• autotag

• MusicBrainz Options

• 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-plugins.

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 .*, *~, and System 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
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.

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 problems
on Windows clients, are also removed.

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 special 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 faster but may behave strangely. Defaults to yes.

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.

list_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.

list_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 items from the database. Defaults to albumartist+
album+. Explicit sort orders override this default.

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.

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

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".

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.

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

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.

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

The --group-albums or -g option to the import-cmd command is equivalent, and the G
interactive option invokes the same workflow.

NOTE:
The import log currently contains less information in album-grouping mode.
(Specifically, no directory names recorded because directories are not used for
grouping in this mode.)

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 interested 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.

AUTOTAGGER 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.

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. Otherwise, you'll see a list of options to choose from.

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:

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 indicated penalty is
applied, the recommendation is downgraded. The setting for each field can be one of none,
low, medium or strong. When the maximum 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 countries 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 insensitively. 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 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.

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

AUTHOR

       Adrian Sampson

COPYRIGHT

       2012, Adrian Sampson