beets/docs/plugins/substitute.rst

Substitute Plugin
=================

The ``substitute`` plugin lets you easily substitute values in your templates
and path formats. Specifically, it is intended to let you *canonicalize* names
such as artists: For example, perhaps you want albums from The Jimi Hendrix
Experience to be sorted into the same folder as solo Hendrix albums.

This plugin is intended as a replacement for the ``rewrite`` plugin. While the
``rewrite`` plugin modifies the metadata, this plugin does not.

Enable the ``substitute`` plugin (see :ref:`using-plugins`), then make a
``substitute:`` section in your config file to contain your rules. Each rule
consists of a case-insensitive regular expression pattern, and a replacement
string. For example, you might use:

.. code-block:: yaml

    substitute:
      .*jimi hendrix.*: Jimi Hendrix

The replacement can be an expression utilising the matched regex, allowing us to
create more general rules. Say for example, we want to sort all albums by
multiple artists into the directory of the first artist. We can thus capture
everything before the first ``,``, ``&`` or ``and``, and use this capture group
in the output, discarding the rest of the string.

.. code-block:: yaml

    substitute:
      ^(.*?)(,| &| and).*: \1

This would handle all the below cases in a single rule:

    |   Bob Dylan and The Band -> Bob Dylan
    |   Neil Young & Crazy Horse -> Neil Young
    |   James Yorkston, Nina Persson & The Second Hand Orchestra -> James
        Yorkston

To apply the substitution, you have to call the function ``%substitute{}`` in
the paths section. For example:

.. code-block:: yaml

    paths:
        default: \%substitute{$albumartist}/$year - $album\%aunique{}/$track - $title