Backup_Repos/beets
1
0
Fork 0
mirror of https://github.com/beetbox/beets.git synced 2025-12-06 08:39:17 +01:00
Code Issues Projects Releases Wiki Activity

Docs: fix linting issues

Browse source
This commit is contained in:
Šarūnas Nejus 2025-08-02 19:14:28 +01:00
parent c2043dad7f
commit 769dcdc88a
No known key found for this signature in database
GPG key ID: DD28F6704DBE3435
58 changed files with 837 additions and 702 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/_templates/autosummary/base.rst vendored
View file

@ -1,3 +1,3 @@
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}
.. auto{{ objtype }}:: {{ objname }}
.. auto{{ objtype }}:: {{ objname }}

7
docs/_templates/autosummary/class.rst vendored
View file

@ -3,10 +3,10 @@
.. currentmodule:: {{ module }}
.. autoclass:: {{ objname }}
:members: <-- add at least this line
:members: <-- add at least this line
:private-members:
:show-inheritance: <-- plus I want to show inheritance...
:inherited-members: <-- ...and inherited members too
:show-inheritance: <-- plus I want to show inheritance...
:inherited-members: <-- ...and inherited members too
{% block methods %}
.. automethod:: __init__
@ -25,4 +25,3 @@
{% endblock %}
.. rubric:: {{ _('Methods definition') }}

2
docs/_templates/autosummary/module.rst vendored
View file

@ -8,4 +8,4 @@
{%- endfor %}
{% endif %}
{% endblock %}
{% endblock %}

2
docs/api/database.rst
View file

@ -44,4 +44,4 @@ Queries
Query
FieldQuery
AndQuery
AndQuery

527
docs/changelog.rst
View file

File diff suppressed because it is too large Load diff

7
docs/dev/library.rst
View file

@ -20,14 +20,15 @@ invocation of beets usually has only one :class:`Library`. It's powered by
abstraction, something like a very minimal `ORM`_. The library is also
responsible for handling queries to retrieve stored objects.
Overview
Overview
''''''''
You can add new items or albums to the library via the
:py:meth:`Library.add` and :py:meth:`Library.add_album` methods.
You may also query the library for items and albums using the
:py:meth:`Library.items`, :py:meth:`Library.albums`, :py:meth:`Library.get_item` and :py:meth:`Library.get_album` methods.
:py:meth:`Library.items`, :py:meth:`Library.albums`, :py:meth:`Library.get_item`
and :py:meth:`Library.get_album` methods.
Any modifications to the library must go through a
:class:`Transaction` object, which you can get using the
@ -64,7 +65,7 @@ We provide CRUD-like methods for interacting with the database:
* :py:meth:`LibModel.store`
* :py:meth:`LibModel.load`
* :py:meth:`LibModel.remove`
* :py:meth:`LibModel.remove`
* :py:meth:`LibModel.add`
The base class :class:`beets.dbcore.Model` has a ``dict``-like interface, so

129
docs/dev/plugins.rst
View file

@ -151,50 +151,50 @@ registration process in this case::
The events currently available are:
* `pluginload`: called after all the plugins have been loaded after the ``beet``
command starts
* ``pluginload``: called after all the plugins have been loaded after the
``beet`` command starts
* `import`: called after a ``beet import`` command finishes (the ``lib`` keyword
argument is a Library object; ``paths`` is a list of paths (strings) that were
imported)
* ``import``: called after a ``beet import`` command finishes (the ``lib``
keyword argument is a Library object; ``paths`` is a list of paths (strings)
that were imported)
* `album_imported`: called with an ``Album`` object every time the ``import``
* ``album_imported``: called with an ``Album`` object every time the ``import``
command finishes adding an album to the library. Parameters: ``lib``,
``album``
* `album_removed`: called with an ``Album`` object every time an album is
* ``album_removed``: called with an ``Album`` object every time an album is
removed from the library (even when its file is not deleted from disk).
* `item_copied`: called with an ``Item`` object whenever its file is copied.
* ``item_copied``: called with an ``Item`` object whenever its file is copied.
Parameters: ``item``, ``source`` path, ``destination`` path
* `item_imported`: called with an ``Item`` object every time the importer adds a
singleton to the library (not called for full-album imports). Parameters:
``lib``, ``item``
* ``item_imported``: called with an ``Item`` object every time the importer
adds a singleton to the library (not called for full-album imports).
Parameters: ``lib``, ``item``
* `before_item_moved`: called with an ``Item`` object immediately before its
* ``before_item_moved``: called with an ``Item`` object immediately before its
file is moved. Parameters: ``item``, ``source`` path, ``destination`` path
* `item_moved`: called with an ``Item`` object whenever its file is moved.
* ``item_moved``: called with an ``Item`` object whenever its file is moved.
Parameters: ``item``, ``source`` path, ``destination`` path
* `item_linked`: called with an ``Item`` object whenever a symlink is created
* ``item_linked``: called with an ``Item`` object whenever a symlink is created
for a file.
Parameters: ``item``, ``source`` path, ``destination`` path
* `item_hardlinked`: called with an ``Item`` object whenever a hardlink is
* ``item_hardlinked``: called with an ``Item`` object whenever a hardlink is
created for a file.
Parameters: ``item``, ``source`` path, ``destination`` path
* `item_reflinked`: called with an ``Item`` object whenever a reflink is
* ``item_reflinked``: called with an ``Item`` object whenever a reflink is
created for a file.
Parameters: ``item``, ``source`` path, ``destination`` path
* `item_removed`: called with an ``Item`` object every time an item (singleton
* ``item_removed``: called with an ``Item`` object every time an item (singleton
or album's part) is removed from the library (even when its file is not
deleted from disk).
* `write`: called with an ``Item`` object, a ``path``, and a ``tags``
* ``write``: called with an ``Item`` object, a ``path``, and a ``tags``
dictionary just before a file's metadata is written to disk (i.e.,
just before the file on disk is opened). Event handlers may change
the ``tags`` dictionary to customize the tags that are written to the
@ -203,84 +203,83 @@ The events currently available are:
operation. Beets will catch that exception, print an error message
and continue.
* `after_write`: called with an ``Item`` object after a file's metadata is
* ``after_write``: called with an ``Item`` object after a file's metadata is
written to disk (i.e., just after the file on disk is closed).
* `import_task_created`: called immediately after an import task is
initialized. Plugins can use this to, for example, change imported files of a
task before anything else happens. It's also possible to replace the task
with another task by returning a list of tasks. This list can contain zero
or more `ImportTask`s. Returning an empty list will stop the task.
Parameters: ``task`` (an `ImportTask`) and ``session`` (an `ImportSession`).
* ``import_task_created``: called immediately after an import task is
initialized. Plugins can use this to, for example, change imported files of
a task before anything else happens. It's also possible to replace the task
with another task by returning a list of tasks. This list can contain zero or
more ``ImportTask``. Returning an empty list will stop the task.
Parameters: ``task`` (an ``ImportTask``) and ``session`` (an
``ImportSession``).
* `import_task_start`: called when before an import task begins processing.
* ``import_task_start``: called when before an import task begins processing.
Parameters: ``task`` and ``session``.
* `import_task_apply`: called after metadata changes have been applied in an
* ``import_task_apply``: called after metadata changes have been applied in an
import task. This is called on the same thread as the UI, so use this
sparingly and only for tasks that can be done quickly. For most plugins, an
import pipeline stage is a better choice (see :ref:`plugin-stage`).
Parameters: ``task`` and ``session``.
* `import_task_before_choice`: called after candidate search for an import task
before any decision is made about how/if to import or tag. Can be used to
present information about the task or initiate interaction with the user
* ``import_task_before_choice``: called after candidate search for an import
task before any decision is made about how/if to import or tag. Can be used
to present information about the task or initiate interaction with the user
before importing occurs. Return an importer action to take a specific action.
Only one handler may return a non-None result.
Parameters: ``task`` and ``session``
* `import_task_choice`: called after a decision has been made about an import
* ``import_task_choice``: called after a decision has been made about an import
task. This event can be used to initiate further interaction with the user.
Use ``task.choice_flag`` to determine or change the action to be
taken. Parameters: ``task`` and ``session``.
* `import_task_files`: called after an import task finishes manipulating the
* ``import_task_files``: called after an import task finishes manipulating the
filesystem (copying and moving files, writing metadata tags). Parameters:
``task`` and ``session``.
* `library_opened`: called after beets starts up and initializes the main
* ``library_opened``: called after beets starts up and initializes the main
Library object. Parameter: ``lib``.
* `database_change`: a modification has been made to the library database. The
* ``database_change``: a modification has been made to the library database. The
change might not be committed yet. Parameters: ``lib`` and ``model``.
* `cli_exit`: called just before the ``beet`` command-line program exits.
* ``cli_exit``: called just before the ``beet`` command-line program exits.
Parameter: ``lib``.
* `import_begin`: called just before a ``beet import`` session starts up.
* ``import_begin``: called just before a ``beet import`` session starts up.
Parameter: ``session``.
* `trackinfo_received`: called after metadata for a track item has been
* ``trackinfo_received``: called after metadata for a track item has been
fetched from a data source, such as MusicBrainz. You can modify the tags
that the rest of the pipeline sees on a ``beet import`` operation or during
later adjustments, such as ``mbsync``. Slow handlers of the event can impact
the operation, since the event is fired for any fetched possible match
`before` the user (or the autotagger machinery) gets to see the match.
``before`` the user (or the autotagger machinery) gets to see the match.
Parameter: ``info``.
* `albuminfo_received`: like `trackinfo_received`, the event indicates new
* ``albuminfo_received``: like ``trackinfo_received``, the event indicates new
metadata for album items. The parameter is an ``AlbumInfo`` object instead
of a ``TrackInfo``.
Parameter: ``info``.
* `before_choose_candidate`: called before the user is prompted for a decision
* ``before_choose_candidate``: called before the user is prompted for a decision
during a ``beet import`` interactive session. Plugins can use this event for
:ref:`appending choices to the prompt <append_prompt_choices>` by returning a
list of ``PromptChoices``. Parameters: ``task`` and ``session``.
* `mb_track_extract`: called after the metadata is obtained from
MusicBrainz. The parameter is a ``dict`` containing the tags retrieved from
MusicBrainz for a track. Plugins must return a new (potentially empty)
``dict`` with additional ``field: value`` pairs, which the autotagger will
apply to the item, as flexible attributes if ``field`` is not a hardcoded
field. Fields already present on the track are overwritten.
* ``mb_track_extract``: called after the metadata is obtained from MusicBrainz.
The parameter is a ``dict`` containing the tags retrieved from MusicBrainz for
a track. Plugins must return a new (potentially empty) ``dict`` with
additional ``field: value`` pairs, which the autotagger will apply to the
item, as flexible attributes if ``field`` is not a hardcoded field. Fields
already present on the track are overwritten. Parameter: ``data``
* ``mb_album_extract``: Like ``mb_track_extract``, but for album tags.
Overwrites tags set at the track level, if they have the same ``field``.
Parameter: ``data``
* `mb_album_extract`: Like `mb_track_extract`, but for album tags. Overwrites
tags set at the track level, if they have the same ``field``.
Parameter: ``data``
The included ``mpdupdate`` plugin provides an example use case for event listeners.
The included ``mpdupdate`` plugin provides an example use case for event
listeners.
Extend the Autotagger
^^^^^^^^^^^^^^^^^^^^^
@ -330,10 +329,10 @@ Read Configuration Options
^^^^^^^^^^^^^^^^^^^^^^^^^^
Plugins can configure themselves using the ``config.yaml`` file. You can read
configuration values in two ways. The first is to use `self.config` within
configuration values in two ways. The first is to use ``self.config`` within
your plugin class. This gives you a view onto the configuration values in a
section with the same name as your plugin's module. For example, if your plugin
is in ``greatplugin.py``, then `self.config` will refer to options under the
is in ``greatplugin.py``, then ``self.config`` will refer to options under the
``greatplugin:`` section of the config file.
For example, if you have a configuration value called "foo", then users can put
@ -343,19 +342,19 @@ this in their ``config.yaml``::
foo: bar
To access this value, say ``self.config['foo'].get()`` at any point in your
plugin's code. The `self.config` object is a *view* as defined by the `Confuse`_
library.
plugin's code. The ``self.config`` object is a *view* as defined by the
`Confuse`_ library.
.. _Confuse: https://confuse.readthedocs.io/en/latest/
If you want to access configuration values *outside* of your plugin's section,
import the `config` object from the `beets` module. That is, just put ``from
import the ``config`` object from the ``beets`` module. That is, just put ``from
beets import config`` at the top of your plugin and access values from there.
If your plugin provides configuration values for sensitive data (e.g.,
passwords, API keys, ...), you should add these to the config so they can be
redacted automatically when users dump their config. This can be done by
setting each value's `redact` flag, like so::
setting each value's ``redact`` flag, like so::
self.config['password'].redact = True
@ -421,7 +420,7 @@ to extend the kinds of metadata that they can easily manage.
The ``MediaFile`` class uses ``MediaField`` descriptors to provide
access to file tags. If you have created a descriptor you can add it through
your plugins :py:meth:`beets.plugins.BeetsPlugin.add_media_field()`` method.
your plugins :py:meth:`beets.plugins.BeetsPlugin.add_media_field()` method.
.. _MediaFile: https://mediafile.readthedocs.io/en/latest/
@ -462,9 +461,9 @@ Multiple stages run in parallel but each stage processes only one task at a time
and each task is processed by only one stage at a time.
Plugins provide stages as functions that take two arguments: ``config`` and
``task``, which are ``ImportSession`` and ``ImportTask`` objects (both defined in
``beets.importer``). Add such a function to the plugin's ``import_stages`` field
to register it::
``task``, which are ``ImportSession`` and ``ImportTask`` objects (both defined
in ``beets.importer``). Add such a function to the plugin's ``import_stages``
field to register it::
from beets.plugins import BeetsPlugin
class ExamplePlugin(BeetsPlugin):
@ -543,11 +542,11 @@ should have an integer type::
def album_types(self):
return {'rating': types.INTEGER}
A plugin may define two attributes: `item_types` and `album_types`.
A plugin may define two attributes: ``item_types`` and ``album_types``.
Each of those attributes is a dictionary mapping a flexible field name
to a type instance. You can find the built-in types in the
`beets.dbcore.types` and `beets.library` modules or implement your own
type by inheriting from the `Type` class.
``beets.dbcore.types`` and ``beets.library`` modules or implement your own
type by inheriting from the ``Type`` class.
Specifying types has several advantages:

12
docs/faq.rst
View file

@ -161,12 +161,11 @@ it's helpful to run on the "bleeding edge". To run the latest source:
git clone https://github.com/beetbox/beets.git
poetry install
This approach lets you decide where the
source is stored, with any changes immediately reflected in your
environment.
This approach lets you decide where the source is stored, with any
changes immediately reflected in your environment.
More details about the beets source are available on the :doc:`developer documentation </dev/index>`
pages.
More details about the beets source are available on the :doc:`developer
documentation </dev/index>` pages.
.. _bugs:
@ -240,7 +239,8 @@ move all your files.
If you've already moved your music *outside* of beets, you have a few options:
- Move the music back (with an ordinary ``mv``) and then use the above steps.
- Delete your database and re-create it from the new paths using ``beet import -AWC``.
- Delete your database and re-create it from the new paths using ``beet import
-AWC``.
- Resort to manually modifying the SQLite database (not recommended).

4
docs/guides/advanced.rst
View file

@ -109,8 +109,8 @@ using the :ref:`modify-cmd` command::
By default, beets will show you the changes that are about to be applied and ask
if you really want to apply them to all, some or none of the items or albums.
You can type y for "yes", n for "no", or s for "select". If you choose the latter,
the command will prompt you for each individual matching item or album.
You can type y for "yes", n for "no", or s for "select". If you choose the
latter, the command will prompt you for each individual matching item or album.
Then :doc:`query </reference/query>` your music just as you would with any
other field::

50
docs/guides/main.rst
View file

@ -21,17 +21,14 @@ Beets works on Python 3.8 or later.
* On **Debian or Ubuntu**, depending on the version, beets is available as an
official package (`Debian details`_, `Ubuntu details`_), so try typing:
``apt-get install beets``. But the version in the repositories might lag
behind, so make sure you read the right version of these docs. If you want
the latest version, you can get everything you need to install with pip
as described below by running:
``apt-get install python-dev python-pip``
* On **Arch Linux**, `beets is in [extra] <Arch extra_>`_, so just run ``pacman -S
beets``. (There's also a bleeding-edge `dev package <AUR_>`_ in the AUR, which will
probably set your computer on fire.)
* On **Alpine Linux**, `beets is in the community repository <Alpine package_>`_
and can be installed with ``apk add beets``.
behind, so make sure you read the right version of these docs. If you want the
latest version, you can get everything you need to install with pip as
described below by running: ``apt-get install python-dev python-pip``
* On **Arch Linux**, `beets is in [extra] <Arch extra_>`_, so just run ``pacman
-S beets``. (There's also a bleeding-edge `dev package <AUR_>`_ in the AUR,
which will probably set your computer on fire.)
* On **Alpine Linux**, `beets is in the community repository <Alpine
package_>`_ and can be installed with ``apk add beets``.
* For **Gentoo Linux**, beets is in Portage as ``media-sound/beets``. Just run
``emerge beets`` to install. There are several USE flags available for
@ -39,15 +36,18 @@ Beets works on Python 3.8 or later.
* On **FreeBSD**, there's a `beets port <FreeBSD_>`_ at ``audio/beets``.
* On **OpenBSD**, there's a `beets port <OpenBSD_>`_ can be installed with ``pkg_add beets``.
* On **OpenBSD**, there's a `beets port <OpenBSD_>`_ can be installed with
``pkg_add beets``.
* For **Slackware**, there's a `SlackBuild`_ available.
* On **Fedora** 22 or later, there's a `DNF package`_ you can install with ``sudo dnf install beets beets-plugins beets-doc``.
* On **Fedora** 22 or later, there's a `DNF package`_ you can install with
``sudo dnf install beets beets-plugins beets-doc``.
* On **Solus**, run ``eopkg install beets``.
* On **NixOS**, there's a `package <NixOS_>`_ you can install with ``nix-env -i beets``.
* On **NixOS**, there's a `package <NixOS_>`_ you can install with ``nix-env -i
beets``.
.. _DNF package: https://packages.fedoraproject.org/pkgs/beets/
.. _SlackBuild: https://slackbuilds.org/repository/14.2/multimedia/beets/
@ -103,13 +103,13 @@ get it right:
box. If you do that, you can skip the next step.
2. If you haven't done so already, set your ``PATH`` environment variable to
include Python and its scripts. To do so, open the "Settings" application,
then access the "System" screen, then access the "About" tab, and then hit
"Advanced system settings" located on the right side of the screen. This
should open the "System Properties" screen, then select the "Advanced" tab,
then hit the "Environmental Variables..." button, and then look for the PATH
variable in the table. Add the following to the end of the variable's value:
``;C:\Python38;C:\Python38\Scripts``. You may need to adjust these paths to
include Python and its scripts. To do so, open the "Settings" application,
then access the "System" screen, then access the "About" tab, and then hit
"Advanced system settings" located on the right side of the screen. This
should open the "System Properties" screen, then select the "Advanced" tab,
then hit the "Environmental Variables..." button, and then look for the PATH
variable in the table. Add the following to the end of the variable's value:
``;C:\Python38;C:\Python38\Scripts``. You may need to adjust these paths to
point to your Python installation.
3. Now install beets by running: ``pip install beets``
@ -277,19 +277,21 @@ put the field before the term, separated by a : character. So ``album:bird``
only looks for ``bird`` in the "album" field of your songs. (Need to know more?
:doc:`/reference/query/` will answer all your questions.)
The ``beet list`` command also has an ``-a`` option, which searches for albums instead of songs::
The ``beet list`` command also has an ``-a`` option, which searches for albums
instead of songs::
$ beet ls -a forever
Bon Iver - For Emma, Forever Ago
Freezepop - Freezepop Forever
There's also an ``-f`` option (for *format*) that lets you specify what gets displayed in the results of a search::
There's also an ``-f`` option (for *format*) that lets you specify what gets
displayed in the results of a search::
$ beet ls -a forever -f "[$format] $album ($year) - $artist - $title"
[MP3] For Emma, Forever Ago (2009) - Bon Iver - Flume
[AAC] Freezepop Forever (2011) - Freezepop - Harebrained Scheme
In the format option, field references like `$format` and `$year` are filled
In the format option, field references like ``$format`` and ``$year`` are filled
in with data from each result. You can see a full list of available fields by
running ``beet fields``.

7
docs/guides/tagger.rst
View file

@ -268,9 +268,10 @@ files, but can get confused when files don't have any metadata (or have wildly
incorrect metadata). In this case, you need *acoustic fingerprinting*, a
technology that identifies songs from the audio itself. With fingerprinting,
beets can autotag files that have very bad or missing tags. The :doc:`"chroma"
plugin </plugins/chroma>`, distributed with beets, uses the `Chromaprint`_ open-source fingerprinting technology, but it's disabled by default. That's because
it's sort of tricky to install. See the :doc:`/plugins/chroma` page for a guide
to getting it set up.
plugin </plugins/chroma>`, distributed with beets, uses the `Chromaprint`_
open-source fingerprinting technology, but it's disabled by default. That's
because it's sort of tricky to install. See the :doc:`/plugins/chroma` page for
a guide to getting it set up.
Before you jump into acoustic fingerprinting with both feet, though, give beets
a try without it. You may be surprised at how well metadata-based matching

