mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 16:42:42 +01:00
98 lines
3.6 KiB
ReStructuredText
98 lines
3.6 KiB
ReStructuredText
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: 이달의 소녀 오드아이써클
|
|
|
|
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`.
|