Advanced Rewrite Plugin#
The advancedrewrite
plugin lets you easily substitute values
in your templates and path formats, similarly to the Rewrite Plugin.
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 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 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 #2786.
As an alternative to this plugin the simpler but less powerful Rewrite Plugin 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 Substitute Plugin.