Discogs Plugin
**************

The "discogs" plugin extends the autotagger's search capabilities to
include matches from the Discogs database.

Files can be imported as albums or as singletons. Since Discogs
matches are always based on Discogs releases, the album tag is written
even to singletons.  This enhances the importers results when
reimporting as (full or partial) albums later on.


Installation
============

To use the "discogs" plugin, first enable it in your configuration
(see 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 import 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):

1. login to Discogs;

2. visit the Developer settings page;

3. press the *Generate new token* button;

4. copy the generated token;

5. place it in your configuration in the "discogs" section as the
   "user_token" option:

      discogs:
          user_token: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"


Configuration
=============

This plugin can be configured like other metadata source plugins as
described in Using Metadata Source Plugins.

There is one additional option in the "discogs:" section,
"index_tracks". 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:

   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 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.

Other configurations available under "discogs:" are:

* **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: "", ""


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.

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.

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.