2
docs/plugins/absubmit.rst
View file

@ -25,7 +25,7 @@ Then, install ``beets`` with ``absubmit`` extra
pip install "beets[absubmit]"
Lastly, enable the plugin in your configuration (see :ref:`using-plugins`).
Lastly, enable the plugin in your configuration (see :ref:`using-plugins`).
Submitting Data

3
docs/plugins/acousticbrainz.rst
View file

@ -10,7 +10,8 @@ As an alternative the `beets-xtractor`_ plugin can be used.
.. _AcousticBrainz: https://acousticbrainz.org/
.. _beets-xtractor: https://github.com/adamjakab/BeetsPluginXtractor
Enable the ``acousticbrainz`` plugin in your configuration (see :ref:`using-plugins`) and run it by typing::
Enable the ``acousticbrainz`` plugin in your configuration (see
:ref:`using-plugins`) and run it by typing::
$ beet acousticbrainz [-f] [QUERY]

3
docs/plugins/albumtypes.rst
View file

@ -53,7 +53,8 @@ With path formats configured like::
comp: Various Artists/$album [$year]$atypes/...
The default plugin configuration generates paths that look like this, for example::
The default plugin configuration generates paths that look like this, for
example::
Aphex Twin/[1993][EP][Remix] On Remixes
Pink Floyd/[1995][Live] p·u·l·s·e

6
docs/plugins/autobpm.rst
View file

@ -1,8 +1,8 @@
AutoBPM Plugin
==============
The `autobpm` plugin uses the `Librosa`_ library to calculate the BPM
of a track from its audio data and store it in the `bpm` field of your
The ``autobpm`` plugin uses the `Librosa`_ library to calculate the BPM
of a track from its audio data and store it in the ``bpm`` field of your
database. It does so automatically when importing music or through
the ``beet autobpm [QUERY]`` command.
@ -26,7 +26,7 @@ configuration file. The available options are:
Otherwise, you need to use the ``beet autobpm`` command explicitly.
Default: ``yes``
- **overwrite**: Calculate a BPM even for files that already have a
`bpm` value.
``bpm`` value.
Default: ``no``.
- **beat_track_kwargs**: Any extra keyword arguments that you would like to
provide to librosa's `beat_track`_ function call, for example:

2
docs/plugins/badfiles.rst
View file

@ -26,7 +26,7 @@ Custom commands will be run once for each file of the specified type, with the
path to the file as the last argument. Commands must return a status code
greater than zero for a file to be considered corrupt.
You can run the checkers when importing files by using the `check_on_import`
You can run the checkers when importing files by using the ``check_on_import``
option. When on, checkers will be run against every imported file and warnings
and errors will be presented when selecting a tagging option.

44
docs/plugins/bareasc.rst
View file

