From 769dcdc88a1263638ae25944ba6b2be3e8933666 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0ar=C5=ABnas=20Nejus?= Date: Sat, 2 Aug 2025 19:14:28 +0100 Subject: [PATCH] Docs: fix linting issues --- docs/_templates/autosummary/base.rst | 2 +- docs/_templates/autosummary/class.rst | 7 +- docs/_templates/autosummary/module.rst | 2 +- docs/api/database.rst | 2 +- docs/changelog.rst | 527 ++++++++++++++----------- docs/dev/library.rst | 7 +- docs/dev/plugins.rst | 129 +++--- docs/faq.rst | 12 +- docs/guides/advanced.rst | 4 +- docs/guides/main.rst | 50 +-- docs/guides/tagger.rst | 7 +- docs/plugins/absubmit.rst | 2 +- docs/plugins/acousticbrainz.rst | 3 +- docs/plugins/albumtypes.rst | 3 +- docs/plugins/autobpm.rst | 6 +- docs/plugins/badfiles.rst | 2 +- docs/plugins/bareasc.rst | 44 ++- docs/plugins/beatport.rst | 3 +- docs/plugins/bucket.rst | 16 +- docs/plugins/chroma.rst | 2 +- docs/plugins/convert.rst | 30 +- docs/plugins/deezer.rst | 8 +- docs/plugins/discogs.rst | 37 +- docs/plugins/embedart.rst | 19 +- docs/plugins/embyupdate.rst | 9 +- docs/plugins/export.rst | 16 +- docs/plugins/fetchart.rst | 34 +- docs/plugins/fish.rst | 14 +- docs/plugins/ftintitle.rst | 5 +- docs/plugins/index.rst | 31 +- docs/plugins/inline.rst | 15 +- docs/plugins/ipfs.rst | 5 +- docs/plugins/keyfinder.rst | 6 +- docs/plugins/kodiupdate.rst | 3 +- docs/plugins/lastgenre.rst | 25 +- docs/plugins/limit.rst | 32 +- docs/plugins/listenbrainz.rst | 12 +- docs/plugins/loadext.rst | 2 +- docs/plugins/mbsubmit.rst | 3 +- docs/plugins/mpdstats.rst | 16 +- docs/plugins/mpdupdate.rst | 9 +- docs/plugins/musicbrainz.rst | 25 +- docs/plugins/parentwork.rst | 4 +- docs/plugins/permissions.rst | 3 +- docs/plugins/play.rst | 16 +- docs/plugins/plexupdate.rst | 12 +- docs/plugins/replace.rst | 2 +- docs/plugins/replaygain.rst | 26 +- docs/plugins/spotify.rst | 16 +- docs/plugins/subsonicplaylist.rst | 24 +- docs/plugins/substitute.rst | 17 +- docs/plugins/unimported.rst | 8 +- docs/plugins/web.rst | 29 +- docs/plugins/zero.rst | 9 +- docs/reference/cli.rst | 100 ++--- docs/reference/config.rst | 57 +-- docs/reference/pathformat.rst | 24 +- docs/reference/query.rst | 6 +- 58 files changed, 837 insertions(+), 702 deletions(-) diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst index 822f55dc2..6ea19ecd9 100644 --- a/docs/_templates/autosummary/base.rst +++ b/docs/_templates/autosummary/base.rst @@ -1,3 +1,3 @@ {{ fullname | escape | underline}} .. currentmodule:: {{ module }} -.. auto{{ objtype }}:: {{ objname }} \ No newline at end of file +.. auto{{ objtype }}:: {{ objname }} diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index 6927f8360..996dab4a5 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -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') }} - diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst index 9383a2307..923bc55f8 100644 --- a/docs/_templates/autosummary/module.rst +++ b/docs/_templates/autosummary/module.rst @@ -8,4 +8,4 @@ {%- endfor %} {% endif %} -{% endblock %} \ No newline at end of file +{% endblock %} diff --git a/docs/api/database.rst b/docs/api/database.rst index 627b5dc39..319290a80 100644 --- a/docs/api/database.rst +++ b/docs/api/database.rst @@ -44,4 +44,4 @@ Queries Query FieldQuery - AndQuery \ No newline at end of file + AndQuery diff --git a/docs/changelog.rst b/docs/changelog.rst index 75a11956b..8ecc74252 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,7 +1,8 @@ Changelog ========= -Changelog goes here! Please add your entry to the bottom of one of the lists below! +Changelog goes here! Please add your entry to the bottom of one of the lists +below! Unreleased ---------- @@ -9,10 +10,10 @@ Unreleased New features: * :doc:`plugins/musicbrainz`: The MusicBrainz autotagger has been moved to - a separate plugin. The default :ref:`plugins-config` includes `musicbrainz`, - but if you've customized your `plugins` list in your configuration, you'll - need to explicitly add `musicbrainz` to continue using this functionality. - Configuration option `musicbrainz.enabled` has thus been deprecated. + a separate plugin. The default :ref:`plugins-config` includes ``musicbrainz``, + but if you've customized your ``plugins`` list in your configuration, you'll + need to explicitly add ``musicbrainz`` to continue using this functionality. + Configuration option ``musicbrainz.enabled`` has thus been deprecated. :bug:`2686` :bug:`4605` * :doc:`plugins/web`: Show notifications when a track plays. This uses the @@ -26,7 +27,7 @@ New features: * :doc:`plugins/duplicates`: Add ``--remove`` option, allowing to remove from the library without deleting media files. :bug:`5832` -* :doc:`plugins/playlist`: Support files with the `.m3u8` extension. +* :doc:`plugins/playlist`: Support files with the ``.m3u8`` extension. :bug:`5829` * :doc:`plugins/mbcollection`: When getting the user collections, only consider collections of releases, and ignore collections of other entity types. @@ -42,7 +43,7 @@ Bug fixes: :bug:`5788` * tests: Fix library tests failing on Windows when run from outside ``D:/``. :bug:`5802` -* Fix an issue where calling `Library.add` would cause the `database_change` +* Fix an issue where calling ``Library.add`` would cause the ``database_change`` event to be sent twice, not once. :bug:`5560` * Fix ``HiddenFileTest`` by using ``bytestring_path()``. @@ -63,22 +64,25 @@ For packagers: * Optional ``extra_tags`` parameter has been removed from ``BeetsPlugin.candidates`` method signature since it is never passed in. If you override this method in your plugin, feel free to remove this parameter. -* Loosened `typing_extensions`` dependency in pyproject.toml to apply to every python version. +* Loosened ``typing_extensions`` dependency in pyproject.toml to apply to every python version. For plugin developers: -* The `fetchart` plugins has seen a few changes to function signatures and +* The ``fetchart`` plugins has seen a few changes to function signatures and source registration in the process of introducing typings to the code. Custom art sources might need to be adapted. * We split the responsibilities of plugins into two base classes #. :class:`beets.plugins.BeetsPlugin` - is the base class for all plugins, any plugin needs to inherit from this class. + is the base class for all plugins, any plugin needs to inherit from + this class. #. :class:`beets.metadata_plugin.MetadataSourcePlugin` - allows plugins to act like metadata sources. E.g. used by the MusicBrainz plugin. All plugins - in the beets repo are opted into this class where applicable. If you are maintaining a plugin - that acts like a metadata source, i.e. you expose any of ``track_for_id``, - ``album_for_id``, ``candidates``, ``item_candidates``, ``album_distance``, ``track_distance`` methods, - please update your plugin to inherit from the new baseclass, as otherwise your plugin will + allows plugins to act like metadata sources. E.g. used by the + MusicBrainz plugin. All plugins in the beets repo are opted into this + class where applicable. If you are maintaining a plugin that acts like + a metadata source, i.e. you expose any of ``track_for_id``, + ``album_for_id``, ``candidates``, ``item_candidates``, + ``album_distance``, ``track_distance`` methods, please update your + plugin to inherit from the new baseclass, as otherwise your plugin will stop working with the next major release. * Several definitions have been moved: * ``BLOB_TYPE`` constant, ``PathQuery`` and ``SingletonQuery`` queries have @@ -103,9 +107,10 @@ For plugin developers: Other changes: -* Refactor: Split responsibilities of Plugins into MetaDataPlugins and general Plugins. +* Refactor: Split responsibilities of Plugins into MetaDataPlugins and general + Plugins. * Documentation structure for auto generated API references changed slightly. - Autogenerated API references are now located in the `docs/api` subdirectory. + Autogenerated API references are now located in the ``docs/api`` subdirectory. * :doc:`/plugins/substitute`: Fix rST formatting for example cases so that each case is shown on separate lines. * Refactored library.py file by splitting it into multiple modules within the @@ -154,13 +159,15 @@ Bug fixes: * :doc:`plugins/thumbnails`: Fix API call to GIO on big endian architectures (like s390x) in thumbnails plugin. :bug:`5708` -* :doc:`plugins/listenbrainz`: Fix rST formatting for URLs of Listenbrainz API Key documentation and config.yaml. -* :doc:`plugins/listenbrainz`: Fix ``UnboundLocalError`` in cases where 'mbid' is not defined. -* :doc:`plugins/fetchart`: Fix fetchart bug where a tempfile could not be deleted due to never being - properly closed. +* :doc:`plugins/listenbrainz`: Fix rST formatting for URLs of Listenbrainz API + Key documentation and config.yaml. +* :doc:`plugins/listenbrainz`: Fix ``UnboundLocalError`` in cases where 'mbid' + is not defined. +* :doc:`plugins/fetchart`: Fix fetchart bug where a tempfile could not be + deleted due to never being properly closed. :bug:`5521` * :doc:`plugins/lyrics`: LRCLib will fallback to plain lyrics if synced lyrics - are not found and `synced` flag is set to `yes`. + are not found and ``synced`` flag is set to ``yes``. * Synchronise files included in the source distribution with what we used to have before the introduction of Poetry. :bug:`5531` @@ -179,10 +186,10 @@ Bug fixes: * :ref:`query-sort`: Fix a bug that would raise an exception when sorting on a non-string field that is not populated in all items. :bug:`5512` -* :doc:`plugins/lastgenre`: Fix track-level genre handling. Now when an album-level - genre is set already, single tracks don't fall back to the album's genre and - request their own last.fm genre. Also log messages regarding what's been - tagged are now more polished. +* :doc:`plugins/lastgenre`: Fix track-level genre handling. Now when an + album-level genre is set already, single tracks don't fall back to the album's + genre and request their own last.fm genre. Also log messages regarding what's + been tagged are now more polished. :bug:`5582` * Fix ambiguous column name ``sqlite3.OperationalError`` that occured in album queries that filtered album track titles, for example ``beet list -a keyword @@ -208,7 +215,8 @@ Bug fixes: lyrics. :bug:`5583` * ImageMagick 7.1.1-44 is now supported. -* :doc:`plugins/parentwork`: Only output parentwork changes when running in verbose mode. +* :doc:`plugins/parentwork`: Only output parentwork changes when running in + verbose mode. For packagers: @@ -222,10 +230,10 @@ Other changes: wrong (outdated) commit. Now the tag is created in the same workflow step right after committing the version update. :bug:`5539` -* :doc:`/plugins/smartplaylist`: URL-encode additional item `fields` within generated - EXTM3U playlists instead of JSON-encoding them. -* typehints: `./beets/importer.py` file now has improved typehints. -* typehints: `./beets/plugins.py` file now includes typehints. +* :doc:`/plugins/smartplaylist`: URL-encode additional item ``fields`` within + generated EXTM3U playlists instead of JSON-encoding them. +* typehints: ``./beets/importer.py`` file now has improved typehints. +* typehints: ``./beets/plugins.py`` file now includes typehints. * :doc:`plugins/ftintitle`: Optimize the plugin by avoiding unnecessary writes to the database. * Database models are now serializable with pickle. @@ -241,19 +249,20 @@ New features: Bug fixes: -* Check if running python from the Microsoft Store and provide feedback to install - from python.org. +* Check if running python from the Microsoft Store and provide feedback to + install from python.org. :bug:`5467` -* Fix bug where matcher doesn't consider medium number when importing. This makes - it difficult to import hybrid SACDs and other releases with duplicate tracks. +* Fix bug where matcher doesn't consider medium number when importing. This + makes it difficult to import hybrid SACDs and other releases with duplicate + tracks. :bug:`5148` * Bring back test files and the manual to the source distribution tarball. :bug:`5513` Other changes: -* Changed `bitesize` label to `good first issue`. Our `contribute`_ page is now - automatically populated with these issues. :bug:`4855` +* Changed ``bitesize`` label to ``good first issue``. Our `contribute`_ page is + now automatically populated with these issues. :bug:`4855` .. _contribute: https://github.com/beetbox/beets/contribute @@ -280,17 +289,23 @@ New features: Bug fixes: -* :doc:`plugins/ftintitle`: The detection of a "feat. X" part in a song title does not produce any false - positives caused by words like "and" or "with" anymore. :bug:`5441` -* :doc:`plugins/ftintitle`: The detection of a "feat. X" part now also matches such parts if they are in - parentheses or brackets. :bug:`5436` -* Improve naming of temporary files by separating the random part with the file extension. +* :doc:`plugins/ftintitle`: The detection of a "feat. X" part in a song title + does not produce any false positives caused by words like "and" or "with" + anymore. + :bug:`5441` +* :doc:`plugins/ftintitle`: The detection of a "feat. X" part now also matches + such parts if they are in parentheses or brackets. + :bug:`5436` +* Improve naming of temporary files by separating the random part with the file + extension. * Fix the ``auto`` value for the :ref:`reflink` config option. -* Fix lyrics plugin only getting part of the lyrics from ``Genius.com`` :bug:`4815` -* Album flexible fields are now correctly saved. For instance MusicBrainz external links - such as `bandcamp_album_id` will be available on albums in addition to tracks. - For albums already in your library, a re-import is required for the fields to be added. - Such a re-import can be done with, in this case, `beet import -L data_source:=MusicBrainz`. +* Fix lyrics plugin only getting part of the lyrics from ``Genius.com`` + :bug:`4815` +* Album flexible fields are now correctly saved. For instance MusicBrainz + external links such as ``bandcamp_album_id`` will be available on albums in + addition to tracks. For albums already in your library, a re-import is + required for the fields to be added. Such a re-import can be done with, in + this case, ``beet import -L data_source:=MusicBrainz``. * :doc:`plugins/autobpm`: Fix the ``TypeError`` where tempo was being returned as a numpy array. Update ``librosa`` dependency constraint to prevent similar issues in the future. @@ -305,7 +320,8 @@ Bug fixes: that it no longer treats "and" and "or" queries the same. To maintain previous behaviour add commas between your query keywords. For help see :ref:`combiningqueries`. -* Fix the ``TypeError`` when :ref:`set_fields` is provided non-string values. :bug:`4840` +* Fix the ``TypeError`` when :ref:`set_fields` is provided non-string values. + :bug:`4840` For packagers: @@ -320,7 +336,7 @@ Other changes: affects beets developers. Please see updates in :ref:`getting-the-source` and :ref:`testing` for more information. * :doc:`contributing`: Since ``poetry`` now manages local virtual environments, - `tox` has been replaced by a task runner ``poethepoet``. This change affects + ``tox`` has been replaced by a task runner ``poethepoet``. This change affects beets developers and contributors. Please see updates in the :ref:`development-tools` section for more details. Type ``poe`` while in the project directory to see the available commands. @@ -361,58 +377,77 @@ Major new features: New features: -* :doc:`/plugins/edit`: Prefer editor from ``VISUAL`` environment variable over ``EDITOR``. -* :ref:`config-cmd`: Prefer editor from ``VISUAL`` environment variable over ``EDITOR``. -* :doc:`/plugins/listenbrainz`: Add initial support for importing history and playlists from `ListenBrainz` +* :doc:`/plugins/edit`: Prefer editor from ``VISUAL`` environment variable over + ``EDITOR``. +* :ref:`config-cmd`: Prefer editor from ``VISUAL`` environment variable over + ``EDITOR``. +* :doc:`/plugins/listenbrainz`: Add initial support for importing history and + playlists from ``ListenBrainz`` :bug:`1719` -* :doc:`plugins/mbsubmit`: add new prompt choices helping further to submit unmatched tracks to MusicBrainz faster. -* :doc:`plugins/spotify`: We now fetch track's ISRC, EAN, and UPC identifiers from Spotify when using the ``spotifysync`` command. +* :doc:`plugins/mbsubmit`: add new prompt choices helping further to submit + unmatched tracks to MusicBrainz faster. +* :doc:`plugins/spotify`: We now fetch track's ISRC, EAN, and UPC identifiers + from Spotify when using the ``spotifysync`` command. :bug:`4992` -* :doc:`plugins/discogs`: supply a value for the `cover_art_url` attribute, for use by `fetchart`. +* :doc:`plugins/discogs`: supply a value for the ``cover_art_url`` attribute, + for use by ``fetchart``. :bug:`429` -* :ref:`update-cmd`: added ```-e``` flag for excluding fields from being updated. -* :doc:`/plugins/deezer`: Import rank and other attributes from Deezer during import and add a function to update the rank of existing items. +* :ref:`update-cmd`: added ``-e`` flag for excluding fields from being + updated. +* :doc:`/plugins/deezer`: Import rank and other attributes from Deezer during + import and add a function to update the rank of existing items. :bug:`4841` -* resolve transl-tracklisting relations for pseudo releases and merge data with the actual release +* resolve transl-tracklisting relations for pseudo releases and merge data with + the actual release :bug:`654` -* Fetchart: Use the right field (`spotify_album_id`) to obtain the Spotify album id +* Fetchart: Use the right field (``spotify_album_id``) to obtain the Spotify + album id :bug:`4803` * Prevent reimporting album if it is permanently removed from Spotify :bug:`4800` -* Added option to use `cover_art_url` as an album art source in the `fetchart` plugin. +* Added option to use ``cover_art_url`` as an album art source in the + ``fetchart`` plugin. :bug:`4707` -* :doc:`/plugins/fetchart`: The plugin can now get album art from `spotify`. -* Added option to specify a URL in the `embedart` plugin. +* :doc:`/plugins/fetchart`: The plugin can now get album art from ``spotify``. +* Added option to specify a URL in the ``embedart`` plugin. :bug:`83` -* :ref:`list-cmd` `singleton:true` queries have been made faster -* :ref:`list-cmd` `singleton:1` and `singleton:0` can now alternatively be used in queries, same as `comp` -* --from-logfile now parses log files using a UTF-8 encoding in `beets/beets/ui/commands.py`. +* :ref:`list-cmd` ``singleton:true`` queries have been made faster +* :ref:`list-cmd` ``singleton:1`` and ``singleton:0`` can now alternatively be + used in queries, same as ``comp`` +* --from-logfile now parses log files using a UTF-8 encoding in + ``beets/beets/ui/commands.py``. :bug:`4693` * :doc:`/plugins/bareasc` lookups have been made faster -* :ref:`list-cmd` lookups using the pattern operator `::` have been made faster -* Added additional error handling for `spotify` plugin. +* :ref:`list-cmd` lookups using the pattern operator ``::`` have been made + faster +* Added additional error handling for ``spotify`` plugin. :bug:`4686` * We now import the remixer field from Musicbrainz into the library. :bug:`4428` -* :doc:`/plugins/mbsubmit`: Added a new `mbsubmit` command to print track information to be submitted to MusicBrainz after initial import. +* :doc:`/plugins/mbsubmit`: Added a new ``mbsubmit`` command to print track + information to be submitted to MusicBrainz after initial import. :bug:`4455` -* Added `spotify_updated` field to track when the information was last updated. -* We now import and tag the `album` information when importing singletons using Spotify source. +* Added ``spotify_updated`` field to track when the information was last + updated. +* We now import and tag the ``album`` information when importing singletons + using Spotify source. :bug:`4398` * :doc:`/plugins/spotify`: The plugin now provides an additional command - `spotifysync` that allows getting track popularity and audio features + ``spotifysync`` that allows getting track popularity and audio features information from Spotify. :bug:`4094` * :doc:`/plugins/spotify`: The plugin now records Spotify-specific IDs in the - `spotify_album_id`, `spotify_artist_id`, and `spotify_track_id` fields. + ``spotify_album_id``, ``spotify_artist_id``, and ``spotify_track_id`` fields. :bug:`4348` * Create the parental directories for database if they do not exist. - :bug:`3808` :bug:`4327` -* :ref:`musicbrainz-config`: a new :ref:`musicbrainz.enabled` option allows disabling - the MusicBrainz metadata source during the autotagging process + :bug:`3808` + :bug:`4327` +* :ref:`musicbrainz-config`: a new :ref:`musicbrainz.enabled` option allows + disabling the MusicBrainz metadata source during the autotagging process * :doc:`/plugins/kodiupdate`: Now supports multiple kodi instances :bug:`4101` -* Add the item fields ``bitrate_mode``, ``encoder_info`` and ``encoder_settings``. +* Add the item fields ``bitrate_mode``, ``encoder_info`` and + ``encoder_settings``. * Add query prefixes ``=`` and ``~``. * A new configuration option, :ref:`duplicate_keys`, lets you change which fields the beets importer uses to identify duplicates. @@ -423,14 +458,16 @@ New features: * :doc:`/plugins/discogs`: Permit appending style to genre. * :doc:`plugins/discogs`: Implement item_candidates for matching singletons. * :doc:`plugins/discogs`: Check for compliant discogs_client module. -* :doc:`/plugins/convert`: Add a new `auto_keep` option that automatically +* :doc:`/plugins/convert`: Add a new ``auto_keep`` option that automatically converts files but keeps the *originals* in the library. - :bug:`1840` :bug:`4302` -* Added a ``-P`` (or ``--disable-plugins``) flag to specify one/multiple plugin(s) to be - disabled at startup. -* :ref:`import-options`: Add support for re-running the importer on paths in - log files that were created with the ``-l`` (or ``--logfile``) argument. - :bug:`4379` :bug:`4387` + :bug:`1840` + :bug:`4302` +* Added a ``-P`` (or ``--disable-plugins``) flag to specify one/multiple + plugin(s) to be disabled at startup. +* :ref:`import-options`: Add support for re-running the importer on paths in log + files that were created with the ``-l`` (or ``--logfile``) argument. + :bug:`4379` + :bug:`4387` * Preserve mtimes from archives :bug:`4392` * Add :ref:`%sunique{} ` template to disambiguate between singletons. @@ -453,60 +490,60 @@ New features: with converted media files. :bug:`4373` * Fetch the ``release_group_title`` field from MusicBrainz. - :bug: `4809` + :bug:`4809` * :doc:`plugins/discogs`: Add support for applying album information on singleton imports. - :bug: `4716` + :bug:`4716` * :doc:`/plugins/smartplaylist`: During explicit runs of the ``splupdate`` command, the log message "Creating playlist ..."" is now displayed instead of hidden in the debug log, which states some form of progress through the UI. :bug:`4861` * :doc:`plugins/subsonicupdate`: Updates are now triggered whenever either the beets database is changed or a smart playlist is created/updated. - :bug: `4862` + :bug:`4862` * :doc:`plugins/importfeeds`: Add a new output format allowing to save a playlist once per import session. - :bug: `4863` + :bug:`4863` * Make ArtResizer work with :pypi:`PIL`/:pypi:`pillow` 10.0.0 removals. :bug:`4869` * A new configuration option, :ref:`duplicate_verbose_prompt`, allows changing how duplicates are presented during import. - :bug: `4866` + :bug:`4866` * :doc:`/plugins/embyupdate`: Add handling for private users by adding ``userid`` config option. :bug:`4402` -* :doc:`/plugins/substitute`: Add the new plugin `substitute` as an alternative - to the `rewrite` plugin. The main difference between them being that - `rewrite` modifies files' metadata and `substitute` does not. +* :doc:`/plugins/substitute`: Add the new plugin ``substitute`` as an + alternative to the ``rewrite`` plugin. The main difference between them being + that ``rewrite`` modifies files' metadata and ``substitute`` does not. :bug:`2786` * Add support for ``artists`` and ``albumartists`` multi-valued tags. :bug:`505` -* :doc:`/plugins/autobpm`: Add the `autobpm` plugin which uses Librosa to +* :doc:`/plugins/autobpm`: Add the ``autobpm`` plugin which uses Librosa to calculate the BPM of the audio. :bug:`3856` * :doc:`/plugins/fetchart`: Fix the error with CoverArtArchive where the - `maxwidth` option would not be used to download a pre-sized thumbnail for + ``maxwidth`` option would not be used to download a pre-sized thumbnail for release groups, as is already done with releases. * :doc:`/plugins/fetchart`: Fix the error with CoverArtArchive where no cover - would be found when the `maxwidth` option matches a pre-sized thumbnail size, - but no thumbnail is provided by CAA. We now fallback to the raw image. -* :doc:`/plugins/advancedrewrite`: Add an advanced version of the `rewrite` + would be found when the ``maxwidth`` option matches a pre-sized thumbnail + size, but no thumbnail is provided by CAA. We now fallback to the raw image. +* :doc:`/plugins/advancedrewrite`: Add an advanced version of the ``rewrite`` plugin which allows to replace fields based on a given library query. * :doc:`/plugins/lyrics`: Add LRCLIB as a new lyrics provider and a new - `synced` option to prefer synced lyrics over plain lyrics. + ``synced`` option to prefer synced lyrics over plain lyrics. * :ref:`import-cmd`: Expose import.quiet_fallback as CLI option. -* :ref:`import-cmd`: Expose `import.incremental_skip_later` as CLI option. +* :ref:`import-cmd`: Expose ``import.incremental_skip_later`` as CLI option. * :doc:`/plugins/smartplaylist`: Expose config options as CLI options. -* :doc:`/plugins/smartplaylist`: Add new option `smartplaylist.output`. -* :doc:`/plugins/smartplaylist`: Add new option `smartplaylist.uri_format`. +* :doc:`/plugins/smartplaylist`: Add new option ``smartplaylist.output``. +* :doc:`/plugins/smartplaylist`: Add new option ``smartplaylist.uri_format``. * Sorted the default configuration file into categories. :bug:`4987` -* :doc:`/plugins/convert`: Don't treat WAVE (`.wav`) files as lossy anymore - when using the `never_convert_lossy_files` option. They will get transcoded +* :doc:`/plugins/convert`: Don't treat WAVE (``.wav``) files as lossy anymore + when using the ``never_convert_lossy_files`` option. They will get transcoded like the other lossless formats. -* Add support for `barcode` field. +* Add support for ``barcode`` field. :bug:`3172` -* :doc:`/plugins/smartplaylist`: Add new config option `smartplaylist.fields`. +* :doc:`/plugins/smartplaylist`: Add new config option ``smartplaylist.fields``. * :doc:`/plugins/fetchart`: Defer source removal config option evaluation to the point where they are used really, supporting temporary config changes. @@ -515,21 +552,26 @@ Bug fixes: * Improve ListenBrainz error handling. :bug:`5459` * :doc:`/plugins/deezer`: Improve requests error handling. -* :doc:`/plugins/lastimport`: Improve error handling in the `process_tracks` function and enable it to be used with other plugins. +* :doc:`/plugins/lastimport`: Improve error handling in the ``process_tracks`` + function and enable it to be used with other plugins. * :doc:`/plugins/spotify`: Improve handling of ConnectionError. -* :doc:`/plugins/deezer`: Improve Deezer plugin error handling and set requests timeout to 10 seconds. +* :doc:`/plugins/deezer`: Improve Deezer plugin error handling and set requests + timeout to 10 seconds. :bug:`4983` * :doc:`/plugins/spotify`: Add bad gateway (502) error handling. -* :doc:`/plugins/spotify`: Add a limit of 3 retries, instead of retrying endlessly when the API is not available. -* Fix a crash when the Spotify API timeouts or does not return a `Retry-After` interval. +* :doc:`/plugins/spotify`: Add a limit of 3 retries, instead of retrying + endlessly when the API is not available. +* Fix a crash when the Spotify API timeouts or does not return a ``Retry-After`` + interval. :bug:`4942` * :doc:`/plugins/scrub`: Fixed the import behavior where scrubbed database tags - were restored to newly imported tracks with config settings ``scrub.auto: yes`` - and ``import.write: no``. + were restored to newly imported tracks with config settings ``scrub.auto: + yes`` and ``import.write: no``. :bug:`4326` -* :doc:`/plugins/deezer`: Fixed the error where Deezer plugin would crash if non-Deezer id is passed during import. +* :doc:`/plugins/deezer`: Fixed the error where Deezer plugin would crash if + non-Deezer id is passed during import. * :doc:`/plugins/fetchart`: Fix fetching from Cover Art Archive when the - `maxwidth` option is set to one of the supported Cover Art Archive widths. + ``maxwidth`` option is set to one of the supported Cover Art Archive widths. * :doc:`/plugins/discogs`: Fix "Discogs plugin replacing Feat. or Ft. with a comma" by fixing an oversight that removed a functionality from the code base when the MetadataSourcePlugin abstract class was introduced in PR's @@ -544,7 +586,8 @@ Bug fixes: should reduce the chance for errors and "file not found" failures when invoking other command-line tools, especially on Windows. :bug:`4507` -* We now respect the Spotify API's rate limiting, which avoids crashing when the API reports code 429 (too many requests). +* We now respect the Spotify API's rate limiting, which avoids crashing when the + API reports code 429 (too many requests). :bug:`4370` * Fix implicit paths OR queries (e.g. ``beet list /path/ , /other-path/``) which have previously been returning the entire library. @@ -562,7 +605,8 @@ Bug fixes: first 25 tracks of a release). * :doc:`/plugins/spotify`: Fix auto tagger pagination issues (fetch beyond the first 50 tracks of a release). -* :doc:`/plugins/lyrics`: Fix Genius search by using query params instead of body. +* :doc:`/plugins/lyrics`: Fix Genius search by using query params instead of + body. * :doc:`/plugins/unimported`: The new ``ignore_subdirectories`` configuration option added in 1.6.0 now has a default value if it hasn't been set. * :doc:`/plugins/deezer`: Tolerate missing fields when searching for singleton @@ -572,7 +616,7 @@ Bug fixes: ``r128_album_gain`` fields was changed from integer to float to fix loss of precision due to truncation. :bug:`4169` -* Fix a regression in the previous release that caused a `TypeError` when +* Fix a regression in the previous release that caused a ``TypeError`` when moving files across filesystems. :bug:`4168` * :doc:`/plugins/convert`: Deleting the original files during conversion no @@ -592,12 +636,12 @@ Bug fixes: * :doc:`plugins/embedart`: Fix a crash when using recent versions of ImageMagick and the ``compare_threshold`` option. :bug:`4272` -* :doc:`plugins/lyrics`: Fixed issue with Genius header being included in lyrics, - added test case of up-to-date Genius html -* :doc:`plugins/importadded`: Fix a bug with recently added reflink import option - that causes a crash when ImportAdded plugin enabled. +* :doc:`plugins/lyrics`: Fixed issue with Genius header being included in + lyrics, added test case of up-to-date Genius html +* :doc:`plugins/importadded`: Fix a bug with recently added reflink import + option that causes a crash when ImportAdded plugin enabled. :bug:`4389` -* :doc:`plugins/convert`: Fix a bug with the `wma` format alias. +* :doc:`plugins/convert`: Fix a bug with the ``wma`` format alias. * :doc:`/plugins/web`: Fix get file from item. * :doc:`/plugins/lastgenre`: Fix a duplicated entry for trip hop in the default genre list. @@ -607,10 +651,12 @@ Bug fixes: :bug:`4406` * :doc:`plugins/embedart`: Add support for ImageMagick 7.1.1-12 :bug:`4836` -* :doc:`/plugins/fromfilename`: Fix failed detection of - filename patterns. - :bug:`4561` :bug:`4600` -* Fix issue where deletion of flexible fields on an album doesn't cascade to items +* :doc:`/plugins/fromfilename`: Fix failed detection of <track> <title> filename + patterns. + :bug:`4561` + :bug:`4600` +* Fix issue where deletion of flexible fields on an album doesn't cascade to + items :bug:`4662` * Fix issue where ``beet write`` continuously retags the ``albumtypes`` metadata field in files. Additionally broken data could have been added to the library @@ -641,9 +687,9 @@ Bug fixes: displayed unless the detail configuration is enabled. * :doc:`/plugins/web`: Fix range request support, allowing to play large audio/ opus files using e.g. a browser/firefox or gstreamer/mopidy directly. -* Fix bug where `zsh` completion script made assumptions about the specific - variant of `awk` installed and required specific settings for `sqlite3` - and caching in `zsh`. +* Fix bug where ``zsh`` completion script made assumptions about the specific + variant of ``awk`` installed and required specific settings for ``sqlite3`` + and caching in ``zsh``. :bug:`3546` * Remove unused functions :bug:`5103` * Fix bug where all media types are reported as the first media type when @@ -653,7 +699,7 @@ Bug fixes: ignored directories. :bug:`5130` * Fix bug where some plugin commands hang indefinitely due to a missing - `requests` timeout. + ``requests`` timeout. * Fix cover art resizing logic to support multiple steps of resizing :bug:`5151` * :doc:`/plugins/convert`: Fix attempt to convert and perform side-effects if @@ -662,7 +708,7 @@ Bug fixes: For plugin developers: * beets now explicitly prevents multiple plugins to define replacement - functions for the same field. When previously defining `template_fields` + functions for the same field. When previously defining ``template_fields`` for the same field in two plugins, the last loaded plugin would silently overwrite the function defined by the other plugin. Now, beets will raise an exception when this happens. @@ -681,7 +727,8 @@ For packagers: Other changes: -* Add ``sphinx`` and ``sphinx_rtd_theme`` as dependencies for a new ``docs`` extra +* Add ``sphinx`` and ``sphinx_rtd_theme`` as dependencies for a new ``docs`` + extra :bug:`4643` * :doc:`/plugins/absubmit`: Deprecate the ``absubmit`` plugin since AcousticBrainz has stopped accepting new submissions. @@ -774,24 +821,24 @@ Bug fixes: For plugin developers: -* :py:meth:`beets.library.Item.destination` now accepts a `replacements` +* :py:meth:`beets.library.Item.destination` now accepts a ``replacements`` argument to be used in favor of the default. -* The `pluginload` event is now sent after plugin types and queries are +* The ``pluginload`` event is now sent after plugin types and queries are available, not before. -* A new plugin event, `album_removed`, is called when an album is removed from +* A new plugin event, ``album_removed``, is called when an album is removed from the library (even when its file is not deleted from disk). Here are some notes for packagers: * As noted above, the minimum Python version is now 3.6. -* We fixed a flaky test, named `test_album_art` in the `test_zero.py` file, +* We fixed a flaky test, named ``test_album_art`` in the ``test_zero.py`` file, that some distributions had disabled. Disabling this test should no longer be necessary. :bug:`4037` :bug:`4038` * This version of beets no longer depends on the `six`_ library. :bug:`4030` -* The `gmusic` plugin was removed since Google Play Music has been shut down. - Thus, the optional dependency on `gmusicapi` does not exist anymore. +* The ``gmusic`` plugin was removed since Google Play Music has been shut down. + Thus, the optional dependency on ``gmusicapi`` does not exist anymore. :bug:`4089` 1.5.0 (August 19, 2021) @@ -814,8 +861,8 @@ Major new features: * Fields in queries now fall back to an item's album and check its fields too. Notably, this allows querying items by an album's attribute: in other words, - ``beet list foo:bar`` will not only find tracks with the `foo` attribute; it - will also find tracks *on albums* that have the `foo` attribute. This may be + ``beet list foo:bar`` will not only find tracks with the ``foo`` attribute; it + will also find tracks *on albums* that have the ``foo`` attribute. This may be particularly useful in the :ref:`path-format-config`, which matches individual items to decide which path to use. Thanks to :user:`FichteFoll`. @@ -852,7 +899,7 @@ Major new features: other commands. :bug:`3882` * :doc:`/plugins/fetchart`: The plugin can now get album art from `last.fm`_. :bug:`3530` -* :doc:`/plugins/web`: The API now supports the HTTP `DELETE` and `PATCH` +* :doc:`/plugins/web`: The API now supports the HTTP ``DELETE`` and ``PATCH`` methods for modifying items. They are disabled by default; set ``readonly: no`` in your configuration file to enable modification via the API. @@ -863,12 +910,12 @@ Other new things: * ``beet remove`` now also allows interactive selection of items from the query, similar to ``beet modify``. * Enable HTTPS for MusicBrainz by default and add configuration option - `https` for custom servers. See :ref:`musicbrainz-config` for more details. -* :doc:`/plugins/mpdstats`: Add a new `strip_path` option to help build the + ``https`` for custom servers. See :ref:`musicbrainz-config` for more details. +* :doc:`/plugins/mpdstats`: Add a new ``strip_path`` option to help build the right local path from MPD information. * :doc:`/plugins/convert`: Conversion can now parallelize conversion jobs on Python 3. -* :doc:`/plugins/lastgenre`: Add a new `title_case` config option to make +* :doc:`/plugins/lastgenre`: Add a new ``title_case`` config option to make title-case formatting optional. * There's a new message when running ``beet config`` when there's no available configuration file. @@ -877,7 +924,7 @@ Other new things: "keep both" to reflect that there may be more than two albums involved. :bug:`3569` * :doc:`/plugins/chroma`: The plugin now updates file metadata after - generating fingerprints through the `submit` command. + generating fingerprints through the ``submit`` command. * :doc:`/plugins/lastgenre`: Added more heavy metal genres to the built-in genre filter lists. * A new :doc:`/plugins/subsonicplaylist` can import playlists from a Subsonic @@ -896,8 +943,8 @@ Other new things: allow downloading of higher resolution iTunes artwork (at the expense of file size). :bug:`3391` -* :doc:`plugins/discogs`: The plugin applies two new fields: `discogs_labelid` - and `discogs_artistid`. +* :doc:`plugins/discogs`: The plugin applies two new fields: ``discogs_labelid`` + and ``discogs_artistid``. :bug:`3413` * :doc:`/plugins/export`: Added a new ``-f`` (``--format``) flag, which can export your data as JSON, JSON lines, CSV, or XML. @@ -942,7 +989,7 @@ Other new things: Windows. Thanks to :user:`MartyLake`. :bug:`3331` :bug:`3334` -* The `data_source` field, which indicates which metadata source was used +* The ``data_source`` field, which indicates which metadata source was used during an autotagging import, is now also applied as an album-level flexible attribute. :bug:`3350` :bug:`1693` @@ -1000,7 +1047,7 @@ Other new things: * :doc:`/plugins/badfiles`: Checkers can now run during import with the ``check_on_import`` config option. * :doc:`/plugins/export`: The plugin is now much faster when using the - `--include-keys` option is used. + ``--include-keys`` option is used. Thanks to :user:`ssssam`. * The importer's :ref:`set_fields` option now saves all updated fields to on-disk metadata. @@ -1017,14 +1064,14 @@ Other new things: * ``beet update`` will now confirm that the user still wants to update if their library folder cannot be found, preventing the user from accidentally wiping out their beets database. - Thanks to user: `logan-arens`. + Thanks to user: ``logan-arens``. :bug:`1934` Fixes: * Adapt to breaking changes in Python's ``ast`` module in Python 3.8. -* :doc:`/plugins/beatport`: Fix the assignment of the `genre` field, and - rename `musical_key` to `initial_key`. +* :doc:`/plugins/beatport`: Fix the assignment of the ``genre`` field, and + rename ``musical_key`` to ``initial_key``. :bug:`3387` * :doc:`/plugins/lyrics`: Fixed the Musixmatch backend for lyrics pages when lyrics are divided into multiple elements on the webpage, and when the @@ -1037,8 +1084,8 @@ Fixes: * :doc:`/plugins/discogs`: Fixed a bug with the ``index_tracks`` option that sometimes caused the index to be discarded. Also, remove the extra semicolon that was added when there is no index track. -* :doc:`/plugins/subsonicupdate`: The API client was using the `POST` method - rather the `GET` method. +* :doc:`/plugins/subsonicupdate`: The API client was using the ``POST`` method + rather the ``GET`` method. Also includes better exception handling, response parsing, and tests. * :doc:`/plugins/the`: Fixed incorrect regex for "the" that matched any 3-letter combination of the letters t, h, e. @@ -1091,7 +1138,7 @@ Fixes: :bug:`3446` * :doc:`/plugins/parentwork`: Don't save tracks when nothing has changed. :bug:`3492` -* Added a warning when configuration files defined in the `include` directive +* Added a warning when configuration files defined in the ``include`` directive of the configuration file fail to be imported. :bug:`3498` * Added normalization to integer values in the database, which should avoid @@ -1139,13 +1186,14 @@ Fixes: :bug:`3773` :bug:`3774` * Fix a bug causing PIL to generate poor quality JPEGs when resizing artwork. :bug:`3743` -* :doc:`plugins/keyfinder`: Catch output from ``keyfinder-cli`` that is missing key. +* :doc:`plugins/keyfinder`: Catch output from ``keyfinder-cli`` that is missing + key. :bug:`2242` * :doc:`plugins/replaygain`: Disable parallel analysis on import by default. :bug:`3819` * :doc:`/plugins/mpdstats`: Fix Python 2/3 compatibility :bug:`3798` -* :doc:`/plugins/discogs`: Replace the deprecated official `discogs-client` +* :doc:`/plugins/discogs`: Replace the deprecated official ``discogs-client`` library with the community supported `python3-discogs-client`_ library. :bug:`3608` * :doc:`/plugins/chroma`: Fixed submitting AcoustID information for tracks @@ -1186,7 +1234,7 @@ Fixes: * :doc:`/plugins/lyrics`: Removed the LyricWiki source (the site shut down on 21/09/2020). * :doc:`/plugins/subsonicupdate`: The plugin is now functional again. A new - `auth` configuration option is required in the configuration to specify the + ``auth`` configuration option is required in the configuration to specify the flavor of authentication to use. :bug:`4002` @@ -1213,16 +1261,16 @@ For plugin developers: fixed. If they resurface, please reopen the relevant issue. :bug:`3309` :bug:`3330` * The ``beets.plugins.MetadataSourcePlugin`` base class has been added to - simplify development of plugins which query album, track, and search - APIs to provide metadata matches for the importer. Refer to the + simplify development of plugins which query album, track, and search APIs to + provide metadata matches for the importer. Refer to the :doc:`/plugins/spotify` and the :doc:`/plugins/deezer` for examples of using this template class. :bug:`3355` -* Accessing fields on an `Item` now falls back to the album's - attributes. So, for example, ``item.foo`` will first look for a field `foo` on - `item` and, if it doesn't exist, next tries looking for a field named `foo` - on the album that contains `item`. If you specifically want to access an - item's attributes, use ``Item.get(key, with_album=False)``. :bug:`2988` +* Accessing fields on an ``Item`` now falls back to the album's attributes. So, + for example, ``item.foo`` will first look for a field ``foo`` on ``item`` + and, if it doesn't exist, next tries looking for a field named ``foo`` on the + album that contains ``item``. If you specifically want to access an item's + attributes, use ``Item.get(key, with_album=False)``. :bug:`2988` * ``Item.keys`` also has a ``with_album`` argument now, defaulting to ``True``. * A ``revision`` attribute has been added to ``Database``. It is increased on every transaction that mutates it. :bug:`2988` @@ -1244,12 +1292,13 @@ For packagers: called `Confuse`_, released as :pypi:`confuse`. Beets now depends on this package. Confuse has existed separately for some time and is used by unrelated projects, but until now we've been bundling a copy within beets. -* We attempted to fix an unreliable test, so a patch to `skip <https://sources.debian.org/src/beets/1.4.7-2/debian/patches/skip-broken-test/>`_ - or `repair <https://build.opensuse.org/package/view_file/openSUSE:Factory/beets/fix_test_command_line_option_relative_to_working_dir.diff?expand=1>`_ - the test may no longer be necessary. +* We attempted to fix an unreliable test, so a patch to `skip-broken-test`_ or + `repairing`_ may no longer be necessary. * This version drops support for Python 3.4. * We have removed an optional dependency on bs1770gain. +.. _repairing: https://build.opensuse.org/package/view_file/openSUSE:Factory/beets/fix_test_command_line_option_relative_to_working_dir.diff?expand=1 +.. _skip-broken-test: https://sources.debian.org/src/beets/1.4.7-2/debian/patches/skip-broken-test/ .. _Fish shell: https://fishshell.com/ .. _MediaFile: https://github.com/beetbox/mediafile .. _Confuse: https://github.com/beetbox/confuse @@ -1289,9 +1338,10 @@ There are some fixes in this release: Here's a note for packagers: * ``pathlib`` is now an optional test dependency on Python 3.4+, removing the - need for `a Debian patch <https://sources.debian.org/src/beets/1.4.7-2/debian/patches/pathlib-is-stdlib/>`_. + need for `Debian pathlib patch`_ :bug:`3275` +.. _Debian pathlib patch: https://sources.debian.org/src/beets/1.4.7-2/debian/patches/pathlib-is-stdlib/ .. _NO_COLOR: https://no-color.org 1.4.8 (May 16, 2019) @@ -1407,7 +1457,8 @@ And many improvements to existing plugins: fields, which enables easier querying and avoids a problem where very small numbers would be stored as strings. Thanks to :user:`rain0r`. - :bug:`2790` :bug:`3238` + :bug:`2790` + :bug:`3238` .. _Google Groups: https://groups.google.com/forum/#!searchin/beets-users/mbsync|sort:date/beets-users/iwCF6bNdh9A/i1xl4Gx8BQAJ @@ -1450,8 +1501,8 @@ Several improvements are related to usability: :bug:`3117` * Modify selection can now be applied early without selecting every item. :bug:`3083` -* Beets now emits more useful messages during startup if SQLite returns an error. The - SQLite error message is now attached to the beets message. +* Beets now emits more useful messages during startup if SQLite returns an + error. The SQLite error message is now attached to the beets message. :bug:`3005` * Fixed a confusing typo when the :doc:`/plugins/convert` plugin copies the art covers. @@ -1510,17 +1561,20 @@ addressing changes interfaces: :bug:`2826` :bug:`3092` * Restore iTunes Store album art source, and remove the dependency on :pypi:`python-itunes`, which had gone unmaintained and was not - Python-3-compatible. - Thanks to :user:`ocelma` for creating :pypi:`python-itunes` in the first place. - Thanks to :user:`nathdwek`. - :bug:`2371` :bug:`2551` :bug:`2718` + Python-3-compatible. Thanks to :user:`ocelma` for creating + :pypi:`python-itunes` in the first place. Thanks to :user:`nathdwek`. + :bug:`2371` + :bug:`2551` + :bug:`2718` * :doc:`/plugins/lastgenre`, :doc:`/plugins/edit`: Avoid a deprecation warnings - from the :pypi:`PyYAML` library by switching to the safe loader. - Thanks to :user:`translit` and :user:`sbraz`. - :bug:`3192` :bug:`3225` -* Fix a problem when resizing images with :pypi:`PIL`/:pypi:`pillow` on Python 3. - Thanks to :user:`architek`. - :bug:`2504` :bug:`3029` + from the :pypi:`PyYAML` library by switching to the safe loader. Thanks to + :user:`translit` and :user:`sbraz`. + :bug:`3192` + :bug:`3225` +* Fix a problem when resizing images with :pypi:`PIL`/:pypi:`pillow` on Python + 3. Thanks to :user:`architek`. + :bug:`2504` + :bug:`3029` And there are many other fixes: @@ -1677,12 +1731,14 @@ There are lots and lots of fixes: * :doc:`/plugins/ftintitle`: The ``drop`` config option had no effect; it now does what it says it should do. :bug:`2817` -* Importing a release with multiple release events now selects the - event based on the order of your :ref:`preferred` countries rather than - the order of release events in MusicBrainz. :bug:`2816` -* :doc:`/plugins/web`: The time display in the web interface would incorrectly jump - at the 30-second mark of every minute. Now, it correctly changes over at zero - seconds. :bug:`2822` +* Importing a release with multiple release events now selects the event based + on the order of your :ref:`preferred` countries rather than the order of + release events in MusicBrainz. + :bug:`2816` +* :doc:`/plugins/web`: The time display in the web interface would incorrectly + jump at the 30-second mark of every minute. Now, it correctly changes over at + zero seconds. + :bug:`2822` * :doc:`/plugins/web`: Fetching album art now works (instead of throwing an exception) under Python 3. Additionally, the server will now return a 404 response when the album ID @@ -1832,7 +1888,7 @@ There are lots and lots of bug fixes: * Fix a crash when numeric metadata fields contain just a minus or plus sign with no following numbers. Thanks to :user:`eigengrau`. :bug:`2741` * :doc:`/plugins/fromfilename`: Recognize file names that contain *only* a - track number, such as `01.mp3`. Also, the plugin now allows underscores as a + track number, such as ``01.mp3``. Also, the plugin now allows underscores as a separator between fields. Thanks to :user:`Vrihub`. :bug:`2738` :bug:`2759` @@ -1845,10 +1901,10 @@ There are some changes for developers: * "Fixed fields" in Album and Item objects are now more strict about translating missing values into type-specific null-like values. This should help in - cases where a string field is unexpectedly `None` sometimes instead of just + cases where a string field is unexpectedly ``None`` sometimes instead of just showing up as an empty string. :bug:`2605` -* Refactored the move functions the `beets.library` module and the - `manipulate_files` function in `beets.importer` to use a single parameter +* Refactored the move functions the ``beets.library`` module and the + ``manipulate_files`` function in ``beets.importer`` to use a single parameter describing the file operation instead of multiple Boolean flags. There is a new numerated type describing how to move, copy, or link files. :bug:`2682` @@ -1865,7 +1921,7 @@ Here are the new features: * You can now set fields to certain values during :ref:`import-cmd`, using either a ``--set field=value`` command-line flag or a new :ref:`set_fields` - configuration option under the `importer` section. + configuration option under the ``importer`` section. Thanks to :user:`bartkl`. :bug:`1881` :bug:`2581` * :ref:`Date queries <datequery>` can now include times, so you can filter your music down to the second. Thanks to :user:`discopatrick`. :bug:`2506` @@ -1877,7 +1933,7 @@ Here are the new features: library. Thanks to :user:`tigranl`. :bug:`2553` :bug:`2586` * :doc:`/plugins/replaygain`: We now keep R128 data in separate tags from classic ReplayGain data for formats that need it (namely, Ogg Opus). A new - `r128` configuration option enables this behavior for specific formats. + ``r128`` configuration option enables this behavior for specific formats. Thanks to :user:`autrimpo`. :bug:`2557` :bug:`2560` * The :ref:`move-cmd` command gained a new ``--export`` flag, which copies files to an external location without changing their paths in the library @@ -1885,8 +1941,8 @@ Here are the new features: There are also some bug fixes: -* :doc:`/plugins/lastgenre`: Fix a crash when using the `prefer_specific` and - `canonical` options together. Thanks to :user:`yacoob`. :bug:`2459` +* :doc:`/plugins/lastgenre`: Fix a crash when using the ``prefer_specific`` and + ``canonical`` options together. Thanks to :user:`yacoob`. :bug:`2459` :bug:`2583` * :doc:`/plugins/web`: Fix a crash on Windows under Python 2 when serving non-ASCII filenames. Thanks to :user:`robot3498712`. :bug:`2592` :bug:`2593` @@ -1930,7 +1986,7 @@ Here's a full list of new features: * The ``%aunique`` template function for :ref:`aunique` now takes a third argument that specifies which brackets to use around the disambiguator value. The argument can be any two characters that represent the left and - right brackets. It defaults to `[]` and can also be blank to turn off + right brackets. It defaults to ``[]`` and can also be blank to turn off bracketing. :bug:`2397` :bug:`2399` * Added a ``--move`` or ``-m`` option to the importer so that the files can be moved to the library instead of being copied or added "in place." @@ -1941,13 +1997,13 @@ Here's a full list of new features: * :doc:`/plugins/embedart`: The explicit ``embedart`` command now asks for confirmation before embedding art into music files. Thanks to :user:`Stunner`. :bug:`1999` -* You can now run beets by typing `python -m beets`. :bug:`2453` +* You can now run beets by typing ``python -m beets``. :bug:`2453` * :doc:`/plugins/smartplaylist`: Different playlist specifications that generate identically-named playlist files no longer conflict; instead, the resulting lists of tracks are concatenated. :bug:`2468` * :doc:`/plugins/missing`: A new mode lets you see missing albums from artists you have in your library. Thanks to :user:`qlyoung`. :bug:`2481` -* :doc:`/plugins/web` : Add new `reverse_proxy` config option to allow serving +* :doc:`/plugins/web` : Add new ``reverse_proxy`` config option to allow serving the web plugins under a reverse proxy. * Importing a release with multiple release events now selects the event based on your :ref:`preferred` countries. :bug:`2501` @@ -2176,7 +2232,7 @@ And there are a few bug fixes too: the plugin would always fail to set permissions (and log a warning). :bug:`2089` * :doc:`/plugins/beatport`: Use track numbers from Beatport (instead of - determining them from the order of tracks) and set the `medium_index` + determining them from the order of tracks) and set the ``medium_index`` value. * With :ref:`per_disc_numbering` enabled, some metadata sources (notably, the :doc:`/plugins/beatport`) would not set the track number at all. This is @@ -2291,14 +2347,14 @@ Smaller new things: * There are two new functions available in templates: ``%first`` and ``%ifdef``. See :ref:`template-functions`. -* :doc:`/plugins/convert`: A new `album_art_maxwidth` setting lets you resize +* :doc:`/plugins/convert`: A new ``album_art_maxwidth`` setting lets you resize album art while copying it. -* :doc:`/plugins/convert`: The `extension` setting is now optional for +* :doc:`/plugins/convert`: The ``extension`` setting is now optional for conversion formats. By default, the extension is the same as the name of the configured format. -* :doc:`/plugins/importadded`: A new `preserve_write_mtimes` option +* :doc:`/plugins/importadded`: A new ``preserve_write_mtimes`` option lets you preserve mtime of files even when beets updates their metadata. -* :doc:`/plugins/fetchart`: The `enforce_ratio` option now lets you tolerate +* :doc:`/plugins/fetchart`: The ``enforce_ratio`` option now lets you tolerate images that are *almost* square but differ slightly from an exact 1:1 aspect ratio. * :doc:`/plugins/fetchart`: The plugin can now optionally save the artwork's @@ -2308,8 +2364,8 @@ Smaller new things: *output* stream.) * A new :ref:`ignore_hidden` configuration option lets you ignore files that your OS marks as invisible. -* :doc:`/plugins/web`: A new `values` endpoint lets you get the distinct values - of a field. Thanks to :user:`sumpfralle`. :bug:`2010` +* :doc:`/plugins/web`: A new ``values`` endpoint lets you get the distinct + values of a field. Thanks to :user:`sumpfralle`. :bug:`2010` .. _fanart.tv: https://fanart.tv/ @@ -2330,9 +2386,9 @@ Fixes: command can't be invoked. :bug:`1927` * :doc:`/plugins/fetchart`: Fix a crash in the Wikipedia backend on non-ASCII artist and album names. :bug:`1960` -* :doc:`/plugins/convert`: Change the default `ogg` encoding quality from 2 to - 3 (to fit the default from the `oggenc(1)` manpage). :bug:`1982` -* :doc:`/plugins/convert`: The `never_convert_lossy_files` option now +* :doc:`/plugins/convert`: Change the default ``ogg`` encoding quality from 2 to + 3 (to fit the default from the ``oggenc(1)`` manpage). :bug:`1982` +* :doc:`/plugins/convert`: The ``never_convert_lossy_files`` option now considers AIFF a lossless format. :bug:`2005` * :doc:`/plugins/web`: A proper 404 error, instead of an internal exception, is returned when missing album art is requested. Thanks to @@ -2620,23 +2676,24 @@ The new features: metadata, but you can configure it to use any list of attributes. * :doc:`/plugins/metasync`: Added a new backend to fetch metadata from iTunes. This plugin is still in an experimental phase. :bug:`1450` -* The `move` command has a new ``--pretend`` option, making the command show +* The ``move`` command has a new ``--pretend`` option, making the command show how the items will be moved without actually changing anything. * The importer now supports matching of "pregap" or HTOA (hidden track-one - audio) tracks when they are listed in MusicBrainz. (This feature depends on a - new version of the `python-musicbrainzngs`_ library that is not yet released, but - will start working when it is available.) Thanks to :user:`ruippeixotog`. + audio) tracks when they are listed in MusicBrainz. (This feature depends on + a new version of the `python-musicbrainzngs`_ library that is not yet + released, but will start working when it is available.) Thanks to + :user:`ruippeixotog`. :bug:`1104` :bug:`1493` * :doc:`/plugins/plexupdate`: A new ``token`` configuration option lets you specify a key for Plex Home setups. Thanks to :user:`edcarroll`. :bug:`1494` Fixes: -* :doc:`/plugins/fetchart`: Complain when the `enforce_ratio` - or `min_width` options are enabled but no local imaging backend is available +* :doc:`/plugins/fetchart`: Complain when the ``enforce_ratio`` + or ``min_width`` options are enabled but no local imaging backend is available to carry them out. :bug:`1460` * :doc:`/plugins/importfeeds`: Avoid generating incorrect m3u filename when - both of the `m3u` and `m3u_multi` options are enabled. :bug:`1490` + both of the ``m3u`` and ``m3u_multi`` options are enabled. :bug:`1490` * :doc:`/plugins/duplicates`: Avoid a crash when misconfigured. :bug:`1457` * :doc:`/plugins/mpdstats`: Avoid a crash when the music played is not in the beets library. Thanks to :user:`CodyReichert`. :bug:`1443` @@ -2726,8 +2783,8 @@ New features: * Queries can now use **"or" logic**: if you use a comma to separate parts of a query, items and albums will match *either* side of the comma. For example, - ``beet ls foo , bar`` will get all the items matching `foo` or matching - `bar`. See :ref:`combiningqueries`. :bug:`1423` + ``beet ls foo , bar`` will get all the items matching ``foo`` or matching + ``bar``. See :ref:`combiningqueries`. :bug:`1423` * The autotagger's **matching algorithm is faster**. We now use the `Jellyfish`_ library to compute string similarity, which is better optimized than our hand-rolled edit distance implementation. :bug:`1389` @@ -2740,8 +2797,8 @@ New features: * An experimental new :doc:`/plugins/metasync` lets you get metadata from your favorite music players, starting with Amarok. :bug:`1386` * :doc:`/plugins/fetchart`: There are new settings to control what constitutes - "acceptable" images. The `minwidth` option constrains the minimum image - width in pixels and the `enforce_ratio` option requires that images be + "acceptable" images. The ``minwidth`` option constrains the minimum image + width in pixels and the ``enforce_ratio`` option requires that images be square. :bug:`1394` Little fixes and improvements: @@ -2766,7 +2823,7 @@ Little fixes and improvements: * Fix a crash when the importer cannot open its log file. Thanks to :user:`barsanuphe`. :bug:`1426` * Fix an error when trying to write tags for items with flexible fields called - `date` and `original_date` (which are not built-in beets fields). + ``date`` and ``original_date`` (which are not built-in beets fields). :bug:`1404` .. _Jellyfish: https://github.com/sunlightlabs/jellyfish @@ -2812,7 +2869,7 @@ Major new features and bigger changes: * The importer now records the data source for a match in a new flexible attribute ``data_source`` on items and albums. :bug:`1311` * The colors used in the terminal interface are now configurable via the new - config option ``colors``, nested under the option ``ui``. (Also, the `color` + config option ``colors``, nested under the option ``ui``. (Also, the ``color`` config option has been moved from top-level to under ``ui``. Beets will respect the old color setting, but will warn the user with a deprecation message.) :bug:`1238` @@ -2836,14 +2893,14 @@ You should probably also know about these core changes to the way beets works: ``albumtotal`` computed attribute that provides the total number of tracks on the album. (The :ref:`per_disc_numbering` option has no influence on this field.) -* The `list_format_album` and `list_format_item` configuration keys +* The ``list_format_album`` and ``list_format_item`` configuration keys now affect (almost) every place where objects are printed and logged. (Previously, they only controlled the :ref:`list-cmd` command and a few other scattered pieces.) :bug:`1269` * Relatedly, the ``beet`` program now accept top-level options ``--format-item`` and ``--format-album`` before any subcommand to control how items and albums are displayed. :bug:`1271` -* `list_format_album` and `list_format_album` have respectively been +* ``list_format_album`` and ``list_format_album`` have respectively been renamed :ref:`format_album` and :ref:`format_item`. The old names still work but each triggers a warning message. :bug:`1271` * :ref:`Path queries <pathquery>` are automatically triggered only if the @@ -2929,7 +2986,7 @@ And many little fixes and improvements: Unicode filenames. :bug:`1297` * :doc:`/plugins/discogs`: Handle and log more kinds of communication errors. :bug:`1299` :bug:`1305` -* :doc:`/plugins/lastgenre`: Bugs in the `pylast` library can no longer crash +* :doc:`/plugins/lastgenre`: Bugs in the ``pylast`` library can no longer crash beets. * :doc:`/plugins/convert`: You can now configure the temporary directory for conversions. Thanks to :user:`autochthe`. :bug:`1382` :bug:`1383` @@ -3381,7 +3438,7 @@ And those all-important bug fixes: embedding album art fails. * :doc:`/plugins/convert`: Embed cover art into converted files. Previously they were embedded into the source files. -* New plugin event: `before_item_moved`. Thanks to Robert Speicher. +* New plugin event: ``before_item_moved``. Thanks to Robert Speicher. 1.3.5 (April 15, 2014) ---------------------- @@ -3397,7 +3454,7 @@ library module. The major new features are: -* Beets can now import `zip`, `tar`, and `rar` archives. Just type ``beet +* Beets can now import ``zip``, ``tar``, and ``rar`` archives. Just type ``beet import music.zip`` to have beets transparently extract the files to import. * :doc:`/plugins/replaygain`: Added support for calculating ReplayGain values with GStreamer as well the mp3gain program. This enables ReplayGain @@ -3410,13 +3467,13 @@ The major new features are: In particular, a full complement of features for supporting musical keys are new in this release: -* A new `initial_key` field is available in the database and files' tags. You +* A new ``initial_key`` field is available in the database and files' tags. You can set the field manually using a command like ``beet modify initial_key=Am``. -* The ``echonest`` plugin sets the `initial_key` field if the data is +* The ``echonest`` plugin sets the ``initial_key`` field if the data is available. * A new :doc:`/plugins/keyfinder` runs a command-line tool to get the key from - audio data and store it in the `initial_key` field. + audio data and store it in the ``initial_key`` field. There are also many bug fixes and little enhancements: @@ -3483,7 +3540,7 @@ New stuff: * :doc:`/plugins/lastgenre`: Separator in genre lists can now be configured. Thanks to brilnius. * We now only use "primary" aliases for artist names from MusicBrainz. This - eliminates some strange naming that could occur when the `languages` config + eliminates some strange naming that could occur when the ``languages`` config option was set. Thanks to Filipe Fortes. * The performance of the autotagger's matching mechanism is vastly improved. This should be noticeable when matching against very large releases such as @@ -4546,8 +4603,8 @@ release. and delete the originals, which is inefficient if the source and destination are on the same filesystem. Use the ``import_move`` configuration option and see :doc:`/reference/config` for more details. Thanks to Domen Kožar. -* New :doc:`/plugins/random`: Randomly select albums and tracks from your library. - Thanks to Philippe Mongeau. +* New :doc:`/plugins/random`: Randomly select albums and tracks from your + library. Thanks to Philippe Mongeau. * The :doc:`/plugins/mbcollection` by Jeffrey Aylesworth was added to the core beets distribution. * New :doc:`/plugins/importfeeds`: Catalog imported files in ``m3u`` playlist @@ -4851,7 +4908,7 @@ below, for a plethora of new features. * **Queries can now contain whitespace.** Spaces passed as shell arguments are now preserved, so you can use your shell's escaping syntax (quotes or backslashes, for instance) to include spaces in queries. For example, - typing``beet ls "the knife"`` or ``beet ls the\ knife``. Read more in + ``beet ls "the knife"`` or ``beet ls the\ knife``. Read more in :doc:`/reference/query`. * Queries can **match items from the library by directory**. A ``path:`` prefix @@ -5031,7 +5088,7 @@ new configuration options and the ability to clean up empty directory subtrees. album type (see below). The default path formats have been changed to use ``$albumartist`` instead of ``$artist``. -* A **new ``albumtype`` field** reflects the release type `as specified by +* A **new ``albumtype`` **field** reflects the release type `as specified by MusicBrainz`_. * When deleting files, beets now appropriately "prunes" the directory @@ -5134,7 +5191,7 @@ issue involves correct ordering of autotagged albums. * Fixed a Unicode encoding error when entering special characters into the "manual search" prompt. -* Added `` beet version`` command that just shows the current release version. +* Added ``beet version`` command that just shows the current release version. .. _upstream bug: https://github.com/quodlibet/mutagen/issues/7 .. _Bluelet: https://github.com/sampsyo/bluelet @@ -5343,7 +5400,7 @@ BPD). To "upgrade" an old database, you can use the included ``albumify`` plugin * Fixed some bugs with encoding paths on Windows. Also, ``:`` is now replaced with ``-`` in path names (instead of ``_``) for readability. -* ``MediaFile``s now have a ``format`` attribute, so you can use ``$format`` in +* ``MediaFile`` now has a ``format`` attribute, so you can use ``$format`` in your library path format strings like ``$artist - $album ($format)`` to get directories with names like ``Paul Simon - Graceland (FLAC)``. diff --git a/docs/dev/library.rst b/docs/dev/library.rst index 8c47e4dc3..d822a5bfd 100644 --- a/docs/dev/library.rst +++ b/docs/dev/library.rst @@ -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 diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst index 885c38ee4..53b498a17 100644 --- a/docs/dev/plugins.rst +++ b/docs/dev/plugins.rst @@ -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: diff --git a/docs/faq.rst b/docs/faq.rst index ac7818ab2..6a2fbea97 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -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). diff --git a/docs/guides/advanced.rst b/docs/guides/advanced.rst index 3802c91b1..a23192a3c 100644 --- a/docs/guides/advanced.rst +++ b/docs/guides/advanced.rst @@ -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:: diff --git a/docs/guides/main.rst b/docs/guides/main.rst index 255484dde..22fc55e3c 100644 --- a/docs/guides/main.rst +++ b/docs/guides/main.rst @@ -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``. diff --git a/docs/guides/tagger.rst b/docs/guides/tagger.rst index bf1ecbd8a..c0da50f00 100644 --- a/docs/guides/tagger.rst +++ b/docs/guides/tagger.rst @@ -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 diff --git a/docs/plugins/absubmit.rst b/docs/plugins/absubmit.rst index 25c176e51..cee657665 100644 --- a/docs/plugins/absubmit.rst +++ b/docs/plugins/absubmit.rst @@ -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 diff --git a/docs/plugins/acousticbrainz.rst b/docs/plugins/acousticbrainz.rst index 3a053e123..f64b220ac 100644 --- a/docs/plugins/acousticbrainz.rst +++ b/docs/plugins/acousticbrainz.rst @@ -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] diff --git a/docs/plugins/albumtypes.rst b/docs/plugins/albumtypes.rst index bf736abca..378ea676b 100644 --- a/docs/plugins/albumtypes.rst +++ b/docs/plugins/albumtypes.rst @@ -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 diff --git a/docs/plugins/autobpm.rst b/docs/plugins/autobpm.rst index 53908c517..f7f7458d8 100644 --- a/docs/plugins/autobpm.rst +++ b/docs/plugins/autobpm.rst @@ -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: diff --git a/docs/plugins/badfiles.rst b/docs/plugins/badfiles.rst index 796f991e1..8f2202c72 100644 --- a/docs/plugins/badfiles.rst +++ b/docs/plugins/badfiles.rst @@ -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. diff --git a/docs/plugins/bareasc.rst b/docs/plugins/bareasc.rst index 0c8d6636c..2d19f3915 100644 --- a/docs/plugins/bareasc.rst +++ b/docs/plugins/bareasc.rst @@ -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 ------------- diff --git a/docs/plugins/beatport.rst b/docs/plugins/beatport.rst index bc10f02a4..cbc3f89f1 100644 --- a/docs/plugins/beatport.rst +++ b/docs/plugins/beatport.rst @@ -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/ diff --git a/docs/plugins/bucket.rst b/docs/plugins/bucket.rst index ee1857777..43df8e691 100644 --- a/docs/plugins/bucket.rst +++ b/docs/plugins/bucket.rst @@ -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. diff --git a/docs/plugins/chroma.rst b/docs/plugins/chroma.rst index 30d57939f..4057ee4c0 100644 --- a/docs/plugins/chroma.rst +++ b/docs/plugins/chroma.rst @@ -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 diff --git a/docs/plugins/convert.rst b/docs/plugins/convert.rst index a41e6c529..6fff2c605 100644 --- a/docs/plugins/convert.rst +++ b/docs/plugins/convert.rst @@ -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 diff --git a/docs/plugins/deezer.rst b/docs/plugins/deezer.rst index 9f8da41fd..9b31f25eb 100644 --- a/docs/plugins/deezer.rst +++ b/docs/plugins/deezer.rst @@ -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. diff --git a/docs/plugins/discogs.rst b/docs/plugins/discogs.rst index c8df12a41..68d4cda21 100644 --- a/docs/plugins/discogs.rst +++ b/docs/plugins/discogs.rst @@ -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 diff --git a/docs/plugins/embedart.rst b/docs/plugins/embedart.rst index 9a91055f4..85998e88e 100644 --- a/docs/plugins/embedart.rst +++ b/docs/plugins/embedart.rst @@ -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 diff --git a/docs/plugins/embyupdate.rst b/docs/plugins/embyupdate.rst index 1c6fc61e4..803703902 100644 --- a/docs/plugins/embyupdate.rst +++ b/docs/plugins/embyupdate.rst @@ -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) diff --git a/docs/plugins/export.rst b/docs/plugins/export.rst index bca9d1e5a..788ce418a 100644 --- a/docs/plugins/export.rst +++ b/docs/plugins/export.rst @@ -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`_. diff --git a/docs/plugins/fetchart.rst b/docs/plugins/fetchart.rst index 1da92a493..7370e544b 100644 --- a/docs/plugins/fetchart.rst +++ b/docs/plugins/fetchart.rst @@ -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. diff --git a/docs/plugins/fish.rst b/docs/plugins/fish.rst index 0c89576c5..361c4b55f 100644 --- a/docs/plugins/fish.rst +++ b/docs/plugins/fish.rst @@ -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. diff --git a/docs/plugins/ftintitle.rst b/docs/plugins/ftintitle.rst index 63d023dc9..348487183 100644 --- a/docs/plugins/ftintitle.rst +++ b/docs/plugins/ftintitle.rst @@ -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 diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 5fbe42d9f..e76bfe44a 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -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. diff --git a/docs/plugins/inline.rst b/docs/plugins/inline.rst index 4dfca261d..9ad91e80b 100644 --- a/docs/plugins/inline.rst +++ b/docs/plugins/inline.rst @@ -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:: diff --git a/docs/plugins/ipfs.rst b/docs/plugins/ipfs.rst index 5bf8ca906..8088d64f2 100644 --- a/docs/plugins/ipfs.rst +++ b/docs/plugins/ipfs.rst @@ -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. diff --git a/docs/plugins/keyfinder.rst b/docs/plugins/keyfinder.rst index a5c64d39c..bab0b41d5 100644 --- a/docs/plugins/keyfinder.rst +++ b/docs/plugins/keyfinder.rst @@ -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/ diff --git a/docs/plugins/kodiupdate.rst b/docs/plugins/kodiupdate.rst index 90b33d9c1..7c3d0e190 100644 --- a/docs/plugins/kodiupdate.rst +++ b/docs/plugins/kodiupdate.rst @@ -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. diff --git a/docs/plugins/lastgenre.rst b/docs/plugins/lastgenre.rst index a48cd3074..50c7ade43 100644 --- a/docs/plugins/lastgenre.rst +++ b/docs/plugins/lastgenre.rst @@ -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: diff --git a/docs/plugins/limit.rst b/docs/plugins/limit.rst index cd89a5579..1684cbcbe 100644 --- a/docs/plugins/limit.rst +++ b/docs/plugins/limit.rst @@ -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+ diff --git a/docs/plugins/listenbrainz.rst b/docs/plugins/listenbrainz.rst index 037ccd685..fe2c1956d 100644 --- a/docs/plugins/listenbrainz.rst +++ b/docs/plugins/listenbrainz.rst @@ -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 diff --git a/docs/plugins/loadext.rst b/docs/plugins/loadext.rst index 5acd10ec7..6764844d6 100644 --- a/docs/plugins/loadext.rst +++ b/docs/plugins/loadext.rst @@ -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 diff --git a/docs/plugins/mbsubmit.rst b/docs/plugins/mbsubmit.rst index 0e86ddc69..90dcf477e 100644 --- a/docs/plugins/mbsubmit.rst +++ b/docs/plugins/mbsubmit.rst @@ -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) diff --git a/docs/plugins/mpdstats.rst b/docs/plugins/mpdstats.rst index 865b615a7..5be9ef414 100644 --- a/docs/plugins/mpdstats.rst +++ b/docs/plugins/mpdstats.rst @@ -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 diff --git a/docs/plugins/mpdupdate.rst b/docs/plugins/mpdupdate.rst index 01a6a9fe7..1b025d700 100644 --- a/docs/plugins/mpdupdate.rst +++ b/docs/plugins/mpdupdate.rst @@ -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. diff --git a/docs/plugins/musicbrainz.rst b/docs/plugins/musicbrainz.rst index 9068ec45d..4e7ad3317 100644 --- a/docs/plugins/musicbrainz.rst +++ b/docs/plugins/musicbrainz.rst @@ -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``. diff --git a/docs/plugins/parentwork.rst b/docs/plugins/parentwork.rst index fb15af9f1..a3a5aec99 100644 --- a/docs/plugins/parentwork.rst +++ b/docs/plugins/parentwork.rst @@ -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`` diff --git a/docs/plugins/permissions.rst b/docs/plugins/permissions.rst index 9c4cdc0aa..40666c4e2 100644 --- a/docs/plugins/permissions.rst +++ b/docs/plugins/permissions.rst @@ -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:: diff --git a/docs/plugins/play.rst b/docs/plugins/play.rst index d72ec4e0d..077c727fb 100644 --- a/docs/plugins/play.rst +++ b/docs/plugins/play.rst @@ -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 diff --git a/docs/plugins/plexupdate.rst b/docs/plugins/plexupdate.rst index 3ca9cbfab..c5db60b0d 100644 --- a/docs/plugins/plexupdate.rst +++ b/docs/plugins/plexupdate.rst @@ -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`` diff --git a/docs/plugins/replace.rst b/docs/plugins/replace.rst index 8695d492c..a972d74be 100644 --- a/docs/plugins/replace.rst +++ b/docs/plugins/replace.rst @@ -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. diff --git a/docs/plugins/replaygain.rst b/docs/plugins/replaygain.rst index 900f6f8c4..39e9b5522 100644 --- a/docs/plugins/replaygain.rst +++ b/docs/plugins/replaygain.rst @@ -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] diff --git a/docs/plugins/spotify.rst b/docs/plugins/spotify.rst index c5aff8ef3..b7d43d6c7 100644 --- a/docs/plugins/spotify.rst +++ b/docs/plugins/spotify.rst @@ -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``. diff --git a/docs/plugins/subsonicplaylist.rst b/docs/plugins/subsonicplaylist.rst index 98c83ebe1..255d96a5d 100644 --- a/docs/plugins/subsonicplaylist.rst +++ b/docs/plugins/subsonicplaylist.rst @@ -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. diff --git a/docs/plugins/substitute.rst b/docs/plugins/substitute.rst index c6fec8054..ace0e5d3f 100644 --- a/docs/plugins/substitute.rst +++ b/docs/plugins/substitute.rst @@ -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 diff --git a/docs/plugins/unimported.rst b/docs/plugins/unimported.rst index 80ee8004b..16b378b8b 100644 --- a/docs/plugins/unimported.rst +++ b/docs/plugins/unimported.rst @@ -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 diff --git a/docs/plugins/web.rst b/docs/plugins/web.rst index 15719e119..f474f4918 100644 --- a/docs/plugins/web.rst +++ b/docs/plugins/web.rst @@ -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`` ++++++++++++++ diff --git a/docs/plugins/zero.rst b/docs/plugins/zero.rst index e3d717dfd..d37da9f06 100644 --- a/docs/plugins/zero.rst +++ b/docs/plugins/zero.rst @@ -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:: diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst index 456059c6c..ebcb689df 100644 --- a/docs/reference/cli.rst +++ b/docs/reference/cli.rst @@ -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. diff --git a/docs/reference/config.rst b/docs/reference/config.rst index 7e93b00ff..cdf9a8099 100644 --- a/docs/reference/config.rst +++ b/docs/reference/config.rst @@ -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. diff --git a/docs/reference/pathformat.rst b/docs/reference/pathformat.rst index d89eb6767..3c500a72a 100644 --- a/docs/reference/pathformat.rst +++ b/docs/reference/pathformat.rst @@ -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 -------------- diff --git a/docs/reference/query.rst b/docs/reference/query.rst index eaa2d6701..b9ffcb886 100644 --- a/docs/reference/query.rst +++ b/docs/reference/query.rst @@ -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::