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