1Configuration 2============= 3 4Beets has an extensive configuration system that lets you customize nearly 5every aspect of its operation. To configure beets, you create a file called 6``config.yaml``. The location of the file depend on your platform (type ``beet 7config -p`` to see the path on your system): 8 9* On Unix-like OSes, write ``~/.config/beets/config.yaml``. 10* On Windows, use ``%APPDATA%\beets\config.yaml``. This is usually in a 11 directory like ``C:\Users\You\AppData\Roaming``. 12* On OS X, you can use either the Unix location or ``~/Library/Application 13 Support/beets/config.yaml``. 14 15You can launch your text editor to create or update your configuration by 16typing ``beet config -e``. (See the :ref:`config-cmd` command for details.) It 17is also possible to customize the location of the configuration file and even 18use multiple layers of configuration. See `Configuration Location`_, below. 19 20The config file uses `YAML`_ syntax. You can use the full power of YAML, but 21most configuration options are simple key/value pairs. This means your config 22file will look like this:: 23 24 option: value 25 another_option: foo 26 bigger_option: 27 key: value 28 foo: bar 29 30In YAML, you will need to use spaces (not tabs!) to indent some lines. If you 31have questions about more sophisticated syntax, take a look at the `YAML`_ 32documentation. 33 34.. _YAML: http://yaml.org/ 35 36The rest of this page enumerates the dizzying litany of configuration options 37available in beets. You might also want to see an 38:ref:`example <config-example>`. 39 40.. contents:: 41 :local: 42 :depth: 2 43 44Global Options 45-------------- 46 47These options control beets' global operation. 48 49library 50~~~~~~~ 51 52Path to the beets library file. By default, beets will use a file called 53``library.db`` alongside your configuration file. 54 55directory 56~~~~~~~~~ 57 58The directory to which files will be copied/moved when adding them to the 59library. Defaults to a folder called ``Music`` in your home directory. 60 61plugins 62~~~~~~~ 63 64A space-separated list of plugin module names to load. See 65:ref:`using-plugins`. 66 67include 68~~~~~~~ 69 70A space-separated list of extra configuration files to include. 71Filenames are relative to the directory containing ``config.yaml``. 72 73pluginpath 74~~~~~~~~~~ 75 76Directories to search for plugins. Each Python file or directory in a plugin 77path represents a plugin and should define a subclass of :class:`BeetsPlugin`. 78A plugin can then be loaded by adding the filename to the `plugins` configuration. 79The plugin path can either be a single string or a list of strings---so, if you 80have multiple paths, format them as a YAML list like so:: 81 82 pluginpath: 83 - /path/one 84 - /path/two 85 86.. _ignore: 87 88ignore 89~~~~~~ 90 91A list of glob patterns specifying file and directory names to be ignored when 92importing. By default, this consists of ``.*``, ``*~``, ``System Volume 93Information``, ``lost+found`` (i.e., beets ignores Unix-style hidden files, 94backup files, and directories that appears at the root of some Linux and Windows 95filesystems). 96 97.. _ignore_hidden: 98 99ignore_hidden 100~~~~~~~~~~~~~ 101 102Either ``yes`` or ``no``; whether to ignore hidden files when importing. On 103Windows, the "Hidden" property of files is used to detect whether or not a file 104is hidden. On OS X, the file's "IsHidden" flag is used to detect whether or not 105a file is hidden. On both OS X and other platforms (excluding Windows), files 106(and directories) starting with a dot are detected as hidden files. 107 108.. _replace: 109 110replace 111~~~~~~~ 112 113A set of regular expression/replacement pairs to be applied to all filenames 114created by beets. Typically, these replacements are used to avoid confusing 115problems or errors with the filesystem (for example, leading dots, which hide 116files on Unix, and trailing whitespace, which is illegal on Windows). To 117override these substitutions, specify a mapping from regular expression to 118replacement strings. For example, ``[xy]: z`` will make beets replace all 119instances of the characters ``x`` or ``y`` with the character ``z``. 120 121If you do change this value, be certain that you include at least enough 122substitutions to avoid causing errors on your operating system. Here are 123the default substitutions used by beets, which are sufficient to avoid 124unexpected behavior on all popular platforms:: 125 126 replace: 127 '[\\/]': _ 128 '^\.': _ 129 '[\x00-\x1f]': _ 130 '[<>:"\?\*\|]': _ 131 '\.$': _ 132 '\s+$': '' 133 '^\s+': '' 134 '^-': _ 135 136These substitutions remove forward and back slashes, leading dots, and 137control characters—all of which is a good idea on any OS. The fourth line 138removes the Windows "reserved characters" (useful even on Unix for for 139compatibility with Windows-influenced network filesystems like Samba). 140Trailing dots and trailing whitespace, which can cause problems on Windows 141clients, are also removed. 142 143When replacements other than the defaults are used, it is possible that they 144will increase the length of the path. In the scenario where this leads to a 145conflict with the maximum filename length, the default replacements will be 146used to resolve the conflict and beets will display a warning. 147 148Note that paths might contain special characters such as typographical 149quotes (``“”``). With the configuration above, those will not be 150replaced as they don't match the typewriter quote (``"``). To also strip these 151special characters, you can either add them to the replacement list or use the 152:ref:`asciify-paths` configuration option below. 153 154.. _asciify-paths: 155 156asciify_paths 157~~~~~~~~~~~~~ 158 159Convert all non-ASCII characters in paths to ASCII equivalents. 160 161For example, if your path template for 162singletons is ``singletons/$title`` and the title of a track is "Café", 163then the track will be saved as ``singletons/Cafe.mp3``. The changes 164take place before applying the :ref:`replace` configuration and are roughly 165equivalent to wrapping all your path templates in the ``%asciify{}`` 166:ref:`template function <template-functions>`. 167 168Default: ``no``. 169 170.. _unidecode module: http://pypi.python.org/pypi/Unidecode 171 172 173.. _art-filename: 174 175art_filename 176~~~~~~~~~~~~ 177 178When importing album art, the name of the file (without extension) where the 179cover art image should be placed. This is a template string, so you can use any 180of the syntax available to :doc:`/reference/pathformat`. Defaults to ``cover`` 181(i.e., images will be named ``cover.jpg`` or ``cover.png`` and placed in the 182album's directory). 183 184threaded 185~~~~~~~~ 186 187Either ``yes`` or ``no``, indicating whether the autotagger should use 188multiple threads. This makes things substantially faster by overlapping work: 189for example, it can copy files for one album in parallel with looking up data 190in MusicBrainz for a different album. You may want to disable this when 191debugging problems with the autotagger. 192Defaults to ``yes``. 193 194 195.. _list_format_item: 196.. _format_item: 197 198format_item 199~~~~~~~~~~~ 200 201Format to use when listing *individual items* with the :ref:`list-cmd` 202command and other commands that need to print out items. Defaults to 203``$artist - $album - $title``. The ``-f`` command-line option overrides 204this setting. 205 206It used to be named `list_format_item`. 207 208.. _list_format_album: 209.. _format_album: 210 211format_album 212~~~~~~~~~~~~ 213 214Format to use when listing *albums* with :ref:`list-cmd` and other 215commands. Defaults to ``$albumartist - $album``. The ``-f`` command-line 216option overrides this setting. 217 218It used to be named `list_format_album`. 219 220.. _sort_item: 221 222sort_item 223~~~~~~~~~ 224 225Default sort order to use when fetching items from the database. Defaults to 226``artist+ album+ disc+ track+``. Explicit sort orders override this default. 227 228.. _sort_album: 229 230sort_album 231~~~~~~~~~~ 232 233Default sort order to use when fetching albums from the database. Defaults to 234``albumartist+ album+``. Explicit sort orders override this default. 235 236.. _sort_case_insensitive: 237 238sort_case_insensitive 239~~~~~~~~~~~~~~~~~~~~~ 240Either ``yes`` or ``no``, indicating whether the case should be ignored when 241sorting lexicographic fields. When set to ``no``, lower-case values will be 242placed after upper-case values (e.g., *Bar Qux foo*), while ``yes`` would 243result in the more expected *Bar foo Qux*. Default: ``yes``. 244 245.. _original_date: 246 247original_date 248~~~~~~~~~~~~~ 249 250Either ``yes`` or ``no``, indicating whether matched albums should have their 251``year``, ``month``, and ``day`` fields set to the release date of the 252*original* version of an album rather than the selected version of the release. 253That is, if this option is turned on, then ``year`` will always equal 254``original_year`` and so on. Default: ``no``. 255 256.. _artist_credit: 257 258artist_credit 259~~~~~~~~~~~~~ 260 261Either ``yes`` or ``no``, indicating whether matched tracks and albums should 262use the artist credit, rather than the artist. That is, if this option is turned 263on, then ``artist`` will contain the artist as credited on the release. 264 265.. _per_disc_numbering: 266 267per_disc_numbering 268~~~~~~~~~~~~~~~~~~ 269 270A boolean controlling the track numbering style on multi-disc releases. By 271default (``per_disc_numbering: no``), tracks are numbered per-release, so the 272first track on the second disc has track number N+1 where N is the number of 273tracks on the first disc. If this ``per_disc_numbering`` is enabled, then the 274first (non-pregap) track on each disc always has track number 1. 275 276If you enable ``per_disc_numbering``, you will likely want to change your 277:ref:`path-format-config` also to include ``$disc`` before ``$track`` to make 278filenames sort correctly in album directories. For example, you might want to 279use a path format like this:: 280 281 paths: 282 default: $albumartist/$album%aunique{}/$disc-$track $title 283 284When this option is off (the default), even "pregap" hidden tracks are 285numbered from one, not zero, so other track numbers may appear to be bumped up 286by one. When it is on, the pregap track for each disc can be numbered zero. 287 288 289.. _config-aunique: 290 291aunique 292~~~~~~~ 293 294These options are used to generate a string that is guaranteed to be unique 295among all albums in the library who share the same set of keys. 296 297The defaults look like this:: 298 299 aunique: 300 keys: albumartist album 301 disambiguators: albumtype year label catalognum albumdisambig releasegroupdisambig 302 bracket: '[]' 303 304See :ref:`aunique` for more details. 305 306 307.. _terminal_encoding: 308 309terminal_encoding 310~~~~~~~~~~~~~~~~~ 311 312The text encoding, as `known to Python`_, to use for messages printed to the 313standard output. It's also used to read messages from the standard input. 314By default, this is determined automatically from the locale 315environment variables. 316 317.. _known to python: http://docs.python.org/2/library/codecs.html#standard-encodings 318 319.. _clutter: 320 321clutter 322~~~~~~~ 323 324When beets imports all the files in a directory, it tries to remove the 325directory if it's empty. A directory is considered empty if it only contains 326files whose names match the glob patterns in `clutter`, which should be a list 327of strings. The default list consists of "Thumbs.DB" and ".DS_Store". 328 329The importer only removes recursively searched subdirectories---the top-level 330directory you specify on the command line is never deleted. 331 332.. _max_filename_length: 333 334max_filename_length 335~~~~~~~~~~~~~~~~~~~ 336 337Set the maximum number of characters in a filename, after which names will be 338truncated. By default, beets tries to ask the filesystem for the correct 339maximum. 340 341.. _id3v23: 342 343id3v23 344~~~~~~ 345 346By default, beets writes MP3 tags using the ID3v2.4 standard, the latest 347version of ID3. Enable this option to instead use the older ID3v2.3 standard, 348which is preferred by certain older software such as Windows Media Player. 349 350.. _va_name: 351 352va_name 353~~~~~~~ 354 355Sets the albumartist for various-artist compilations. Defaults to ``'Various 356Artists'`` (the MusicBrainz standard). Affects other sources, such as 357:doc:`/plugins/discogs`, too. 358 359 360UI Options 361---------- 362 363The options that allow for customization of the visual appearance 364of the console interface. 365 366These options are available in this section: 367 368color 369~~~~~ 370 371Either ``yes`` or ``no``; whether to use color in console output (currently 372only in the ``import`` command). Turn this off if your terminal doesn't 373support ANSI colors. 374 375.. note:: 376 377 The `color` option was previously a top-level configuration. This is 378 still respected, but a deprecation message will be shown until your 379 top-level `color` configuration has been nested under `ui`. 380 381colors 382~~~~~~ 383 384The colors that are used throughout the user interface. These are only used if 385the ``color`` option is set to ``yes``. For example, you might have a section 386in your configuration file that looks like this:: 387 388 ui: 389 color: yes 390 colors: 391 text_success: green 392 text_warning: yellow 393 text_error: red 394 text_highlight: red 395 text_highlight_minor: lightgray 396 action_default: turquoise 397 action: blue 398 399Available colors: black, darkred, darkgreen, brown (darkyellow), darkblue, 400purple (darkmagenta), teal (darkcyan), lightgray, darkgray, red, green, 401yellow, blue, fuchsia (magenta), turquoise (cyan), white 402 403 404Importer Options 405---------------- 406 407The options that control the :ref:`import-cmd` command are indented under the 408``import:`` key. For example, you might have a section in your configuration 409file that looks like this:: 410 411 import: 412 write: yes 413 copy: yes 414 resume: no 415 416These options are available in this section: 417 418.. _config-import-write: 419 420write 421~~~~~ 422 423Either ``yes`` or ``no``, controlling whether metadata (e.g., ID3) tags are 424written to files when using ``beet import``. Defaults to ``yes``. The ``-w`` 425and ``-W`` command-line options override this setting. 426 427.. _config-import-copy: 428 429copy 430~~~~ 431 432Either ``yes`` or ``no``, indicating whether to **copy** files into the 433library directory when using ``beet import``. Defaults to ``yes``. Can be 434overridden with the ``-c`` and ``-C`` command-line options. 435 436The option is ignored if ``move`` is enabled (i.e., beets can move or 437copy files but it doesn't make sense to do both). 438 439.. _config-import-move: 440 441move 442~~~~ 443 444Either ``yes`` or ``no``, indicating whether to **move** files into the 445library directory when using ``beet import``. 446Defaults to ``no``. 447 448The effect is similar to the ``copy`` option but you end up with only 449one copy of the imported file. ("Moving" works even across filesystems; if 450necessary, beets will copy and then delete when a simple rename is 451impossible.) Moving files can be risky—it's a good idea to keep a backup in 452case beets doesn't do what you expect with your files. 453 454This option *overrides* ``copy``, so enabling it will always move 455(and not copy) files. The ``-c`` switch to the ``beet import`` command, 456however, still takes precedence. 457 458.. _link: 459 460link 461~~~~ 462 463Either ``yes`` or ``no``, indicating whether to use symbolic links instead of 464moving or copying files. (It conflicts with the ``move``, ``copy`` and 465``hardlink`` options.) Defaults to ``no``. 466 467This option only works on platforms that support symbolic links: i.e., Unixes. 468It will fail on Windows. 469 470It's likely that you'll also want to set ``write`` to ``no`` if you use this 471option to preserve the metadata on the linked files. 472 473.. _hardlink: 474 475hardlink 476~~~~~~~~ 477 478Either ``yes`` or ``no``, indicating whether to use hard links instead of 479moving or copying or symlinking files. (It conflicts with the ``move``, 480``copy``, and ``link`` options.) Defaults to ``no``. 481 482As with symbolic links (see :ref:`link`, above), this will not work on Windows 483and you will want to set ``write`` to ``no``. Otherwise, metadata on the 484original file will be modified. 485 486resume 487~~~~~~ 488 489Either ``yes``, ``no``, or ``ask``. Controls whether interrupted imports 490should be resumed. "Yes" means that imports are always resumed when 491possible; "no" means resuming is disabled entirely; "ask" (the default) 492means that the user should be prompted when resuming is possible. The ``-p`` 493and ``-P`` flags correspond to the "yes" and "no" settings and override this 494option. 495 496.. _incremental: 497 498incremental 499~~~~~~~~~~~ 500 501Either ``yes`` or ``no``, controlling whether imported directories are 502recorded and whether these recorded directories are skipped. This 503corresponds to the ``-i`` flag to ``beet import``. 504 505.. _incremental_skip_later: 506 507incremental_skip_later 508~~~~~~~~~~~~~~~~~~~~~~ 509 510Either ``yes`` or ``no``, controlling whether skipped directories are 511recorded in the incremental list. When set to ``yes``, skipped directories 512will be recorded, and skipped later. When set to ``no``, skipped 513directories won't be recorded, and beets will try to import them again 514later. Defaults to ``no``. 515 516.. _from_scratch: 517 518from_scratch 519~~~~~~~~~~~~ 520 521Either ``yes`` or ``no`` (default), controlling whether existing metadata is 522discarded when a match is applied. This corresponds to the ``--from_scratch`` 523flag to ``beet import``. 524 525quiet_fallback 526~~~~~~~~~~~~~~ 527 528Either ``skip`` (default) or ``asis``, specifying what should happen in 529quiet mode (see the ``-q`` flag to ``import``, above) when there is no 530strong recommendation. 531 532.. _none_rec_action: 533 534none_rec_action 535~~~~~~~~~~~~~~~ 536 537Either ``ask`` (default), ``asis`` or ``skip``. Specifies what should happen 538during an interactive import session when there is no recommendation. Useful 539when you are only interested in processing medium and strong recommendations 540interactively. 541 542timid 543~~~~~ 544 545Either ``yes`` or ``no``, controlling whether the importer runs in *timid* 546mode, in which it asks for confirmation on every autotagging match, even the 547ones that seem very close. Defaults to ``no``. The ``-t`` command-line flag 548controls the same setting. 549 550.. _import_log: 551 552log 553~~~ 554 555Specifies a filename where the importer's log should be kept. By default, 556no log is written. This can be overridden with the ``-l`` flag to 557``import``. 558 559.. _default_action: 560 561default_action 562~~~~~~~~~~~~~~ 563 564One of ``apply``, ``skip``, ``asis``, or ``none``, indicating which option 565should be the *default* when selecting an action for a given match. This is the 566action that will be taken when you type return without an option letter. The 567default is ``apply``. 568 569.. _languages: 570 571languages 572~~~~~~~~~ 573 574A list of locale names to search for preferred aliases. For example, setting 575this to ``en`` uses the transliterated artist name "Pyotr Ilyich Tchaikovsky" 576instead of the Cyrillic script for the composer's name when tagging from 577MusicBrainz. You can use a space-separated list of language abbreviations, like 578``en jp es``, to specify a preference order. Defaults to an empty list, meaning 579that no language is preferred. 580 581.. _detail: 582 583detail 584~~~~~~ 585 586Whether the importer UI should show detailed information about each match it 587finds. When enabled, this mode prints out the title of every track, regardless 588of whether it matches the original metadata. (The default behavior only shows 589changes.) Default: ``no``. 590 591.. _group_albums: 592 593group_albums 594~~~~~~~~~~~~ 595 596By default, the beets importer groups tracks into albums based on the 597directories they reside in. This option instead uses files' metadata to 598partition albums. Enable this option if you have directories that contain 599tracks from many albums mixed together. 600 601The ``--group-albums`` or ``-g`` option to the :ref:`import-cmd` command is 602equivalent, and the *G* interactive option invokes the same workflow. 603 604Default: ``no``. 605 606.. _autotag: 607 608autotag 609~~~~~~~ 610 611By default, the beets importer always attempts to autotag new music. If 612most of your collection consists of obscure music, you may be interested in 613disabling autotagging by setting this option to ``no``. (You can re-enable it 614with the ``-a`` flag to the :ref:`import-cmd` command.) 615 616Default: ``yes``. 617 618.. _duplicate_action: 619 620duplicate_action 621~~~~~~~~~~~~~~~~ 622 623Either ``skip``, ``keep``, ``remove``, ``merge`` or ``ask``. 624Controls how duplicates are treated in import task. 625"skip" means that new item(album or track) will be skipped; 626"keep" means keep both old and new items; "remove" means remove old 627item; "merge" means merge into one album; "ask" means the user 628should be prompted for the action each time. The default is ``ask``. 629 630.. _bell: 631 632bell 633~~~~ 634 635Ring the terminal bell to get your attention when the importer needs your input. 636 637Default: ``no``. 638 639.. _set_fields: 640 641set_fields 642~~~~~~~~~~ 643 644A dictionary indicating fields to set to values for newly imported music. 645Here's an example:: 646 647 set_fields: 648 genre: 'To Listen' 649 collection: 'Unordered' 650 651Other field/value pairs supplied via the ``--set`` option on the command-line 652override any settings here for fields with the same name. 653 654Default: ``{}`` (empty). 655 656.. _musicbrainz-config: 657 658MusicBrainz Options 659------------------- 660 661You can instruct beets to use `your own MusicBrainz database`_ instead of 662the `main server`_. Use the ``host`` and ``ratelimit`` options under a 663``musicbrainz:`` header, like so:: 664 665 musicbrainz: 666 host: localhost:5000 667 ratelimit: 100 668 669The ``host`` key, of course, controls the Web server hostname (and port, 670optionally) that will be contacted by beets (default: musicbrainz.org). 671The server must have search indices enabled (see `Building search indexes`_). 672 673The ``ratelimit`` option, an integer, controls the number of Web service requests 674per second (default: 1). **Do not change the rate limit setting** if you're 675using the main MusicBrainz server---on this public server, you're `limited`_ 676to one request per second. 677 678.. _your own MusicBrainz database: https://musicbrainz.org/doc/MusicBrainz_Server/Setup 679.. _main server: https://musicbrainz.org/ 680.. _limited: http://musicbrainz.org/doc/XML_Web_Service/Rate_Limiting 681.. _Building search indexes: https://musicbrainz.org/doc/MusicBrainz_Server/Setup#Building_search_indexes 682 683.. _searchlimit: 684 685searchlimit 686~~~~~~~~~~~ 687 688The number of matches returned when sending search queries to the 689MusicBrainz server. 690 691Default: ``5``. 692 693.. _match-config: 694 695Autotagger Matching Options 696--------------------------- 697 698You can configure some aspects of the logic beets uses when automatically 699matching MusicBrainz results under the ``match:`` section. To control how 700*tolerant* the autotagger is of differences, use the ``strong_rec_thresh`` 701option, which reflects the distance threshold below which beets will make a 702"strong recommendation" that the metadata be used. Strong recommendations 703are accepted automatically (except in "timid" mode), so you can use this to 704make beets ask your opinion more or less often. 705 706The threshold is a *distance* value between 0.0 and 1.0, so you can think of it 707as the opposite of a *similarity* value. For example, if you want to 708automatically accept any matches above 90% similarity, use:: 709 710 match: 711 strong_rec_thresh: 0.10 712 713The default strong recommendation threshold is 0.04. 714 715The ``medium_rec_thresh`` and ``rec_gap_thresh`` options work similarly. When a 716match is below the *medium* recommendation threshold or the distance between it 717and the next-best match is above the *gap* threshold, the importer will suggest 718that match but not automatically confirm it. Otherwise, you'll see a list of 719options to choose from. 720 721.. _max_rec: 722 723max_rec 724~~~~~~~ 725 726As mentioned above, autotagger matches have *recommendations* that control how 727the UI behaves for a certain quality of match. The recommendation for a certain 728match is based on the overall distance calculation. But you can also control 729the recommendation when a specific distance penalty is applied by defining 730*maximum* recommendations for each field: 731 732To define maxima, use keys under ``max_rec:`` in the ``match`` section. The 733defaults are "medium" for missing and unmatched tracks and "strong" (i.e., no 734maximum) for everything else:: 735 736 match: 737 max_rec: 738 missing_tracks: medium 739 unmatched_tracks: medium 740 741If a recommendation is higher than the configured maximum and the indicated 742penalty is applied, the recommendation is downgraded. The setting for 743each field can be one of ``none``, ``low``, ``medium`` or ``strong``. When the 744maximum recommendation is ``strong``, no "downgrading" occurs. The available 745penalty names here are: 746 747* source 748* artist 749* album 750* media 751* mediums 752* year 753* country 754* label 755* catalognum 756* albumdisambig 757* album_id 758* tracks 759* missing_tracks 760* unmatched_tracks 761* track_title 762* track_artist 763* track_index 764* track_length 765* track_id 766 767.. _preferred: 768 769preferred 770~~~~~~~~~ 771 772In addition to comparing the tagged metadata with the match metadata for 773similarity, you can also specify an ordered list of preferred countries and 774media types. 775 776A distance penalty will be applied if the country or media type from the match 777metadata doesn't match. The specified values are preferred in descending order 778(i.e., the first item will be most preferred). Each item may be a regular 779expression, and will be matched case insensitively. The number of media will 780be stripped when matching preferred media (e.g. "2x" in "2xCD"). 781 782You can also tell the autotagger to prefer matches that have a release year 783closest to the original year for an album. 784 785Here's an example:: 786 787 match: 788 preferred: 789 countries: ['US', 'GB|UK'] 790 media: ['CD', 'Digital Media|File'] 791 original_year: yes 792 793By default, none of these options are enabled. 794 795.. _ignored: 796 797ignored 798~~~~~~~ 799 800You can completely avoid matches that have certain penalties applied by adding 801the penalty name to the ``ignored`` setting:: 802 803 match: 804 ignored: missing_tracks unmatched_tracks 805 806The available penalties are the same as those for the :ref:`max_rec` setting. 807 808For example, setting ``ignored: missing_tracks`` will skip any album matches where your audio files are missing some of the tracks. The importer will not attempt to display these matches. It does not ignore the fact that the album is missing tracks, which would allow these matches to apply more easily. To do that, you'll want to adjust the penalty for missing tracks. 809 810.. _required: 811 812required 813~~~~~~~~ 814 815You can avoid matches that lack certain required information. Add the tags you 816want to enforce to the ``required`` setting:: 817 818 match: 819 required: year label catalognum country 820 821No tags are required by default. 822 823.. _ignored_media: 824 825ignored_media 826~~~~~~~~~~~~~ 827 828A list of media (i.e., formats) in metadata databases to ignore when matching 829music. You can use this to ignore all media that usually contain video instead 830of audio, for example:: 831 832 match: 833 ignored_media: ['Data CD', 'DVD', 'DVD-Video', 'Blu-ray', 'HD-DVD', 834 'VCD', 'SVCD', 'UMD', 'VHS'] 835 836No formats are ignored by default. 837 838 839.. _ignore_data_tracks: 840 841ignore_data_tracks 842~~~~~~~~~~~~~~~~~~~ 843 844By default, audio files contained in data tracks within a release are included 845in the album's tracklist. If you want them to be included, set it ``no``. 846 847Default: ``yes``. 848 849.. _ignore_video_tracks: 850 851ignore_video_tracks 852~~~~~~~~~~~~~~~~~~~ 853 854By default, video tracks within a release will be ignored. If you want them to 855be included (for example if you would like to track the audio-only versions of 856the video tracks), set it to ``no``. 857 858Default: ``yes``. 859 860.. _path-format-config: 861 862Path Format Configuration 863------------------------- 864 865You can also configure the directory hierarchy beets uses to store music. 866These settings appear under the ``paths:`` key. Each string is a template 867string that can refer to metadata fields like ``$artist`` or ``$title``. The 868filename extension is added automatically. At the moment, you can specify three 869special paths: ``default`` for most releases, ``comp`` for "various artist" 870releases with no dominant artist, and ``singleton`` for non-album tracks. The 871defaults look like this:: 872 873 paths: 874 default: $albumartist/$album%aunique{}/$track $title 875 singleton: Non-Album/$artist/$title 876 comp: Compilations/$album%aunique{}/$track $title 877 878Note the use of ``$albumartist`` instead of ``$artist``; this ensures that albums 879will be well-organized. For more about these format strings, see 880:doc:`pathformat`. The ``aunique{}`` function ensures that identically-named 881albums are placed in different directories; see :ref:`aunique` for details. 882 883In addition to ``default``, ``comp``, and ``singleton``, you can condition path 884queries based on beets queries (see :doc:`/reference/query`). This means that a 885config file like this:: 886 887 paths: 888 albumtype:soundtrack: Soundtracks/$album/$track $title 889 890will place soundtrack albums in a separate directory. The queries are tested in 891the order they appear in the configuration file, meaning that if an item matches 892multiple queries, beets will use the path format for the *first* matching query. 893 894Note that the special ``singleton`` and ``comp`` path format conditions are, in 895fact, just shorthand for the explicit queries ``singleton:true`` and 896``comp:true``. In contrast, ``default`` is special and has no query equivalent: 897the ``default`` format is only used if no queries match. 898 899 900Configuration Location 901---------------------- 902 903The beets configuration file is usually located in a standard location that 904depends on your OS, but there are a couple of ways you can tell beets where to 905look. 906 907Environment Variable 908~~~~~~~~~~~~~~~~~~~~ 909 910First, you can set the ``BEETSDIR`` environment variable to a directory 911containing a ``config.yaml`` file. This replaces your configuration in the 912default location. This also affects where auxiliary files, like the library 913database, are stored by default (that's where relative paths are resolved to). 914This environment variable is useful if you need to manage multiple beets 915libraries with separate configurations. 916 917Command-Line Option 918~~~~~~~~~~~~~~~~~~~ 919 920Alternatively, you can use the ``--config`` command-line option to indicate a 921YAML file containing options that will then be merged with your existing 922options (from ``BEETSDIR`` or the default locations). This is useful if you 923want to keep your configuration mostly the same but modify a few options as a 924batch. For example, you might have different strategies for importing files, 925each with a different set of importer options. 926 927Default Location 928~~~~~~~~~~~~~~~~ 929 930In the absence of a ``BEETSDIR`` variable, beets searches a few places for 931your configuration, depending on the platform: 932 933- On Unix platforms, including OS X:``~/.config/beets`` and then 934 ``$XDG_CONFIG_DIR/beets``, if the environment variable is set. 935- On OS X, we also search ``~/Library/Application Support/beets`` before the 936 Unixy locations. 937- On Windows: ``~\AppData\Roaming\beets``, and then ``%APPDATA%\beets``, if 938 the environment variable is set. 939 940Beets uses the first directory in your platform's list that contains 941``config.yaml``. If no config file exists, the last path in the list is used. 942 943 944.. _config-example: 945 946Example 947------- 948 949Here's an example file:: 950 951 directory: /var/mp3 952 import: 953 copy: yes 954 write: yes 955 log: beetslog.txt 956 art_filename: albumart 957 plugins: bpd 958 pluginpath: ~/beets/myplugins 959 ui: 960 color: yes 961 962 paths: 963 default: $genre/$albumartist/$album/$track $title 964 singleton: Singletons/$artist - $title 965 comp: $genre/$album/$track $title 966 albumtype:soundtrack: Soundtracks/$album/$track $title 967 968.. only:: man 969 970 See Also 971 -------- 972 973 ``http://beets.readthedocs.org/`` 974 975 :manpage:`beet(1)` 976