mirror of
https://github.com/beetbox/beets.git
synced 2025-12-24 09:33:46 +01:00
cb350de2ea
Add a configuration section that lists all options for each plugin. List options in alphabetic order. Mention the default value for each option. Use same sentences to describe concepts common to different plugins eg 'auto option, install description
67 lines
2.4 KiB
ReStructuredText
67 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 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: u'%02i.%02i' % (disc, track) if
|
|
disctotal > 1 else u'%02i' % (track)
|
|
|
|
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)
|