.\" Man page generated from reStructuredText. . .TH "BEETSCONFIG" "5" "Jan 23, 2017" "1.3" "beets" .SH NAME beetsconfig \- beets configuration file . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .sp Beets has an extensive configuration system that lets you customize nearly every aspect of its operation. To configure beets, you create a file called \fBconfig.yaml\fP\&. The location of the file depend on your platform (type \fBbeet config \-p\fP to see the path on your system): .INDENT 0.0 .IP \(bu 2 On Unix\-like OSes, write \fB~/.config/beets/config.yaml\fP\&. .IP \(bu 2 On Windows, use \fB%APPDATA%\ebeets\econfig.yaml\fP\&. This is usually in a directory like \fBC:\eUsers\eYou\eAppData\eRoaming\fP\&. .IP \(bu 2 On OS X, you can use either the Unix location or \fB~/Library/Application Support/beets/config.yaml\fP\&. .UNINDENT .sp You can launch your text editor to create or update your configuration by typing \fBbeet config \-e\fP\&. (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 \fI\%Configuration Location\fP, below. .sp The config file uses \fI\%YAML\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C option: value another_option: foo bigger_option: key: value foo: bar .ft P .fi .UNINDENT .UNINDENT .sp 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 \fI\%YAML\fP documentation. .sp The rest of this page enumerates the dizzying litany of configuration options available in beets. You might also want to see an \fI\%example\fP\&. .INDENT 0.0 .IP \(bu 2 \fI\%Global Options\fP .INDENT 2.0 .IP \(bu 2 \fI\%library\fP .IP \(bu 2 \fI\%directory\fP .IP \(bu 2 \fI\%plugins\fP .IP \(bu 2 \fI\%include\fP .IP \(bu 2 \fI\%pluginpath\fP .IP \(bu 2 \fI\%ignore\fP .IP \(bu 2 \fI\%ignore_hidden\fP .IP \(bu 2 \fI\%replace\fP .IP \(bu 2 \fI\%asciify_paths\fP .IP \(bu 2 \fI\%art_filename\fP .IP \(bu 2 \fI\%threaded\fP .IP \(bu 2 \fI\%format_item\fP .IP \(bu 2 \fI\%format_album\fP .IP \(bu 2 \fI\%sort_item\fP .IP \(bu 2 \fI\%sort_album\fP .IP \(bu 2 \fI\%sort_case_insensitive\fP .IP \(bu 2 \fI\%original_date\fP .IP \(bu 2 \fI\%per_disc_numbering\fP .IP \(bu 2 \fI\%terminal_encoding\fP .IP \(bu 2 \fI\%clutter\fP .IP \(bu 2 \fI\%max_filename_length\fP .IP \(bu 2 \fI\%id3v23\fP .IP \(bu 2 \fI\%va_name\fP .UNINDENT .IP \(bu 2 \fI\%UI Options\fP .INDENT 2.0 .IP \(bu 2 \fI\%color\fP .IP \(bu 2 \fI\%colors\fP .UNINDENT .IP \(bu 2 \fI\%Importer Options\fP .INDENT 2.0 .IP \(bu 2 \fI\%write\fP .IP \(bu 2 \fI\%copy\fP .IP \(bu 2 \fI\%move\fP .IP \(bu 2 \fI\%link\fP .IP \(bu 2 \fI\%resume\fP .IP \(bu 2 \fI\%incremental\fP .IP \(bu 2 \fI\%quiet_fallback\fP .IP \(bu 2 \fI\%none_rec_action\fP .IP \(bu 2 \fI\%timid\fP .IP \(bu 2 \fI\%log\fP .IP \(bu 2 \fI\%default_action\fP .IP \(bu 2 \fI\%languages\fP .IP \(bu 2 \fI\%detail\fP .IP \(bu 2 \fI\%group_albums\fP .IP \(bu 2 \fI\%autotag\fP .IP \(bu 2 \fI\%duplicate_action\fP .UNINDENT .IP \(bu 2 \fI\%MusicBrainz Options\fP .INDENT 2.0 .IP \(bu 2 \fI\%searchlimit\fP .UNINDENT .IP \(bu 2 \fI\%Autotagger Matching Options\fP .INDENT 2.0 .IP \(bu 2 \fI\%max_rec\fP .IP \(bu 2 \fI\%preferred\fP .IP \(bu 2 \fI\%ignored\fP .IP \(bu 2 \fI\%required\fP .UNINDENT .IP \(bu 2 \fI\%Path Format Configuration\fP .IP \(bu 2 \fI\%Configuration Location\fP .INDENT 2.0 .IP \(bu 2 \fI\%Environment Variable\fP .IP \(bu 2 \fI\%Command\-Line Option\fP .IP \(bu 2 \fI\%Default Location\fP .UNINDENT .IP \(bu 2 \fI\%Example\fP .UNINDENT .SH GLOBAL OPTIONS .sp These options control beets\(aq global operation. .SS library .sp Path to the beets library file. By default, beets will use a file called \fBlibrary.db\fP alongside your configuration file. .SS directory .sp The directory to which files will be copied/moved when adding them to the library. Defaults to a folder called \fBMusic\fP in your home directory. .SS plugins .sp A space\-separated list of plugin module names to load. See using\-plugins\&. .SS include .sp A space\-separated list of extra configuration files to include. Filenames are relative to the directory containing \fBconfig.yaml\fP\&. .SS pluginpath .sp Directories to search for plugins. Each Python file or directory in a plugin path represents a plugin and should define a subclass of \fBBeetsPlugin\fP\&. A plugin can then be loaded by adding the filename to the \fIplugins\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pluginpath: \- /path/one \- /path/two .ft P .fi .UNINDENT .UNINDENT .SS ignore .sp A list of glob patterns specifying file and directory names to be ignored when importing. By default, this consists of \fB\&.*\fP, \fB*~\fP, \fBSystem Volume Information\fP, \fBlost+found\fP (i.e., beets ignores Unix\-style hidden files, backup files, and directories that appears at the root of some Linux and Windows filesystems). .SS ignore_hidden .sp Either \fByes\fP or \fBno\fP; 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\(aqs "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. .SS replace .sp 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, \fB[xy]: z\fP will make beets replace all instances of the characters \fBx\fP or \fBy\fP with the character \fBz\fP\&. .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C replace: \(aq[\e\e/]\(aq: _ \(aq^\e.\(aq: _ \(aq[\ex00\-\ex1f]\(aq: _ \(aq[<>:"\e?\e*\e|]\(aq: _ \(aq\e.$\(aq: _ \(aq\es+$\(aq: \(aq\(aq \(aq^\es+\(aq: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .sp 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. .sp 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 display a warning. .sp Note that paths might contain special characters such as typographical quotes (\fB“”\fP). With the configuration above, those will not be replaced as they don\(aqt match the typewriter quote (\fB"\fP). To also strip these special characters, you can either add them to the replacement list or use the \fI\%asciify_paths\fP configuration option below. .SS asciify_paths .sp Convert all non\-ASCII characters in paths to ASCII equivalents. .sp For example, if your path template for singletons is \fBsingletons/$title\fP and the title of a track is "Café", then the track will be saved as \fBsingletons/Cafe.mp3\fP\&. The changes take place before applying the \fI\%replace\fP configuration and are roughly equivalent to wrapping all your path templates in the \fB%asciify{}\fP template function\&. .sp Default: \fBno\fP\&. .SS art_filename .sp 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 \fBcover\fP (i.e., images will be named \fBcover.jpg\fP or \fBcover.png\fP and placed in the album\(aqs directory). .SS threaded .sp Either \fByes\fP or \fBno\fP, 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 \fByes\fP\&. .SS format_item .sp Format to use when listing \fIindividual items\fP with the list\-cmd command and other commands that need to print out items. Defaults to \fB$artist \- $album \- $title\fP\&. The \fB\-f\fP command\-line option overrides this setting. .sp It used to be named \fIlist_format_item\fP\&. .SS format_album .sp Format to use when listing \fIalbums\fP with list\-cmd and other commands. Defaults to \fB$albumartist \- $album\fP\&. The \fB\-f\fP command\-line option overrides this setting. .sp It used to be named \fIlist_format_album\fP\&. .SS sort_item .sp Default sort order to use when fetching items from the database. Defaults to \fBartist+ album+ disc+ track+\fP\&. Explicit sort orders override this default. .SS sort_album .sp Default sort order to use when fetching items from the database. Defaults to \fBalbumartist+ album+\fP\&. Explicit sort orders override this default. .SS sort_case_insensitive .sp Either \fByes\fP or \fBno\fP, indicating whether the case should be ignored when sorting lexicographic fields. When set to \fBno\fP, lower\-case values will be placed after upper\-case values (e.g., \fIBar Qux foo\fP), while \fByes\fP would result in the more expected \fIBar foo Qux\fP\&. Default: \fByes\fP\&. .SS original_date .sp Either \fByes\fP or \fBno\fP, indicating whether matched albums should have their \fByear\fP, \fBmonth\fP, and \fBday\fP fields set to the release date of the \fIoriginal\fP version of an album rather than the selected version of the release. That is, if this option is turned on, then \fByear\fP will always equal \fBoriginal_year\fP and so on. Default: \fBno\fP\&. .SS per_disc_numbering .sp A boolean controlling the track numbering style on multi\-disc releases. By default (\fBper_disc_numbering: no\fP), 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 \fBper_disc_numbering\fP is enabled, then the first (non\-pregap) track on each disc always has track number 1. .sp If you enable \fBper_disc_numbering\fP, you will likely want to change your \fI\%Path Format Configuration\fP also to include \fB$disc\fP before \fB$track\fP to make filenames sort correctly in album directories. For example, you might want to use a path format like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C paths: default: $albumartist/$album%aunique{}/$disc\-$track $title .ft P .fi .UNINDENT .UNINDENT .sp 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. .SS terminal_encoding .sp The text encoding, as \fI\%known to Python\fP, to use for messages printed to the standard output. It\(aqs also used to read messages from the standard input. By default, this is determined automatically from the locale environment variables. .SS clutter .sp When beets imports all the files in a directory, it tries to remove the directory if it\(aqs empty. A directory is considered empty if it only contains files whose names match the glob patterns in \fIclutter\fP, which should be a list of strings. The default list consists of "Thumbs.DB" and ".DS_Store". .sp The importer only removes recursively searched subdirectories\-\-\-the top\-level directory you specify on the command line is never deleted. .SS max_filename_length .sp 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. .SS id3v23 .sp 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. .SS va_name .sp Sets the albumartist for various\-artist compilations. Defaults to \fB\(aqVarious Artists\(aq\fP (the MusicBrainz standard). Affects other sources, such as /plugins/discogs, too. .SH UI OPTIONS .sp The options that allow for customization of the visual appearance of the console interface. .sp These options are available in this section: .SS color .sp Either \fByes\fP or \fBno\fP; whether to use color in console output (currently only in the \fBimport\fP command). Turn this off if your terminal doesn\(aqt support ANSI colors. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fIcolor\fP option was previously a top\-level configuration. This is still respected, but a deprecation message will be shown until your top\-level \fIcolor\fP configuration has been nested under \fIui\fP\&. .UNINDENT .UNINDENT .SS colors .sp The colors that are used throughout the user interface. These are only used if the \fBcolor\fP option is set to \fByes\fP\&. For example, you might have a section in your configuration file that looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 .ft P .fi .UNINDENT .UNINDENT .sp Available colors: black, darkred, darkgreen, brown (darkyellow), darkblue, purple (darkmagenta), teal (darkcyan), lightgray, darkgray, red, green, yellow, blue, fuchsia (magenta), turquoise (cyan), white .SH IMPORTER OPTIONS .sp The options that control the import\-cmd command are indented under the \fBimport:\fP key. For example, you might have a section in your configuration file that looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import: write: yes copy: yes resume: no .ft P .fi .UNINDENT .UNINDENT .sp These options are available in this section: .SS write .sp Either \fByes\fP or \fBno\fP, controlling whether metadata (e.g., ID3) tags are written to files when using \fBbeet import\fP\&. Defaults to \fByes\fP\&. The \fB\-w\fP and \fB\-W\fP command\-line options override this setting. .SS copy .sp Either \fByes\fP or \fBno\fP, indicating whether to \fBcopy\fP files into the library directory when using \fBbeet import\fP\&. Defaults to \fByes\fP\&. Can be overridden with the \fB\-c\fP and \fB\-C\fP command\-line options. .sp The option is ignored if \fBmove\fP is enabled (i.e., beets can move or copy files but it doesn\(aqt make sense to do both). .SS move .sp Either \fByes\fP or \fBno\fP, indicating whether to \fBmove\fP files into the library directory when using \fBbeet import\fP\&. Defaults to \fBno\fP\&. .sp The effect is similar to the \fBcopy\fP 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\(aqs a good idea to keep a backup in case beets doesn\(aqt do what you expect with your files. .sp This option \fIoverrides\fP \fBcopy\fP, so enabling it will always move (and not copy) files. The \fB\-c\fP switch to the \fBbeet import\fP command, however, still takes precedence. .SS link .sp Either \fByes\fP or \fBno\fP, indicating whether to use symbolic links instead of moving or copying files. (It conflicts with the \fBmove\fP and \fBcopy\fP options.) Defaults to \fBno\fP\&. .sp This option only works on platforms that support symbolic links: i.e., Unixes. It will fail on Windows. .sp It\(aqs likely that you\(aqll also want to set \fBwrite\fP to \fBno\fP if you use this option to preserve the metadata on the linked files. .SS resume .sp Either \fByes\fP, \fBno\fP, or \fBask\fP\&. 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 \fB\-p\fP and \fB\-P\fP flags correspond to the "yes" and "no" settings and override this option. .SS incremental .sp Either \fByes\fP or \fBno\fP, controlling whether imported directories are recorded and whether these recorded directories are skipped. This corresponds to the \fB\-i\fP flag to \fBbeet import\fP\&. .SS quiet_fallback .sp Either \fBskip\fP (default) or \fBasis\fP, specifying what should happen in quiet mode (see the \fB\-q\fP flag to \fBimport\fP, above) when there is no strong recommendation. .SS none_rec_action .sp Either \fBask\fP (default), \fBasis\fP or \fBskip\fP\&. 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. .SS timid .sp Either \fByes\fP or \fBno\fP, controlling whether the importer runs in \fItimid\fP mode, in which it asks for confirmation on every autotagging match, even the ones that seem very close. Defaults to \fBno\fP\&. The \fB\-t\fP command\-line flag controls the same setting. .SS log .sp Specifies a filename where the importer\(aqs log should be kept. By default, no log is written. This can be overridden with the \fB\-l\fP flag to \fBimport\fP\&. .SS default_action .sp One of \fBapply\fP, \fBskip\fP, \fBasis\fP, or \fBnone\fP, indicating which option should be the \fIdefault\fP 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 \fBapply\fP\&. .SS languages .sp 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\(aqs name when tagging from MusicBrainz. Defaults to an empty list, meaning that no language is preferred. .SS detail .sp 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: \fBno\fP\&. .SS group_albums .sp By default, the beets importer groups tracks into albums based on the directories they reside in. This option instead uses files\(aq metadata to partition albums. Enable this option if you have directories that contain tracks from many albums mixed together. .sp The \fB\-\-group\-albums\fP or \fB\-g\fP option to the import\-cmd command is equivalent, and the \fIG\fP interactive option invokes the same workflow. .sp Default: \fBno\fP\&. .SS autotag .sp 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 \fBno\fP\&. (You can re\-enable it with the \fB\-a\fP flag to the import\-cmd command.) .sp Default: \fByes\fP\&. .SS duplicate_action .sp Either \fBskip\fP, \fBkeep\fP, \fBremove\fP, or \fBask\fP\&. Controls how duplicates are treated in import task. "skip" means that new item(album or track) will be skiped; "keep" means keep both old and new items; "remove" means remove old item; "ask" means the user should be prompted for the action each time. The default is \fBask\fP\&. .SH MUSICBRAINZ OPTIONS .sp If you run your own \fI\%MusicBrainz\fP server, you can instruct beets to use it instead of the main server. Use the \fBhost\fP and \fBratelimit\fP options under a \fBmusicbrainz:\fP header, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C musicbrainz: host: localhost:5000 ratelimit: 100 .ft P .fi .UNINDENT .UNINDENT .sp The \fBhost\fP key, of course, controls the Web server hostname (and port, optionally) that will be contacted by beets (default: musicbrainz.org). The \fBratelimit\fP option, an integer, controls the number of Web service requests per second (default: 1). \fBDo not change the rate limit setting\fP if you\(aqre using the main MusicBrainz server\-\-\-on this public server, you\(aqre \fI\%limited\fP to one request per second. .SS searchlimit .sp The number of matches returned when sending search queries to the MusicBrainz server. .sp Default: \fB5\fP\&. .SH AUTOTAGGER MATCHING OPTIONS .sp You can configure some aspects of the logic beets uses when automatically matching MusicBrainz results under the \fBmatch:\fP section. To control how \fItolerant\fP the autotagger is of differences, use the \fBstrong_rec_thresh\fP 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. .sp The threshold is a \fIdistance\fP value between 0.0 and 1.0, so you can think of it as the opposite of a \fIsimilarity\fP value. For example, if you want to automatically accept any matches above 90% similarity, use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C match: strong_rec_thresh: 0.10 .ft P .fi .UNINDENT .UNINDENT .sp The default strong recommendation threshold is 0.04. .sp The \fBmedium_rec_thresh\fP and \fBrec_gap_thresh\fP options work similarly. When a match is above the \fImedium\fP recommendation threshold or the distance between it and the next\-best match is above the \fIgap\fP threshold, the importer will suggest that match but not automatically confirm it. Otherwise, you\(aqll see a list of options to choose from. .SS max_rec .sp As mentioned above, autotagger matches have \fIrecommendations\fP 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 \fImaximum\fP recommendations for each field: .sp To define maxima, use keys under \fBmax_rec:\fP in the \fBmatch\fP section. The defaults are "medium" for missing and unmatched tracks and "strong" (i.e., no maximum) for everything else: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C match: max_rec: missing_tracks: medium unmatched_tracks: medium .ft P .fi .UNINDENT .UNINDENT .sp 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 \fBnone\fP, \fBlow\fP, \fBmedium\fP or \fBstrong\fP\&. When the maximum recommendation is \fBstrong\fP, no "downgrading" occurs. The available penalty names here are: .INDENT 0.0 .IP \(bu 2 source .IP \(bu 2 artist .IP \(bu 2 album .IP \(bu 2 media .IP \(bu 2 mediums .IP \(bu 2 year .IP \(bu 2 country .IP \(bu 2 label .IP \(bu 2 catalognum .IP \(bu 2 albumdisambig .IP \(bu 2 album_id .IP \(bu 2 tracks .IP \(bu 2 missing_tracks .IP \(bu 2 unmatched_tracks .IP \(bu 2 track_title .IP \(bu 2 track_artist .IP \(bu 2 track_index .IP \(bu 2 track_length .IP \(bu 2 track_id .UNINDENT .SS preferred .sp 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. .sp A distance penalty will be applied if the country or media type from the match metadata doesn\(aqt 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"). .sp You can also tell the autotagger to prefer matches that have a release year closest to the original year for an album. .sp Here\(aqs an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C match: preferred: countries: [\(aqUS\(aq, \(aqGB|UK\(aq] media: [\(aqCD\(aq, \(aqDigital Media|File\(aq] original_year: yes .ft P .fi .UNINDENT .UNINDENT .sp By default, none of these options are enabled. .SS ignored .sp You can completely avoid matches that have certain penalties applied by adding the penalty name to the \fBignored\fP setting: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C match: ignored: missing_tracks unmatched_tracks .ft P .fi .UNINDENT .UNINDENT .sp The available penalties are the same as those for the \fI\%max_rec\fP setting. .SS required .sp You can avoid matches that lack certain required information. Add the tags you want to enforce to the \fBrequired\fP setting: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C match: required: year label catalognum country .ft P .fi .UNINDENT .UNINDENT .sp No tags are required by default. .SH PATH FORMAT CONFIGURATION .sp You can also configure the directory hierarchy beets uses to store music. These settings appear under the \fBpaths:\fP key. Each string is a template string that can refer to metadata fields like \fB$artist\fP or \fB$title\fP\&. The filename extension is added automatically. At the moment, you can specify three special paths: \fBdefault\fP for most releases, \fBcomp\fP for "various artist" releases with no dominant artist, and \fBsingleton\fP for non\-album tracks. The defaults look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C paths: default: $albumartist/$album%aunique{}/$track $title singleton: Non\-Album/$artist/$title comp: Compilations/$album%aunique{}/$track $title .ft P .fi .UNINDENT .UNINDENT .sp Note the use of \fB$albumartist\fP instead of \fB$artist\fP; this ensures that albums will be well\-organized. For more about these format strings, see pathformat\&. The \fBaunique{}\fP function ensures that identically\-named albums are placed in different directories; see aunique for details. .sp In addition to \fBdefault\fP, \fBcomp\fP, and \fBsingleton\fP, you can condition path queries based on beets queries (see /reference/query). This means that a config file like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C paths: albumtype:soundtrack: Soundtracks/$album/$track $title .ft P .fi .UNINDENT .UNINDENT .sp 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 \fIfirst\fP matching query. .sp Note that the special \fBsingleton\fP and \fBcomp\fP path format conditions are, in fact, just shorthand for the explicit queries \fBsingleton:true\fP and \fBcomp:true\fP\&. In contrast, \fBdefault\fP is special and has no query equivalent: the \fBdefault\fP format is only used if no queries match. .SH CONFIGURATION LOCATION .sp 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. .SS Environment Variable .sp First, you can set the \fBBEETSDIR\fP environment variable to a directory containing a \fBconfig.yaml\fP file. This replaces your configuration in the default location. This also affects where auxiliary files, like the library database, are stored by default (that\(aqs where relative paths are resolved to). This environment variable is useful if you need to manage multiple beets libraries with separate configurations. .SS Command\-Line Option .sp Alternatively, you can use the \fB\-\-config\fP command\-line option to indicate a YAML file containing options that will then be merged with your existing options (from \fBBEETSDIR\fP 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. .SS Default Location .sp In the absence of a \fBBEETSDIR\fP variable, beets searches a few places for your configuration, depending on the platform: .INDENT 0.0 .IP \(bu 2 On Unix platforms, including OS X:\fB~/.config/beets\fP and then \fB$XDG_CONFIG_DIR/beets\fP, if the environment variable is set. .IP \(bu 2 On OS X, we also search \fB~/Library/Application Support/beets\fP before the Unixy locations. .IP \(bu 2 On Windows: \fB~\eAppData\eRoaming\ebeets\fP, and then \fB%APPDATA%\ebeets\fP, if the environment variable is set. .UNINDENT .sp Beets uses the first directory in your platform\(aqs list that contains \fBconfig.yaml\fP\&. If no config file exists, the last path in the list is used. .SH EXAMPLE .sp Here\(aqs an example file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 ignore_hidden: yes art_filename: albumart plugins: bpd pluginpath: ~/beets/myplugins threaded: yes 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 .ft P .fi .UNINDENT .UNINDENT .SH SEE ALSO .sp \fBhttp://beets.readthedocs.org/\fP .sp \fBbeet(1)\fP .SH AUTHOR Adrian Sampson .SH COPYRIGHT 2017, Adrian Sampson .\" Generated by docutils manpage writer. .