mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 08:39:17 +01:00
72 lines
2.4 KiB
ReStructuredText
72 lines
2.4 KiB
ReStructuredText
Inline Plugin
|
|
=============
|
|
|
|
The ``inline`` plugin lets you use Python to customize your path formats. Using
|
|
it, you can define template fields in your beets configuration file and refer to
|
|
them from your template strings in the ``paths:`` section (see
|
|
:doc:`/reference/config/`).
|
|
|
|
To use the ``inline`` plugin, enable it in your configuration (see
|
|
:ref:`using-plugins`). Then, make a ``item_fields:`` block in your config file.
|
|
Under this key, every line defines a new template field; the key is the name of
|
|
the field (you'll use the name to refer to the field in your templates) and the
|
|
value is a Python expression or function body. The Python code has all of a
|
|
track's fields in scope, so you can refer to any normal attributes (such as
|
|
``artist`` or ``title``) as Python variables.
|
|
|
|
Here are a couple of examples of expressions:
|
|
|
|
::
|
|
|
|
item_fields:
|
|
initial: albumartist[0].upper() + u'.'
|
|
disc_and_track: f"{disc:02d}.{track:02d}" if disctotal > 1 else f"{track:02d}"
|
|
|
|
Note that YAML syntax allows newlines in values if the subsequent lines are
|
|
indented.
|
|
|
|
These examples define ``$initial`` and ``$disc_and_track`` fields that can be
|
|
referenced in path templates like so:
|
|
|
|
::
|
|
|
|
paths:
|
|
default: $initial/$artist/$album%aunique{}/$disc_and_track $title
|
|
|
|
Block Definitions
|
|
-----------------
|
|
|
|
If you need to use statements like ``import``, you can write a Python function
|
|
body instead of a single expression. In this case, you'll need to ``return`` a
|
|
result for the value of the path field, like so:
|
|
|
|
::
|
|
|
|
item_fields:
|
|
filename: |
|
|
import os
|
|
from beets.util import bytestring_path
|
|
return bytestring_path(os.path.basename(path))
|
|
|
|
You might want to use the YAML syntax for "block literals," in which a leading
|
|
``|`` character indicates a multi-line block of text.
|
|
|
|
Album Fields
|
|
------------
|
|
|
|
The above examples define fields for *item* templates, but you can also define
|
|
fields for *album* templates. Use the ``album_fields`` configuration section. In
|
|
this context, all existing album fields are available as variables along with
|
|
``items``, which is a list of items in the album.
|
|
|
|
This example defines a ``$bitrate`` field for albums as the average of the
|
|
tracks' fields:
|
|
|
|
::
|
|
|
|
album_fields:
|
|
bitrate: |
|
|
total = 0
|
|
for item in items:
|
|
total += item.bitrate
|
|
return total / len(items)
|