Backup_Repos/beets
1
0
Fork 0
mirror of https://github.com/beetbox/beets.git synced 2026-01-04 15:03:22 +01:00
Code Issues Projects Releases Wiki Activity

Convert autotagger plugin docs to use conf role

Browse source
This commit is contained in:
Šarūnas Nejus 2025-10-12 00:19:08 +01:00
parent a938449b29
commit 498b14ee1d
No known key found for this signature in database
7 changed files with 305 additions and 275 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
beetsplug/discogs.py
View file

@ -132,9 +132,9 @@ class DiscogsPlugin(MetadataSourcePlugin):
"user_token": "",
"separator": ", ",
"index_tracks": False,
"featured_string": "Feat.",
"append_style_genre": False,
"strip_disambiguation": True,
"featured_string": "Feat.",
"anv": {
"artist_credit": True,
"artist": False,

20
docs/plugins/deezer.rst
View file

@ -35,15 +35,23 @@ Default
.. code-block:: yaml
deezer:
search_query_ascii: no
data_source_mismatch_penalty: 0.5
search_limit: 5
search_query_ascii: no
- **search_query_ascii**: If set to ``yes``, the search query will be converted
to ASCII before being sent to Deezer. 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``.
.. conf:: search_query_ascii
:default: no
If enabled, the search query will be converted to ASCII before being sent to
Deezer. 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``).
.. include:: ./shared_metadata_source_config.rst
Commands
--------
The ``deezer`` plugin provides an additional command ``deezerupdate`` to update
the ``rank`` information from Deezer. The ``rank`` (ranges from 0 to 1M) is a

132
docs/plugins/discogs.rst
View file

@ -71,67 +71,93 @@ Default
.. code-block:: yaml
discogs:
data_source_mismatch_penalty: 0.5
search_limit: 5
apikey: REDACTED
apisecret: REDACTED
tokenfile: discogs_token.json
user_token: REDACTED
user_token:
index_tracks: no
append_style_genre: no
separator: ', '
strip_disambiguation: yes
- **index_tracks**: Index tracks (see the `Discogs guidelines`_) along with
headers, mark divisions between distinct works on the same release or within
works. When enabled, beets will incorporate the names of the divisions
containing each track into the imported track's title. Default: ``no``.
For example, importing `divisions album`_ would result in track names like:
.. code-block:: text
Messiah, Part I: No.1: Sinfony
Messiah, Part II: No.22: Chorus- Behold The Lamb Of God
Athalia, Act I, Scene I: Sinfonia
whereas with ``index_tracks`` disabled you'd get:
.. code-block:: text
No.1: Sinfony
No.22: Chorus- Behold The Lamb Of God
Sinfonia
This option is useful when importing classical music.
- **append_style_genre**: Appends the Discogs style (if found) to the genre tag.
This can be useful if you want more granular genres to categorize your music.
For example, a release in Discogs might have a genre of "Electronic" and a
style of "Techno": enabling this setting would set the genre to be
"Electronic, Techno" (assuming default separator of ``", "``) instead of just
"Electronic". Default: ``False``
- **separator**: How to join multiple genre and style values from Discogs into a
string. Default: ``", "``
- **strip_disambiguation**: Discogs uses strings like ``"(4)"`` to mark distinct
artists and labels with the same name. If you'd like to use the discogs
disambiguation in your tags, you can disable it. Default: ``True``
- **featured_string**: Configure the string used for noting featured artists.
Useful if you prefer ``Featuring`` or ``ft.``. Default: ``Feat.``
- **anv**: These configuration option are dedicated to handling Artist Name
Variations (ANVs). Sometimes a release credits artists differently compared to
the majority of their work. For example, "Basement Jaxx" may be credited as
"Tha Jaxx" or "The Basement Jaxx".You can select any combination of these
config options to control where beets writes and stores the variation credit.
The default, shown below, writes variations to the artist_credit field.
.. code-block:: yaml
discogs:
featured_string: Feat.
anv:
artist_credit: True
artist: False
album_artist: False
artist_credit: yes
artist: no
album_artist: no
data_source_mismatch_penalty: 0.5
search_limit: 5
.. conf:: index_tracks
:default: no
Index tracks (see the `Discogs guidelines`_) along with headers, mark divisions
between distinct works on the same release or within works. When enabled,
beets will incorporate the names of the divisions containing each track into the
imported track's title.
For example, importing `divisions album`_ would result in track names like:
.. code-block:: text
Messiah, Part I: No.1: Sinfony
Messiah, Part II: No.22: Chorus- Behold The Lamb Of God
Athalia, Act I, Scene I: Sinfonia
whereas with ``index_tracks`` disabled you'd get:
.. code-block:: text
No.1: Sinfony
No.22: Chorus- Behold The Lamb Of God
Sinfonia
This option is useful when importing classical music.
.. conf:: append_style_genre
:default: no
Appends the Discogs style (if found) to the genre tag. This can be useful if
you want more granular genres to categorize your music. For example,
a release in Discogs might have a genre of "Electronic" and a style of
"Techno": enabling this setting would set the genre to be "Electronic,
Techno" (assuming default separator of ``", "``) instead of just
"Electronic".
.. conf:: separator
:default: ", "
How to join multiple genre and style values from Discogs into a string.
.. conf:: strip_disambiguation
:default: yes
Discogs uses strings like ``"(4)"`` to mark distinct artists and labels with
the same name. If you'd like to use the Discogs disambiguation in your tags,
you can disable this option.
.. conf:: featured_string
:default: Feat.
Configure the string used for noting featured artists. Useful if you prefer ``Featuring`` or ``ft.``.
.. conf:: anv
This configuration option is dedicated to handling Artist Name
Variations (ANVs). Sometimes a release credits artists differently compared to
the majority of their work. For example, "Basement Jaxx" may be credited as
"Tha Jaxx" or "The Basement Jaxx". You can select any combination of these
config options to control where beets writes and stores the variation credit.
The default, shown below, writes variations to the artist_credit field.
.. code-block:: yaml
discogs:
anv:
artist_credit: yes
artist: no
album_artist: no
.. include:: ./shared_metadata_source_config.rst
.. _discogs guidelines: https://support.discogs.com/hc/en-us/articles/360005055373-Database-Guidelines-12-Tracklisting#Index_Tracks_And_Headings

