From 082357b063ef9d06771508f8757a5b87d489052c Mon Sep 17 00:00:00 2001
From: Rahul Ahuja <rah.ahuja@gmail.com>
Date: Sun, 20 Jan 2019 12:40:11 -0800
Subject: [PATCH] document new functionality, use Spotify ID for
 AlbumInfo.album_id

---
 beetsplug/spotify.py     |  3 +-
 docs/plugins/spotify.rst | 60 +++++++++++++++++++++++++++++++++++++---
 2 files changed, 57 insertions(+), 6 deletions(-)

diff --git a/beetsplug/spotify.py b/beetsplug/spotify.py
index ef6f26e48..713c670f0 100644
--- a/beetsplug/spotify.py
+++ b/beetsplug/spotify.py
@@ -41,7 +41,6 @@ class SpotifyPlugin(BeetsPlugin):
                 'client_secret': '6DRS7k66h4643yQEbepPxOuxeVW0yZpk',
                 'tokenfile': 'spotify_token.json',
                 'source_weight': 0.5,
-                'user_token': '',
             }
         )
         self.config['client_secret'].redact = True
@@ -184,7 +183,7 @@ class SpotifyPlugin(BeetsPlugin):
 
         return AlbumInfo(
             album=response_data['name'],
-            album_id=album_id,
+            album_id=spotify_id,
             artist=artist,
             artist_id=artist_id,
             tracks=tracks,
diff --git a/docs/plugins/spotify.rst b/docs/plugins/spotify.rst
index b993a66d2..fb0cec9ef 100644
--- a/docs/plugins/spotify.rst
+++ b/docs/plugins/spotify.rst
@@ -1,10 +1,20 @@
 Spotify Plugin
 ==============
 
-The ``spotify`` plugin generates `Spotify`_ playlists from tracks in your library. Using the `Spotify Web API`_, any tracks that can be matched with a Spotify ID are returned, and the results can be either pasted in to a playlist or opened directly in the Spotify app.
+The ``spotify`` plugin generates `Spotify`_ playlists from tracks in your
+library with the ``beet spotify`` command. Using the `Spotify Search API`_,
+any tracks that can be matched with a Spotify ID are returned, and the
+results can be either pasted in to a playlist or opened directly in the
+Spotify app.
+
+Spotify URLs and IDs may also be provided in the ``Enter release ID:`` prompt
+during ``beet import`` to autotag music with data from the Spotify
+`Album`_ and `Track`_ APIs.
 
 .. _Spotify: https://www.spotify.com/
-.. _Spotify Web API: https://developer.spotify.com/web-api/search-item/
+.. _Spotify Search API: https://developer.spotify.com/documentation/web-api/reference/search/search/
+.. _Album: https://developer.spotify.com/documentation/web-api/reference/albums/get-album/
+.. _Track: https://developer.spotify.com/documentation/web-api/reference/tracks/get-track/
 
 Why Use This Plugin?
 --------------------
@@ -12,12 +22,23 @@ 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 want to check which tracks in your library are available on Spotify.
+* You want to autotag music with Spotify metadata
 
 Basic Usage
 -----------
 
-First, enable the ``spotify`` plugin (see :ref:`using-plugins`).
-Then, use the ``spotify`` command with a beets query::
+First, register a `Spotify application`_ to use with beets and add your Client ID
+and Client Secret to your :doc:`configuration file </reference/config>` under a
+``spotify`` section::
+
+    spotify:
+        client_id: N3dliiOOTBEEFqCH5NDDUmF5Eo8bl7AN
+        client_secret: 6DRS7k66h4643yQEbepPxOuxeVW0yZpk
+
+.. _Spotify application: https://developer.spotify.com/documentation/general/guides/app-settings/
+
+Then, enable the ``spotify`` plugin (see :ref:`using-plugins`) and use the ``spotify``
+command with a beets query::
 
     beet spotify [OPTIONS...] QUERY
 
@@ -37,6 +58,24 @@ Command-line options include:
 * ``--show-failures`` or ``-f``: List the tracks that did not match a Spotify
   ID.
 
+A Spotify ID or URL may also be provided to the ``Enter release ID``
+prompt during import::
+
+    Enter search, enter Id, aBort, eDit, edit Candidates, plaY? i
+    Enter release ID: https://open.spotify.com/album/2rFYTHFBLQN3AYlrymBPPA
+    Tagging:
+        Bear Hands - Blue Lips / Ignoring the Truth / Back Seat Driver (Spirit Guide) / 2AM
+    URL:
+        https://open.spotify.com/album/2rFYTHFBLQN3AYlrymBPPA
+    (Similarity: 88.2%) (source, tracks) (Spotify, 2019, Spensive Sounds)
+     * Blue Lips (feat. Ursula Rose)   -> Blue Lips (feat. Ursula Rose) (source)
+     * Ignoring the Truth              -> Ignoring the Truth (source)
+     * Back Seat Driver (Spirit Guide) -> Back Seat Driver (Spirit Guide) (source)
+     * 2AM                             -> 2AM (source)
+    [A]pply, More candidates, Skip, Use as-is, as Tracks, Group albums,
+    Enter search, enter Id, aBort, eDit, edit Candidates, plaY?
+
+
 Configuration
 -------------
 
@@ -67,10 +106,23 @@ 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.
+- **tokenfile**: Filename of the JSON file stored in the beets configuration
+  directory to use for caching the OAuth access token.
+  access token.
+  Default: ``spotify_token.json``.
+- **source_weight**: Penalty applied to Spotify matches during import. Set to
+  0.0 to disable.
+  Default: ``0.5``.
+
+.. _beets configuration directory: https://beets.readthedocs.io/en/stable/reference/config.html#default-location
 
 Here's an example::
 
     spotify:
+        client_id: N3dliiOOTBEEFqCH5NDDUmF5Eo8bl7AN
+        client_secret: 6DRS7k66h4643yQEbepPxOuxeVW0yZpk
+        source_weight: 0.7
+        tokenfile: my_spotify_token.json
         mode: open
         region_filter: US
         show_failures: on