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.
These options are available, all of which must appear under the [beets] section header:
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 the *<>| characters are 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 some recommended base replacements for Unix-like OSes:
replace = [\\/\?"]|^\.' _ : -
And, on Windows:
replace = [\\/\?"]|^\.' _ ["\*<>\|]|^\.|\.$|\s+$ _ : -
Note that the above examples are, in fact, the default substitutions used by beets.
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/$track $title singleton: Non-Album/$artist/$title comp: Compilations/$album/$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 Path Formats.
In addition to default, comp, and singleton, you can condition path queries based on beets queries (see Queries). 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.
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.)
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.