60
docs/plugins/index.rst
View file

@ -50,65 +50,7 @@ Using Metadata Source Plugins
We provide several :ref:`autotagger_extensions` that fetch metadata from online
databases. They share the following configuration options:
.. _data_source_mismatch_penalty:
- **data_source_mismatch_penalty**: Penalty applied when the data source of a
match candidate differs from the original source of your existing tracks. Any
decimal number between 0.0 and 1.0. Default: ``0.5``.
This setting controls how much to penalize matches from different metadata
sources during import. The penalty is applied when beets detects that a match
candidate comes from a different data source than what appears to be the
original source of your music collection.
**Example configurations:**
.. code-block:: yaml
# Prefer MusicBrainz over Discogs when sources don't match
plugins: musicbrainz discogs
musicbrainz:
data_source_mismatch_penalty: 0.3 # Lower penalty = preferred
discogs:
data_source_mismatch_penalty: 0.8 # Higher penalty = less preferred
.. code-block:: yaml
# Do not penalise candidates from Discogs at all
plugins: musicbrainz discogs
musicbrainz:
data_source_mismatch_penalty: 0.5
discogs:
data_source_mismatch_penalty: 0.0
.. code-block:: yaml
# Disable cross-source penalties entirely
plugins: musicbrainz discogs
musicbrainz:
data_source_mismatch_penalty: 0.0
discogs:
data_source_mismatch_penalty: 0.0
.. tip::
The last configuration is equivalent to setting:
.. code-block:: yaml
match:
distance_weights:
data_source: 0.0 # Disable data source matching
- **source_weight**
.. deprecated:: 2.5 Use `data_source_mismatch_penalty`_ instead.
- **search_limit**: Maximum number of search results to consider. Default:
``5``.
.. include:: ./shared_metadata_source_config.rst
.. toctree::
:hidden:

201
docs/plugins/musicbrainz.rst
View file

