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 command for details.) It is
23 also possible to customize the location of the configuration file and
24 even use multiple layers of configuration. See Configuration Location,
25 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 • path_sep_replace
63 • asciify_paths
65 • art_filename
67 • threaded
69 • format_item
71 • format_album
73 • sort_item
75 • sort_album
77 • sort_case_insensitive
79 • original_date
81 • artist_credit
83 • per_disc_numbering
85 • aunique
87 • terminal_encoding
89 • clutter
91 • max_filename_length
93 • id3v23
95 • va_name
97 • UI Options
99 • color
101 • colors
103 • Importer Options
105 • write
107 • copy
109 • move
111 • link
113 • hardlink
115 • reflink
117 • resume
119 • incremental
121 • incremental_skip_later
123 • from_scratch
125 • quiet
127 • quiet_fallback
129 • none_rec_action
131 • timid
133 • log
135 • default_action
137 • languages
139 • detail
141 • group_albums
143 • autotag
145 • duplicate_action
147 • bell
149 • set_fields
151 • MusicBrainz Options
153 • searchlimit
155 • extra_tags
157 • genres
159 • Autotagger Matching Options
161 • max_rec
163 • preferred
165 • ignored
167 • required
169 • ignored_media
171 • ignore_data_tracks
173 • ignore_video_tracks
175 • Path Format Configuration
177 • Configuration Location
179 • Environment Variable
181 • Command-Line Option
183 • Default Location
185 • Example
187
189 These options control beets' global operation.
190 library
192 Path to the beets library file. By default, beets will use a file
193 called library.db alongside your configuration file.
194 directory
196 The directory to which files will be copied/moved when adding them to
197 the library. Defaults to a folder called Music in your home directory.
198 plugins
200 A space-separated list of plugin module names to load. See Using Plug‐
201 ins.
202 include
204 A space-separated list of extra configuration files to include. File‐
205 names are relative to the directory containing config.yaml.
206 pluginpath
208 Directories to search for plugins. Each Python file or directory in a
209 plugin path represents a plugin and should define a subclass of Beet‐
210 sPlugin. A plugin can then be loaded by adding the filename to the
211 plugins configuration. The plugin path can either be a single string
212 or a list of strings---so, if you have multiple paths, format them as a
213 YAML list like so:
214 pluginpath:
216 - /path/one
217 - /path/two
218 ignore
220 A list of glob patterns specifying file and directory names to be ig‐
221 nored when importing. By default, this consists of .*, *~, System
222 Volume Information, lost+found (i.e., beets ignores Unix-style hidden
223 files, backup files, and directories that appears at the root of some
224 Linux and Windows filesystems).
225 ignore_hidden
227 Either yes or no; whether to ignore hidden files when importing. On
228 Windows, the "Hidden" property of files is used to detect whether or
229 not a file is hidden. On OS X, the file's "IsHidden" flag is used to
230 detect whether or not a file is hidden. On both OS X and other plat‐
231 forms (excluding Windows), files (and directories) starting with a dot
232 are detected as hidden files.
233 replace
235 A set of regular expression/replacement pairs to be applied to all
236 filenames created by beets. Typically, these replacements are used to
237 avoid confusing problems or errors with the filesystem (for example,
238 leading dots, which hide files on Unix, and trailing whitespace, which
239 is illegal on Windows). To override these substitutions, specify a map‐
240 ping from regular expression to replacement strings. For example, [xy]:
241 z will make beets replace all instances of the characters x or y with
242 the character z.
243 If you do change this value, be certain that you include at least
245 enough substitutions to avoid causing errors on your operating system.
246 Here are the default substitutions used by beets, which are sufficient
247 to avoid unexpected behavior on all popular platforms:
248 replace:
250 '[\\/]': _
251 '^\.': _
252 '[\x00-\x1f]': _
253 '[<>:"\?\*\|]': _
254 '\.$': _
255 '\s+$': ''
256 '^\s+': ''
257 '^-': _
258 These substitutions remove forward and back slashes, leading dots, and
260 control characters—all of which is a good idea on any OS. The fourth
261 line removes the Windows "reserved characters" (useful even on Unix for
262 for compatibility with Windows-influenced network filesystems like
263 Samba). Trailing dots and trailing whitespace, which can cause prob‐
264 lems on Windows clients, are also removed.
265 When replacements other than the defaults are used, it is possible that
267 they will increase the length of the path. In the scenario where this
268 leads to a conflict with the maximum filename length, the default re‐
269 placements will be used to resolve the conflict and beets will display
270 a warning.
271 Note that paths might contain special characters such as typographical
273 quotes (“”). With the configuration above, those will not be replaced
274 as they don't match the typewriter quote ("). To also strip these spe‐
275 cial characters, you can either add them to the replacement list or use
276 the asciify_paths configuration option below.
277 path_sep_replace
279 A string that replaces the path separator (for example, the forward
280 slash / on Linux and MacOS, and the backward slash \\ on Windows) when
281 generating filenames with beets. This option is related to replace,
282 but is distict from it for technical reasons.
283 WARNING:
285 Changing this option is potentially dangerous. For example, setting
286 it to the actual path separator could create directories in unex‐
287 pected locations. Use caution when changing it and always try it out
288 on a small number of files before applying it to your whole library.
289 Default: _.
291 asciify_paths
293 Convert all non-ASCII characters in paths to ASCII equivalents.
294 For example, if your path template for singletons is singletons/$title
296 and the title of a track is "Café", then the track will be saved as
297 singletons/Cafe.mp3. The changes take place before applying the
298 replace configuration and are roughly equivalent to wrapping all your
299 path templates in the %asciify{} template function.
300 This uses the unidecode module which is language agnostic, so some
302 characters may be transliterated from a different language than ex‐
303 pected. For example, Japanese kanji will usually use their Chinese
304 readings.
305 Default: no.
307 art_filename
309 When importing album art, the name of the file (without extension)
310 where the cover art image should be placed. This is a template string,
311 so you can use any of the syntax available to Path Formats. Defaults to
312 cover (i.e., images will be named cover.jpg or cover.png and placed in
313 the album's directory).
314 threaded
316 Either yes or no, indicating whether the autotagger should use multiple
317 threads. This makes things substantially faster by overlapping work:
318 for example, it can copy files for one album in parallel with looking
319 up data in MusicBrainz for a different album. You may want to disable
320 this when debugging problems with the autotagger. Defaults to yes.
321 format_item
323 Format to use when listing individual items with the list command and
324 other commands that need to print out items. Defaults to $artist - $al‐
325 bum - $title. The -f command-line option overrides this setting.
326 It used to be named list_format_item.
328 format_album
330 Format to use when listing albums with list and other commands. De‐
331 faults to $albumartist - $album. The -f command-line option overrides
332 this setting.
333 It used to be named list_format_album.
335 sort_item
337 Default sort order to use when fetching items from the database. De‐
338 faults to artist+ album+ disc+ track+. Explicit sort orders override
339 this default.
340 sort_album
342 Default sort order to use when fetching albums from the database. De‐
343 faults to albumartist+ album+. Explicit sort orders override this de‐
344 fault.
345 sort_case_insensitive
347 Either yes or no, indicating whether the case should be ignored when
348 sorting lexicographic fields. When set to no, lower-case values will be
349 placed after upper-case values (e.g., Bar Qux foo), while yes would re‐
350 sult in the more expected Bar foo Qux. Default: yes.
351 original_date
353 Either yes or no, indicating whether matched albums should have their
354 year, month, and day fields set to the release date of the original
355 version of an album rather than the selected version of the release.
356 That is, if this option is turned on, then year will always equal orig‐
357 inal_year and so on. Default: no.
358 artist_credit
360 Either yes or no, indicating whether matched tracks and albums should
361 use the artist credit, rather than the artist. That is, if this option
362 is turned on, then artist will contain the artist as credited on the
363 release.
364 per_disc_numbering
366 A boolean controlling the track numbering style on multi-disc releases.
367 By default (per_disc_numbering: no), tracks are numbered per-release,
368 so the first track on the second disc has track number N+1 where N is
369 the number of tracks on the first disc. If this per_disc_numbering is
370 enabled, then the first (non-pregap) track on each disc always has
371 track number 1.
372 If you enable per_disc_numbering, you will likely want to change your
374 Path Format Configuration also to include $disc before $track to make
375 filenames sort correctly in album directories. For example, you might
376 want to use a path format like this:
377 paths:
379 default: $albumartist/$album%aunique{}/$disc-$track $title
380 When this option is off (the default), even "pregap" hidden tracks are
382 numbered from one, not zero, so other track numbers may appear to be
383 bumped up by one. When it is on, the pregap track for each disc can be
384 numbered zero.
385 aunique
387 These options are used to generate a string that is guaranteed to be
388 unique among all albums in the library who share the same set of keys.
389 The defaults look like this:
391 aunique:
393 keys: albumartist album
394 disambiguators: albumtype year label catalognum albumdisambig releasegroupdisambig
395 bracket: '[]'
396 See Album Disambiguation for more details.
398 terminal_encoding
400 The text encoding, as known to Python, to use for messages printed to
401 the standard output. It's also used to read messages from the standard
402 input. By default, this is determined automatically from the locale
403 environment variables.
404 clutter
406 When beets imports all the files in a directory, it tries to remove the
407 directory if it's empty. A directory is considered empty if it only
408 contains files whose names match the glob patterns in clutter, which
409 should be a list of strings. The default list consists of "Thumbs.DB"
410 and ".DS_Store".
411 The importer only removes recursively searched subdirectories---the
413 top-level directory you specify on the command line is never deleted.
414 max_filename_length
416 Set the maximum number of characters in a filename, after which names
417 will be truncated. By default, beets tries to ask the filesystem for
418 the correct maximum.
419 id3v23
421 By default, beets writes MP3 tags using the ID3v2.4 standard, the lat‐
422 est version of ID3. Enable this option to instead use the older ID3v2.3
423 standard, which is preferred by certain older software such as Windows
424 Media Player.
425 va_name
427 Sets the albumartist for various-artist compilations. Defaults to 'Var‐
428 ious Artists' (the MusicBrainz standard). Affects other sources, such
429 as Discogs Plugin, too.
430
432 The options that allow for customization of the visual appearance of
433 the console interface.
434 These options are available in this section:
436 color
438 Either yes or no; whether to use color in console output (currently
439 only in the import command). Turn this off if your terminal doesn't
440 support ANSI colors.
441 NOTE:
443 The color option was previously a top-level configuration. This is
444 still respected, but a deprecation message will be shown until your
445 top-level color configuration has been nested under ui.
446 colors
448 The colors that are used throughout the user interface. These are only
449 used if the color option is set to yes. For example, you might have a
450 section in your configuration file that looks like this:
451 ui:
453 color: yes
454 colors:
455 text_success: green
456 text_warning: yellow
457 text_error: red
458 text_highlight: red
459 text_highlight_minor: lightgray
460 action_default: turquoise
461 action: blue
462 Available colors: black, darkred, darkgreen, brown (darkyellow), dark‐
464 blue, purple (darkmagenta), teal (darkcyan), lightgray, darkgray, red,
465 green, yellow, blue, fuchsia (magenta), turquoise (cyan), white
466
468 The options that control the import command are indented under the im‐
469 port: key. For example, you might have a section in your configuration
470 file that looks like this:
471 import:
473 write: yes
474 copy: yes
475 resume: no
476 These options are available in this section:
478 write
480 Either yes or no, controlling whether metadata (e.g., ID3) tags are
481 written to files when using beet import. Defaults to yes. The -w and -W
482 command-line options override this setting.
483 copy
485 Either yes or no, indicating whether to copy files into the library di‐
486 rectory when using beet import. Defaults to yes. Can be overridden
487 with the -c and -C command-line options.
488 The option is ignored if move is enabled (i.e., beets can move or copy
490 files but it doesn't make sense to do both).
491 move
493 Either yes or no, indicating whether to move files into the library di‐
494 rectory when using beet import. Defaults to no.
495 The effect is similar to the copy option but you end up with only one
497 copy of the imported file. ("Moving" works even across filesystems; if
498 necessary, beets will copy and then delete when a simple rename is im‐
499 possible.) Moving files can be risky—it's a good idea to keep a backup
500 in case beets doesn't do what you expect with your files.
501 This option overrides copy, so enabling it will always move (and not
503 copy) files. The -c switch to the beet import command, however, still
504 takes precedence.
505 link
507 Either yes or no, indicating whether to use symbolic links instead of
508 moving or copying files. (It conflicts with the move, copy and hardlink
509 options.) Defaults to no.
510 This option only works on platforms that support symbolic links: i.e.,
512 Unixes. It will fail on Windows.
513 It's likely that you'll also want to set write to no if you use this
515 option to preserve the metadata on the linked files.
516 hardlink
518 Either yes or no, indicating whether to use hard links instead of mov‐
519 ing, copying, or symlinking files. (It conflicts with the move, copy,
520 and link options.) Defaults to no.
521 As with symbolic links (see link, above), this will not work on Windows
523 and you will want to set write to no. Otherwise, metadata on the orig‐
524 inal file will be modified.
525 reflink
527 Either yes, no, or auto, indicating whether to use copy-on-write file
528 clones (a.k.a. "reflinks") instead of copying or moving files. The
529 auto option uses reflinks when possible and falls back to plain copying
530 when necessary. Defaults to no.
531 This kind of clone is only available on certain filesystems: for exam‐
533 ple, btrfs and APFS. For more details on filesystem support, see the
534 pyreflink documentation. Note that you need to install pyreflink, ei‐
535 ther through python -m pip install beets[reflink] or python -m pip in‐
536 stall reflink.
537 The option is ignored if move is enabled (i.e., beets can move or copy
539 files but it doesn't make sense to do both).
540 resume
542 Either yes, no, or ask. Controls whether interrupted imports should be
543 resumed. "Yes" means that imports are always resumed when possible;
544 "no" means resuming is disabled entirely; "ask" (the default) means
545 that the user should be prompted when resuming is possible. The -p and
546 -P flags correspond to the "yes" and "no" settings and override this
547 option.
548 incremental
550 Either yes or no, controlling whether imported directories are recorded
551 and whether these recorded directories are skipped. This corresponds
552 to the -i flag to beet import.
553 incremental_skip_later
555 Either yes or no, controlling whether skipped directories are recorded
556 in the incremental list. When set to yes, skipped directories won't be
557 recorded, and beets will try to import them again later. When set to
558 no, skipped directories will be recorded, and skipped later. Defaults
559 to no.
560 from_scratch
562 Either yes or no (default), controlling whether existing metadata is
563 discarded when a match is applied. This corresponds to the
564 --from_scratch flag to beet import.
565 quiet
567 Either yes or no (default), controlling whether to ask for a manual de‐
568 cision from the user when the importer is unsure how to proceed. This
569 corresponds to the --quiet flag to beet import.
570 quiet_fallback
572 Either skip (default) or asis, specifying what should happen in quiet
573 mode (see the -q flag to import, above) when there is no strong recom‐
574 mendation.
575 none_rec_action
577 Either ask (default), asis or skip. Specifies what should happen during
578 an interactive import session when there is no recommendation. Useful
579 when you are only interested in processing medium and strong recommen‐
580 dations interactively.
581 timid
583 Either yes or no, controlling whether the importer runs in timid mode,
584 in which it asks for confirmation on every autotagging match, even the
585 ones that seem very close. Defaults to no. The -t command-line flag
586 controls the same setting.
587 log
589 Specifies a filename where the importer's log should be kept. By de‐
590 fault, no log is written. This can be overridden with the -l flag to
591 import.
592 default_action
594 One of apply, skip, asis, or none, indicating which option should be
595 the default when selecting an action for a given match. This is the ac‐
596 tion that will be taken when you type return without an option letter.
597 The default is apply.
598 languages
600 A list of locale names to search for preferred aliases. For example,
601 setting this to en uses the transliterated artist name "Pyotr Ilyich
602 Tchaikovsky" instead of the Cyrillic script for the composer's name
603 when tagging from MusicBrainz. You can use a space-separated list of
604 language abbreviations, like en jp es, to specify a preference order.
605 Defaults to an empty list, meaning that no language is preferred.
606 detail
608 Whether the importer UI should show detailed information about each
609 match it finds. When enabled, this mode prints out the title of every
610 track, regardless of whether it matches the original metadata. (The de‐
611 fault behavior only shows changes.) Default: no.
612 group_albums
614 By default, the beets importer groups tracks into albums based on the
615 directories they reside in. This option instead uses files' metadata to
616 partition albums. Enable this option if you have directories that con‐
617 tain tracks from many albums mixed together.
618 The --group-albums or -g option to the import command is equivalent,
620 and the G interactive option invokes the same workflow.
621 Default: no.
623 autotag
625 By default, the beets importer always attempts to autotag new music. If
626 most of your collection consists of obscure music, you may be inter‐
627 ested in disabling autotagging by setting this option to no. (You can
628 re-enable it with the -a flag to the import command.)
629 Default: yes.
631 duplicate_action
633 Either skip, keep, remove, merge or ask. Controls how duplicates are
634 treated in import task. "skip" means that new item(album or track)
635 will be skipped; "keep" means keep both old and new items; "remove"
636 means remove old item; "merge" means merge into one album; "ask" means
637 the user should be prompted for the action each time. The default is
638 ask.
639 bell
641 Ring the terminal bell to get your attention when the importer needs
642 your input.
643 Default: no.
645 set_fields
647 A dictionary indicating fields to set to values for newly imported mu‐
648 sic. Here's an example:
649 set_fields:
651 genre: 'To Listen'
652 collection: 'Unordered'
653 Other field/value pairs supplied via the --set option on the com‐
655 mand-line override any settings here for fields with the same name.
656 Fields are set on both the album and each individual track of the al‐
658 bum. Fields are persisted to the media files of each track.
659 Default: {} (empty).
661
663 You can instruct beets to use your own MusicBrainz database instead of
664 the main server. Use the host, https and ratelimit options under a mu‐
665 sicbrainz: header, like so:
666 musicbrainz:
668 host: localhost:5000
669 https: no
670 ratelimit: 100
671 The host key, of course, controls the Web server hostname (and port,
673 optionally) that will be contacted by beets (default: musicbrainz.org).
674 The https key makes the client use HTTPS instead of HTTP. This setting
675 applies only to custom servers. The official MusicBrainz server always
676 uses HTTPS. (Default: no.) The server must have search indices enabled
677 (see Building search indexes).
678 The ratelimit option, an integer, controls the number of Web service
680 requests per second (default: 1). Do not change the rate limit setting
681 if you're using the main MusicBrainz server---on this public server,
682 you're limited to one request per second.
683 searchlimit
685 The number of matches returned when sending search queries to the Mu‐
686 sicBrainz server.
687 Default: 5.
689 extra_tags
691 By default, beets will use only the artist, album, and track count to
692 query MusicBrainz. Additional tags to be queried can be supplied with
693 the extra_tags setting. For example:
694 musicbrainz:
696 extra_tags: [year, catalognum, country, media, label]
697 This setting should improve the autotagger results if the metadata with
699 the given tags match the metadata returned by MusicBrainz.
700 Note that the only tags supported by this setting are the ones listed
702 in the above example.
703 Default: []
705 genres
707 Use MusicBrainz genre tags to populate (and replace if it's already
708 set) the genre tag. This will make it a list of all the genres tagged
709 for the release and the release-group on MusicBrainz, separated by "; "
710 and sorted by the total number of votes. Default: no
711
713 You can configure some aspects of the logic beets uses when automati‐
714 cally matching MusicBrainz results under the match: section. To control
715 how tolerant the autotagger is of differences, use the
716 strong_rec_thresh option, which reflects the distance threshold below
717 which beets will make a "strong recommendation" that the metadata be
718 used. Strong recommendations are accepted automatically (except in
719 "timid" mode), so you can use this to make beets ask your opinion more
720 or less often.
721 The threshold is a distance value between 0.0 and 1.0, so you can think
723 of it as the opposite of a similarity value. For example, if you want
724 to automatically accept any matches above 90% similarity, use:
725 match:
727 strong_rec_thresh: 0.10
728 The default strong recommendation threshold is 0.04.
730 The medium_rec_thresh and rec_gap_thresh options work similarly. When a
732 match is below the medium recommendation threshold or the distance be‐
733 tween it and the next-best match is above the gap threshold, the im‐
734 porter will suggest that match but not automatically confirm it. Other‐
735 wise, you'll see a list of options to choose from.
736 max_rec
738 As mentioned above, autotagger matches have recommendations that con‐
739 trol how the UI behaves for a certain quality of match. The recommenda‐
740 tion for a certain match is based on the overall distance calculation.
741 But you can also control the recommendation when a specific distance
742 penalty is applied by defining maximum recommendations for each field:
743 To define maxima, use keys under max_rec: in the match section. The de‐
745 faults are "medium" for missing and unmatched tracks and "strong"
746 (i.e., no maximum) for everything else:
747 match:
749 max_rec:
750 missing_tracks: medium
751 unmatched_tracks: medium
752 If a recommendation is higher than the configured maximum and the indi‐
754 cated penalty is applied, the recommendation is downgraded. The setting
755 for each field can be one of none, low, medium or strong. When the max‐
756 imum recommendation is strong, no "downgrading" occurs. The available
757 penalty names here are:
758 • source
760 • artist
762 • album
764 • media
766 • mediums
768 • year
770 • country
772 • label
774 • catalognum
776 • albumdisambig
778 • album_id
780 • tracks
782 • missing_tracks
784 • unmatched_tracks
786 • track_title
788 • track_artist
790 • track_index
792 • track_length
794 • track_id
796 preferred
798 In addition to comparing the tagged metadata with the match metadata
799 for similarity, you can also specify an ordered list of preferred coun‐
800 tries and media types.
801 A distance penalty will be applied if the country or media type from
803 the match metadata doesn't match. The specified values are preferred in
804 descending order (i.e., the first item will be most preferred). Each
805 item may be a regular expression, and will be matched case insensi‐
806 tively. The number of media will be stripped when matching preferred
807 media (e.g. "2x" in "2xCD").
808 You can also tell the autotagger to prefer matches that have a release
810 year closest to the original year for an album.
811 Here's an example:
813 match:
815 preferred:
816 countries: ['US', 'GB|UK']
817 media: ['CD', 'Digital Media|File']
818 original_year: yes
819 By default, none of these options are enabled.
821 ignored
823 You can completely avoid matches that have certain penalties applied by
824 adding the penalty name to the ignored setting:
825 match:
827 ignored: missing_tracks unmatched_tracks
828 The available penalties are the same as those for the max_rec setting.
830 For example, setting ignored: missing_tracks will skip any album
832 matches where your audio files are missing some of the tracks. The im‐
833 porter will not attempt to display these matches. It does not ignore
834 the fact that the album is missing tracks, which would allow these
835 matches to apply more easily. To do that, you'll want to adjust the
836 penalty for missing tracks.
837 required
839 You can avoid matches that lack certain required information. Add the
840 tags you want to enforce to the required setting:
841 match:
843 required: year label catalognum country
844 No tags are required by default.
846 ignored_media
848 A list of media (i.e., formats) in metadata databases to ignore when
849 matching music. You can use this to ignore all media that usually con‐
850 tain video instead of audio, for example:
851 match:
853 ignored_media: ['Data CD', 'DVD', 'DVD-Video', 'Blu-ray', 'HD-DVD',
854 'VCD', 'SVCD', 'UMD', 'VHS']
855 No formats are ignored by default.
857 ignore_data_tracks
859 By default, audio files contained in data tracks within a release are
860 included in the album's tracklist. If you want them to be included, set
861 it no.
862 Default: yes.
864 ignore_video_tracks
866 By default, video tracks within a release will be ignored. If you want
867 them to be included (for example if you would like to track the au‐
868 dio-only versions of the video tracks), set it to no.
869 Default: yes.
871
873 You can also configure the directory hierarchy beets uses to store mu‐
874 sic. These settings appear under the paths: key. Each string is a tem‐
875 plate string that can refer to metadata fields like $artist or $title.
876 The filename extension is added automatically. At the moment, you can
877 specify three special paths: default for most releases, comp for "vari‐
878 ous artist" releases with no dominant artist, and singleton for non-al‐
879 bum tracks. The defaults look like this:
880 paths:
882 default: $albumartist/$album%aunique{}/$track $title
883 singleton: Non-Album/$artist/$title
884 comp: Compilations/$album%aunique{}/$track $title
885 Note the use of $albumartist instead of $artist; this ensures that al‐
887 bums will be well-organized. For more about these format strings, see
888 Path Formats. The aunique{} function ensures that identically-named al‐
889 bums are placed in different directories; see Album Disambiguation for
890 details.
891 In addition to default, comp, and singleton, you can condition path
893 queries based on beets queries (see Queries). This means that a config
894 file like this:
895 paths:
897 albumtype:soundtrack: Soundtracks/$album/$track $title
898 will place soundtrack albums in a separate directory. The queries are
900 tested in the order they appear in the configuration file, meaning that
901 if an item matches multiple queries, beets will use the path format for
902 the first matching query.
903 Note that the special singleton and comp path format conditions are, in
905 fact, just shorthand for the explicit queries singleton:true and
906 comp:true. In contrast, default is special and has no query equivalent:
907 the default format is only used if no queries match.
908
910 The beets configuration file is usually located in a standard location
911 that depends on your OS, but there are a couple of ways you can tell
912 beets where to look.
913 Environment Variable
915 First, you can set the BEETSDIR environment variable to a directory
916 containing a config.yaml file. This replaces your configuration in the
917 default location. This also affects where auxiliary files, like the li‐
918 brary database, are stored by default (that's where relative paths are
919 resolved to). This environment variable is useful if you need to man‐
920 age multiple beets libraries with separate configurations.
921 Command-Line Option
923 Alternatively, you can use the --config command-line option to indicate
924 a YAML file containing options that will then be merged with your ex‐
925 isting options (from BEETSDIR or the default locations). This is useful
926 if you want to keep your configuration mostly the same but modify a few
927 options as a batch. For example, you might have different strategies
928 for importing files, each with a different set of importer options.
929 Default Location
931 In the absence of a BEETSDIR variable, beets searches a few places for
932 your configuration, depending on the platform:
933 • On Unix platforms, including OS X:~/.config/beets and then $XDG_CON‐
935 FIG_DIR/beets, if the environment variable is set.
936 • On OS X, we also search ~/Library/Application Support/beets before
938 the Unixy locations.
939 • On Windows: ~\AppData\Roaming\beets, and then %APPDATA%\beets, if the
941 environment variable is set.
942 Beets uses the first directory in your platform's list that contains
944 config.yaml. If no config file exists, the last path in the list is
945 used.
946
948 Here's an example file:
949 directory: /var/mp3
951 import:
952 copy: yes
953 write: yes
954 log: beetslog.txt
955 art_filename: albumart
956 plugins: bpd
957 pluginpath: ~/beets/myplugins
958 ui:
959 color: yes
960 paths:
962 default: $genre/$albumartist/$album/$track $title
963 singleton: Singletons/$artist - $title
964 comp: $genre/$album/$track $title
965 albumtype:soundtrack: Soundtracks/$album/$track $title
966
968 https://beets.readthedocs.org/
969 beet(1)
971
973 Adrian Sampson
974
976 2023, Adrian Sampson
9771.6 Jul 19, 2023 BEETSCONFIG(5)