NAME¶
beetsconfig - beets configuration file
The
beet command reads configuration information from
~/.beetsconfig on Unix-like OSes (inluding Mac OS X) and
%APPDATA%\beetsconfig.ini on Windows. The file is in INI format.
OPTIONS¶
These options are available, all of which must appear under the
[beets]
section header:
- library
- Path to the beets library file. Defaults to
~/.beetsmusic.blb on Unix and %APPDATA\beetsmusic.blb on
Windows.
- directory
- The directory to which files will be copied/moved when
adding them to the library. Defaults to ~/Music.
- import_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.
- import_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 import_move is enabled (i.e., beets can move
or copy files but it doesn't make sense to do both).
- import_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 import_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 import_copy, so enabling it will always
move (and not copy) files. The -c switch to the beet import
command, however, still takes precedence.
- import_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.
- import_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.
- import_art
- Either yes or no, indicating whether the
autotagger should attempt to find and download album cover art for the
files it imports. Defaults to yes. The -r and -R
command-line options override this setting.
- 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.
- import_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.
- import_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.
- ignore
- A space-separated list of glob patterns specifying file and
directory names to be ignored when importing. Defaults to .* *~
(i.e., ignore Unix-style hidden files and backup 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 . characters are replaced on Unix and trailing whitespace
is removed on Windows). To override these substitutions, specify a
sequence of whitespace-separated terms; the first term is a regular
expression and the second is a string that should replace anything
matching that regex. For example, replace = [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+$ <strip>
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.
To replace space characters, use the \s (whitespace) entity:
replace = \s _
...
This will avoid using a literal space and thus confusing beets. ( \s
also matches tabs and newlines, but that is probably fine.)
To remove characters entirely, use <strip> as the replacement.
For example, to remove all vowels from your filenames:
replace = [aeiou] <strip>
...
- art_filename
- When importing album art, the name of the file (without
extension) where the cover art image should be placed. Defaults to
cover (i.e., images will be named cover.jpg or
cover.png and placed in the album's directory).
- plugins
- A space-separated list of plugin module names to load. For
instance, beets includes the BPD plugin for playing music.
- pluginpath
- A colon-separated list of directories to search for
plugins. These paths are just added to sys.path before the plugins
are loaded. The plugins still have to be contained in a beetsplug
namespace package.
- 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.
- timeout
- The amount of time that the SQLite library should wait
before raising an exception when the database lock is contended. This
should almost never need to be changed except on very slow systems.
Defaults to 5.0 (5 seconds).
- import_delete
- Either yes or no. When enabled in conjunction
with import_copy, deletes original files after they are copied into
your library. Has no effect if the importer is in import_move mode
or "leave files in place" mode. Defaults to no.
This option is historical and deprecated: it's almost always more
appropriate to use import_move instead.
You can also configure the directory hierarchy beets uses to store music. These
settings appear under the
[paths] section (rather than the main
[beets] section we used above). 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).
There's one catch: because the
: character is reserved for separating
the query from the template string, the
_ character is substituted for
: in these queries. 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.
EXAMPLE¶
Here's an example file:
[beets]
library: /var/music.blb
directory: /var/mp3
path_format: $genre/$artist/$album/$track $title
import_copy: yes
import_write: yes
import_resume: ask
import_art: yes
import_quiet_fallback: skip
import_timid: no
import_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
[bpd]
host: 127.0.0.1
port: 6600
password: seekrit
(That
[bpd] section configures the optional
BPD plugin.)
LOCATION¶
The configuration file is typically located at
$HOME/.beetsconfig. If you
want to store your
.beetsconfig file somewhere else for whatever
reason, you can specify its path by setting the
BEETSCONFIG environment
variable.
AUTHOR¶
Adrian Sampson
COPYRIGHT¶
2011, Adrian Sampson