1.. _RenamingFiles: 2 3Renaming files 4============== 5 6Basic Syntax 7------------ 8 9Quod Libet allows you to rename files based on their tags. In some cases 10you may wish to alter the filename depending on whether some tags are 11present or missing, in addition to their values. A common pattern might be:: 12 13 <tracknumber>. <title~version> 14 15 16You can use a ``|`` to only insert text when a tag is present:: 17 18 <tracknumber|<tracknumber>. ><title~version> 19 20 21You can also specify literal text to use if the tag is missing by adding 22another `|`:: 23 24 <album|<album>|No Album> - <title> 25 26A reasonable use of albumartist would be:: 27 28 <albumartist|<albumartist>|<artist|<artist>|No artist>> 29 30 31..which uses the first of the following: Albumartist, Artist or "No artist". 32 33You can of course also move files across your filesystem to another 34directory by mixing path elements and ``<tag>`` syntax:: 35 36 /home/*username*/Music/<artist>/<album>/... 37 38 39Simple Renames 40-------------- 41 42Like tagging by filename, renaming by tags uses tag names enclosed by 43``<...>`` to substitute values. To rename songs as their artist followed 44by their title, use ``<artist> - <title>`` (The file extension, .ogg, .mpc, 45and so on, is automatically added). Other common patterns include 46 47 * ``<tracknumber>. <title>`` 48 * ``<tracknumber>. <artist> - <title>`` 49 * ``~/music/<artist> - <album>/<tracknumber>. <title>`` 50 * ``~/music/<artist>/<album>/<tracknumber>. <title>`` 51 52You can also use tied tags to rename, e.g. ``<artist~title>``. 53 54 55Creating Directories 56-------------------- 57 58Note that if you use ``/`` (a directory separator) in your filename, you 59''must'' start the pattern with a ``/`` (or a ``~/``, which expands to your 60home directory). To see why, consider what would happen if you tried to 61rename the same file twice with ``<artist>/<title>``. The first time it 62would go under ``Artist/Title.ogg``, the second time, 63``Artist/Artist/Title.ogg``. When you specify the full path, this can't 64happen. 65 66If you don't use a `/` in the pattern, the file gets put in the same directory. 67 68 69Conditional Renaming 70-------------------- 71 72Consider the ``<tracknumber>. <title>`` pattern. 73 74When the file is missing a track number, you get a filename that starts 75with ., which isn't good. So Quod Libet lets you use ''conditional 76renaming'' to avoid that. 77 78To use conditional text, after the tag name (but inside the ``<...>``) put 79a ``|`` (a pipe). Then after the pipe, place all the text you want, 80including other tag names inside ``<...>``. That text will only be added when 81that tag isn't empty. 82 83To avoid the original problem, only display the track number, period, and 84space when the track number tag exists: 85 86``<tracknumber|<tracknumber>. ><title>``. 87 88Quod Libet also lets you change the text if a tag ''doesn't'' exist: Use a 89second pipe. ``<tracknumber|<tracknumber>|00>. <title>`` will use the 90track number at the start of the filename if it exists, or *00* if it 91doesn't. 92 93 94Go crazy with conditions / More examples 95---------------------------------------- 96 97So you basically want to remember that it goes ``<condition|<conditional 98tag>|<else tag>>`` You can however even put conditions inside each other. 99Here's an example that I just created, and so far it seems to work: 100 101I first had:: 102 103 /mnt/musik/<genre|<genre>/><artist|<artist>|Unknown>/<album|<album>/><tracknumber|<tracknumber> - ><title> 104 105Let's dissect this: 106 107 * ``/mnt/musik``: My basic music partition 108 * ``<genre|<genre>/>``: If there is a tag "genre", put the song into that 109 folder (creating the folder if necessary). If there is no tag genre, 110 skip this level in the folder hierarchy (note that the trailing slash 111 of ``<genre>/`` is inside the < > that delineate the conditional "block". 112 * ``<artist>|<artist>|Unknown>/``: If there's a tag artist, put everything 113 into that folder, else put into a folder called "Unknown". Not that the 114 trailing slash is outside the < > that delineate the conditional block, 115 since we always want that folder level. 116 * ``<album|<album>/>``: Album folder as needed, else skip 117 * ``<tracknumber|<tracknumber> - >``: Prepend tracknumber if it exists 118 * ``<title>``: Duh. 119 120However, for songs that don't have a genre tag, I wanted to use a tag I use 121called "language" and sort into that folder instead. But I have some songs 122that have a genre tag and also a language tag, and those songs should only 123go into the genre folder; the language folder should be ignored. 124 125Turns out QL can do this just fine, by expanding the ``<genre>`` conditional 126block in the expression above to ``<genre|<genre>/|<language|<language>/>>``. 127 128Basically, the pipe after the second ``<genre>/`` introduces what should be 129done if the first condition isn't met (i.e. no genre tag), but here instead 130of putting straightforward text or another label we then introduce a second 131conditional block, ``<language|<language/>>``, which puts in a language tag 132folder, if the song has a tag "language". 133 134The full expression now looks like this:: 135 136 /mnt/musik/<genre|<genre>/|<language|<language>/>><artist|<artist>|Unknown>/<album|<album>/><tracknumber|<tracknumber> - ><title> 137