1BEETSCONFIG(5) beets BEETSCONFIG(5)
2
6 beetsconfig - beets configuration file
7 Beets has an extensive configuration system that lets you customize
9 nearly every aspect of its operation. To configure beets, you create a
10 file called config.yaml. The location of the file depend on your plat‐
11 form (type beet config -p to see the path on your system):
12 • On Unix-like OSes, write ~/.config/beets/config.yaml.
14 • On Windows, use %APPDATA%\beets\config.yaml. This is usually in a di‐
16 rectory like C:\Users\You\AppData\Roaming.
17 • On OS X, you can use either the Unix location or ~/Library/Applica‐
19 tion Support/beets/config.yaml.
20 You can launch your text editor to create or update your configuration
22 by typing beet config -e. (See the config-cmd command for details.) It
23 is also possible to customize the location of the configuration file
24 and even use multiple layers of configuration. See Configuration Loca‐
25 tion, below.
26 The config file uses YAML syntax. You can use the full power of YAML,
28 but most configuration options are simple key/value pairs. This means
29 your config file will look like this:
30 option: value
32 another_option: foo
33 bigger_option:
34 key: value
35 foo: bar
36 In YAML, you will need to use spaces (not tabs!) to indent some lines.
38 If you have questions about more sophisticated syntax, take a look at
39 the YAML documentation.
40 The rest of this page enumerates the dizzying litany of configuration
42 options available in beets. You might also want to see an example.
43 • Global Options
45 • library
47 • directory
49 • plugins
51 • include
53 • pluginpath
55 • ignore
57 • ignore_hidden
59 • replace
61 • asciify_paths
63 • art_filename
65 • threaded
67 • format_item
69 • format_album
71 • sort_item
73 • sort_album
75 • sort_case_insensitive
77 • original_date
79 • artist_credit
81 • per_disc_numbering
83 • aunique
85 • terminal_encoding
87 • clutter
89 • max_filename_length
91 • id3v23
93 • va_name
95 • UI Options
97 • color
99 • colors
101 • Importer Options
103 • write
105 • copy
107 • move
109 • link
111 • hardlink
113 • resume
115 • incremental
117 • incremental_skip_later
119 • from_scratch
121 • quiet_fallback
123 • none_rec_action
125 • timid
127 • log
129 • default_action
131 • languages
133 • detail
135 • group_albums
137 • autotag
139 • duplicate_action
141 • bell
143 • set_fields
145 • MusicBrainz Options
147 • searchlimit
149 • Autotagger Matching Options
151 • max_rec
153 • preferred
155 • ignored
157 • required
159 • ignored_media
161 • ignore_data_tracks
163 • ignore_video_tracks
165 • Path Format Configuration
167 • Configuration Location
169 • Environment Variable
171 • Command-Line Option
173 • Default Location
175 • Example
177
179 These options control beets' global operation.
180 library
182 Path to the beets library file. By default, beets will use a file
183 called library.db alongside your configuration file.
184 directory
186 The directory to which files will be copied/moved when adding them to
187 the library. Defaults to a folder called Music in your home directory.
188 plugins
190 A space-separated list of plugin module names to load. See using-plug‐
191 ins.
192 include
194 A space-separated list of extra configuration files to include. File‐
195 names are relative to the directory containing config.yaml.
196 pluginpath
198 Directories to search for plugins. Each Python file or directory in a
199 plugin path represents a plugin and should define a subclass of Beet‐
200 sPlugin. A plugin can then be loaded by adding the filename to the
201 plugins configuration. The plugin path can either be a single string
202 or a list of strings---so, if you have multiple paths, format them as a
203 YAML list like so:
204 pluginpath:
206 - /path/one
207 - /path/two
208 ignore
210 A list of glob patterns specifying file and directory names to be ig‐
211 nored when importing. By default, this consists of .*, *~, System
212 Volume Information, lost+found (i.e., beets ignores Unix-style hidden
213 files, backup files, and directories that appears at the root of some
214 Linux and Windows filesystems).
215 ignore_hidden
217 Either yes or no; whether to ignore hidden files when importing. On
218 Windows, the "Hidden" property of files is used to detect whether or
219 not a file is hidden. On OS X, the file's "IsHidden" flag is used to
220 detect whether or not a file is hidden. On both OS X and other plat‐
221 forms (excluding Windows), files (and directories) starting with a dot
222 are detected as hidden files.
223 replace
225 A set of regular expression/replacement pairs to be applied to all
226 filenames created by beets. Typically, these replacements are used to
227 avoid confusing problems or errors with the filesystem (for example,
228 leading dots, which hide files on Unix, and trailing whitespace, which
229 is illegal on Windows). To override these substitutions, specify a map‐
230 ping from regular expression to replacement strings. For example, [xy]:
231 z will make beets replace all instances of the characters x or y with
232 the character z.
233 If you do change this value, be certain that you include at least
235 enough substitutions to avoid causing errors on your operating system.
236 Here are the default substitutions used by beets, which are sufficient
237 to avoid unexpected behavior on all popular platforms:
238 replace:
240 '[\\/]': _
241 '^\.': _
242 '[\x00-\x1f]': _
243 '[<>:"\?\*\|]': _
244 '\.$': _
245 '\s+$': ''
246 '^\s+': ''
247 '^-': _
248 These substitutions remove forward and back slashes, leading dots, and
250 control characters—all of which is a good idea on any OS. The fourth
251 line removes the Windows "reserved characters" (useful even on Unix for
252 for compatibility with Windows-influenced network filesystems like
253 Samba). Trailing dots and trailing whitespace, which can cause prob‐
254 lems on Windows clients, are also removed.
255 When replacements other than the defaults are used, it is possible that
257 they will increase the length of the path. In the scenario where this
258 leads to a conflict with the maximum filename length, the default re‐
259 placements will be used to resolve the conflict and beets will display
260 a warning.
261 Note that paths might contain special characters such as typographical
263 quotes (“”). With the configuration above, those will not be replaced
264 as they don't match the typewriter quote ("). To also strip these spe‐
265 cial characters, you can either add them to the replacement list or use
266 the asciify_paths configuration option below.
267 asciify_paths
269 Convert all non-ASCII characters in paths to ASCII equivalents.
270 For example, if your path template for singletons is singletons/$title
272 and the title of a track is "Café", then the track will be saved as
273 singletons/Cafe.mp3. The changes take place before applying the
274 replace configuration and are roughly equivalent to wrapping all your
275 path templates in the %asciify{} template function.
276 Default: no.
278 art_filename
280 When importing album art, the name of the file (without extension)
281 where the cover art image should be placed. This is a template string,
282 so you can use any of the syntax available to /reference/pathformat.
283 Defaults to cover (i.e., images will be named cover.jpg or cover.png
284 and placed in the album's directory).
285 threaded
287 Either yes or no, indicating whether the autotagger should use multiple
288 threads. This makes things substantially faster by overlapping work:
289 for example, it can copy files for one album in parallel with looking
290 up data in MusicBrainz for a different album. You may want to disable
291 this when debugging problems with the autotagger. Defaults to yes.
292 format_item
294 Format to use when listing individual items with the list-cmd command
295 and other commands that need to print out items. Defaults to $artist -
296 $album - $title. The -f command-line option overrides this setting.
297 It used to be named list_format_item.
299 format_album
301 Format to use when listing albums with list-cmd and other commands. De‐
302 faults to $albumartist - $album. The -f command-line option overrides
303 this setting.
304 It used to be named list_format_album.
306 sort_item
308 Default sort order to use when fetching items from the database. De‐
309 faults to artist+ album+ disc+ track+. Explicit sort orders override
310 this default.
311 sort_album
313 Default sort order to use when fetching albums from the database. De‐
314 faults to albumartist+ album+. Explicit sort orders override this de‐
315 fault.
316 sort_case_insensitive
318 Either yes or no, indicating whether the case should be ignored when
319 sorting lexicographic fields. When set to no, lower-case values will be
320 placed after upper-case values (e.g., Bar Qux foo), while yes would re‐
321 sult in the more expected Bar foo Qux. Default: yes.
322 original_date
324 Either yes or no, indicating whether matched albums should have their
325 year, month, and day fields set to the release date of the original
326 version of an album rather than the selected version of the release.
327 That is, if this option is turned on, then year will always equal orig‐
328 inal_year and so on. Default: no.
329 artist_credit
331 Either yes or no, indicating whether matched tracks and albums should
332 use the artist credit, rather than the artist. That is, if this option
333 is turned on, then artist will contain the artist as credited on the
334 release.
335 per_disc_numbering
337 A boolean controlling the track numbering style on multi-disc releases.
338 By default (per_disc_numbering: no), tracks are numbered per-release,
339 so the first track on the second disc has track number N+1 where N is
340 the number of tracks on the first disc. If this per_disc_numbering is
341 enabled, then the first (non-pregap) track on each disc always has
342 track number 1.
343 If you enable per_disc_numbering, you will likely want to change your
345 Path Format Configuration also to include $disc before $track to make
346 filenames sort correctly in album directories. For example, you might
347 want to use a path format like this:
348 paths:
350 default: $albumartist/$album%aunique{}/$disc-$track $title
351 When this option is off (the default), even "pregap" hidden tracks are
353 numbered from one, not zero, so other track numbers may appear to be
354 bumped up by one. When it is on, the pregap track for each disc can be
355 numbered zero.
356 aunique
358 These options are used to generate a string that is guaranteed to be
359 unique among all albums in the library who share the same set of keys.
360 The defaults look like this:
362 aunique:
364 keys: albumartist album
365 disambiguators: albumtype year label catalognum albumdisambig releasegroupdisambig
366 bracket: '[]'
367 See aunique for more details.
369 terminal_encoding
371 The text encoding, as known to Python, to use for messages printed to
372 the standard output. It's also used to read messages from the standard
373 input. By default, this is determined automatically from the locale
374 environment variables.
375 clutter
377 When beets imports all the files in a directory, it tries to remove the
378 directory if it's empty. A directory is considered empty if it only
379 contains files whose names match the glob patterns in clutter, which
380 should be a list of strings. The default list consists of "Thumbs.DB"
381 and ".DS_Store".
382 The importer only removes recursively searched subdirectories---the
384 top-level directory you specify on the command line is never deleted.
385 max_filename_length
387 Set the maximum number of characters in a filename, after which names
388 will be truncated. By default, beets tries to ask the filesystem for
389 the correct maximum.
390 id3v23
392 By default, beets writes MP3 tags using the ID3v2.4 standard, the lat‐
393 est version of ID3. Enable this option to instead use the older ID3v2.3
394 standard, which is preferred by certain older software such as Windows
395 Media Player.
396 va_name
398 Sets the albumartist for various-artist compilations. Defaults to 'Var‐
399 ious Artists' (the MusicBrainz standard). Affects other sources, such
400 as /plugins/discogs, too.
401
403 The options that allow for customization of the visual appearance of
404 the console interface.
405 These options are available in this section:
407 color
409 Either yes or no; whether to use color in console output (currently
410 only in the import command). Turn this off if your terminal doesn't
411 support ANSI colors.
412 NOTE:
414 The color option was previously a top-level configuration. This is
415 still respected, but a deprecation message will be shown until your
416 top-level color configuration has been nested under ui.
417 colors
419 The colors that are used throughout the user interface. These are only
420 used if the color option is set to yes. For example, you might have a
421 section in your configuration file that looks like this:
422 ui:
424 color: yes
425 colors:
426 text_success: green
427 text_warning: yellow
428 text_error: red
429 text_highlight: red
430 text_highlight_minor: lightgray
431 action_default: turquoise
432 action: blue
433 Available colors: black, darkred, darkgreen, brown (darkyellow), dark‐
435 blue, purple (darkmagenta), teal (darkcyan), lightgray, darkgray, red,
436 green, yellow, blue, fuchsia (magenta), turquoise (cyan), white
437
439 The options that control the import-cmd command are indented under the
440 import: key. For example, you might have a section in your configura‐
441 tion file that looks like this:
442 import:
444 write: yes
445 copy: yes
446 resume: no
447 These options are available in this section:
449 write
451 Either yes or no, controlling whether metadata (e.g., ID3) tags are
452 written to files when using beet import. Defaults to yes. The -w and -W
453 command-line options override this setting.
454 copy
456 Either yes or no, indicating whether to copy files into the library di‐
457 rectory when using beet import. Defaults to yes. Can be overridden
458 with the -c and -C command-line options.
459 The option is ignored if move is enabled (i.e., beets can move or copy
461 files but it doesn't make sense to do both).
462 move
464 Either yes or no, indicating whether to move files into the library di‐
465 rectory when using beet import. Defaults to no.
466 The effect is similar to the copy option but you end up with only one
468 copy of the imported file. ("Moving" works even across filesystems; if
469 necessary, beets will copy and then delete when a simple rename is im‐
470 possible.) Moving files can be risky—it's a good idea to keep a backup
471 in case beets doesn't do what you expect with your files.
472 This option overrides copy, so enabling it will always move (and not
474 copy) files. The -c switch to the beet import command, however, still
475 takes precedence.
476 link
478 Either yes or no, indicating whether to use symbolic links instead of
479 moving or copying files. (It conflicts with the move, copy and hardlink
480 options.) Defaults to no.
481 This option only works on platforms that support symbolic links: i.e.,
483 Unixes. It will fail on Windows.
484 It's likely that you'll also want to set write to no if you use this
486 option to preserve the metadata on the linked files.
487 hardlink
489 Either yes or no, indicating whether to use hard links instead of mov‐
490 ing or copying or symlinking files. (It conflicts with the move, copy,
491 and link options.) Defaults to no.
492 As with symbolic links (see link, above), this will not work on Windows
494 and you will want to set write to no. Otherwise, metadata on the orig‐
495 inal file will be modified.
496 resume
498 Either yes, no, or ask. Controls whether interrupted imports should be
499 resumed. "Yes" means that imports are always resumed when possible;
500 "no" means resuming is disabled entirely; "ask" (the default) means
501 that the user should be prompted when resuming is possible. The -p and
502 -P flags correspond to the "yes" and "no" settings and override this
503 option.
504 incremental
506 Either yes or no, controlling whether imported directories are recorded
507 and whether these recorded directories are skipped. This corresponds
508 to the -i flag to beet import.
509 incremental_skip_later
511 Either yes or no, controlling whether skipped directories are recorded
512 in the incremental list. When set to yes, skipped directories will be
513 recorded, and skipped later. When set to no, skipped directories won't
514 be recorded, and beets will try to import them again later. Defaults to
515 no.
516 from_scratch
518 Either yes or no (default), controlling whether existing metadata is
519 discarded when a match is applied. This corresponds to the
520 --from_scratch flag to beet import.
521 quiet_fallback
523 Either skip (default) or asis, specifying what should happen in quiet
524 mode (see the -q flag to import, above) when there is no strong recom‐
525 mendation.
526 none_rec_action
528 Either ask (default), asis or skip. Specifies what should happen during
529 an interactive import session when there is no recommendation. Useful
530 when you are only interested in processing medium and strong recommen‐
531 dations interactively.
532 timid
534 Either yes or no, controlling whether the importer runs in timid mode,
535 in which it asks for confirmation on every autotagging match, even the
536 ones that seem very close. Defaults to no. The -t command-line flag
537 controls the same setting.
538 log
540 Specifies a filename where the importer's log should be kept. By de‐
541 fault, no log is written. This can be overridden with the -l flag to
542 import.
543 default_action
545 One of apply, skip, asis, or none, indicating which option should be
546 the default when selecting an action for a given match. This is the ac‐
547 tion that will be taken when you type return without an option letter.
548 The default is apply.
549 languages
551 A list of locale names to search for preferred aliases. For example,
552 setting this to en uses the transliterated artist name "Pyotr Ilyich
553 Tchaikovsky" instead of the Cyrillic script for the composer's name
554 when tagging from MusicBrainz. You can use a space-separated list of
555 language abbreviations, like en jp es, to specify a preference order.
556 Defaults to an empty list, meaning that no language is preferred.
557 detail
559 Whether the importer UI should show detailed information about each
560 match it finds. When enabled, this mode prints out the title of every
561 track, regardless of whether it matches the original metadata. (The de‐
562 fault behavior only shows changes.) Default: no.
563 group_albums
565 By default, the beets importer groups tracks into albums based on the
566 directories they reside in. This option instead uses files' metadata to
567 partition albums. Enable this option if you have directories that con‐
568 tain tracks from many albums mixed together.
569 The --group-albums or -g option to the import-cmd command is equiva‐
571 lent, and the G interactive option invokes the same workflow.
572 Default: no.
574 autotag
576 By default, the beets importer always attempts to autotag new music. If
577 most of your collection consists of obscure music, you may be inter‐
578 ested in disabling autotagging by setting this option to no. (You can
579 re-enable it with the -a flag to the import-cmd command.)
580 Default: yes.
582 duplicate_action
584 Either skip, keep, remove, merge or ask. Controls how duplicates are
585 treated in import task. "skip" means that new item(album or track)
586 will be skipped; "keep" means keep both old and new items; "remove"
587 means remove old item; "merge" means merge into one album; "ask" means
588 the user should be prompted for the action each time. The default is
589 ask.
590 bell
592 Ring the terminal bell to get your attention when the importer needs
593 your input.
594 Default: no.
596 set_fields
598 A dictionary indicating fields to set to values for newly imported mu‐
599 sic. Here's an example:
600 set_fields:
602 genre: 'To Listen'
603 collection: 'Unordered'
604 Other field/value pairs supplied via the --set option on the com‐
606 mand-line override any settings here for fields with the same name.
607 Default: {} (empty).
609
611 You can instruct beets to use your own MusicBrainz database instead of
612 the main server. Use the host and ratelimit options under a mu‐
613 sicbrainz: header, like so:
614 musicbrainz:
616 host: localhost:5000
617 ratelimit: 100
618 The host key, of course, controls the Web server hostname (and port,
620 optionally) that will be contacted by beets (default: musicbrainz.org).
621 The server must have search indices enabled (see Building search in‐
622 dexes).
623 The ratelimit option, an integer, controls the number of Web service
625 requests per second (default: 1). Do not change the rate limit setting
626 if you're using the main MusicBrainz server---on this public server,
627 you're limited to one request per second.
628 searchlimit
630 The number of matches returned when sending search queries to the Mu‐
631 sicBrainz server.
632 Default: 5.
634
636 You can configure some aspects of the logic beets uses when automati‐
637 cally matching MusicBrainz results under the match: section. To control
638 how tolerant the autotagger is of differences, use the
639 strong_rec_thresh option, which reflects the distance threshold below
640 which beets will make a "strong recommendation" that the metadata be
641 used. Strong recommendations are accepted automatically (except in
642 "timid" mode), so you can use this to make beets ask your opinion more
643 or less often.
644 The threshold is a distance value between 0.0 and 1.0, so you can think
646 of it as the opposite of a similarity value. For example, if you want
647 to automatically accept any matches above 90% similarity, use:
648 match:
650 strong_rec_thresh: 0.10
651 The default strong recommendation threshold is 0.04.
653 The medium_rec_thresh and rec_gap_thresh options work similarly. When a
655 match is below the medium recommendation threshold or the distance be‐
656 tween it and the next-best match is above the gap threshold, the im‐
657 porter will suggest that match but not automatically confirm it. Other‐
658 wise, you'll see a list of options to choose from.
659 max_rec
661 As mentioned above, autotagger matches have recommendations that con‐
662 trol how the UI behaves for a certain quality of match. The recommenda‐
663 tion for a certain match is based on the overall distance calculation.
664 But you can also control the recommendation when a specific distance
665 penalty is applied by defining maximum recommendations for each field:
666 To define maxima, use keys under max_rec: in the match section. The de‐
668 faults are "medium" for missing and unmatched tracks and "strong"
669 (i.e., no maximum) for everything else:
670 match:
672 max_rec:
673 missing_tracks: medium
674 unmatched_tracks: medium
675 If a recommendation is higher than the configured maximum and the indi‐
677 cated penalty is applied, the recommendation is downgraded. The setting
678 for each field can be one of none, low, medium or strong. When the max‐
679 imum recommendation is strong, no "downgrading" occurs. The available
680 penalty names here are:
681 • source
683 • artist
685 • album
687 • media
689 • mediums
691 • year
693 • country
695 • label
697 • catalognum
699 • albumdisambig
701 • album_id
703 • tracks
705 • missing_tracks
707 • unmatched_tracks
709 • track_title
711 • track_artist
713 • track_index
715 • track_length
717 • track_id
719 preferred
721 In addition to comparing the tagged metadata with the match metadata
722 for similarity, you can also specify an ordered list of preferred coun‐
723 tries and media types.
724 A distance penalty will be applied if the country or media type from
726 the match metadata doesn't match. The specified values are preferred in
727 descending order (i.e., the first item will be most preferred). Each
728 item may be a regular expression, and will be matched case insensi‐
729 tively. The number of media will be stripped when matching preferred
730 media (e.g. "2x" in "2xCD").
731 You can also tell the autotagger to prefer matches that have a release
733 year closest to the original year for an album.
734 Here's an example:
736 match:
738 preferred:
739 countries: ['US', 'GB|UK']
740 media: ['CD', 'Digital Media|File']
741 original_year: yes
742 By default, none of these options are enabled.
744 ignored
746 You can completely avoid matches that have certain penalties applied by
747 adding the penalty name to the ignored setting:
748 match:
750 ignored: missing_tracks unmatched_tracks
751 The available penalties are the same as those for the max_rec setting.
753 For example, setting ignored: missing_tracks will skip any album
755 matches where your audio files are missing some of the tracks. The im‐
756 porter will not attempt to display these matches. It does not ignore
757 the fact that the album is missing tracks, which would allow these
758 matches to apply more easily. To do that, you'll want to adjust the
759 penalty for missing tracks.
760 required
762 You can avoid matches that lack certain required information. Add the
763 tags you want to enforce to the required setting:
764 match:
766 required: year label catalognum country
767 No tags are required by default.
769 ignored_media
771 A list of media (i.e., formats) in metadata databases to ignore when
772 matching music. You can use this to ignore all media that usually con‐
773 tain video instead of audio, for example:
774 match:
776 ignored_media: ['Data CD', 'DVD', 'DVD-Video', 'Blu-ray', 'HD-DVD',
777 'VCD', 'SVCD', 'UMD', 'VHS']
778 No formats are ignored by default.
780 ignore_data_tracks
782 By default, audio files contained in data tracks within a release are
783 included in the album's tracklist. If you want them to be included, set
784 it no.
785 Default: yes.
787 ignore_video_tracks
789 By default, video tracks within a release will be ignored. If you want
790 them to be included (for example if you would like to track the au‐
791 dio-only versions of the video tracks), set it to no.
792 Default: yes.
794
796 You can also configure the directory hierarchy beets uses to store mu‐
797 sic. These settings appear under the paths: key. Each string is a tem‐
798 plate string that can refer to metadata fields like $artist or $title.
799 The filename extension is added automatically. At the moment, you can
800 specify three special paths: default for most releases, comp for "vari‐
801 ous artist" releases with no dominant artist, and singleton for non-al‐
802 bum tracks. The defaults look like this:
803 paths:
805 default: $albumartist/$album%aunique{}/$track $title
806 singleton: Non-Album/$artist/$title
807 comp: Compilations/$album%aunique{}/$track $title
808 Note the use of $albumartist instead of $artist; this ensures that al‐
810 bums will be well-organized. For more about these format strings, see
811 pathformat. The aunique{} function ensures that identically-named al‐
812 bums are placed in different directories; see aunique for details.
813 In addition to default, comp, and singleton, you can condition path
815 queries based on beets queries (see /reference/query). This means that
816 a config file like this:
817 paths:
819 albumtype:soundtrack: Soundtracks/$album/$track $title
820 will place soundtrack albums in a separate directory. The queries are
822 tested in the order they appear in the configuration file, meaning that
823 if an item matches multiple queries, beets will use the path format for
824 the first matching query.
825 Note that the special singleton and comp path format conditions are, in
827 fact, just shorthand for the explicit queries singleton:true and
828 comp:true. In contrast, default is special and has no query equivalent:
829 the default format is only used if no queries match.
830
832 The beets configuration file is usually located in a standard location
833 that depends on your OS, but there are a couple of ways you can tell
834 beets where to look.
835 Environment Variable
837 First, you can set the BEETSDIR environment variable to a directory
838 containing a config.yaml file. This replaces your configuration in the
839 default location. This also affects where auxiliary files, like the li‐
840 brary database, are stored by default (that's where relative paths are
841 resolved to). This environment variable is useful if you need to man‐
842 age multiple beets libraries with separate configurations.
843 Command-Line Option
845 Alternatively, you can use the --config command-line option to indicate
846 a YAML file containing options that will then be merged with your ex‐
847 isting options (from BEETSDIR or the default locations). This is useful
848 if you want to keep your configuration mostly the same but modify a few
849 options as a batch. For example, you might have different strategies
850 for importing files, each with a different set of importer options.
851 Default Location
853 In the absence of a BEETSDIR variable, beets searches a few places for
854 your configuration, depending on the platform:
855 • On Unix platforms, including OS X:~/.config/beets and then $XDG_CON‐
857 FIG_DIR/beets, if the environment variable is set.
858 • On OS X, we also search ~/Library/Application Support/beets before
860 the Unixy locations.
861 • On Windows: ~\AppData\Roaming\beets, and then %APPDATA%\beets, if the
863 environment variable is set.
864 Beets uses the first directory in your platform's list that contains
866 config.yaml. If no config file exists, the last path in the list is
867 used.
868
870 Here's an example file:
871 directory: /var/mp3
873 import:
874 copy: yes
875 write: yes
876 log: beetslog.txt
877 art_filename: albumart
878 plugins: bpd
879 pluginpath: ~/beets/myplugins
880 ui:
881 color: yes
882 paths:
884 default: $genre/$albumartist/$album/$track $title
885 singleton: Singletons/$artist - $title
886 comp: $genre/$album/$track $title
887 albumtype:soundtrack: Soundtracks/$album/$track $title
888
890 http://beets.readthedocs.org/
891 beet(1)
893
895 Adrian Sampson
896
898 2021, Adrian Sampson
8991.4 Jul 21, 2021 BEETSCONFIG(5)