@ -1,11 +1,11 @@
Bare-ASCII Search Plugin
========================
The ``bareasc`` plugin provides a prefixed query that searches your library using
simple ASCII character matching, with accented characters folded to their base
ASCII character. This can be useful if you want to find a track with accented
characters in the title or artist, particularly if you are not confident
you have the accents correct. It is also not unknown for the accents
The ``bareasc`` plugin provides a prefixed query that searches your library
using simple ASCII character matching, with accented characters folded to their
base ASCII character. This can be useful if you want to find a track with
accented characters in the title or artist, particularly if you are not
confident you have the accents correct. It is also not unknown for the accents
to not be correct in the database entry or wrong in the CD information.
First, enable the plugin named ``bareasc`` (see :ref:`using-plugins`).
@ -17,11 +17,12 @@ You'll then be able to use the ``#`` prefix to use bare-ASCII matching::
Command
-------
In addition to the query prefix, the plugin provides a utility ``bareasc`` command.
This command is **exactly** the same as the ``beet list`` command except that
the output is passed through the bare-ASCII transformation before being printed.
This allows you to easily check what the library data looks like in bare ASCII,
which can be useful if you are trying to work out why a query is not matching.
In addition to the query prefix, the plugin provides a utility ``bareasc``
command. This command is **exactly** the same as the ``beet list`` command
except that the output is passed through the bare-ASCII transformation before
being printed. This allows you to easily check what the library data looks like
in bare ASCII, which can be useful if you are trying to work out why a query is
not matching.
Using the same example track as above::
@ -37,19 +38,20 @@ Notes
If the query string is all in lower case, the comparison ignores case as well as
accents.
The default ``bareasc`` prefix (``#``) is used as a comment character in some shells
so may need to be protected (for example in quotes) when typed into the command line.
The default ``bareasc`` prefix (``#``) is used as a comment character in some
shells so may need to be protected (for example in quotes) when typed into the
command line.
The bare ASCII transliteration is quite simple. It may not give the expected output
for all languages. For example, German u-umlaut ``ü`` is transformed into ASCII ``u``,
not into ``ue``.
The bare ASCII transliteration is quite simple. It may not give the expected
output for all languages. For example, German u-umlaut ``ü`` is transformed into
ASCII ``u``, not into ``ue``.
The bare ASCII transformation also changes Unicode punctuation like double quotes,
apostrophes and even some hyphens. It is often best to leave out punctuation
in the queries. Note that the punctuation changes are often not even visible
with normal terminal fonts. You can always use the ``bareasc`` command to print the
transformed entries and use a command like ``diff`` to compare with the output
from the ``list`` command.
The bare ASCII transformation also changes Unicode punctuation like double
quotes, apostrophes and even some hyphens. It is often best to leave out
punctuation in the queries. Note that the punctuation changes are often not even
visible with normal terminal fonts. You can always use the ``bareasc`` command
to print the transformed entries and use a command like ``diff`` to compare with
the output from the ``list`` command.
Configuration
-------------

3
docs/plugins/beatport.rst
View file

@ -38,6 +38,7 @@ also search for an id like so::
Configuration
-------------
This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`.
This plugin can be configured like other metadata source plugins as described in
:ref:`metadata-source-plugin-configuration`.
.. _Beatport: https://www.beatport.com/

16
docs/plugins/bucket.rst
View file

@ -30,10 +30,10 @@ The definition of a range is somewhat loose, and multiple formats are allowed:
alphanumeric characters in the string you provide. For example, ``ABCD``,
``A-D``, ``A->D``, and ``[AD]`` are all equivalent.
- For year ranges: digits characters are extracted and the two extreme years
define the range. For example, ``1975-77``, ``1975,76,77`` and ``1975-1977`` are
equivalent. If no upper bound is given, the range is extended to current year
(unless a later range is defined). For example, ``1975`` encompasses all years
from 1975 until now.
define the range. For example, ``1975-77``, ``1975,76,77`` and ``1975-1977``
are equivalent. If no upper bound is given, the range is extended to current
year (unless a later range is defined). For example, ``1975`` encompasses all
years from 1975 until now.
The ``%bucket`` template function guesses whether to use alpha- or year-style
buckets depending on the text it receives. It can guess wrong if, for example,
@ -52,7 +52,7 @@ The available options are:
fields.
Default: none.
- **bucket_alpha_regex**: A ``range: regex`` mapping (one per line) where
``range`` is one of the `bucket_alpha` ranges and ``value`` is a regex that
``range`` is one of the ``bucket_alpha`` ranges and ``value`` is a regex that
overrides original range definition.
Default: none.
- **bucket_year**: Ranges to use for all substitutions occurring on the
@ -72,6 +72,6 @@ Here's an example::
bucket_alpha_regex:
'A - D': ^[0-9a-dA-D…äÄ]
This configuration creates five-year ranges for any input year.
The `A - D` bucket now matches also all artists starting with ä or Ä and 0 to 9
and … (ellipsis). The other alpha buckets work as ranges.
This configuration creates five-year ranges for any input year. The ``A - D``
bucket now matches also all artists starting with ä or Ä and 0 to 9 and …
(ellipsis). The other alpha buckets work as ranges.

2
docs/plugins/chroma.rst
View file

@ -23,7 +23,7 @@ If you're willing to pay the performance cost for fingerprinting, read on!
Installing Dependencies
-----------------------
To get fingerprinting working, you'll need to install three things:
To get fingerprinting working, you'll need to install three things:
1. `pyacoustid`_ Python library (version 0.6 or later). You can install it by
installing ``beets`` with ``chroma`` extra

30
docs/plugins/convert.rst
View file

@ -84,7 +84,7 @@ file. The available options are:
defined in your config file.
Default: ``no``.
.. note:: You probably want to use only one of the `auto` and `auto_keep`
.. note:: You probably want to use only one of the ``auto`` and ``auto_keep``
options, not both. Enabling both will convert your files twice on import,
which you probably don't want.
@ -108,8 +108,10 @@ file. The available options are:
a lower bitrate---that depends on the encoder and its configuration.
Default: none.
- **no_convert**: Does not transcode items matching the query string provided
(see :doc:`/reference/query`). For example, to not convert AAC or WMA formats, you can use ``format:AAC, format:WMA`` or
``path::\.(m4a|wma)$``. If you only want to transcode WMA format, you can use a negative query, e.g., ``^path::\.(wma)$``, to not convert any other format except WMA.
(see :doc:`/reference/query`). For example, to not convert AAC or WMA
formats, you can use ``format:AAC, format:WMA`` or ``path::\.(m4a|wma)$``. If
you only want to transcode WMA format, you can use a negative query, e.g.,
``^path::\.(wma)$``, to not convert any other format except WMA.
- **never_convert_lossy_files**: Cross-conversions between lossy codecs---such
as mp3, ogg vorbis, etc.---makes little sense as they will decrease quality
even further. If set to ``yes``, lossy files are always copied.
@ -127,18 +129,20 @@ file. The available options are:
to their destination. This option creates symbolic links instead. Note that
options such as ``embed`` that modify the output files after the transcoding
step will cause the original files to be modified as well if ``link`` is
enabled. For this reason, album-art embedding is disabled
for files that are linked.
enabled. For this reason, album-art embedding is disabled for files that are
linked.
Default: ``false``.
- **hardlink**: This options works similar to ``link``, but it creates
hard links instead of symlinks.
This option overrides ``link``. Only works when converting to a directory
on the same filesystem as the library.
- **hardlink**: This options works similar to ``link``, but it creates hard
links instead of symlinks. This option overrides ``link``. Only works when
converting to a directory on the same filesystem as the library.
Default: ``false``.
- **delete_originals**: Transcoded files will be copied or moved to their destination, depending on the import configuration. By default, the original files are not modified by the plugin. This option deletes the original files after the transcoding step has completed.
- **delete_originals**: Transcoded files will be copied or moved to their
destination, depending on the import configuration. By default, the original
files are not modified by the plugin. This option deletes the original files
after the transcoding step has completed.
Default: ``false``.
- **playlist**: The name of a playlist file that should be written on each run
of the plugin. A relative file path (e.g `playlists/mylist.m3u8`) is allowed
of the plugin. A relative file path (e.g ``playlists/mylist.m3u8``) is allowed
as well. The final destination of the playlist file will always be relative
to the destination path (``dest``, ``--dest``, ``-d``). This configuration is
overridden by the ``-m`` (``--playlist``) command line option.
@ -173,7 +177,7 @@ and select a command with the ``--format`` command-line option or the
wav: ffmpeg -i $source -y -acodec pcm_s16le $dest
In this example ``beet convert`` will use the *speex* command by
default. To convert the audio to `wav`, run ``beet convert -f wav``.
default. To convert the audio to ``wav``, run ``beet convert -f wav``.
This will also use the format key (``wav``) as the file extension.
Each entry in the ``formats`` map consists of a key (the name of the
@ -185,7 +189,7 @@ command to use to transcode audio. The tokens ``$source`` and ``$dest`` in the
command are replaced with the paths to the existing and new file.
The plugin in comes with default commands for the most common audio
formats: `mp3`, `alac`, `flac`, `aac`, `opus`, `ogg`, `wma`. For
formats: ``mp3``, ``alac``, ``flac``, ``aac``, ``opus``, ``ogg``, ``wma``. For
details have a look at the output of ``beet config -d``.
For a one-command-fits-all solution use the ``convert.command`` and

8
docs/plugins/deezer.rst
View file

@ -22,6 +22,10 @@ prompt during import::
Configuration
-------------
This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`.
This plugin can be configured like other metadata source plugins as described in
:ref:`metadata-source-plugin-configuration`.
The ``deezer`` plugin provides an additional command ``deezerupdate`` to update the ``rank`` information from Deezer. The ``rank`` (ranges from 0 to 1M) is a global indicator of a song's popularity on Deezer that is updated daily based on streams. The higher the ``rank``, the more popular the track is.
The ``deezer`` plugin provides an additional command ``deezerupdate`` to update
the ``rank`` information from Deezer. The ``rank`` (ranges from 0 to 1M) is a
global indicator of a song's popularity on Deezer that is updated daily based on
streams. The higher the ``rank``, the more popular the track is.

37
docs/plugins/discogs.rst
View file

@ -42,16 +42,17 @@ Subsequent runs will not require re-authorization.
Authentication via Personal Access Token
````````````````````````````````````````
As an alternative to OAuth, you can get a token from Discogs and add it to
your configuration.
To get a personal access token (called a "user token" in the `python3-discogs-client`_
documentation):
As an alternative to OAuth, you can get a token from Discogs and add it to your
configuration. To get a personal access token (called a "user token" in the
`python3-discogs-client`_ documentation):
#. login to `Discogs`_;
#. visit the `Developer settings page <https://www.discogs.com/settings/developers>`_;
#. visit the `Developer settings page
<https://www.discogs.com/settings/developers>`_;
#. press the *Generate new token* button;
#. copy the generated token;
#. place it in your configuration in the ``discogs`` section as the ``user_token`` option:
#. place it in your configuration in the ``discogs`` section as the
``user_token`` option:
.. code-block:: yaml
@ -62,13 +63,13 @@ documentation):
Configuration
-------------
This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`.
This plugin can be configured like other metadata source plugins as described in
:ref:`metadata-source-plugin-configuration`.
There is one additional option in the ``discogs:`` section, ``index_tracks``.
Index tracks (see the `Discogs guidelines
<https://support.discogs.com/hc/en-us/articles/360005055373-Database-Guidelines-12-Tracklisting#Index_Tracks_And_Headings>`_),
along with headers, mark divisions between distinct works on the same release
or within works. When ``index_tracks`` is enabled:
Index tracks (see the `Discogs guidelines`_) along with headers, mark divisions
between distinct works on the same release or within works. When
``index_tracks`` is enabled:
.. code-block:: yaml
@ -78,10 +79,7 @@ or within works. When ``index_tracks`` is enabled:
beets will incorporate the names of the divisions containing each track into
the imported track's title.
For example, importing
`this album
<https://www.discogs.com/Handel-Sutherland-Kirkby-Kwella-Nelson-Watkinson-Bowman-Rolfe-Johnson-Elliott-Partridge-Thomas-The-A/release/2026070>`_
would result in track names like:
For example, importing `divisions album`_ would result in track names like:
.. code-block:: text
@ -111,11 +109,13 @@ Other configurations available under ``discogs:`` are:
- **separator**: How to join multiple genre and style values from Discogs into
a string.
Default: ``", "``
- **search_limit**: The maximum number of results to return from Discogs. This is
useful if you want to limit the number of results returned to speed up
- **search_limit**: The maximum number of results to return from Discogs. This
is useful if you want to limit the number of results returned to speed up
searches.
Default: ``5``
.. _Divisions album: https://www.discogs.com/Handel-Sutherland-Kirkby-Kwella-Nelson-Watkinson-Bowman-Rolfe-Johnson-Elliott-Partridge-Thomas-The-A/release/2026070
.. _Discogs guidelines: https://support.discogs.com/hc/en-us/articles/360005055373-Database-Guidelines-12-Tracklisting#Index_Tracks_And_Headings
Troubleshooting
---------------
@ -132,6 +132,7 @@ Here are two things you can try:
your request if your clock is too out of sync.
Matching tracks by Discogs ID is not yet supported. The ``--group-albums``
option in album import mode provides an alternative to singleton mode for autotagging tracks that are not in album-related folders.
option in album import mode provides an alternative to singleton mode for
autotagging tracks that are not in album-related folders.
.. _python3-discogs-client: https://github.com/joalla/discogs_client

19
docs/plugins/embedart.rst
View file

@ -90,15 +90,16 @@ Manually Embedding and Extracting Art
The ``embedart`` plugin provides a couple of commands for manually managing
embedded album art:
* ``beet embedart [-f IMAGE] QUERY``: embed images in every track of the
albums matching the query. If the ``-f`` (``--file``) option is given, then
use a specific image file from the filesystem; otherwise, each album embeds
its own currently associated album art. The command prompts for confirmation
before making the change unless you specify the ``-y`` (``--yes``) option.
* ``beet embedart [-u IMAGE_URL] QUERY``: embed image specified in the URL
into every track of the albums matching the query. The ``-u`` (``--url``) option can be used to specify the URL of the image to be used. The command prompts for confirmation before making the change unless you specify the ``-y`` (``--yes``) option.
* ``beet embedart [-f IMAGE] QUERY``: embed images in every track of the albums
matching the query. If the ``-f`` (``--file``) option is given, then use a
specific image file from the filesystem; otherwise, each album embeds its own
currently associated album art. The command prompts for confirmation before
making the change unless you specify the ``-y`` (``--yes``) option.
* ``beet embedart [-u IMAGE_URL] QUERY``: embed image specified in the URL into
every track of the albums matching the query. The ``-u`` (``--url``) option
can be used to specify the URL of the image to be used. The command prompts
for confirmation before making the change unless you specify the ``-y``
(``--yes``) option.
* ``beet extractart [-a] [-n FILE] QUERY``: extracts the images for all albums
matching the query. The images are placed inside the album folder. You can
specify the destination file name using the ``-n`` option, but leave off the

9
docs/plugins/embyupdate.rst
View file

@ -22,7 +22,8 @@ that using an ``emby`` section in your ``config.yaml``
username: user
apikey: apikey
With that all in place, you'll see beets send the "update" command to your Emby server every time you change your beets library.
With that all in place, you'll see beets send the "update" command to your Emby
server every time you change your beets library.
.. _Emby: https://emby.media/
@ -31,11 +32,13 @@ Configuration
The available options under the ``emby:`` section are:
- **host**: The Emby server host. You also can include ``http://`` or ``https://``.
- **host**: The Emby server host. You also can include ``http://`` or
``https://``.
Default: ``localhost``
- **port**: The Emby server port.
Default: 8096
- **username**: A username of an Emby user that is allowed to refresh the library.
- **username**: A username of an Emby user that is allowed to refresh the
library.
- **userid**: A user ID of an Emby user that is allowed to refresh the library.
(This is only necessary for private users i.e. when the user is hidden from
login screens)

16
docs/plugins/export.rst
View file

@ -8,8 +8,9 @@ as `JSON`_, `CSV`_, or `XML`_.
.. _CSV: https://fileinfo.com/extension/csv
.. _XML: https://fileinfo.com/extension/xml
Enable the ``export`` plugin (see :ref:`using-plugins` for help). Then, type ``beet export`` followed by a :doc:`query </reference/query>` to get the data from
your library. For example, run this::
Enable the ``export`` plugin (see :ref:`using-plugins` for help). Then, type
``beet export`` followed by a :doc:`query </reference/query>` to get the data
from your library. For example, run this::
$ beet export beatles
@ -39,10 +40,10 @@ The ``export`` command has these command-line options:
* ``--output`` or ``-o``: Path for an output file. If not informed, will print
the data in the console.
* ``--append``: Appends the data to the file instead of writing.
* ``--format`` or ``-f``: Specifies the format the data will be exported as. If not informed, JSON will be used by default. The format options include csv, json, `jsonlines <https://jsonlines.org/>`_ and xml.
* ``--format`` or ``-f``: Specifies the format the data will be exported as. If
not informed, JSON will be used by default. The format options include csv,
json, `jsonlines <https://jsonlines.org/>`_ and xml.
Configuration
-------------
@ -61,8 +62,9 @@ Those options match the options from the `Python json module`_.
Similarly, these options are available for the CSV format under the ``csv``
key:
- **delimiter**: Used as the separating character between fields. The default value is a comma (,).
- **dialect**: The kind of CSV file to produce. The default is `excel`.
- **delimiter**: Used as the separating character between fields. The default
value is a comma (,).
- **dialect**: The kind of CSV file to produce. The default is ``excel``.
These options match the options from the `Python csv module`_.

34
docs/plugins/fetchart.rst
View file

@ -63,7 +63,7 @@ file. The available options are:
still be considered valid. This can be done either in pixels
(``enforce_ratio: 10px``) or as a percentage of the longer edge
(``enforce_ratio: 0.5%``). Default: ``no``.
- **sources**: List of sources to search for images. An asterisk `*` expands
- **sources**: List of sources to search for images. An asterisk ``*`` expands
to all available sources.
Default: ``filesystem coverart itunes amazon albumart``, i.e., everything but
``wikipedia``, ``google``, ``fanarttv`` and ``lastfm``. Enable those sources
@ -143,8 +143,8 @@ be processed; otherwise, the command processes every album in your library.
Display Only Missing Album Art
------------------------------
Use the ``fetchart`` command with the ``-q`` switch in order to display only missing
art::
Use the ``fetchart`` command with the ``-q`` switch in order to display only
missing art::
$ beet fetchart [-q] [query]
@ -157,12 +157,13 @@ fetched, or for which artwork could not be found will be printed.
Image Resizing
--------------
Beets can resize images using `Pillow`_, `ImageMagick`_, or a server-side resizing
proxy. If either Pillow or ImageMagick is installed, beets will use those;
otherwise, it falls back to the resizing proxy. If the resizing proxy is used,
no resizing is performed for album art found on the filesystem---only downloaded
art is resized. Server-side resizing can also be slower than local resizing, so
consider installing one of the two backends for better performance.
Beets can resize images using `Pillow`_, `ImageMagick`_, or a server-side
resizing proxy. If either Pillow or ImageMagick is installed, beets will use
those; otherwise, it falls back to the resizing proxy. If the resizing proxy is
used, no resizing is performed for album art found on the filesystem---only
downloaded art is resized. Server-side resizing can also be slower than local
resizing, so consider installing one of the two backends for better
performance.
When using ImageMagick, beets looks for the ``convert`` executable in your path.
On some versions of Windows, the program can be shadowed by a system-provided
@ -258,7 +259,8 @@ the list of sources in your configuration.
Spotify
'''''''
Spotify backend is enabled by default and will update album art if a valid Spotify album id is found.
Spotify backend is enabled by default and will update album art if a valid
Spotify album id is found.
.. _pip: https://pip.pypa.io
.. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/bs4/doc/
@ -266,10 +268,10 @@ Spotify backend is enabled by default and will update album art if a valid Spoti
Cover Art URL
'''''''''''''
The `fetchart` plugin can also use a flexible attribute field ``cover_art_url``
where you can manually specify the image URL to be used as cover art. Any custom
plugin can use this field to provide the cover art and ``fetchart`` will use it
as a source.
The ``fetchart`` plugin can also use a flexible attribute field
``cover_art_url`` where you can manually specify the image URL to be used as
cover art. Any custom plugin can use this field to provide the cover art and
``fetchart`` will use it as a source.
.. _cover-art-archive-maxwidth:
@ -277,8 +279,8 @@ Cover Art Archive Pre-sized Thumbnails
--------------------------------------
The CAA provides pre-sized thumbnails of width 250, 500, and 1200 pixels. If you
set the `maxwidth` option to one of these values, the corresponding image will
be downloaded, saving `beets` the need to scale down the image. It can also
set the ``maxwidth`` option to one of these values, the corresponding image will
be downloaded, saving ``beets`` the need to scale down the image. It can also
speed up the downloading process, as some cover arts can sometimes be very
large.

14
docs/plugins/fish.rst
View file

@ -41,13 +41,13 @@ commands and option flags.
If you want generated completions to also contain album/track field *values* for
the items in your library, you can use the ``-e`` or ``--extravalues`` option.
For example: ``beet fish -e genre`` or ``beet fish -e genre -e albumartist``
In the latter case, subsequently typing ``beet list genre: <TAB>`` will display
a list of all the genres in your library and ``beet list albumartist: <TAB>``
will show a list of the album artists in your library. Keep in mind that all of
these values will be put into the generated completions file, so use this option
with care when specified fields contain a large number of values. Libraries with,
for example, very large numbers of genres/artists may result in higher memory
For example: ``beet fish -e genre`` or ``beet fish -e genre -e albumartist`` In
the latter case, subsequently typing ``beet list genre: <TAB>`` will display a
list of all the genres in your library and ``beet list albumartist: <TAB>`` will
show a list of the album artists in your library. Keep in mind that all of these
values will be put into the generated completions file, so use this option with
care when specified fields contain a large number of values. Libraries with, for
example, very large numbers of genres/artists may result in higher memory
utilization, completion latency, et cetera. This option is not meant to replace
database queries altogether.

5
docs/plugins/ftintitle.rst
View file

@ -24,8 +24,9 @@ file. The available options are:
- **drop**: Remove featured artists entirely instead of adding them to the
title field.
Default: ``no``.
- **format**: Defines the format for the featuring X part of the new title field.
In this format the ``{0}`` is used to define where the featured artists are placed.
- **format**: Defines the format for the featuring X part of the new title
field. In this format the ``{0}`` is used to define where the featured
artists are placed.
Default: ``feat. {0}``
- **keep_in_artist**: Keep the featuring X part in the artist field. This can
be useful if you still want to be able to search for features in the artist

31
docs/plugins/index.rst
View file

@ -13,7 +13,8 @@ Using Plugins
-------------
To use one of the plugins included with beets (see the rest of this page for a
list), just use the ``plugins`` option in your :doc:`config.yaml </reference/config>` file:
list), just use the ``plugins`` option in your :doc:`config.yaml
</reference/config>` file:
.. code-block:: sh
@ -23,7 +24,8 @@ The value for ``plugins`` can be a space-separated list of plugin names or a
YAML list like ``[foo, bar]``. You can see which plugins are currently enabled
by typing ``beet version``.
Each plugin has its own set of options that can be defined in a section bearing its name:
Each plugin has its own set of options that can be defined in a section bearing
its name:
.. code-block:: yaml
@ -176,7 +178,8 @@ Metadata
--------
:doc:`absubmit <absubmit>`
Analyse audio with the `streaming_extractor_music`_ program and submit the metadata to an AcousticBrainz server
Analyse audio with the `streaming_extractor_music`_ program and submit the
metadata to an AcousticBrainz server
:doc:`acousticbrainz <acousticbrainz>`
Fetch various AcousticBrainz metadata
@ -209,7 +212,7 @@ Metadata
:doc:`importadded <importadded>`
Use file modification times for guessing the value for
the `added` field in the database.
the ``added`` field in the database.
:doc:`lastgenre <lastgenre>`
Fetch genres based on Last.fm tags.
@ -415,9 +418,8 @@ are two options for installation:
* Make sure it's in the Python path (known as ``sys.path`` to developers). This
just means the plugin has to be installed on your system (e.g., with a
``setup.py`` script or a command like ``pip`` or ``easy_install``).
* Set the ``pluginpath`` config variable to point to the directory containing the
plugin. (See :doc:`/reference/config`.)
* Set the ``pluginpath`` config variable to point to the directory containing
the plugin. (See :doc:`/reference/config`.)
Once the plugin is installed, enable it by placing its name on the ``plugins``
line in your config file.
@ -449,7 +451,8 @@ Here are a few of the plugins written by the beets community:
search for their metadata.
`beetcamp`_
Enables **bandcamp.com** autotagger with a fairly extensive amount of metadata.
Enables **bandcamp.com** autotagger with a fairly extensive amount of
metadata.
`beetstream`_
Server implementation of the `Subsonic API`_ specification, serving the
@ -481,7 +484,7 @@ Here are a few of the plugins written by the beets community:
`beets-filetote`_
Helps bring non-music extra files, attachments, and artifacts during
imports and CLI file manipulation actions (`beet move`, etc.).
imports and CLI file manipulation actions (``beet move``, etc.).
`beets-follow`_
Lets you check for new albums from artists you like.
@ -507,13 +510,15 @@ Here are a few of the plugins written by the beets community:
Adds JioSaavn.com as a tagger data source.
`beets-more`_
Finds versions of indexed releases with more tracks, like deluxe and anniversary editions.
Finds versions of indexed releases with more tracks, like deluxe and
anniversary editions.
`beets-mosaic`_
Generates a montage of a mosaic from cover art.
`beets-mpd-utils`_
Plugins to interface with `MPD`_. Comes with ``mpd_tracker`` (track play/skip counts from MPD) and ``mpd_dj`` (auto-add songs to your queue.)
Plugins to interface with `MPD`_. Comes with ``mpd_tracker`` (track
play/skip counts from MPD) and ``mpd_dj`` (auto-add songs to your queue.)
`beets-noimport`_
Adds and removes directories from the incremental import skip list.
@ -523,7 +528,9 @@ Here are a few of the plugins written by the beets community:
to improve autotagger results.
`beets-plexsync`_
Allows you to sync your Plex library with your beets library, create smart playlists in Plex, and import online playlists (from services like Spotify) into Plex.
Allows you to sync your Plex library with your beets library, create smart
playlists in Plex, and import online playlists (from services like Spotify)
into Plex.
`beets-setlister`_
Generate playlists from the setlists of a given artist.

