1BEETSCONFIG(5)                       beets                      BEETSCONFIG(5)
2
3
4

NAME

6       beetsconfig - beets configuration file
7
8       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
13       • On Unix-like OSes, write ~/.config/beets/config.yaml.
14
15       • On Windows, use %APPDATA%\beets\config.yaml. This is usually in a di‐
16         rectory like C:\Users\You\AppData\Roaming.
17
18       • On  OS  X, you can use either the Unix location or ~/Library/Applica‐
19         tion Support/beets/config.yaml.
20
21       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
27       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
31          option: value
32          another_option: foo
33          bigger_option:
34              key: value
35              foo: bar
36
37       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
41       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
44Global Options
45
46library
47
48directory
49
50plugins
51
52include
53
54pluginpath
55
56ignore
57
58ignore_hidden
59
60replace
61
62path_sep_replace
63
64asciify_paths
65
66art_filename
67
68threaded
69
70format_item
71
72format_album
73
74sort_item
75
76sort_album
77
78sort_case_insensitive
79
80original_date
81
82artist_credit
83
84per_disc_numbering
85
86aunique
87
88terminal_encoding
89
90clutter
91
92max_filename_length
93
94id3v23
95
96va_name
97
98UI Options
99
100color
101
102colors
103
104Importer Options
105
106write
107
108copy
109
110move
111
112link
113
114hardlink
115
116reflink
117
118resume
119
120incremental
121
122incremental_skip_later
123
124from_scratch
125
126quiet
127
128quiet_fallback
129
130none_rec_action
131
132timid
133
134log
135
136default_action
137
138languages
139
140detail
141
142group_albums
143
144autotag
145
146duplicate_action
147
148bell
149
150set_fields
151
152MusicBrainz Options
153
154searchlimit
155
156extra_tags
157
158genres
159
160Autotagger Matching Options
161
162max_rec
163
164preferred
165
166ignored
167
168required
169
170ignored_media
171
172ignore_data_tracks
173
174ignore_video_tracks
175
176Path Format Configuration
177
178Configuration Location
179
180Environment Variable
181
182Command-Line Option
183
184Default Location
185
186Example
187

GLOBAL OPTIONS

189       These options control beets' global operation.
190
191   library
192       Path  to  the  beets  library  file.  By default, beets will use a file
193       called library.db alongside your configuration file.
194
195   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
199   plugins
200       A  space-separated list of plugin module names to load. See Using Plug‐
201       ins.
202
203   include
204       A space-separated list of extra configuration files to include.   File‐
205       names are relative to the directory containing config.yaml.
206
207   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
215          pluginpath:
216              - /path/one
217              - /path/two
218
219   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
226   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
234   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
244       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
249          replace:
250              '[\\/]': _
251              '^\.': _
252              '[\x00-\x1f]': _
253              '[<>:"\?\*\|]': _
254              '\.$': _
255              '\s+$': ''
256              '^\s+': ''
257              '^-': _
258
259       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
266       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
272       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
278   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
284       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
290       Default: _.
291
292   asciify_paths
293       Convert all non-ASCII characters in paths to ASCII equivalents.
294
295       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
301       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
306       Default: no.
307
308   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
315   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
322   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
327       It used to be named list_format_item.
328
329   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
334       It used to be named list_format_album.
335
336   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
341   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
346   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
352   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
359   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
365   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
373       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
378          paths:
379              default: $albumartist/$album%aunique{}/$disc-$track $title
380
381       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
386   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
390       The defaults look like this:
391
392          aunique:
393              keys: albumartist album
394              disambiguators: albumtype year label catalognum albumdisambig releasegroupdisambig
395              bracket: '[]'
396
397       See Album Disambiguation for more details.
398
399   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
405   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
412       The importer only  removes  recursively  searched  subdirectories---the
413       top-level directory you specify on the command line is never deleted.
414
415   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
420   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
426   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

UI OPTIONS

432       The options that allow for customization of the  visual  appearance  of
433       the console interface.
434
435       These options are available in this section:
436
437   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
442       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
447   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
452          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
463       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

