mirror of
https://github.com/beetbox/beets.git
synced 2025-12-06 08:39:17 +01:00
2a53b890be
- Clarify basic search behaviour in intro chapter of discogs plugin, - and state change introduced in PR#4227 (discogs: Discogs query on insufficiently tagged files)
93 lines
3.4 KiB
ReStructuredText
93 lines
3.4 KiB
ReStructuredText
Discogs Plugin
|
|
==============
|
|
|
|
The ``discogs`` plugin extends the autotagger's search capabilities to
|
|
include matches from the `Discogs`_ database.
|
|
|
|
.. _Discogs: https://discogs.com
|
|
|
|
Installation
|
|
------------
|
|
|
|
To use the ``discogs`` plugin, first enable it in your configuration (see
|
|
:ref:`using-plugins`). Then, install the `python3-discogs-client`_ library by typing::
|
|
|
|
pip install python3-discogs-client
|
|
|
|
You will also need to register for a `Discogs`_ account, and provide
|
|
authentication credentials via a personal access token or an OAuth2
|
|
authorization.
|
|
|
|
Matches from Discogs will now show up during import alongside matches from
|
|
MusicBrainz. The search terms sent to the Discogs API are based on the artist
|
|
and album tags of your tracks. If those are empty no query will be issued.
|
|
|
|
If you have a Discogs ID for an album you want to tag, you can also enter it
|
|
at the "enter Id" prompt in the importer.
|
|
|
|
OAuth Authorization
|
|
```````````````````
|
|
|
|
The first time you run the :ref:`import-cmd` command after enabling the plugin,
|
|
it will ask you to authorize with Discogs by visiting the site in a browser.
|
|
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), login to `Discogs`_, and visit the
|
|
`Developer settings page
|
|
<https://www.discogs.com/settings/developers>`_. Press the ``Generate new
|
|
token`` button, and place the generated token in your configuration, as the
|
|
``user_token`` config option in the ``discogs`` section.
|
|
|
|
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#12.13>`_),
|
|
along with headers, mark divisions between distinct works on the same release
|
|
or within works. When ``index_tracks`` is enabled::
|
|
|
|
discogs:
|
|
index_tracks: yes
|
|
|
|
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::
|
|
|
|
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::
|
|
|
|
No.1: Sinfony
|
|
No.22: Chorus- Behold The Lamb Of God
|
|
Sinfonia
|
|
|
|
This option is useful when importing classical music.
|
|
|
|
Troubleshooting
|
|
---------------
|
|
|
|
Several issues have been encountered with the Discogs API. If you have one,
|
|
please start by searching for `a similar issue on the repo
|
|
<https://github.com/beetbox/beets/issues?utf8=%E2%9C%93&q=is%3Aissue+discogs>`_.
|
|
|
|
Here are two things you can try:
|
|
|
|
* Try deleting the token file (``~/.config/beets/discogs_token.json`` by
|
|
default) to force re-authorization.
|
|
* Make sure that your system clock is accurate. The Discogs servers can reject
|
|
your request if your clock is too out of sync.
|
|
|
|
.. _python3-discogs-client: https://github.com/joalla/discogs_client
|