15
docs/plugins/inline.rst
View file

@ -6,14 +6,13 @@ 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.
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::

5
docs/plugins/ipfs.rst
View file

@ -71,4 +71,7 @@ The ipfs plugin will automatically add imported albums to ipfs and add those
hashes to the database. This can be turned off by setting the ``auto`` option
in the ``ipfs:`` section of the config to ``no``.
If the setting ``nocopy`` is true (defaults false) then the plugin will pass the ``--nocopy`` option when adding things to ipfs. If the filestore option of ipfs is enabled this will mean files are neither removed from beets nor copied somewhere else.
If the setting ``nocopy`` is true (defaults false) then the plugin will pass the
``--nocopy`` option when adding things to ipfs. If the filestore option of ipfs
is enabled this will mean files are neither removed from beets nor copied
somewhere else.

6
docs/plugins/keyfinder.rst
View file

@ -1,9 +1,9 @@
Key Finder Plugin
=================
The `keyfinder` plugin uses either the `KeyFinder`_ or `keyfinder-cli`_
The ``keyfinder`` plugin uses either the `KeyFinder`_ or `keyfinder-cli`_
program to detect the musical key of a track from its audio data and store
it in the `initial_key` field of your database. It does so
it in the ``initial_key`` field of your database. It does so
automatically when importing music or through the ``beet keyfinder
[QUERY]`` command.
@ -28,7 +28,7 @@ configuration file. The available options are:
If using `keyfinder-cli`_, the binary must be named ``keyfinder-cli``.
Default: ``KeyFinder`` (i.e., search for the program in your ``$PATH``)..
- **overwrite**: Calculate a key even for files that already have an
`initial_key` value.
``initial_key`` value.
Default: ``no``.
.. _KeyFinder: http://www.ibrahimshaath.co.uk/keyfinder/

