1Path Formats 2============ 3 4The ``paths:`` section of the config file (see :doc:`config`) lets 5you specify the directory and file naming scheme for your music library. 6Templates substitute symbols like ``$title`` (any field value prefixed by ``$``) 7with the appropriate value from the track's metadata. Beets adds the filename 8extension automatically. 9 10For example, consider this path format string: 11``$albumartist/$album/$track $title`` 12 13Here are some paths this format will generate: 14 15* ``Yeah Yeah Yeahs/It's Blitz!/01 Zero.mp3`` 16 17* ``Spank Rock/YoYoYoYoYo/11 Competition.mp3`` 18 19* ``The Magnetic Fields/Realism/01 You Must Be Out of Your Mind.mp3`` 20 21Because ``$`` is used to delineate a field reference, you can use ``$$`` to emit 22a dollars sign. As with `Python template strings`_, ``${title}`` is equivalent 23to ``$title``; you can use this if you need to separate a field name from the 24text that follows it. 25 26.. _Python template strings: http://docs.python.org/library/string.html#template-strings 27 28 29A Note About Artists 30-------------------- 31 32Note that in path formats, you almost certainly want to use ``$albumartist`` and 33not ``$artist``. The latter refers to the "track artist" when it is present, 34which means that albums that have tracks from different artists on them (like 35`Stop Making Sense`_, for example) will be placed into different folders! 36Continuing with the Stop Making Sense example, you'll end up with most of the 37tracks in a "Talking Heads" directory and one in a "Tom Tom Club" directory. You 38probably don't want that! So use ``$albumartist``. 39 40.. _Stop Making Sense: 41 http://musicbrainz.org/release/798dcaab-0f1a-4f02-a9cb-61d5b0ddfd36.html 42 43As a convenience, however, beets allows ``$albumartist`` to fall back to the value for ``$artist`` and vice-versa if one tag is present but the other is not. 44 45 46.. _template-functions: 47 48Template Functions 49------------------ 50 51Beets path formats also support *function calls*, which can be used to transform 52text and perform logical manipulations. The syntax for function calls is like 53this: ``%func{arg,arg}``. For example, the ``upper`` function makes its argument 54upper-case, so ``%upper{beets rocks}`` will be replaced with ``BEETS ROCKS``. 55You can, of course, nest function calls and place variable references in 56function arguments, so ``%upper{$artist}`` becomes the upper-case version of the 57track's artists. 58 59These functions are built in to beets: 60 61* ``%lower{text}``: Convert ``text`` to lowercase. 62* ``%upper{text}``: Convert ``text`` to UPPERCASE. 63* ``%title{text}``: Convert ``text`` to Title Case. 64* ``%left{text,n}``: Return the first ``n`` characters of ``text``. 65* ``%right{text,n}``: Return the last ``n`` characters of ``text``. 66* ``%if{condition,text}`` or ``%if{condition,truetext,falsetext}``: If 67 ``condition`` is nonempty (or nonzero, if it's a number), then returns 68 the second argument. Otherwise, returns the third argument if specified (or 69 nothing if ``falsetext`` is left off). 70* ``%asciify{text}``: Convert non-ASCII characters to their ASCII equivalents. 71 For example, "café" becomes "cafe". Uses the mapping provided by the 72 `unidecode module`_. See the :ref:`asciify-paths` configuration 73 option. 74* ``%aunique{identifiers,disambiguators,brackets}``: Provides a unique string 75 to disambiguate similar albums in the database. See :ref:`aunique`, below. 76* ``%time{date_time,format}``: Return the date and time in any format accepted 77 by `strftime`_. For example, to get the year some music was added to your 78 library, use ``%time{$added,%Y}``. 79* ``%first{text}``: Returns the first item, separated by ``;`` (a semicolon 80 followed by a space). 81 You can use ``%first{text,count,skip}``, where ``count`` is the number of 82 items (default 1) and ``skip`` is number to skip (default 0). You can also use 83 ``%first{text,count,skip,sep,join}`` where ``sep`` is the separator, like 84 ``;`` or ``/`` and join is the text to concatenate the items. 85* ``%ifdef{field}``, ``%ifdef{field,truetext}`` or 86 ``%ifdef{field,truetext,falsetext}``: Checks if an flexible attribute 87 ``field`` is defined. If it exists, then return ``truetext`` or ``field`` 88 (default). Otherwise, returns ``falsetext``. The ``field`` should be entered 89 without ``$``. Note that this doesn't work with built-in :ref:`itemfields`, as 90 they are always defined. 91 92.. _unidecode module: http://pypi.python.org/pypi/Unidecode 93.. _strftime: http://docs.python.org/2/library/time.html#time.strftime 94 95Plugins can extend beets with more template functions (see 96:ref:`templ_plugins`). 97 98 99.. _aunique: 100 101Album Disambiguation 102-------------------- 103 104Occasionally, bands release two albums with the same name (c.f. Crystal Castles, 105Weezer, and any situation where a single has the same name as an album or EP). 106Beets ships with special support, in the form of the ``%aunique{}`` template 107function, to avoid placing two identically-named albums in the same directory on 108disk. 109 110The ``aunique`` function detects situations where two albums have some identical 111fields and emits text from additional fields to disambiguate the albums. For 112example, if you have both Crystal Castles albums in your library, ``%aunique{}`` 113will expand to "[2008]" for one album and "[2010]" for the other. The 114function detects that you have two albums with the same artist and title but 115that they have different release years. 116 117For full flexibility, the ``%aunique`` function takes three arguments. The 118first two are whitespace-separated lists of album field names: a set of 119*identifiers* and a set of *disambiguators*. The third argument is a pair of 120characters used to surround the disambiguator. 121 122Any group of albums with identical values for all the identifiers will be 123considered "duplicates". Then, the function tries each disambiguator field, 124looking for one that distinguishes each of the duplicate albums from each 125other. The first such field is used as the result for ``%aunique``. If no field 126suffices, an arbitrary number is used to distinguish the two albums. 127 128The default identifiers are ``albumartist album`` and the default 129disambiguators are ``albumtype year label catalognum albumdisambig 130releasegroupdisambig``. So you can get reasonable disambiguation 131behavior if you just use ``%aunique{}`` with no parameters in your 132path forms (as in the default path formats), but you can customize the 133disambiguation if, for example, you include the year by default in 134path formats. 135 136The default characters used as brackets are ``[]``. To change this, provide a 137third argument to the ``%aunique`` function consisting of two characters: the left 138and right brackets. Or, to turn off bracketing entirely, leave argument blank. 139 140One caveat: When you import an album that is named identically to one already in 141your library, the *first* album—the one already in your library— will not 142consider itself a duplicate at import time. This means that ``%aunique{}`` will 143expand to nothing for this album and no disambiguation string will be used at 144its import time. Only the second album will receive a disambiguation string. If 145you want to add the disambiguation string to both albums, just run ``beet move`` 146(possibly restricted by a query) to update the paths for the albums. 147 148 149Syntax Details 150-------------- 151 152The characters ``$``, ``%``, ``{``, ``}``, and ``,`` are "special" in the path 153template syntax. This means that, for example, if you want a ``%`` character to 154appear in your paths, you'll need to be careful that you don't accidentally 155write a function call. To escape any of these characters (except ``{``, and 156``,`` outside a function argument), prefix it with a ``$``. For example, 157``$$`` becomes ``$``; ``$%`` becomes ``%``, etc. The only exceptions are: 158 159* ``${``, which is ambiguous with the variable reference syntax (like 160 ``${title}``). To insert a ``{`` alone, it's always sufficient to just type 161 ``{``. 162* commas are used as argument separators in function calls. Inside of a 163 function's argument, use ``$,`` to get a literal ``,`` character. Outside of 164 any function argument, escaping is not necessary: ``,`` by itself will 165 produce ``,`` in the output. 166 167If a value or function is undefined, the syntax is simply left unreplaced. For 168example, if you write ``$foo`` in a path template, this will yield ``$foo`` in 169the resulting paths because "foo" is not a valid field name. The same is true of 170syntax errors like unclosed ``{}`` pairs; if you ever see template syntax 171constructs leaking into your paths, check your template for errors. 172 173If an error occurs in the Python code that implements a function, the function 174call will be expanded to a string that describes the exception so you can debug 175your template. For example, the second parameter to ``%left`` must be an 176integer; if you write ``%left{foo,bar}``, this will be expanded to something 177like ``<ValueError: invalid literal for int()>``. 178 179 180.. _itemfields: 181 182Available Values 183---------------- 184 185Here's a list of the different values available to path formats. The current 186list can be found definitively by running the command ``beet fields``. Note that 187plugins can add new (or replace existing) template values (see 188:ref:`templ_plugins`). 189 190Ordinary metadata: 191 192* title 193* artist 194* artist_sort: The "sort name" of the track artist (e.g., "Beatles, The" or 195 "White, Jack"). 196* artist_credit: The track-specific `artist credit`_ name, which may be a 197 variation of the artist's "canonical" name. 198* album 199* albumartist: The artist for the entire album, which may be different from the 200 artists for the individual tracks. 201* albumartist_sort 202* albumartist_credit 203* genre 204* composer 205* grouping 206* year, month, day: The release date of the specific release. 207* original_year, original_month, original_day: The release date of the original 208 version of the album. 209* track 210* tracktotal 211* disc 212* disctotal 213* lyrics 214* comments 215* bpm 216* comp: Compilation flag. 217* albumtype: The MusicBrainz album type; the MusicBrainz wiki has a `list of 218 type names`_. 219* label 220* asin 221* catalognum 222* script 223* language 224* country 225* albumstatus 226* media 227* albumdisambig 228* disctitle 229* encoder 230 231.. _artist credit: http://wiki.musicbrainz.org/Artist_Credit 232.. _list of type names: http://musicbrainz.org/doc/Release_Group/Type 233 234Audio information: 235 236* length (in seconds) 237* bitrate (in kilobits per second, with units: e.g., "192kbps") 238* format (e.g., "MP3" or "FLAC") 239* channels 240* bitdepth (only available for some formats) 241* samplerate (in kilohertz, with units: e.g., "48kHz") 242 243MusicBrainz and fingerprint information: 244 245* mb_trackid 246* mb_releasetrackid 247* mb_albumid 248* mb_artistid 249* mb_albumartistid 250* mb_releasegroupid 251* acoustid_fingerprint 252* acoustid_id 253 254Library metadata: 255 256* mtime: The modification time of the audio file. 257* added: The date and time that the music was added to your library. 258* path: The item's filename. 259 260 261.. _templ_plugins: 262 263Template functions and values provided by plugins 264------------------------------------------------- 265 266Beets plugins can provide additional fields and functions to templates. See 267the :doc:`/plugins/index` page for a full list of plugins. Some plugin-provided 268constructs include: 269 270* ``$missing`` by :doc:`/plugins/missing`: The number of missing tracks per 271 album. 272* ``%bucket{text}`` by :doc:`/plugins/bucket`: Substitute a string by the 273 range it belongs to. 274* ``%the{text}`` by :doc:`/plugins/the`: Moves English articles to ends of 275 strings. 276 277The :doc:`/plugins/inline` lets you define template fields in your beets 278configuration file using Python snippets. And for more advanced processing, 279you can go all-in and write a dedicated plugin to register your own fields and 280functions (see :ref:`writing-plugins`). 281