IMPORTER OPTIONS

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
472          import:
473              write: yes
474              copy: yes
475              resume: no
476
477       These options are available in this section:
478
479   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
484   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
489       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
492   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
496       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
502       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
506   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
511       This  option only works on platforms that support symbolic links: i.e.,
512       Unixes.  It will fail on Windows.
513
514       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
517   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
522       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
526   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
532       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
538       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
541   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
549   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
554   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
561   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
566   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
571   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
576   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
582   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
588   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
593   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
599   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
607   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
613   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
619       The --group-albums or -g option to the import  command  is  equivalent,
620       and the G interactive option invokes the same workflow.
621
622       Default: no.
623
624   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
630       Default: yes.
631
632   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
640   bell
641       Ring  the  terminal  bell to get your attention when the importer needs
642       your input.
643
644       Default: no.
645
646   set_fields
647       A dictionary indicating fields to set to values for newly imported  mu‐
648       sic.  Here's an example:
649
650          set_fields:
651              genre: 'To Listen'
652              collection: 'Unordered'
653
654       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
657       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
660       Default: {} (empty).
661

MUSICBRAINZ OPTIONS

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
667          musicbrainz:
668              host: localhost:5000
669              https: no
670              ratelimit: 100
671
672       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
679       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
684   searchlimit
685       The  number  of matches returned when sending search queries to the Mu‐
686       sicBrainz server.
687
688       Default: 5.
689
690   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
695          musicbrainz:
696              extra_tags: [year, catalognum, country, media, label]
697
698       This setting should improve the autotagger results if the metadata with
699       the given tags match the metadata returned by MusicBrainz.
700
701       Note  that  the only tags supported by this setting are the ones listed
702       in the above example.
703
704       Default: []
705
706   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

AUTOTAGGER MATCHING OPTIONS

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
722       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
726          match:
727              strong_rec_thresh: 0.10
728
729       The default strong recommendation threshold is 0.04.
730
731       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
737   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
744       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
748          match:
749              max_rec:
750                  missing_tracks: medium
751                  unmatched_tracks: medium
752
753       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
759       • source
760
761       • artist
762
763       • album
764
765       • media
766
767       • mediums
768
769       • year
770
771       • country
772
773       • label
774
775       • catalognum
776
777       • albumdisambig
778
779       • album_id
780
781       • tracks
782
783       • missing_tracks
784
785       • unmatched_tracks
786
787       • track_title
788
789       • track_artist
790
791       • track_index
792
793       • track_length
794
795       • track_id
796
797   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
802       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
809       You  can also tell the autotagger to prefer matches that have a release
810       year closest to the original year for an album.
811
812       Here's an example:
813
814          match:
815              preferred:
816                  countries: ['US', 'GB|UK']
817                  media: ['CD', 'Digital Media|File']
818                  original_year: yes
819
820       By default, none of these options are enabled.
821
822   ignored
823       You can completely avoid matches that have certain penalties applied by
824       adding the penalty name to the ignored setting:
825
826          match:
827              ignored: missing_tracks unmatched_tracks
828
829       The available penalties are the same as those for the max_rec setting.
830
831       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
838   required
839       You can avoid matches that lack certain required information.  Add  the
840       tags you want to enforce to the required setting:
841
842          match:
843              required: year label catalognum country
844
845       No tags are required by default.
846
847   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
852          match:
853              ignored_media: ['Data CD', 'DVD', 'DVD-Video', 'Blu-ray', 'HD-DVD',
854                              'VCD', 'SVCD', 'UMD', 'VHS']
855
856       No formats are ignored by default.
857
858   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
863       Default: yes.
864
865   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
870       Default: yes.
871

PATH FORMAT CONFIGURATION

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
881          paths:
882              default: $albumartist/$album%aunique{}/$track $title
883              singleton: Non-Album/$artist/$title
884              comp: Compilations/$album%aunique{}/$track $title
885
886       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
892       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
896          paths:
897              albumtype:soundtrack: Soundtracks/$album/$track $title
898
899       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
904       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

CONFIGURATION LOCATION

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
914   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
922   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
930   Default Location
931       In  the absence of a BEETSDIR variable, beets searches a few places for
932       your configuration, depending on the platform:
933
934       • On Unix platforms, including OS X:~/.config/beets and then  $XDG_CON‐
935         FIG_DIR/beets, if the environment variable is set.
936
937       • On  OS  X,  we also search ~/Library/Application Support/beets before
938         the Unixy locations.
939
940       • On Windows: ~\AppData\Roaming\beets, and then %APPDATA%\beets, if the
941         environment variable is set.
942
943       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

EXAMPLE

948       Here's an example file:
949
950          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
961          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

SEE ALSO

968       https://beets.readthedocs.org/
969
970       beet(1)
971

AUTHOR

973       Adrian Sampson
974
976       2022, Adrian Sampson
977
978
979
980
9811.6                              Aug 15, 2022                   BEETSCONFIG(5)
Impressum