diff --git a/docs/plugins/beatport.rst b/docs/plugins/beatport.rst new file mode 100644 index 000000000..da77cd4cd --- /dev/null +++ b/docs/plugins/beatport.rst @@ -0,0 +1,36 @@ +Beatport Plugin +=============== + +The ``beatport`` plugin adds support for querying the `Beatport`_ catalogue +during the autotagging process. This can potentially be helpful for users +whose collection includes a lot of diverse electronic music releases, for which +both MusicBrainz and (to a lesser degree) Discogs show no matches. + +Installation +------------ + +To use the ``beatport`` plugin, first enable it in your configuration (see +:ref:`using-plugins`). Then, install the `requests`_ and `requests_oauthlib`_ +libraries (which we need for querying and authorizing with the Beatport API) +by typing:: + + pip install requests requests_oauthlib + +You will also need to register for a `Beatport`_ account. The first time you +run the :ref:`import-cmd` command after enabling the plugin, it will ask you +to authorize with Beatport by visiting the site in a browser. On the site +you will be asked to enter your username and password to authorize beets +to query the Beatport API. You will then be displayed with a single line of +text that you should paste into your terminal. This will store the +authentication data for subsequent runs and you will not be required to +repeat the above steps. + +Matches from Beatport should now show up alongside matches +from MusicBrainz and other sources. + +If you have a Beatport ID or a URL for a release or track you want to tag, you +can just enter one of the two at the "enter Id" prompt in the importer. + +.. _requests: http://docs.python-requests.org/en/latest/ +.. _requests_oauthlib: https://github.com/requests/requests-oauthlib +.. _Beatport: http://beatport.com