3
docs/plugins/kodiupdate.rst
View file

@ -38,7 +38,8 @@ To use the ``kodiupdate`` plugin, first enable it in your configuration (see
You'll also need to enable JSON-RPC in Kodi.
In Kodi's interface, navigate to System/Settings/Network/Services and choose "Allow control of Kodi via HTTP."
In Kodi's interface, navigate to System/Settings/Network/Services and choose
"Allow control of Kodi via HTTP."
With that all in place, you'll see beets send the "update" command to your Kodi
host every time you change your beets library.

25
docs/plugins/lastgenre.rst
View file

@ -1,9 +1,8 @@
LastGenre Plugin
================
The ``lastgenre`` plugin fetches *tags* from `Last.fm`_ and assigns them as genres
to your albums and items.
The ``lastgenre`` plugin fetches *tags* from `Last.fm`_ and assigns them as
genres to your albums and items.
.. _Last.fm: https://last.fm/
@ -39,8 +38,8 @@ Canonicalization
The plugin can also *canonicalize* genres, meaning that more obscure genres can
be turned into coarser-grained ones that are present in the whitelist. This
works using a `tree of nested genre names`_, represented using `YAML`_, where the
leaves of the tree represent the most specific genres.
works using a `tree of nested genre names`_, represented using `YAML`_, where
the leaves of the tree represent the most specific genres.
The most common way to use this would be with a custom whitelist containing only
a desired subset of genres. Consider for a example this minimal whitelist::
@ -154,8 +153,8 @@ make sure any existing genres remain, set ``whitelist: no``).
keep_existing: yes
.. attention::
If ``force`` is disabled the ``keep_existing`` option is simply ignored (since ``force:
no`` means `not touching` existing tags anyway).
If ``force`` is disabled the ``keep_existing`` option is simply ignored
(since ``force: no`` means ``not touching`` existing tags anyway).
@ -173,9 +172,9 @@ configuration file. The available options are:
Default: ``no`` (disabled).
- **count**: Number of genres to fetch.
Default: 1
- **fallback**: A string to use as a fallback genre when no genre is found `or`
the original genre is not desired to be kept (``keep_existing: no``). You can
use the empty string ``''`` to reset the genre.
- **fallback**: A string to use as a fallback genre when no genre is found
``or`` the original genre is not desired to be kept (``keep_existing: no``).
You can use the empty string ``''`` to reset the genre.
Default: None.
- **force**: By default, lastgenre will fetch new genres for empty tags only,
enable this option to always try to fetch new last.fm genres. Enable the
@ -214,9 +213,9 @@ configuration file. The available options are:
Running Manually
----------------
In addition to running automatically on import, the plugin can also be run manually
from the command line. Use the command ``beet lastgenre [QUERY]`` to fetch
genres for albums or items matching a certain query.
In addition to running automatically on import, the plugin can also be run
manually from the command line. Use the command ``beet lastgenre [QUERY]`` to
fetch genres for albums or items matching a certain query.
By default, ``beet lastgenre`` matches albums. To match
individual tracks or singletons, use the ``-A`` switch:

32
docs/plugins/limit.rst
View file

@ -1,32 +1,32 @@
Limit Query Plugin
==================
``limit`` is a plugin to limit a query to the first or last set of
results. We also provide a query prefix ``'<n'`` to inline the same
``limit`` is a plugin to limit a query to the first or last set of
results. We also provide a query prefix ``'<n'`` to inline the same
behavior in the ``list`` command. They are analogous to piping results:
$ beet [list|ls] [QUERY] | [head|tail] -n n
There are two provided interfaces:
1. ``beet lslimit [--head n | --tail n] [QUERY]`` returns the head or
1. ``beet lslimit [--head n | --tail n] [QUERY]`` returns the head or
tail of a query
2. ``beet [list|ls] [QUERY] '<n'`` returns the head of a query
There are two differences in behavior:
There are two differences in behavior:
1. The query prefix does not support tail.
2. The query prefix could appear anywhere in the query but will only
have the same behavior as the ``lslimit`` command and piping to ``head``
2. The query prefix could appear anywhere in the query but will only
have the same behavior as the ``lslimit`` command and piping to ``head``
when it appears last.
Performance for the query previx is much worse due to the current
singleton-based implementation.
Performance for the query previx is much worse due to the current
singleton-based implementation.
So why does the query prefix exist? Because it composes with any other
query-based API or plugin (see :doc:`/reference/query`). For example,
So why does the query prefix exist? Because it composes with any other
query-based API or plugin (see :doc:`/reference/query`). For example,
you can use the query prefix in ``smartplaylist``
(see :doc:`/plugins/smartplaylist`) to limit the number of tracks in a smart
playlist for applications like most played and recently added.
@ -42,17 +42,23 @@ Examples
First 10 tracks
$ beet ls | head -n 10
$ beet lslimit --head 10
$ beet ls '<10'
.. code-block:: sh
$ beet ls | head -n 10
$ beet lslimit --head 10
$ beet ls '<10'
Last 10 tracks
.. code-block:: sh
$ beet ls | tail -n 10
$ beet lslimit --tail 10
100 mostly recently released tracks
.. code-block:: sh
$ beet lslimit --head 100 year- month- day-
$ beet ls year- month- day- '<100'
$ beet lslimit --tail 100 year+ month+ day+

12
docs/plugins/listenbrainz.rst
View file

@ -3,19 +3,22 @@
ListenBrainz Plugin
===================
The ListenBrainz plugin for beets allows you to interact with the ListenBrainz service.
The ListenBrainz plugin for beets allows you to interact with the ListenBrainz
service.
Installation
------------
To enable the ListenBrainz plugin, add the following to your beets configuration file (`config.yaml`_):
To enable the ListenBrainz plugin, add the following to your beets
configuration file (`config.yaml`_):
.. code-block:: yaml
plugins:
- listenbrainz
You can then configure the plugin by providing your Listenbrainz token (see intructions `here`_) and username::
You can then configure the plugin by providing your Listenbrainz token (see
intructions `here`_) and username::
listenbrainz:
token: TOKEN
@ -25,7 +28,8 @@ You can then configure the plugin by providing your Listenbrainz token (see intr
Usage
-----
Once the plugin is enabled, you can import the listening history using the `lbimport` command in beets.
Once the plugin is enabled, you can import the listening history using the
``lbimport`` command in beets.
.. _here: https://listenbrainz.readthedocs.io/en/latest/users/api/index.html#get-the-user-token

2
docs/plugins/loadext.rst
View file

@ -49,5 +49,5 @@ specifics may vary from system to system):
$ wget https://sqlite.org/2019/sqlite-src-3280000.zip
$ unzip sqlite-src-3280000.zip
$ cd sqlite-src-3280000/ext/icu
$ gcc -shared -fPIC icu.c `icu-config --ldflags` -o libicu.so
$ gcc -shared -fPIC icu.c $(icu-config --ldflags) -o libicu.so
$ cp libicu.so ~/.config/beets

3
docs/plugins/mbsubmit.rst
View file

@ -44,7 +44,8 @@ choice is demonstrated::
[U]se as-is, as Tracks, Group albums, Skip, Enter search, enter Id, aBort,
Print tracks?
You can also run ``beet mbsubmit QUERY`` to print the track information for any album::
You can also run ``beet mbsubmit QUERY`` to print the track information for any
album::
$ beet mbsubmit album:"An Obscure Album"
01. An Obscure Track - An Obscure Artist (3:37)

16
docs/plugins/mpdstats.rst
View file

@ -9,9 +9,9 @@ habits from `MPD`_. It collects the following information about tracks:
* ``last_played``: UNIX timestamp when you last played this track.
* ``rating``: A rating based on ``play_count`` and ``skip_count``.
To gather these statistics it runs as an MPD client and watches the current state
of MPD. This means that ``mpdstats`` needs to be running continuously for it to
work.
To gather these statistics it runs as an MPD client and watches the current
state of MPD. This means that ``mpdstats`` needs to be running continuously for
it to work.
.. _MPD: https://www.musicpd.org/
@ -50,16 +50,16 @@ configuration file. The available options are:
- **music_directory**: If your MPD library is at a different location from the
beets library (e.g., because one is mounted on a NFS share), specify the path
here.
- **strip_path**: If your MPD library contains local path, specify the part to remove
here. Combining this with **music_directory** you can mangle MPD path to match the
beets library one.
- **strip_path**: If your MPD library contains local path, specify the part to
remove here. Combining this with **music_directory** you can mangle MPD path
to match the beets library one.
Default: The beets library directory.
- **rating**: Enable rating updates.
Default: ``yes``.
- **rating_mix**: Tune the way rating is calculated (see below).
Default: 0.75.
- **played_ratio_threshold**: If a song was played for less than this percentage
of its duration it will be considered a skip.
- **played_ratio_threshold**: If a song was played for less than this
percentage of its duration it will be considered a skip.
Default: 0.85
A Word on Ratings

9
docs/plugins/mpdupdate.rst
View file

