Advanced Rewrite Plugin
=======================

The ``advancedrewrite`` plugin lets you easily substitute values in your
templates and path formats, similarly to the :doc:`/plugins/rewrite`. It's
recommended to read the documentation of that plugin first.

The *advanced* rewrite plugin does not only support the simple rule format of
the ``rewrite`` plugin, but also an advanced format: there, the plugin doesn't
consider the value of the rewritten field, but instead checks if the given item
matches a :doc:`query </reference/query>`. Only then, the field is replaced with
the given value. It's also possible to replace multiple fields at once, and even
supports multi-valued fields.

To use advanced field rewriting, first enable the ``advancedrewrite`` plugin
(see :ref:`using-plugins`). Then, make a ``advancedrewrite:`` section in your
config file to contain your rewrite rules.

In contrast to the normal ``rewrite`` plugin, you need to provide a list of
replacement rule objects, which can have a different syntax depending on the
rule complexity.

The simple syntax is the same as the one of the rewrite plugin and allows to
replace a single field:

::

    advancedrewrite:
      - artist ODD EYE CIRCLE: 이달의 소녀 오드아이써클

As with :doc:`/plugins/rewrite`, simple rules applied to a multi-valued field
rewrite only the matching list entries.

The advanced syntax consists of a query to match against, as well as a map of
replacements to apply. For example, to credit all songs of ODD EYE CIRCLE before
2023 to their original group name, you can use the following rule:

::

    advancedrewrite:
      - match: "mb_artistid:dec0f331-cb08-4c8e-9c9f-aeb1f0f6d88c year:..2022"
        replacements:
          artist: 이달의 소녀 오드아이써클
          artist_sort: LOONA / ODD EYE CIRCLE

Note how the sort name is also rewritten within the same rule. You can specify
as many fields as you'd like in the replacements map.

If you need to work with multi-valued fields, you can use the following syntax:

::

    advancedrewrite:
      - match: "artist:배유빈 feat. 김미현"
        replacements:
          artists:
            - 유빈
            - 미미

As a convenience, the plugin applies patterns for the ``artist`` field to the
``albumartist`` field as well. (Otherwise, you would probably want to duplicate
every rule for ``artist`` and ``albumartist``.)

Make sure to properly quote your query strings if they contain spaces, otherwise
they might not do what you expect, or even cause beets to crash.

Take the following example:

::

    advancedrewrite:
      # BAD, DON'T DO THIS!
      - match: album:THE ALBUM
        replacements:
          artist: New artist

On the first sight, this might look sane, and replace the artist of the album
*THE ALBUM* with *New artist*. However, due to the space and missing quotes,
this query will evaluate to ``album:THE`` and match ``ALBUM`` on any field,
including ``artist``. As ``artist`` is the field being replaced, this query will
result in infinite recursion and ultimately crash beets.

Instead, you should use the following rule:

::

    advancedrewrite:
      # Note the quotes around the query string!
      - match: album:"THE ALBUM"
        replacements:
          artist: New artist

A word of warning: This plugin theoretically only applies to templates and path
formats; it initially does not modify files' metadata tags or the values tracked
by beets' library database, but since it *rewrites all field lookups*, it
modifies the file's metadata anyway. See comments in issue :bug:`2786`.

As an alternative to this plugin the simpler but less powerful
:doc:`/plugins/rewrite` can be used. If you don't want to modify the item's
metadata and only replace values in file paths, you can check out the
:doc:`/plugins/substitute`.
