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

GLOBAL OPTIONS

175       These options control beets' global operation.
176
177   library
178       Path  to  the  beets  library  file.  By default, beets will use a file
179       called library.db alongside your configuration file.
180
181   directory
182       The directory to which files will be copied/moved when adding  them  to
183       the library. Defaults to a folder called Music in your home directory.
184
185   plugins
186       A  space-separated list of plugin module names to load. See using-plug‐
187       ins.
188
189   include
190       A space-separated list of extra configuration files to include.   File‐
191       names are relative to the directory containing config.yaml.
192
193   pluginpath
194       Directories  to search for plugins.  Each Python file or directory in a
195       plugin path represents a plugin and should define a subclass  of  Beet‐
196       sPlugin.   A  plugin  can  then be loaded by adding the filename to the
197       plugins configuration.  The plugin path can either be a  single  string
198       or a list of strings---so, if you have multiple paths, format them as a
199       YAML list like so:
200
201          pluginpath:
202              - /path/one
203              - /path/two
204
205   ignore
206       A list of glob patterns specifying  file  and  directory  names  to  be
207       ignored  when  importing. By default, this consists of .*,  *~,  System
208       Volume Information, lost+found (i.e., beets ignores  Unix-style  hidden
209       files,  backup  files, and directories that appears at the root of some
210       Linux and Windows filesystems).
211
212   ignore_hidden
213       Either yes or no; whether to ignore hidden  files  when  importing.  On
214       Windows,  the  "Hidden"  property of files is used to detect whether or
215       not a file is hidden. On OS X, the file's "IsHidden" flag  is  used  to
216       detect  whether  or  not a file is hidden. On both OS X and other plat‐
217       forms (excluding Windows), files (and directories) starting with a  dot
218       are detected as hidden files.
219
220   replace
221       A  set  of  regular  expression/replacement  pairs to be applied to all
222       filenames created by beets. Typically, these replacements are  used  to
223       avoid  confusing  problems  or errors with the filesystem (for example,
224       leading dots, which hide files on Unix, and trailing whitespace,  which
225       is illegal on Windows). To override these substitutions, specify a map‐
226       ping from regular expression to replacement strings. For example, [xy]:
227       z  will  make beets replace all instances of the characters x or y with
228       the character z.
229
230       If you do change this value, be  certain  that  you  include  at  least
231       enough  substitutions to avoid causing errors on your operating system.
232       Here are the default substitutions used by beets, which are  sufficient
233       to avoid unexpected behavior on all popular platforms:
234
235          replace:
236              '[\\/]': _
237              '^\.': _
238              '[\x00-\x1f]': _
239              '[<>:"\?\*\|]': _
240              '\.$': _
241              '\s+$': ''
242              '^\s+': ''
243              '^-': _
244
245       These  substitutions remove forward and back slashes, leading dots, and
246       control characters—all of which is a good idea on any  OS.  The  fourth
247       line removes the Windows "reserved characters" (useful even on Unix for
248       for compatibility  with  Windows-influenced  network  filesystems  like
249       Samba).   Trailing  dots and trailing whitespace, which can cause prob‐
250       lems on Windows clients, are also removed.
251
252       When replacements other than the defaults are used, it is possible that
253       they  will  increase the length of the path. In the scenario where this
254       leads to a conflict with  the  maximum  filename  length,  the  default
255       replacements  will  be used to resolve the conflict and beets will dis‐
256       play a warning.
257
258       Note that paths might contain special characters such as  typographical
259       quotes  (“”).  With the configuration above, those will not be replaced
260       as they don't match the typewriter quote ("). To also strip these  spe‐
261       cial characters, you can either add them to the replacement list or use
262       the asciify_paths configuration option below.
263
264   asciify_paths
265       Convert all non-ASCII characters in paths to ASCII equivalents.
266
267       For example, if your path template for singletons is  singletons/$title
268       and  the  title  of  a track is "Café", then the track will be saved as
269       singletons/Cafe.mp3.   The  changes  take  place  before  applying  the
270       replace  configuration  and are roughly equivalent to wrapping all your
271       path templates in the %asciify{} template function.
272
273       Default: no.
274
275   art_filename
276       When importing album art, the name  of  the  file  (without  extension)
277       where  the cover art image should be placed. This is a template string,
278       so you can use any of the syntax  available  to  /reference/pathformat.
279       Defaults  to  cover  (i.e., images will be named cover.jpg or cover.png
280       and placed in the album's directory).
281
282   threaded
283       Either yes or no, indicating whether the autotagger should use multiple
284       threads.  This  makes  things substantially faster by overlapping work:
285       for example, it can copy files for one album in parallel  with  looking
286       up  data  in MusicBrainz for a different album. You may want to disable
287       this when debugging problems with the autotagger.  Defaults to yes.
288
289   format_item
290       Format to use when listing individual items with the  list-cmd  command
291       and  other commands that need to print out items. Defaults to $artist -
292       $album - $title. The -f command-line option overrides this setting.
293
294       It used to be named list_format_item.
295
296   format_album
297       Format to use when listing albums with  list-cmd  and  other  commands.
298       Defaults to $albumartist - $album. The -f command-line option overrides
299       this setting.
300
301       It used to be named list_format_album.
302
303   sort_item
304       Default sort order to  use  when  fetching  items  from  the  database.
305       Defaults  to artist+ album+ disc+ track+. Explicit sort orders override
306       this default.
307
308   sort_album
309       Default sort order to use  when  fetching  albums  from  the  database.
310       Defaults  to  albumartist+  album+.  Explicit sort orders override this
311       default.
312
313   sort_case_insensitive
314       Either yes or no, indicating whether the case should  be  ignored  when
315       sorting lexicographic fields. When set to no, lower-case values will be
316       placed after upper-case values (e.g., Bar Qux  foo),  while  yes  would
317       result in the more expected Bar foo Qux. Default: yes.
318
319   original_date
320       Either  yes  or no, indicating whether matched albums should have their
321       year, month, and day fields set to the release  date  of  the  original
322       version  of  an  album rather than the selected version of the release.
323       That is, if this option is turned on, then year will always equal orig‐
324       inal_year and so on. Default: no.
325
326   artist_credit
327       Either  yes  or no, indicating whether matched tracks and albums should
328       use the artist credit, rather than the artist. That is, if this  option
329       is  turned  on,  then artist will contain the artist as credited on the
330       release.
331
332   per_disc_numbering
333       A boolean controlling the track numbering style on multi-disc releases.
334       By  default  (per_disc_numbering: no), tracks are numbered per-release,
335       so the first track on the second disc has track number N+1 where  N  is
336       the  number  of tracks on the first disc. If this per_disc_numbering is
337       enabled, then the first (non-pregap) track  on  each  disc  always  has
338       track number 1.
339
340       If  you  enable per_disc_numbering, you will likely want to change your
341       Path Format Configuration also to include $disc before $track  to  make
342       filenames  sort  correctly in album directories. For example, you might
343       want to use a path format like this:
344
345          paths:
346              default: $albumartist/$album%aunique{}/$disc-$track $title
347
348       When this option is off (the default), even "pregap" hidden tracks  are
349       numbered  from  one,  not zero, so other track numbers may appear to be
350       bumped up by one. When it is on, the pregap track for each disc can  be
351       numbered zero.
352
353   terminal_encoding
354       The  text  encoding, as known to Python, to use for messages printed to
355       the standard output. It's also used to read messages from the  standard
356       input.   By  default,  this is determined automatically from the locale
357       environment variables.
358
359   clutter
360       When beets imports all the files in a directory, it tries to remove the
361       directory  if  it's  empty.  A directory is considered empty if it only
362       contains files whose names match the glob patterns  in  clutter,  which
363       should  be  a list of strings. The default list consists of "Thumbs.DB"
364       and ".DS_Store".
365
366       The importer only  removes  recursively  searched  subdirectories---the
367       top-level directory you specify on the command line is never deleted.
368
369   max_filename_length
370       Set  the  maximum number of characters in a filename, after which names
371       will be truncated. By default, beets tries to ask  the  filesystem  for
372       the correct maximum.
373
374   id3v23
375       By  default, beets writes MP3 tags using the ID3v2.4 standard, the lat‐
376       est version of ID3. Enable this option to instead use the older ID3v2.3
377       standard,  which is preferred by certain older software such as Windows
378       Media Player.
379
380   va_name
381       Sets the albumartist for various-artist compilations. Defaults to 'Var‐
382       ious  Artists'  (the MusicBrainz standard). Affects other sources, such
383       as /plugins/discogs, too.
384

UI OPTIONS

386       The options that allow for customization of the  visual  appearance  of
387       the console interface.
388
389       These options are available in this section:
390
391   color
392       Either  yes  or  no;  whether to use color in console output (currently
393       only in the import command). Turn this off  if  your  terminal  doesn't
394       support ANSI colors.
395
396       NOTE:
397          The  color  option was previously a top-level configuration. This is
398          still respected, but a deprecation message will be shown until  your
399          top-level color configuration has been nested under ui.
400
401   colors
402       The  colors that are used throughout the user interface. These are only
403       used if the color option is set to yes. For example, you might  have  a
404       section in your configuration file that looks like this:
405
406          ui:
407              color: yes
408              colors:
409                  text_success: green
410                  text_warning: yellow
411                  text_error: red
412                  text_highlight: red
413                  text_highlight_minor: lightgray
414                  action_default: turquoise
415                  action: blue
416
417       Available  colors: black, darkred, darkgreen, brown (darkyellow), dark‐
418       blue, purple (darkmagenta), teal (darkcyan), lightgray, darkgray,  red,
419       green, yellow, blue, fuchsia (magenta), turquoise (cyan), white
420

IMPORTER OPTIONS

422       The  options that control the import-cmd command are indented under the
423       import: key. For example, you might have a section in  your  configura‐
424       tion file that looks like this:
425
426          import:
427              write: yes
428              copy: yes
429              resume: no
430
431       These options are available in this section:
432
433   write
434       Either  yes  or  no,  controlling whether metadata (e.g., ID3) tags are
435       written to files when using beet import. Defaults to yes. The -w and -W
436       command-line options override this setting.
437
438   copy
439       Either  yes  or  no,  indicating whether to copy files into the library
440       directory when using beet import. Defaults to yes.  Can  be  overridden
441       with the -c and -C command-line options.
442
443       The  option is ignored if move is enabled (i.e., beets can move or copy
444       files but it doesn't make sense to do both).
445
446   move
447       Either yes or no, indicating whether to move  files  into  the  library
448       directory when using beet import.  Defaults to no.
449
450       The  effect  is similar to the copy option but you end up with only one
451       copy of the imported file. ("Moving" works even across filesystems;  if
452       necessary,  beets  will  copy  and  then delete when a simple rename is
453       impossible.) Moving files can be risky—it's  a  good  idea  to  keep  a
454       backup in case beets doesn't do what you expect with your files.
455
456       This  option  overrides  copy, so enabling it will always move (and not
457       copy) files. The -c switch to the beet import command,  however,  still
458       takes precedence.
459
460   link
461       Either  yes  or no, indicating whether to use symbolic links instead of
462       moving or copying files. (It conflicts with the move, copy and hardlink
463       options.) Defaults to no.
464
465       This  option only works on platforms that support symbolic links: i.e.,
466       Unixes.  It will fail on Windows.
467
468       It's likely that you'll also want to set write to no if  you  use  this
469       option to preserve the metadata on the linked files.
470
471   hardlink
472       Either  yes or no, indicating whether to use hard links instead of mov‐
473       ing or copying or symlinking files. (It conflicts with the move,  copy,
474       and link options.) Defaults to no.
475
476       As with symbolic links (see link, above), this will not work on Windows
477       and you will want to set write to no.  Otherwise, metadata on the orig‐
478       inal file will be modified.
479
480   resume
481       Either  yes, no, or ask. Controls whether interrupted imports should be
482       resumed. "Yes" means that imports are  always  resumed  when  possible;
483       "no"  means  resuming  is  disabled entirely; "ask" (the default) means
484       that the user should be prompted when resuming is possible. The -p  and
485       -P  flags  correspond  to the "yes" and "no" settings and override this
486       option.
487
488   incremental
489       Either yes or no, controlling whether imported directories are recorded
490       and  whether  these recorded directories are skipped.  This corresponds
491       to the -i flag to beet import.
492
493   incremental_skip_later
494       Either yes or no, controlling whether skipped directories are  recorded
495       in  the  incremental  list. Set this option to yes if you would like to
496       revisit  skipped  directories  later  whilst  using  incremental  mode.
497       Defaults to no.
498
499   from_scratch
500       Either  yes  or  no (default), controlling whether existing metadata is
501       discarded  when  a  match  is  applied.   This   corresponds   to   the
502       --from_scratch flag to beet import.
503
504   quiet_fallback
505       Either  skip  (default) or asis, specifying what should happen in quiet
506       mode (see the -q flag to import, above) when there is no strong  recom‐
507       mendation.
508
509   none_rec_action
510       Either ask (default), asis or skip. Specifies what should happen during
511       an interactive import session when there is no  recommendation.  Useful
512       when  you are only interested in processing medium and strong recommen‐
513       dations interactively.
514
515   timid
516       Either yes or no, controlling whether the importer runs in timid  mode,
517       in  which it asks for confirmation on every autotagging match, even the
518       ones that seem very close. Defaults to no.  The  -t  command-line  flag
519       controls the same setting.
520
521   log
522       Specifies  a  filename  where  the  importer's  log should be kept.  By
523       default, no log is written. This can be overridden with the -l flag  to
524       import.
525
526   default_action
527       One  of  apply,  skip, asis, or none, indicating which option should be
528       the default when selecting an action for a given  match.  This  is  the
529       action  that  will be taken when you type return without an option let‐
530       ter. The default is apply.
531
532   languages
533       A list of locale names to search for preferred  aliases.  For  example,
534       setting  this to "en" uses the transliterated artist name "Pyotr Ilyich
535       Tchaikovsky" instead of the Cyrillic script  for  the  composer's  name
536       when  tagging from MusicBrainz. Defaults to an empty list, meaning that
537       no language is preferred.
538
539   detail
540       Whether the importer UI should show  detailed  information  about  each
541       match  it  finds. When enabled, this mode prints out the title of every
542       track, regardless of whether it matches  the  original  metadata.  (The
543       default behavior only shows changes.) Default: no.
544
545   group_albums
546       By  default,  the beets importer groups tracks into albums based on the
547       directories they reside in. This option instead uses files' metadata to
548       partition  albums. Enable this option if you have directories that con‐
549       tain tracks from many albums mixed together.
550
551       The --group-albums or -g option to the import-cmd  command  is  equiva‐
552       lent, and the G interactive option invokes the same workflow.
553
554       Default: no.
555
556   autotag
557       By default, the beets importer always attempts to autotag new music. If
558       most of your collection consists of obscure music, you  may  be  inter‐
559       ested  in  disabling autotagging by setting this option to no. (You can
560       re-enable it with the -a flag to the import-cmd command.)
561
562       Default: yes.
563
564   duplicate_action
565       Either skip, keep, remove, merge or ask.  Controls how  duplicates  are
566       treated  in  import  task.   "skip" means that new item(album or track)
567       will be skipped; "keep" means keep both old  and  new  items;  "remove"
568       means  remove old item; "merge" means merge into one album; "ask" means
569       the user should be prompted for the action each time.  The  default  is
570       ask.
571
572   bell
573       Ring  the  terminal  bell to get your attention when the importer needs
574       your input.
575
576       Default: no.
577
578   set_fields
579       A dictionary indicating fields to set  to  values  for  newly  imported
580       music.  Here's an example:
581
582          set_fields:
583              genre: 'To Listen'
584              collection: 'Unordered'
585
586       Other  field/value  pairs  supplied  via  the  --set option on the com‐
587       mand-line override any settings here for fields with the same name.
588
589       Default: {} (empty).
590

MUSICBRAINZ OPTIONS

592       If you run your own MusicBrainz server, you can instruct beets  to  use
593       it instead of the main server. Use the host and ratelimit options under
594       a musicbrainz: header, like so:
595
596          musicbrainz:
597              host: localhost:5000
598              ratelimit: 100
599
600       The host key, of course, controls the Web server  hostname  (and  port,
601       optionally) that will be contacted by beets (default: musicbrainz.org).
602       The ratelimit option, an integer, controls the number  of  Web  service
603       requests  per second (default: 1). Do not change the rate limit setting
604       if you're using the main MusicBrainz server---on  this  public  server,
605       you're limited to one request per second.
606
607   searchlimit
608       The  number  of  matches  returned  when  sending search queries to the
609       MusicBrainz server.
610
611       Default: 5.
612

AUTOTAGGER MATCHING OPTIONS

614       You can configure some aspects of the logic beets uses  when  automati‐
615       cally matching MusicBrainz results under the match: section. To control
616       how   tolerant   the   autotagger   is   of   differences,   use    the
617       strong_rec_thresh  option,  which reflects the distance threshold below
618       which beets will make a "strong recommendation" that  the  metadata  be
619       used.  Strong  recommendations  are  accepted  automatically (except in
620       "timid" mode), so you can use this to make beets ask your opinion  more
621       or less often.
622
623       The threshold is a distance value between 0.0 and 1.0, so you can think
624       of it as the opposite of a similarity value. For example, if  you  want
625       to automatically accept any matches above 90% similarity, use:
626
627          match:
628              strong_rec_thresh: 0.10
629
630       The default strong recommendation threshold is 0.04.
631
632       The medium_rec_thresh and rec_gap_thresh options work similarly. When a
633       match is below the medium  recommendation  threshold  or  the  distance
634       between  it  and  the  next-best  match is above the gap threshold, the
635       importer will suggest that match but not automatically confirm it. Oth‐
636       erwise, you'll see a list of options to choose from.
637
638   max_rec
639       As  mentioned  above, autotagger matches have recommendations that con‐
640       trol how the UI behaves for a certain quality of match. The recommenda‐
641       tion  for a certain match is based on the overall distance calculation.
642       But you can also control the recommendation when  a  specific  distance
643       penalty is applied by defining maximum recommendations for each field:
644
645       To  define  maxima,  use  keys under max_rec: in the match section. The
646       defaults are "medium" for missing and  unmatched  tracks  and  "strong"
647       (i.e., no maximum) for everything else:
648
649          match:
650              max_rec:
651                  missing_tracks: medium
652                  unmatched_tracks: medium
653
654       If a recommendation is higher than the configured maximum and the indi‐
655       cated penalty is applied, the recommendation is downgraded. The setting
656       for each field can be one of none, low, medium or strong. When the max‐
657       imum recommendation is strong, no "downgrading" occurs.  The  available
658       penalty names here are:
659
660       · source
661
662       · artist
663
664       · album
665
666       · media
667
668       · mediums
669
670       · year
671
672       · country
673
674       · label
675
676       · catalognum
677
678       · albumdisambig
679
680       · album_id
681
682       · tracks
683
684       · missing_tracks
685
686       · unmatched_tracks
687
688       · track_title
689
690       · track_artist
691
692       · track_index
693
694       · track_length
695
696       · track_id
697
698   preferred
699       In  addition  to  comparing the tagged metadata with the match metadata
700       for similarity, you can also specify an ordered list of preferred coun‐
701       tries and media types.
702
703       A  distance  penalty  will be applied if the country or media type from
704       the match metadata doesn't match. The specified values are preferred in
705       descending  order  (i.e.,  the first item will be most preferred). Each
706       item may be a regular expression, and will  be  matched  case  insensi‐
707       tively.  The  number  of media will be stripped when matching preferred
708       media (e.g. "2x" in "2xCD").
709
710       You can also tell the autotagger to prefer matches that have a  release
711       year closest to the original year for an album.
712
713       Here's an example:
714
715          match:
716              preferred:
717                  countries: ['US', 'GB|UK']
718                  media: ['CD', 'Digital Media|File']
719                  original_year: yes
720
721       By default, none of these options are enabled.
722
723   ignored
724       You can completely avoid matches that have certain penalties applied by
725       adding the penalty name to the ignored setting:
726
727          match:
728              ignored: missing_tracks unmatched_tracks
729
730       The available penalties are the same as those for the max_rec setting.
731
732   required
733       You can avoid matches that lack certain required information.  Add  the
734       tags you want to enforce to the required setting:
735
736          match:
737              required: year label catalognum country
738
739       No tags are required by default.
740
741   ignored_media
742       A  list  of  media (i.e., formats) in metadata databases to ignore when
743       matching music. You can use this to ignore all media that usually  con‐
744       tain video instead of audio, for example:
745
746          match:
747              ignored_media: ['Data CD', 'DVD', 'DVD-Video', 'Blu-ray', 'HD-DVD',
748                              'VCD', 'SVCD', 'UMD', 'VHS']
749
750       No formats are ignored by default.
751
752   ignore_video_tracks
753       By  default, video tracks within a release will be ignored. If you want
754       them to be included (for  example  if  you  would  like  to  track  the
755       audio-only versions of the video tracks), set it to no.
756
757       Default: yes.
758

PATH FORMAT CONFIGURATION

760       You  can  also  configure  the  directory hierarchy beets uses to store
761       music.  These settings appear under the paths: key. Each  string  is  a
762       template  string  that  can  refer  to  metadata fields like $artist or
763       $title. The filename extension is added automatically. At  the  moment,
764       you  can  specify  three special paths: default for most releases, comp
765       for "various artist" releases with no dominant  artist,  and  singleton
766       for non-album tracks. The defaults look like this:
767
768          paths:
769              default: $albumartist/$album%aunique{}/$track $title
770              singleton: Non-Album/$artist/$title
771              comp: Compilations/$album%aunique{}/$track $title
772
773       Note  the  use  of  $albumartist  instead of $artist; this ensures that
774       albums will be well-organized. For more about these format strings, see
775       pathformat.  The  aunique{}  function  ensures  that  identically-named
776       albums are placed in different directories; see aunique for details.
777
778       In addition to default, comp, and singleton,  you  can  condition  path
779       queries  based on beets queries (see /reference/query). This means that
780       a config file like this:
781
782          paths:
783              albumtype:soundtrack: Soundtracks/$album/$track $title
784
785       will place soundtrack albums in a separate directory. The  queries  are
786       tested in the order they appear in the configuration file, meaning that
787       if an item matches multiple queries, beets will use the path format for
788       the first matching query.
789
790       Note that the special singleton and comp path format conditions are, in
791       fact, just  shorthand  for  the  explicit  queries  singleton:true  and
792       comp:true. In contrast, default is special and has no query equivalent:
793       the default format is only used if no queries match.
794

CONFIGURATION LOCATION

796       The beets configuration file is usually located in a standard  location
797       that  depends  on  your OS, but there are a couple of ways you can tell
798       beets where to look.
799
800   Environment Variable
801       First, you can set the BEETSDIR environment  variable  to  a  directory
802       containing  a config.yaml file. This replaces your configuration in the
803       default location. This also affects where  auxiliary  files,  like  the
804       library  database,  are  stored by default (that's where relative paths
805       are resolved to).  This environment variable is useful if you  need  to
806       manage multiple beets libraries with separate configurations.
807
808   Command-Line Option
809       Alternatively, you can use the --config command-line option to indicate
810       a YAML file containing options that  will  then  be  merged  with  your
811       existing options (from BEETSDIR or the default locations). This is use‐
812       ful if you want to keep your configuration mostly the same but modify a
813       few  options  as a batch. For example, you might have different strate‐
814       gies for importing  files,  each  with  a  different  set  of  importer
815       options.
816
817   Default Location
818       In  the absence of a BEETSDIR variable, beets searches a few places for
819       your configuration, depending on the platform:
820
821       · On Unix platforms, including OS X:~/.config/beets and then  $XDG_CON‐
822         FIG_DIR/beets, if the environment variable is set.
823
824       · On  OS  X,  we also search ~/Library/Application Support/beets before
825         the Unixy locations.
826
827       · On Windows: ~\AppData\Roaming\beets, and then %APPDATA%\beets, if the
828         environment variable is set.
829
830       Beets  uses  the  first directory in your platform's list that contains
831       config.yaml. If no config file exists, the last path  in  the  list  is
832       used.
833

EXAMPLE

835       Here's an example file:
836
837          directory: /var/mp3
838          import:
839              copy: yes
840              write: yes
841              log: beetslog.txt
842          art_filename: albumart
843          plugins: bpd
844          pluginpath: ~/beets/myplugins
845          ui:
846              color: yes
847
848          paths:
849              default: $genre/$albumartist/$album/$track $title
850              singleton: Singletons/$artist - $title
851              comp: $genre/$album/$track $title
852              albumtype:soundtrack: Soundtracks/$album/$track $title
853

SEE ALSO

855       http://beets.readthedocs.org/
856
857       beet(1)
858

AUTHOR

860       Adrian Sampson
861
863       2016, Adrian Sampson
864
865
866
867
8681.4                              Jan 31, 2019                   BEETSCONFIG(5)
Impressum