@ -20,9 +20,9 @@ which looks like this::
With that all in place, you'll see beets send the "update" command to your MPD
server every time you change your beets library.
If you want to communicate with MPD over a Unix domain socket instead over
TCP, just give the path to the socket in the filesystem for the ``host``
setting. (Any ``host`` value starting with a slash or a tilde is interpreted as a domain
If you want to communicate with MPD over a Unix domain socket instead over TCP,
just give the path to the socket in the filesystem for the ``host`` setting.
(Any ``host`` value starting with a slash or a tilde is interpreted as a domain
socket.)
Configuration
@ -31,7 +31,8 @@ Configuration
The available options under the ``mpd:`` section are:
- **host**: The MPD server name.
Default: The ``$MPD_HOST`` environment variable if set, falling back to ``localhost`` otherwise.
Default: The ``$MPD_HOST`` environment variable if set, falling back to
``localhost`` otherwise.
- **port**: The MPD server port.
Default: The ``$MPD_PORT`` environment variable if set, falling back to 6600
otherwise.

25
docs/plugins/musicbrainz.rst
View file

@ -51,15 +51,16 @@ under a ``musicbrainz:`` header, like so
ratelimit: 100
The ``host`` key, of course, controls the Web server hostname (and port,
optionally) that will be contacted by beets (default: musicbrainz.org).
The ``https`` key makes the client use HTTPS instead of HTTP. This setting applies
only to custom servers. The official MusicBrainz server always uses HTTPS. (Default: no.)
The server must have search indices enabled (see `Building search indexes`_).
optionally) that will be contacted by beets (default: musicbrainz.org). The
``https`` key makes the client use HTTPS instead of HTTP. This setting applies
only to custom servers. The official MusicBrainz server always uses HTTPS.
(Default: no.) The server must have search indices enabled (see `Building search
indexes`_).
The ``ratelimit`` option, an integer, controls the number of Web service requests
per second (default: 1). **Do not change the rate limit setting** if you're
using the main MusicBrainz server---on this public server, you're `limited`_
to one request per second.
The ``ratelimit`` option, an integer, controls the number of Web service
requests per second (default: 1). **Do not change the rate limit setting** if
you're using the main MusicBrainz server---on this public server, you're
`limited`_ to one request per second.
.. _your own MusicBrainz database: https://musicbrainz.org/doc/MusicBrainz_Server/Setup
.. _main server: https://musicbrainz.org/
@ -72,11 +73,11 @@ enabled
~~~~~~~
.. deprecated:: 2.3
Add `musicbrainz` to the `plugins` list instead.
Add ``musicbrainz`` to the ``plugins`` list instead.
This option allows you to disable using MusicBrainz as a metadata source. This applies
if you use plugins that fetch data from alternative sources and should make the import
process quicker.
This option allows you to disable using MusicBrainz as a metadata source. This
applies if you use plugins that fetch data from alternative sources and should
make the import process quicker.
Default: ``yes``.

4
docs/plugins/parentwork.rst
View file