@ -26,8 +26,6 @@ Default
.. code-block:: yaml
musicbrainz:
data_source_mismatch_penalty: 0.5
search_limit: 5
host: musicbrainz.org
https: no
ratelimit: 1
@ -41,122 +39,107 @@ Default
deezer: no
beatport: no
tidal: no
data_source_mismatch_penalty: 0.5
search_limit: 5
You can instruct beets to use `your own MusicBrainz database
<https://musicbrainz.org/doc/MusicBrainz_Server/Setup>`__ instead of the
.. conf:: host
:default: musicbrainz.org
`main server`_. Use the ``host``, ``https`` and ``ratelimit`` options under a
``musicbrainz:`` header, like so
The Web server hostname (and port, optionally) that will be contacted by beets.
You can use this to configure beets to use `your own MusicBrainz database
<https://musicbrainz.org/doc/MusicBrainz_Server/Setup>`__ instead of the
`main server`_.
.. code-block:: yaml
The server must have search indices enabled (see `Building search indexes`_).
musicbrainz:
host: localhost:5000
https: no
ratelimit: 100
Example:
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`_).
.. code-block:: yaml
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.
musicbrainz:
host: localhost:5000
.. conf:: https
:default: no
Makes the client use HTTPS instead of HTTP. This setting applies only to custom
servers. The official MusicBrainz server always uses HTTPS.
.. conf:: ratelimit
:default: 1
Controls the number of Web service requests per second.
**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.
.. conf:: ratelimit_interval
:default: 1.0
The time interval (in seconds) for the rate limit.
.. conf:: enabled
:default: yes
.. deprecated:: 2.4 Add ``musicbrainz`` to the ``plugins`` list instead.
.. conf:: extra_tags
:default: []
By default, beets will use only the artist, album, and track count to query
MusicBrainz. Additional tags to be queried can be supplied with the
``extra_tags`` setting.
This setting should improve the autotagger results if the metadata with the
given tags match the metadata returned by MusicBrainz.
Note that the only tags supported by this setting are: ``barcode``,
``catalognum``, ``country``, ``label``, ``media``, and ``year``.
Example:
.. code-block:: yaml
musicbrainz:
extra_tags: [barcode, catalognum, country, label, media, year]
.. conf:: genres
:default: no
Use MusicBrainz genre tags to populate (and replace if it's already set) the
``genre`` tag. This will make it a list of all the genres tagged for the release
and the release-group on MusicBrainz, separated by "; " and sorted by the total
number of votes.
.. conf:: external_ids
**Default**
.. code-block:: yaml
musicbrainz:
external_ids:
discogs: no
spotify: no
bandcamp: no
beatport: no
deezer: no
tidal: no
Set any of the ``external_ids`` options to ``yes`` to enable the MusicBrainz
importer to look for links to related metadata sources. If such a link is
available the release ID will be extracted from the URL provided and imported to
the beets library.
The library fields of the corresponding :ref:`autotagger_extensions` are used to
save the data as flexible attributes (``discogs_album_id``, ``bandcamp_album_id``, ``spotify_album_id``,
``beatport_album_id``, ``deezer_album_id``, ``tidal_album_id``). On re-imports
existing data will be overwritten.
.. include:: ./shared_metadata_source_config.rst
.. _building search indexes: https://musicbrainz.org/doc/Development/Search_server_setup
.. _limited: https://musicbrainz.org/doc/XML_Web_Service/Rate_Limiting
.. _main server: https://musicbrainz.org/
.. _musicbrainz.enabled:
enabled
+++++++
.. deprecated:: 2.4 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.
Default: ``yes``.
.. _search_limit:
search_limit
++++++++++++
The number of matches returned when sending search queries to the MusicBrainz
server.
Default: ``5``.
searchlimit
+++++++++++
.. deprecated:: 2.4 Use `search_limit`_.
.. _extra_tags:
extra_tags
++++++++++
By default, beets will use only the artist, album, and track count to query
MusicBrainz. Additional tags to be queried can be supplied with the
``extra_tags`` setting. For example
.. code-block:: yaml
musicbrainz:
extra_tags: [barcode, catalognum, country, label, media, year]
This setting should improve the autotagger results if the metadata with the
given tags match the metadata returned by MusicBrainz.
Note that the only tags supported by this setting are the ones listed in the
above example.
Default: ``[]``
.. _genres:
genres
++++++
Use MusicBrainz genre tags to populate (and replace if it's already set) the
``genre`` tag. This will make it a list of all the genres tagged for the release
and the release-group on MusicBrainz, separated by "; " and sorted by the total
number of votes. Default: ``no``
.. _musicbrainz.external_ids:
external_ids
++++++++++++
Set any of the ``external_ids`` options to ``yes`` to enable the MusicBrainz
importer to look for links to related metadata sources. If such a link is
available the release ID will be extracted from the URL provided and imported to
the beets library
.. code-block:: yaml
musicbrainz:
external_ids:
discogs: yes
spotify: yes
bandcamp: yes
beatport: yes
deezer: yes
tidal: yes
The library fields of the corresponding :ref:`autotagger_extensions` are used to
save the data (``discogs_albumid``, ``bandcamp_album_id``, ``spotify_album_id``,
``beatport_album_id``, ``deezer_album_id``, ``tidal_album_id``). On re-imports
existing data will be overwritten.
The default of all options is ``no``.

65
docs/plugins/shared_metadata_source_config.rst Normal file
View file

@ -0,0 +1,65 @@
.. _data_source_mismatch_penalty:
.. conf:: data_source_mismatch_penalty
:default: 0.5
Penalty applied when the data source of a
match candidate differs from the original source of your existing tracks. Any
decimal number between 0.0 and 1.0
This setting controls how much to penalize matches from different metadata
sources during import. The penalty is applied when beets detects that a match
candidate comes from a different data source than what appears to be the
original source of your music collection.
**Example configurations:**
.. code-block:: yaml
# Prefer MusicBrainz over Discogs when sources don't match
plugins: musicbrainz discogs
musicbrainz:
data_source_mismatch_penalty: 0.3 # Lower penalty = preferred
discogs:
data_source_mismatch_penalty: 0.8 # Higher penalty = less preferred
.. code-block:: yaml
# Do not penalise candidates from Discogs at all
plugins: musicbrainz discogs
musicbrainz:
data_source_mismatch_penalty: 0.5
discogs:
data_source_mismatch_penalty: 0.0
.. code-block:: yaml
# Disable cross-source penalties entirely
plugins: musicbrainz discogs
musicbrainz:
data_source_mismatch_penalty: 0.0
discogs:
data_source_mismatch_penalty: 0.0
.. tip::
The last configuration is equivalent to setting:
.. code-block:: yaml
match:
distance_weights:
data_source: 0.0 # Disable data source matching
.. conf:: source_weight
:default: 0.5
.. deprecated:: 2.5 Use `data_source_mismatch_penalty`_ instead.
.. conf:: search_limit
:default: 5
Maximum number of search results to return.

100
docs/plugins/spotify.rst
View file

@ -73,8 +73,6 @@ Default
.. code-block:: yaml
spotify:
data_source_mismatch_penalty: 0.5
search_limit: 5
mode: list
region_filter:
show_failures: no
@ -84,59 +82,67 @@ Default
client_id: REDACTED
client_secret: REDACTED
tokenfile: spotify_token.json
data_source_mismatch_penalty: 0.5
search_limit: 5
- **mode**: One of the following:
.. conf:: mode
:default: list
- ``list``: Print out the playlist as a list of links. This list can then
be pasted in to a new or existing Spotify playlist.
- ``open``: This mode actually sends a link to your default browser with
instructions to open Spotify with the playlist you created. Until this
has been tested on all platforms, it will remain optional.
Controls how the playlist is output:
Default: ``list``.
- ``list``: Print out the playlist as a list of links. This list can then
be pasted in to a new or existing Spotify playlist.
- ``open``: This mode actually sends a link to your default browser with
instructions to open Spotify with the playlist you created. Until this
has been tested on all platforms, it will remain optional.
- **region_filter**: A two-character country abbreviation, to limit results to
that market. Default: None.
- **show_failures**: List each lookup that does not return a Spotify ID (and
therefore cannot be added to a playlist). Default: ``no``.
- **tiebreak**: How to choose the track if there is more than one identical
result. For example, there might be multiple releases of the same album. The
options are ``popularity`` and ``first`` (to just choose the first match
returned). Default: ``popularity``.
- **regex**: An array of regex transformations to perform on the
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``). Default: ``no``.
.. conf:: region_filter
:default:
Here's an example:
A two-character country abbreviation, to limit results to that market.
::
.. conf:: show_failures
:default: no
spotify:
data_source_mismatch_penalty: 0.7
mode: open
region_filter: US
show_failures: on
tiebreak: first
search_query_ascii: no
List each lookup that does not return a Spotify ID (and therefore cannot be
added to a playlist).
regex: [
{
field: "albumartist", # Field in the item object to regex.
search: "Something", # String to look for.
replace: "Replaced" # Replacement value.
},
{
field: "title",
search: "Something Else",
replace: "AlsoReplaced"
}
]
.. conf:: tiebreak
:default: popularity
How to choose the candidate if there is more than one identical result. For
example, there might be multiple releases of the same album.
- ``popularity``: pick the more popular candidate
- ``first``: pick the first candidate
.. conf:: regex
:default: []
An array of regex transformations to perform on the track/album/artist fields
before sending them to Spotify. Can be useful for changing certain
abbreviations, like ft. -> feat. For example:
.. code-block:: yaml
regex:
- field: albumartist
search: Something
replace: Replaced
- field: title
search: Something Else
replace: AlsoReplaced
.. conf:: search_query_ascii
:default: no
If enabled, 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``).
.. include:: ./shared_metadata_source_config.rst
Obtaining Track Popularity and Audio Features from Spotify
----------------------------------------------------------