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-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
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
62asciify_paths
63
64art_filename
65
66threaded
67
68format_item
69
70format_album
71
72sort_item
73
74sort_album
75
76sort_case_insensitive
77
78original_date
79
80artist_credit
81
82per_disc_numbering
83
84aunique
85
86terminal_encoding
87
88clutter
89
90max_filename_length
91
92id3v23
93
94va_name
95
96UI Options
97
98color
99
100colors
101
102Importer Options
103
104write
105
106copy
107
108move
109
110link
111
112hardlink
113
114resume
115
116incremental
117
118incremental_skip_later
119
120from_scratch
121
122quiet_fallback
123
124none_rec_action
125
126timid
127
128log
129
130default_action
131
132languages
133
134detail
135
136group_albums
137
138autotag
139
140duplicate_action
141
142bell
143
144set_fields
145
146MusicBrainz Options
147
148searchlimit
149
150Autotagger Matching Options
151
152max_rec
153
154preferred
155
156ignored
157
158required
159
160ignored_media
161
162ignore_data_tracks
163
164ignore_video_tracks
165
166Path Format Configuration
167
168Configuration Location
169
170Environment Variable
171
172Command-Line Option
173
174Default Location
175
176Example
177

GLOBAL OPTIONS

179       These options control beets' global operation.
180
181   library
182       Path  to  the  beets  library  file.  By default, beets will use a file
183       called library.db alongside your configuration file.
184
185   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
189   plugins
190       A  space-separated list of plugin module names to load. See using-plug‐
191       ins.
192
193   include
194       A space-separated list of extra configuration files to include.   File‐
195       names are relative to the directory containing config.yaml.
196
197   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
205          pluginpath:
206              - /path/one
207              - /path/two
208
209   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
216   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
224   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
234       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
239          replace:
240              '[\\/]': _
241              '^\.': _
242              '[\x00-\x1f]': _
243              '[<>:"\?\*\|]': _
244              '\.$': _
245              '\s+$': ''
246              '^\s+': ''
247              '^-': _
248
249       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
256       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
262       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
268   asciify_paths
269       Convert all non-ASCII characters in paths to ASCII equivalents.
270
271       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
277       Default: no.
278
279   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
286   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
293   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
298       It used to be named list_format_item.
299
300   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
305       It used to be named list_format_album.
306
307   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
312   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
317   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
323   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
330   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
336   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
344       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
349          paths:
350              default: $albumartist/$album%aunique{}/$disc-$track $title
351
352       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
357   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
361       The defaults look like this:
362
363          aunique:
364              keys: albumartist album
365              disambiguators: albumtype year label catalognum albumdisambig releasegroupdisambig
366              bracket: '[]'
367
368       See aunique for more details.
369
370   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
376   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
383       The  importer  only  removes  recursively searched subdirectories---the
384       top-level directory you specify on the command line is never deleted.
385
386   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
391   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
397   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

UI OPTIONS

403       The  options  that  allow for customization of the visual appearance of
404       the console interface.
405
406       These options are available in this section:
407
408   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
413       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
418   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
423          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
434       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

IMPORTER OPTIONS

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
443          import:
444              write: yes
445              copy: yes
446              resume: no
447
448       These options are available in this section:
449
450   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
455   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
460       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
463   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
467       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
473       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
477   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
482       This option only works on platforms that support symbolic links:  i.e.,
483       Unixes.  It will fail on Windows.
484
485       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
488   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
493       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
497   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
505   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
510   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
517   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
522   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
527   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
533   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
539   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
544   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
550   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
558   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
564   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
570       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
573       Default: no.
574
575   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
581       Default: yes.
582
583   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
591   bell
592       Ring the terminal bell to get your attention when  the  importer  needs
593       your input.
594
595       Default: no.
596
597   set_fields
598       A  dictionary indicating fields to set to values for newly imported mu‐
599       sic.  Here's an example:
600
601          set_fields:
602              genre: 'To Listen'
603              collection: 'Unordered'
604
605       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
608       Default: {} (empty).
609

MUSICBRAINZ OPTIONS

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
615          musicbrainz:
616              host: localhost:5000
617              ratelimit: 100
618
619       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
624       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
629   searchlimit
630       The  number  of matches returned when sending search queries to the Mu‐
631       sicBrainz server.
632
633       Default: 5.
634

AUTOTAGGER MATCHING OPTIONS

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
645       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
649          match:
650              strong_rec_thresh: 0.10
651
652       The default strong recommendation threshold is 0.04.
653
654       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
660   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
667       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
671          match:
672              max_rec:
673                  missing_tracks: medium
674                  unmatched_tracks: medium
675
676       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
682       • source
683
684       • artist
685
686       • album
687
688       • media
689
690       • mediums
691
692       • year
693
694       • country
695
696       • label
697
698       • catalognum
699
700       • albumdisambig
701
702       • album_id
703
704       • tracks
705
706       • missing_tracks
707
708       • unmatched_tracks
709
710       • track_title
711
712       • track_artist
713
714       • track_index
715
716       • track_length
717
718       • track_id
719
720   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
725       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
732       You can also tell the autotagger to prefer matches that have a  release
733       year closest to the original year for an album.
734
735       Here's an example:
736
737          match:
738              preferred:
739                  countries: ['US', 'GB|UK']
740                  media: ['CD', 'Digital Media|File']
741                  original_year: yes
742
743       By default, none of these options are enabled.
744
745   ignored
746       You can completely avoid matches that have certain penalties applied by
747       adding the penalty name to the ignored setting:
748
749          match:
750              ignored: missing_tracks unmatched_tracks
751
752       The available penalties are the same as those for the max_rec setting.
753
754       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
761   required
762       You  can  avoid matches that lack certain required information. Add the
763       tags you want to enforce to the required setting:
764
765          match:
766              required: year label catalognum country
767
768       No tags are required by default.
769
770   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
775          match:
776              ignored_media: ['Data CD', 'DVD', 'DVD-Video', 'Blu-ray', 'HD-DVD',
777                              'VCD', 'SVCD', 'UMD', 'VHS']
778
779       No formats are ignored by default.
780
781   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
786       Default: yes.
787
788   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
793       Default: yes.
794

PATH FORMAT CONFIGURATION

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
804          paths:
805              default: $albumartist/$album%aunique{}/$track $title
806              singleton: Non-Album/$artist/$title
807              comp: Compilations/$album%aunique{}/$track $title
808
809       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
814       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
818          paths:
819              albumtype:soundtrack: Soundtracks/$album/$track $title
820
821       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
826       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

CONFIGURATION LOCATION

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
836   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
844   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
852   Default Location
853       In  the absence of a BEETSDIR variable, beets searches a few places for
854       your configuration, depending on the platform:
855
856       • On Unix platforms, including OS X:~/.config/beets and then  $XDG_CON‐
857         FIG_DIR/beets, if the environment variable is set.
858
859       • On  OS  X,  we also search ~/Library/Application Support/beets before
860         the Unixy locations.
861
862       • On Windows: ~\AppData\Roaming\beets, and then %APPDATA%\beets, if the
863         environment variable is set.
864
865       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

EXAMPLE

870       Here's an example file:
871
872          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
883          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

SEE ALSO

890       http://beets.readthedocs.org/
891
892       beet(1)
893

AUTHOR

895       Adrian Sampson
896
898       2021, Adrian Sampson
899
900
901
902
9031.4                              Jul 21, 2021                   BEETSCONFIG(5)
Impressum