@ -37,7 +37,7 @@ This plugin adds seven tags:
that has a composition date. Format: yyyy-mm-dd.
- **parentwork_workid_current**: The MusicBrainz id of the work as it was when
the parentwork was retrieved. This tag exists only for internal bookkeeping,
to keep track of recordings whose works have changed.
to keep track of recordings whose works have changed.
- **parentwork_date**: The composition date of the parent work.
To use the ``parentwork`` plugin, enable it in your configuration (see
@ -50,7 +50,7 @@ To configure the plugin, make a ``parentwork:`` section in your
configuration file. The available options are:
- **force**: As a default, ``parentwork`` only fetches work info for
recordings that do not already have a ``parentwork`` tag or where
recordings that do not already have a ``parentwork`` tag or where
``mb_workid`` differs from ``parentwork_workid_current``. If ``force``
is enabled, it fetches it for all recordings.
Default: ``no``

3
docs/plugins/permissions.rst
View file

@ -12,7 +12,8 @@ Configuration
To configure the plugin, make an ``permissions:`` section in your configuration
file. The ``file`` config value therein uses **octal modes** to specify the
desired permissions. The default flags for files are octal 644 and 755 for directories.
desired permissions. The default flags for files are octal 644 and 755 for
directories.
Here's an example::

16
docs/plugins/play.rst
View file

@ -33,8 +33,8 @@ Interactive Usage
-----------------
The ``play`` plugin can also be invoked during an import. If enabled, the plugin
adds a ``plaY`` option to the prompt, so pressing ``y`` will execute the configured
command and play the items currently being imported.
adds a ``plaY`` option to the prompt, so pressing ``y`` will execute the
configured command and play the items currently being imported.
Once the configured command exits, you will be returned to the import
decision prompt. If your player is configured to run in the background (in a
@ -99,7 +99,7 @@ indicates that you need to insert extra arguments before specifying the
playlist.
The ``--yes`` (or ``-y``) flag to the ``play`` command will skip the warning
message if you choose to play more items than the **warning_threshold**
message if you choose to play more items than the **warning_threshold**
value usually allows.
Note on the Leakage of the Generated Playlists
@ -108,10 +108,10 @@ Note on the Leakage of the Generated Playlists
Because the command that will open the generated ``.m3u`` files can be
arbitrarily configured by the user, beets won't try to delete those files. For
this reason, using this plugin will leave one or several playlist(s) in the
directory selected to create temporary files (Most likely ``/tmp/`` on Unix-like
systems. See `tempfile.tempdir`_ in the Python docs.). Leaking those playlists until
they are externally wiped could be an issue for privacy or storage reasons. If
this is the case for you, you might want to use the ``raw`` config option
described above.
directory selected to create temporary files (Most likely ``/tmp/`` on
Unix-like systems. See `tempfile.tempdir`_ in the Python docs.). Leaking those
playlists until they are externally wiped could be an issue for privacy or
storage reasons. If this is the case for you, you might want to use the ``raw``
config option described above.
.. _tempfile.tempdir: https://docs.python.org/2/library/tempfile.html#tempfile.tempdir

12
docs/plugins/plexupdate.rst
View file

@ -10,9 +10,9 @@ Firstly, install ``beets`` with ``plexupdate`` extra
pip install "beets[plexupdate]"
Then, enable ``plexupdate`` plugin it in your configuration (see :ref:`using-plugins`).
Optionally, configure the specifics of your Plex server. You can do this using
a ``plex:`` section in your ``config.yaml``:
Then, enable ``plexupdate`` plugin it in your configuration (see
:ref:`using-plugins`). Optionally, configure the specifics of your Plex server.
You can do this using a ``plex:`` section in your ``config.yaml``:
.. code-block:: yaml
@ -21,7 +21,8 @@ a ``plex:`` section in your ``config.yaml``:
port: 32400
token: "TOKEN"
The ``token`` key is optional: you'll need to use it when in a Plex Home (see Plex's own `documentation about tokens`_).
The ``token`` key is optional: you'll need to use it when in a Plex Home (see
Plex's own `documentation about tokens`_).
With that all in place, you'll see beets send the "update" command to your Plex
server every time you change your beets library.
@ -44,5 +45,6 @@ The available options under the ``plex:`` section are:
Default: ``Music``
- **secure**: Use secure connections to the Plex server.
Default: ``False``
- **ignore_cert_errors**: Ignore TLS certificate errors when using secure connections.
- **ignore_cert_errors**: Ignore TLS certificate errors when using secure
connections.
Default: ``False``

2
docs/plugins/replace.rst
View file

@ -13,5 +13,5 @@ and then type::
The plugin will show you a list of files for you to pick from, and then
ask for confirmation.
Consider using the `replaygain` command from the
Consider using the ``replaygain`` command from the
:doc:`/plugins/replaygain` plugin, if you usually use it during imports.

26
docs/plugins/replaygain.rst
View file

@ -28,7 +28,8 @@ GStreamer
To use `GStreamer`_ for ReplayGain analysis, you will of course need to
install GStreamer and plugins for compatibility with your audio files.
You will need at least GStreamer 1.0 and `PyGObject 3.x`_ (a.k.a. ``python-gi``).
You will need at least GStreamer 1.0 and `PyGObject 3.x`_ (a.k.a.
``python-gi``).
.. _PyGObject 3.x: https://pygobject.readthedocs.io/en/latest/
.. _GStreamer: https://gstreamer.freedesktop.org/
@ -108,17 +109,16 @@ configuration file. The available options are:
- **auto**: Enable ReplayGain analysis during import.
Default: ``yes``.
- **threads**: The number of parallel threads to run the analysis in. Overridden
by ``--threads`` at the command line.
- **threads**: The number of parallel threads to run the analysis in.
Overridden by ``--threads`` at the command line.
Default: # of logical CPU cores
- **parallel_on_import**: Whether to enable parallel analysis during import.
As of now this ReplayGain data is not written to files properly, so this option
is disabled by default.
If you wish to enable it, remember to run ``beet write`` after importing to
actually write to the imported files.
- **parallel_on_import**: Whether to enable parallel analysis during import. As
of now this ReplayGain data is not written to files properly, so this option
is disabled by default. If you wish to enable it, remember to run ``beet
write`` after importing to actually write to the imported files.
Default: ``no``
- **backend**: The analysis backend; either ``gstreamer``, ``command``, ``audiotools``
or ``ffmpeg``.
- **backend**: The analysis backend; either ``gstreamer``, ``command``,
``audiotools`` or ``ffmpeg``.
Default: ``command``.
- **overwrite**: On import, re-analyze files that already have ReplayGain tags.
Note that, for historical reasons, the name of this option is somewhat
@ -136,7 +136,8 @@ configuration file. The available options are:
integer values instead of the common ``REPLAYGAIN_`` tags with floating point
values. Requires the "ffmpeg" backend.
Default: ``Opus``.
- **per_disc**: Calculate album ReplayGain on disc level instead of album level.
- **per_disc**: Calculate album ReplayGain on disc level instead of album
level.
Default: ``no``
These options only work with the "command" backend:
@ -171,7 +172,8 @@ whether ReplayGain tags are written into the music files, or stored in the
beets database only (the default is to use :ref:`the importer's configuration
<config-import-write>`).
To execute with a different number of threads, call ``beet replaygain --threads N``::
To execute with a different number of threads, call ``beet replaygain --threads
N``::
$ beet replaygain --threads N [-Waf] [QUERY]

16
docs/plugins/spotify.rst
View file

@ -16,7 +16,8 @@ Why Use This Plugin?
--------------------
* You're a Beets user and Spotify user already.
* You have playlists or albums you'd like to make available in Spotify from Beets without having to search for each artist/album/track.
* You have playlists or albums you'd like to make available in Spotify from
Beets without having to search for each artist/album/track.
* You want to check which tracks in your library are available on Spotify.
* You want to autotag music with metadata from the Spotify API.
* You want to obtain track popularity and audio features (e.g., danceability)
@ -53,7 +54,8 @@ prompt during import::
Configuration
-------------
This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`. In addition, the following
This plugin can be configured like other metadata source plugins as described in
:ref:`metadata-source-plugin-configuration`. In addition, the following
configuration options are provided.
The default options should work as-is, but there are some options you can put
@ -83,11 +85,11 @@ in config.yaml under the ``spotify:`` section:
track/album/artist fields before sending them to Spotify. Can be useful for
changing certain abbreviations, like ft. -> feat. See the examples below.
Default: None.
- **search_query_ascii**: If set to ``yes``, the search query will be converted to
ASCII before being sent to Spotify. Converting searches to ASCII can
enhance search results in some cases, but in general, it is not recommended.
For instance `artist:deadmau5 album:4×4` will be converted to
`artist:deadmau5 album:4x4` (notice `×!=x`).
- **search_query_ascii**: If set to ``yes``, the search query will be converted
to ASCII before being sent to Spotify. Converting searches to ASCII can
enhance search results in some cases, but in general, it is not recommended.
For instance ``artist:deadmau5 album:4×4`` will be converted to
``artist:deadmau5 album:4x4`` (notice ``×!=x``).
Default: ``no``.

24
docs/plugins/subsonicplaylist.rst
View file

@ -1,14 +1,15 @@
Subsonic Playlist Plugin
========================
The ``subsonicplaylist`` plugin allows to import playlists from a subsonic server.
This is done by retrieving the track info from the subsonic server, searching
for them in the beets library, and adding the playlist names to the
`subsonic_playlist` tag of the found items. The content of the tag has the format:
The ``subsonicplaylist`` plugin allows to import playlists from a subsonic
server. This is done by retrieving the track info from the subsonic server,
searching for them in the beets library, and adding the playlist names to the
``subsonic_playlist`` tag of the found items. The content of the tag has the
format:
subsonic_playlist: ";first playlist;second playlist;"
To get all items in a playlist use the query `;playlist name;`.
To get all items in a playlist use the query ``;playlist name;``.
Command Line Usage
------------------
@ -22,15 +23,18 @@ Next, configure the plugin to connect to your Subsonic server, like this::
username: someUser
password: somePassword
After this you can import your playlists by invoking the `subsonicplaylist` command.
After this you can import your playlists by invoking the ``subsonicplaylist``
command.
By default only the tags of the items found for playlists will be updated.
This means that, if one imported a playlist, then delete one song from it and
imported the playlist again, the deleted song will still have the playlist set
in its `subsonic_playlist` tag. To solve this problem one can use the `-d/--delete`
flag. This resets all `subsonic_playlist` tag before importing playlists.
in its ``subsonic_playlist`` tag. To solve this problem one can use the
``-d/--delete`` flag. This resets all ``subsonic_playlist`` tag before importing
playlists.
Here's an example configuration with all the available options and their default values::
Here's an example configuration with all the available options and their default
values::
subsonicplaylist:
base_url: "https://your.subsonic.server"
@ -40,4 +44,4 @@ Here's an example configuration with all the available options and their default
username: ''
password: ''
The `base_url`, `username`, and `password` options are required.
The ``base_url``, ``username``, and ``password`` options are required.

17
docs/plugins/substitute.rst
View file

@ -1,17 +1,18 @@
Substitute Plugin
=================
The ``substitute`` plugin lets you easily substitute values in your templates and
path formats. Specifically, it is intended to let you *canonicalize* names
The ``substitute`` plugin lets you easily substitute values in your templates
and path formats. Specifically, it is intended to let you *canonicalize* names
such as artists: For example, perhaps you want albums from The Jimi Hendrix
Experience to be sorted into the same folder as solo Hendrix albums.
This plugin is intended as a replacement for the ``rewrite`` plugin. While
the ``rewrite`` plugin modifies the metadata, this plugin does not.
Enable the ``substitute`` plugin (see :ref:`using-plugins`), then make a ``substitute:`` section in your config file to contain your rules.
Each rule consists of a case-insensitive regular expression pattern, and a
replacement string. For example, you might use:
Enable the ``substitute`` plugin (see :ref:`using-plugins`), then make a
``substitute:`` section in your config file to contain your rules. Each rule
consists of a case-insensitive regular expression pattern, and a replacement
string. For example, you might use:
.. code-block:: yaml
@ -21,7 +22,7 @@ replacement string. For example, you might use:
The replacement can be an expression utilising the matched regex, allowing us
to create more general rules. Say for example, we want to sort all albums by
multiple artists into the directory of the first artist. We can thus capture
everything before the first ``,``, `` &`` or `` and``, and use this capture
everything before the first ``,``, ``\ &`` or ``\ and``, and use this capture
group in the output, discarding the rest of the string.
.. code-block:: yaml
@ -35,8 +36,8 @@ This would handle all the below cases in a single rule:
| Neil Young & Crazy Horse -> Neil Young
| James Yorkston, Nina Persson & The Second Hand Orchestra -> James Yorkston
To apply the substitution, you have to call the function ``%substitute{}`` in the paths section. For example:
To apply the substitution, you have to call the function ``%substitute{}`` in
the paths section. For example:
.. code-block:: yaml

8
docs/plugins/unimported.rst
View file

@ -1,15 +1,17 @@
Unimported Plugin
=================
The ``unimported`` plugin allows one to list all files in the library folder which are not listed in the beets library database, including art files.
The ``unimported`` plugin allows one to list all files in the library folder
which are not listed in the beets library database, including art files.
Command Line Usage
------------------
To use the ``unimported`` plugin, enable it in your configuration (see
:ref:`using-plugins`). Then use it by invoking the ``beet unimported`` command.
The command will list all files in the library folder which are not imported. You can
exclude file extensions or entire subdirectories using the configuration file::
The command will list all files in the library folder which are not imported.
You can exclude file extensions or entire subdirectories using the configuration
file::
unimported:
ignore_extensions: jpg png

29
docs/plugins/web.rst
View file

@ -55,14 +55,16 @@ configuration file. The available options are:
Default: 8337.
- **cors**: The CORS allowed origin (see :ref:`web-cors`, below).
Default: CORS is disabled.
- **cors_supports_credentials**: Support credentials when using CORS (see :ref:`web-cors`, below).
- **cors_supports_credentials**: Support credentials when using CORS (see
:ref:`web-cors`, below).
Default: CORS_SUPPORTS_CREDENTIALS is disabled.
- **reverse_proxy**: If true, enable reverse proxy support (see
:ref:`reverse-proxy`, below).
Default: false.
- **include_paths**: If true, includes paths in item objects.
Default: false.
- **readonly**: If true, DELETE and PATCH operations are not allowed. Only GET is permitted.
- **readonly**: If true, DELETE and PATCH operations are not allowed. Only GET
is permitted.
Default: true.
Implementation
@ -184,16 +186,16 @@ code.
``DELETE /item/6``
++++++++++++++++++
Removes the item with id *6* from the beets library. If the *?delete* query string is included,
the matching file will be deleted from disk.
Removes the item with id *6* from the beets library. If the *?delete* query
string is included, the matching file will be deleted from disk.
Only allowed if ``readonly`` configuration option is set to ``no``.
``PATCH /item/6``
++++++++++++++++++
Updates the item with id *6* and write the changes to the music file. The body should be a JSON object
containing the changes to the object.
Updates the item with id *6* and write the changes to the music file. The body
should be a JSON object containing the changes to the object.
Returns the updated JSON representation. ::
@ -210,11 +212,11 @@ Only allowed if ``readonly`` configuration option is set to ``no``.
Response with a list of tracks with the ids *6*, *12* and *13*. The format of
the response is the same as for `GET /item/`_. It is *not guaranteed* that the
response includes all the items requested. If a track is not found it is silently
dropped from the response.
response includes all the items requested. If a track is not found it is
silently dropped from the response.
This endpoint also supports *DELETE* and *PATCH* methods as above, to operate on all
items of the list.
This endpoint also supports *DELETE* and *PATCH* methods as above, to operate on
all items of the list.
``GET /item/path/...``
++++++++++++++++++++++
@ -244,8 +246,8 @@ Path elements are joined as parts of a query. For example,
To specify literal path separators in a query, use a backslash instead of a
slash.
This endpoint also supports *DELETE* and *PATCH* methods as above, to operate on all
items returned by the query.
This endpoint also supports *DELETE* and *PATCH* methods as above, to operate on
all items returned by the query.
``GET /item/6/file``
++++++++++++++++++++
@ -281,7 +283,8 @@ or ``/album/5,7``. In addition we can request the cover art of an album with
``GET /album/5/art``.
You can also add the '?expand' flag to get the individual items of an album.
``DELETE`` is only allowed if ``readonly`` configuration option is set to ``no``.
``DELETE`` is only allowed if ``readonly`` configuration option is set to
``no``.
``GET /stats``
++++++++++++++

9
docs/plugins/zero.rst
View file

@ -7,8 +7,10 @@ the plugin can strip useless comments like "ripped by MyGreatRipper."
The plugin can work in one of two modes:
* ``fields``: A blacklist, where you choose the tags you want to remove (used by default).
* ``keep_fields``: A whitelist, where you instead specify the tags you want to keep.
* ``fields``: A blacklist, where you choose the tags you want to remove (used by
default).
* ``keep_fields``: A whitelist, where you instead specify the tags you want to
keep.
To use the ``zero`` plugin, enable the plugin in your configuration
(see :ref:`using-plugins`).
@ -31,7 +33,8 @@ fields to nullify and the conditions for nullifying them:
* To conditionally filter a field, use ``field: [regexp, regexp]`` to specify
regular expressions.
* By default this plugin only affects files' tags; the beets database is left
unchanged. To update the tags in the database, set the ``update_database`` option to true.
unchanged. To update the tags in the database, set the ``update_database``
option to true.
For example::

100
docs/reference/cli.rst
View file

@ -65,9 +65,9 @@ Directories passed to the import command can contain either a single
album or many, in which case the leaf directories will be considered
albums (the latter case is true of typical Artist/Album organizations
and many people's "downloads" folders). The path can also be a single
song or an archive. Beets supports `zip` and `tar` archives out of the
box. To extract `rar` files, install the `rarfile`_ package and the
`unrar` command. To extract `7z` files, install the `py7zr`_ package.
song or an archive. Beets supports ``zip`` and ``tar`` archives out of the
box. To extract ``rar`` files, install the `rarfile`_ package and the
``unrar`` command. To extract ``7z`` files, install the `py7zr`_ package.
Optional command flags:
@ -95,7 +95,7 @@ Optional command flags:
normal autotagger mode would ask for confirmation, the quiet mode
performs a fallback action that can be configured using the
``quiet_fallback`` configuration or ``--quiet-fallback`` CLI option.
By default it pessimistically ``skip``s the file.
By default it pessimistically skips the file.
Alternatively, it can be used as is, by configuring ``asis``.
* Speaking of resuming interrupted imports, the tagger will prompt you if it
@ -116,7 +116,7 @@ Optional command flags:
``incremental`` configuration option.
* If you don't want to record skipped files during an *incremental* import, use
the ``--incremental-skip-later`` flag which corresponds to the
the ``--incremental-skip-later`` flag which corresponds to the
``incremental_skip_later`` configuration option.
Setting the flag prevents beets from persisting skip decisions during a
non-interactive import so that a user can make a decision regarding
@ -157,9 +157,10 @@ Optional command flags:
searching for other candidates by using the ``--search-id SEARCH_ID`` option.
Multiple IDs can be specified by simply repeating the option several times.
* You can supply ``--set field=value`` to assign `field` to `value` on import.
Values support the same template syntax as beets'
:doc:`path formats <pathformat>`.
* You can supply ``--set field=value`` to assign ``field`` to ``value`` on
import. Values support the same template syntax as beets' :doc:`path formats
<pathformat>`.
These assignments will merge with (and possibly override) the
:ref:`set_fields` configuration dictionary. You can use the option multiple
times on the command line, like so::
@ -246,21 +247,22 @@ remove
Remove music from your library.
This command uses the same :doc:`query <query>` syntax as the ``list`` command.
By default, it just removes entries from the library database; it doesn't
touch the files on disk. To actually delete the files, use the ``-d`` flag.
When the ``-a`` flag is given, the command operates on albums instead of
individual tracks.
By default, it just removes entries from the library database; it doesn't touch
the files on disk. To actually delete the files, use the ``-d`` flag. When the
``-a`` flag is given, the command operates on albums instead of individual
tracks.
When you run the ``remove`` command, it prints a list of all affected items in
the library and asks for your permission before removing them. You can then
choose to abort (type ``n``), confirm (``y``), or interactively choose some of
the items (``s``). In the latter case, the command will prompt you for every
matching item or album and invite you to type ``y`` to remove the item/album,
``n`` to keep it or ``q`` to exit and only remove the items/albums selected up
to this point.
When you run the ``remove`` command, it prints a list of all
affected items in the library and asks for your permission before removing
them. You can then choose to abort (type `n`), confirm (`y`), or interactively
choose some of the items (`s`). In the latter case, the command will prompt you
for every matching item or album and invite you to type `y` to remove the
item/album, `n` to keep it or `q` to exit and only remove the items/albums
selected up to this point.
This option lets you choose precisely which tracks/albums to remove without
spending too much time to carefully craft a query.
If you do not want to be prompted at all, use the ``-f`` option.
spending too much time to carefully craft a query. If you do not want to be
prompted at all, use the ``-f`` option.
.. _modify-cmd:
@ -299,18 +301,17 @@ prevent this behavior, use ``-I``/``--noinherit``.
Items will automatically be moved around when necessary if they're in your
library directory, but you can disable that with ``-M``. Tags will be written
to the files according to the settings you have for imports, but these can be
overridden with ``-w`` (write tags, the default) and ``-W`` (don't write
tags).
overridden with ``-w`` (write tags, the default) and ``-W`` (don't write tags).
When you run the ``modify`` command, it prints a list of all
affected items in the library and asks for your permission before making any
changes. You can then choose to abort the change (type `n`), confirm
(`y`), or interactively choose some of the items (`s`). In the latter case,
the command will prompt you for every matching item or album and invite you to
type `y` to apply the changes, `n` to discard them or `q` to exit and apply
the selected changes. This option lets you choose precisely which data to
change without spending too much time to carefully craft a query. To skip the
prompts entirely, use the ``-y`` option.
When you run the ``modify`` command, it prints a list of all affected items in
the library and asks for your permission before making any changes. You can
then choose to abort the change (type ``n``), confirm (``y``), or interactively
choose some of the items (``s``). In the latter case, the command will prompt
you for every matching item or album and invite you to type ``y`` to apply the
changes, ``n`` to discard them or ``q`` to exit and apply the selected changes.
This option lets you choose precisely which data to change without spending too
much time to carefully craft a query. To skip the prompts entirely, use the
``-y`` option.
.. _move-cmd:
@ -357,10 +358,10 @@ This will show you all the proposed changes but won't actually change anything
on disk.
By default, all the changed metadata will be populated back to the database.
If you only want certain fields to be written, specify them with the ```-F```
If you only want certain fields to be written, specify them with the ``-F``
flags (which can be used multiple times). Alternatively, specify fields to *not*
write with ```-e``` flags (which can be used multiple times). For the list of
supported fields, please see ```beet fields```.
write with ``-e`` flags (which can be used multiple times). For the list of
supported fields, please see ``beet fields``.
When an updated track is part of an album, the album-level fields of *all*
tracks from the album are also updated. (Specifically, the command copies
@ -382,19 +383,20 @@ write
Write metadata from the database into files' tags.
When you make changes to the metadata stored in beets' library database
(during import or with the :ref:`modify-cmd` command, for example), you often
have the option of storing changes only in the database, leaving your files
untouched. The ``write`` command lets you later change your mind and write the
contents of the database into the files. By default, this writes the changes only if there is a difference between the database and the tags in the file.
When you make changes to the metadata stored in beets' library database (during
import or with the :ref:`modify-cmd` command, for example), you often have the
option of storing changes only in the database, leaving your files untouched.
The ``write`` command lets you later change your mind and write the contents of
the database into the files. By default, this writes the changes only if there
is a difference between the database and the tags in the file.
You can think of this command as the opposite of :ref:`update-cmd`.
The ``-p`` option previews metadata changes without actually applying them.
The ``-f`` option forces a write to the file, even if the file tags match the database. This is useful for making sure that enabled plugins that run on write (e.g., the Scrub and Zero plugins) are run on the file.
The ``-f`` option forces a write to the file, even if the file tags match the
database. This is useful for making sure that enabled plugins that run on write
(e.g., the Scrub and Zero plugins) are run on the file.
.. _stats-cmd:
@ -469,12 +471,12 @@ import ...``.
in this config file will override the corresponding settings in your base
configuration.
* ``-p plugins``: specify a comma-separated list of plugins to enable. If
specified, the plugin list in your configuration is ignored. The long form
of this argument also allows specifying no plugins, effectively disabling
all plugins: ``--plugins=``.
specified, the plugin list in your configuration is ignored. The long form of
this argument also allows specifying no plugins, effectively disabling all
plugins: ``--plugins=``.
* ``-P plugins``: specify a comma-separated list of plugins to disable in a
specific beets run. This will overwrite ``-p`` if used with it. To disable all plugins, use
``--plugins=`` instead.
specific beets run. This will overwrite ``-p`` if used with it. To disable
all plugins, use ``--plugins=`` instead.
Beets also uses the ``BEETSDIR`` environment variable to look for
configuration and data.
@ -522,7 +524,7 @@ zsh
```
If you use zsh, take a look at the included `completion script`_. The script
should be placed in a directory that is part of your ``fpath``, and `not`
should be placed in a directory that is part of your ``fpath``, and ``not``
sourced in your ``.zshrc``. Running ``echo $fpath`` will give you a list of
valid directories.

57
docs/reference/config.rst
View file

@ -75,11 +75,11 @@ Filenames are relative to the directory containing ``config.yaml``.
pluginpath
~~~~~~~~~~
Directories to search for plugins. Each Python file or directory in a plugin
Directories to search for plugins. Each Python file or directory in a plugin
path represents a plugin and should define a subclass of :class:`BeetsPlugin`.
A plugin can then be loaded by adding the filename to the `plugins` configuration.
The plugin path can either be a single string or a list of strings---so, if you
have multiple paths, format them as a YAML list like so::
A plugin can then be loaded by adding the filename to the ``plugins``
configuration. The plugin path can either be a single string or a list of
strings---so, if you have multiple paths, format them as a YAML list like so::
pluginpath:
- /path/one
@ -186,8 +186,8 @@ take place before applying the :ref:`replace` configuration and are roughly
equivalent to wrapping all your path templates in the ``%asciify{}``
:ref:`template function <template-functions>`.
This uses the `unidecode module`_ which is language agnostic, so some
characters may be transliterated from a different language than expected.
This uses the `unidecode module`_ which is language agnostic, so some
characters may be transliterated from a different language than expected.
For example, Japanese kanji will usually use their Chinese readings.
Default: ``no``.
@ -228,7 +228,7 @@ command and other commands that need to print out items. Defaults to
``$artist - $album - $title``. The ``-f`` command-line option overrides
this setting.
It used to be named `list_format_item`.
It used to be named ``list_format_item``.
.. _list_format_album:
.. _format_album:
@ -240,7 +240,7 @@ Format to use when listing *albums* with :ref:`list-cmd` and other
commands. Defaults to ``$albumartist - $album``. The ``-f`` command-line
option overrides this setting.
It used to be named `list_format_album`.
It used to be named ``list_format_album``.
.. _sort_item:
@ -283,11 +283,12 @@ That is, if this option is turned on, then ``year`` will always equal
overwrite_null
~~~~~~~~~~~~~~
This confusingly-named option indicates which fields have meaningful `null` values. If
an album or track field is in the corresponding list, then an existing value for this
field in an item in the database can be overwritten with `null`. By default, however,
`null` is interpreted as information about the field being unavailable, so it would not
overwrite existing values. For example::
This confusingly-named option indicates which fields have meaningful ``null``
values. If an album or track field is in the corresponding list, then an
existing value for this field in an item in the database can be overwritten with
``null``. By default, however, ``null`` is interpreted as information about the
field being unavailable, so it would not overwrite existing values. For
example::
overwrite_null:
album: ["albumid"]
@ -382,7 +383,7 @@ clutter
When beets imports all the files in a directory, it tries to remove the
directory if it's empty. A directory is considered empty if it only contains
files whose names match the glob patterns in `clutter`, which should be a list
files whose names match the glob patterns in ``clutter``, which should be a list
of strings. The default list consists of "Thumbs.DB" and ".DS_Store".
The importer only removes recursively searched subdirectories---the top-level
@ -434,9 +435,9 @@ support ANSI colors.
.. note::
The `color` option was previously a top-level configuration. This is
The ``color`` option was previously a top-level configuration. This is
still respected, but a deprecation message will be shown until your
top-level `color` configuration has been nested under `ui`.
top-level ``color`` configuration has been nested under ``ui``.
.. _colors:
@ -728,8 +729,8 @@ languages
A list of locale names to search for preferred aliases. For example, setting
this to ``en`` uses the transliterated artist name "Pyotr Ilyich Tchaikovsky"
instead of the Cyrillic script for the composer's name when tagging from
MusicBrainz. You can use a space-separated list of language abbreviations, like
``en jp es``, to specify a preference order. Defaults to an empty list, meaning
MusicBrainz. You can use a space-separated list of language abbreviations, like
``en jp es``, to specify a preference order. Defaults to an empty list, meaning
that no language is preferred.
.. _ignored_alias_types:
@ -739,7 +740,7 @@ ignored_alias_types
A list of alias types to be ignored when importing new items.
See the `MusicBrainz Documentation` for more information on aliases.
See the ``MusicBrainz Documentation`` for more information on aliases.
.._MusicBrainz Documentation: https://musicbrainz.org/doc/Aliases
@ -801,11 +802,11 @@ Default::
duplicate_action
~~~~~~~~~~~~~~~~
Either ``skip``, ``keep``, ``remove``, ``merge`` or ``ask``.
Controls how duplicates are treated in import task.
"skip" means that new item(album or track) will be skipped;
Either ``skip``, ``keep``, ``remove``, ``merge`` or ``ask``.
Controls how duplicates are treated in import task.
"skip" means that new item(album or track) will be skipped;
"keep" means keep both old and new items; "remove" means remove old
item; "merge" means merge into one album; "ask" means the user
item; "merge" means merge into one album; "ask" means the user
should be prompted for the action each time. The default is ``ask``.
.. _duplicate_verbose_prompt:
@ -991,7 +992,11 @@ the penalty name to the ``ignored`` setting::
The available penalties are the same as those for the :ref:`max_rec` setting.
For example, setting ``ignored: missing_tracks`` will skip any album matches where your audio files are missing some of the tracks. The importer will not attempt to display these matches. It does not ignore the fact that the album is missing tracks, which would allow these matches to apply more easily. To do that, you'll want to adjust the penalty for missing tracks.
For example, setting ``ignored: missing_tracks`` will skip any album matches
where your audio files are missing some of the tracks. The importer will not
attempt to display these matches. It does not ignore the fact that the album is
missing tracks, which would allow these matches to apply more easily. To do
that, you'll want to adjust the penalty for missing tracks.
.. _required:
@ -1061,8 +1066,8 @@ defaults look like this::
singleton: Non-Album/$artist/$title
comp: Compilations/$album%aunique{}/$track $title
Note the use of ``$albumartist`` instead of ``$artist``; this ensures that albums
will be well-organized. For more about these format strings, see
Note the use of ``$albumartist`` instead of ``$artist``; this ensures that
albums will be well-organized. For more about these format strings, see
:doc:`pathformat`. The ``aunique{}`` function ensures that identically-named
albums are placed in different directories; see :ref:`aunique` for details.

24
docs/reference/pathformat.rst
View file

@ -40,7 +40,9 @@ probably don't want that! So use ``$albumartist``.
.. _Stop Making Sense:
https://musicbrainz.org/release/798dcaab-0f1a-4f02-a9cb-61d5b0ddfd36.html
As a convenience, however, beets allows ``$albumartist`` to fall back to the value for ``$artist`` and vice-versa if one tag is present but the other is not.
As a convenience, however, beets allows ``$albumartist`` to fall back to the
value for ``$artist`` and vice-versa if one tag is present but the other is
not.
.. _template-functions:
@ -60,13 +62,14 @@ These functions are built in to beets:
* ``%lower{text}``: Convert ``text`` to lowercase.
* ``%upper{text}``: Convert ``text`` to UPPERCASE.
* ``%capitalize{text}``: Make the first letter of ``text`` UPPERCASE and the rest lowercase.
* ``%capitalize{text}``: Make the first letter of ``text`` UPPERCASE and the
rest lowercase.
* ``%title{text}``: Convert ``text`` to Title Case.
* ``%left{text,n}``: Return the first ``n`` characters of ``text``.
* ``%right{text,n}``: Return the last ``n`` characters of ``text``.
* ``%right{text,n}``: Return the last ``n`` characters of ``text``.
* ``%if{condition,text}`` or ``%if{condition,truetext,falsetext}``: If
``condition`` is nonempty (or nonzero, if it's a number), then returns
the second argument. Otherwise, returns the third argument if specified (or
``condition`` is nonempty (or nonzero, if it's a number), then returns the
second argument. Otherwise, returns the third argument if specified (or
nothing if ``falsetext`` is left off).
* ``%asciify{text}``: Convert non-ASCII characters to their ASCII equivalents.
For example, "café" becomes "cafe". Uses the mapping provided by the
@ -137,8 +140,9 @@ disambiguation if, for example, you include the year by default in
path formats.
The default characters used as brackets are ``[]``. To change this, provide a
third argument to the ``%aunique`` function consisting of two characters: the left
and right brackets. Or, to turn off bracketing entirely, leave argument blank.
third argument to the ``%aunique`` function consisting of two characters: the
left and right brackets. Or, to turn off bracketing entirely, leave argument
blank.
One caveat: When you import an album that is named identically to one already in
your library, the *first* album—the one already in your library— will not
@ -157,9 +161,9 @@ It is also possible to have singleton tracks with the same name and the same
artist. Beets provides the ``%sunique{}`` template to avoid giving these
tracks the same file path.
It has the same arguments as the :ref:`%aunique <aunique>` template, but the default
values are different. The default identifiers are ``artist title`` and the
default disambiguators are ``year trackdisambig``.
It has the same arguments as the :ref:`%aunique <aunique>` template, but the
default values are different. The default identifiers are ``artist title`` and
the default disambiguators are ``year trackdisambig``.
Syntax Details
--------------

6
docs/reference/query.rst
View file

@ -181,8 +181,8 @@ shell).
Numeric Range Queries
---------------------
For numeric fields, such as year, bitrate, and track, you can query using one-
or two-sided intervals. That is, you can find music that falls within a
For numeric fields, such as year, bitrate, and track, you can query using
one-or two-sided intervals. That is, you can find music that falls within a
*range* of values. To use ranges, write a query that has two dots (``..``) at
the beginning, middle, or end of a string of numbers. Dots in the beginning
let you specify a maximum (e.g., ``..7``); dots at the end mean a minimum
@ -343,7 +343,7 @@ filesystem.
Sort Order
----------
Queries can specify a sort order. Use the name of the `field` you want to sort
Queries can specify a sort order. Use the name of the ``field`` you want to sort
on, followed by a ``+`` or ``-`` sign to indicate ascending or descending
sort. For example, this command::