mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 08:39:17 +01:00
91 lines
3.6 KiB
ReStructuredText
91 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`.
|