From 771abb84830678455de4625ac7f082d8100f0ea0 Mon Sep 17 00:00:00 2001
From: jao <jao@gnu.org>
Date: Tue, 2 Feb 2021 05:16:17 +0000
Subject: libs -> lib/

---
 lib/media/espotify.org | 627 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 627 insertions(+)
 create mode 100644 lib/media/espotify.org

(limited to 'lib/media/espotify.org')

diff --git a/lib/media/espotify.org b/lib/media/espotify.org
new file mode 100644
index 0000000..93338a9
--- /dev/null
+++ b/lib/media/espotify.org
@@ -0,0 +1,627 @@
+#+title: consulting spotify
+#+date: <2021-01-08 04:02>
+#+filetags: emacs
+#+PROPERTY: header-args :tangle yes :comments no :results silent
+
+(/Note/: you can tangle this file (e.g., with =C-c C-v t= inside Emacs)
+into three elisp libraries, =espotify.el=, =espotify-consult.el,
+=espotify-embark=. and =espotify-counsel=)
+
+We have two kinds of interaction with Spotify: via its HTTP API to
+perform operations such as search, and via our local DBUS to talk to
+client players running in our computer, such as the official client,
+[[https://github.com/Spotifyd/spotifyd][spotifyd]] or [[https://mopidy.com/ext/spotify/][mopidy-spotify]].  Our goal is to obtain via the former a
+track or album identifier that we can send then to the latter to play,
+with emacs completion mechanisms (consult and friends in this case)
+providing the glue between both worlds.
+
+Let's start with an umbrella customization group:
+#+begin_src emacs-lisp
+  ;;; espotify.el - spotify search and play -  -*- lexical-binding: t; -*-
+
+  (defgroup espotify nil
+    "Access to Spotify API and clients"
+    :group 'multimedia)
+#+end_src
+
+* Access to Spotify's API: authentication
+
+  I am stealing most of the ideas on how to establish authenticated
+  connections to the Spotify API and performing queries from
+  [[https://github.com/Lautaro-Garcia/counsel-spotify][counsel-spotify]], with many simplifications.
+
+  We start defining a couple of end-points:
+
+  #+begin_src emacs-lisp
+    (defvar espotify-spotify-api-url "https://api.spotify.com/v1")
+    (defvar espotify-spotify-api-authentication-url
+      "https://accounts.spotify.com/api/token")
+  #+end_src
+
+  And we're going to need as well a client id and secret for our
+  application, which i am again defining as variables since i expect
+  them to be set in some secure manner instead of via customize:
+
+  #+begin_src emacs-lisp
+    (defvar espotify-client-id nil "Spotify application client ID.")
+    (defvar espotify-client-secret nil "Spotify application client secret.")
+  #+end_src
+
+  To get valid values for them, one just needs to [[https://developer.spotify.com/my-applications][register a Spotify
+  application]].  From them we can derive a base64-encoded credentials
+  value:
+
+  #+begin_src emacs-lisp
+    (defun espotify--basic-auth-credentials ()
+      (let ((credential (concat espotify-client-id ":" espotify-client-secret)))
+        (concat "Basic " (base64-encode-string credential t))))
+  #+end_src
+
+  The return value of the function above is to be used as the
+  "Authorization" header of our requests to the authorization
+  end-point, which is going to answer with an authorization token
+  that we can then use to further requests.  Let's define a function to
+  wrap that operation:
+
+  #+begin_src emacs-lisp
+    (defun espotify--with-auth-token (callback)
+      (let ((url-request-method "POST")
+            (url-request-data "&grant_type=client_credentials")
+            (url-request-extra-headers
+             `(("Content-Type" . "application/x-www-form-urlencoded")
+               ("Authorization" . ,(espotify--basic-auth-credentials)))))
+         (url-retrieve espotify-spotify-api-authentication-url
+                       (lambda (_status)
+                         (goto-char url-http-end-of-headers)
+                         (funcall callback
+                                  (alist-get 'access_token (json-read)))))))
+  #+end_src
+
+  For instance:
+  #+begin_src emacs-lisp :load no :tangle no
+    (espotify--with-auth-token
+     (lambda (token) (message "Your token is: %s" token)))
+  #+end_src
+
+  obtains an auth token and prints it as a message.  Note that ~body~
+  is evaluated asynchronously by ~url-retrieve~, so invocations to
+  ~espotify-with-auth-token~ evaluate to the request's buffer and are
+  usually discarded.
+
+* Search queries using the Spotify API
+
+  We are interested in performing a search for some ~term~, of items
+  of a given ~types~ (~:track~, ~:album~, ~:artist~, etc.), possibly with an
+  additional ~filter~.  That's specified in a GET request's URL
+  as constructed by this function:
+
+  #+begin_src emacs-lisp
+    (defun espotify--make-search-url (term types &optional filter)
+      (when (null types)
+        (error "Must supply a non-empty list of types to search for"))
+      (let ((term (url-encode-url term)))
+        (format "%s/search?q=%s&type=%s&limit=50"
+                espotify-spotify-api-url
+                (if filter (format "%s:%s" filter term) term)
+                (mapconcat #'symbol-name types ","))))
+  #+end_src
+
+  For instance:
+
+  #+begin_src emacs-lisp :load no :tangle no :results replace
+    (espotify--make-search-url "dream blue turtles" '(album))
+  #+end_src
+
+  #+RESULTS:
+  : https://api.spotify.com/v1/search?q=dream%20blue%20turtles&type=album&limit=50
+
+  If we have an [[*Access to Spotify's API: authentication][authorisation token]] and a search URL in our hands,
+  we can use them as in the following helper function, which will
+  calls the given callback with the results of the query:
+
+  #+begin_src emacs-lisp
+    (defun espotify--with-query-results (token url callback)
+      (let ((url-request-extra-headers
+             `(("Authorization" . ,(concat "Bearer " token)))))
+        (url-retrieve url
+                      (lambda (_status)
+                        (goto-char url-http-end-of-headers)
+                        (funcall callback
+                                 (let ((json-array-type 'list))
+                                   (thread-first
+                                       (buffer-substring (point) (point-max))
+                                     (decode-coding-string 'utf-8)
+                                     (json-read-from-string))))))))
+  #+end_src
+
+  So we can combine this macro with ~espotify--with-auth-token~ in a
+  single search function that takes a callback that will be applied
+  to a given query, specified as a triple of term, types and filter:
+
+  #+begin_src emacs-lisp
+    (defun espotify-get (callback url)
+      (espotify--with-auth-token
+         (lambda (token)
+           (espotify--with-query-results token url callback))))
+
+    (defun espotify-search (callback term types &optional filter)
+      (espotify-get callback (espotify--make-search-url term types filter)))
+  #+end_src
+
+  For instance:
+  #+begin_src emacs-lisp :load no :tangle no
+    (defvar espotify-query-result nil)
+    (espotify-search (lambda (res) (setq espotify-query-result res))
+                     "dream blue turtles"
+                     '(album artist))
+    (sit-for 0)
+  #+end_src
+
+  #+begin_src emacs-lisp :load no :tangle no :results replace
+    (mapcar 'car espotify-query-result)
+  #+end_src
+
+  #+RESULTS:
+  | albums | artists |
+
+  So Spotify is returning a results entry per type, which in turn,
+  contains an ~items~ with the list of actual results.  So let's
+  provide an interface for a callback that takes as many lists of
+  items as types it asks for:
+
+  #+begin_src emacs-lisp
+    (defun espotify--type-items (res type)
+      (alist-get 'items (alist-get (intern (format "%ss" type)) res)))
+
+    (defun espotify-search* (callback term types &optional filter)
+      (let* ((types (if (listp types) types (list types)))
+             (cb (lambda (res)
+                   (let ((its (mapcar (lambda (tp)
+                                        (espotify--type-items res tp))
+                                      types)))
+                     (apply callback its)))))
+        (espotify-search cb term types filter)))
+  #+end_src
+
+  For example:
+
+  #+begin_src emacs-lisp :load no :tangle no
+    (defvar espotify-query-result nil)
+    (espotify-search* (lambda (al ar)
+                        (message "Found %s albums, %s artists"
+                                 (length al) (length ar))
+                        (setq espotify-query-result (cons al ar)))
+                     "blue turtles"
+                     '(album artist))
+    (sit-for 0)
+    (list (mapcar 'car (car (car espotify-query-result)))
+          (mapcar 'car (car (cdr espotify-query-result))))
+  #+end_src
+
+  #+RESULTS:
+  | album_type    | artists   | available_markets | external_urls | href | id     | images | name       | release_date | release_date_precision | total_tracks | type | uri |
+  | external_urls | followers | genres            | href          | id   | images | name   | popularity | type         | uri                    |              |      |     |
+
+  Another strategy would be to search for several types and pass to
+  our callback the concatenation of all items:
+
+  #+begin_src emacs-lisp
+    (defun espotify-search-all (callback term &optional types filter)
+      (let ((types (or types '(album track artist playlist))))
+        (espotify-search* (lambda (&rest items)
+                            (funcall callback (apply 'append items)))
+                          term
+                          types
+                          filter)))
+  #+end_src
+
+* Listing user resources in the Spotify API
+
+  It is also possible to obtain lists of items of a given type for the
+  current user, with a standard URL format:
+
+  #+begin_src emacs-lisp
+    (defun espotify--make-user-url (type)
+      (format "%s/me/%ss" espotify-spotify-api-url (symbol-name type)))
+  #+end_src
+
+  and we can then use ~espotify-get~ to offer access to our playlists,
+  albums, etc.:
+
+  #+begin_src emacs-lisp
+    (defun espotify-with-user-resources (callback type)
+      (espotify-get (lambda (res) (funcall callback (alist-get 'items res)))
+                    (espotify--make-user-url type)))
+  #+end_src
+
+* Sending commands to local players
+
+  Once we now the URI we want to play (that ~uri~ entry in our items),
+  sending it to a local player via DBUS is fairly easy.  Let's
+  define a couple of customizable variables pointing to the service
+  name and bus:
+
+  #+begin_src emacs-lisp
+    (defcustom espotify-service-name "mopidy"
+      "Name of the DBUS service used by the client we talk to.
+
+    The official Spotify client uses `spotify', but one can also use
+    alternative clients such as mopidy or spotifyd."
+      :type 'string)
+
+    (defcustom espotify-use-system-bus-p t
+      "Whether to access the spotify client using the system DBUS.")
+  #+end_src
+
+  and then using the Emacs DBUS API to send methods to it is a
+  breeze:
+
+  #+begin_src emacs-lisp
+    (defun espotify-call-spotify-via-dbus (method &rest args)
+      "Tell Spotify to execute METHOD with ARGS through DBUS."
+      (apply #'dbus-call-method `(,(if espotify-use-system-bus-p :system :session)
+                                  ,(format "org.mpris.MediaPlayer2.%s"
+                                           espotify-service-name)
+                                  "/org/mpris/MediaPlayer2"
+                                  "org.mpris.MediaPlayer2.Player"
+                                  ,method
+                                  ,@args)))
+
+    (defun espotify-play-uri (uri)
+      (espotify-call-spotify-via-dbus "OpenUri" uri))
+  #+end_src
+
+* Search front-end using consult
+  :PROPERTIES:
+  :header-args: :tangle espotify-consult.el
+  :END:
+
+  I am exploring [[https://github.com/minad/consult][consult.el]] (and friends) to replace ivy/counsel,
+  inspired in part by [[https://protesilaos.com/codelog/2021-01-06-emacs-default-completion/][Protesilaos Stavrou's musings]], and liking a
+  lot what i see.  Up till now, everything i had with counsel is
+  supported, often in better ways, with one exception: completing
+  search of spotify albums using [[https://github.com/Lautaro-Garcia/counsel-spotify][counsel-spotify]].  So let's fix that
+  by defining an asynchronous consult function that does precisely
+  that!
+
+  The top-level command will have this form:
+
+  #+begin_src emacs-lisp
+    ;;; espotify-consult.el - consult support -  -*- lexical-binding: t; -*-
+
+    (require 'espotify)
+    (require 'consult)
+
+    (defvar espotify-consult-history nil)
+
+    (defun espotify-consult-by (type &optional filter)
+      (let ((orderless-matching-styles '(orderless-literal)))
+        (consult--read (format "Search %ss: " type)
+                       (espotify--search-generator type filter)
+                       :lookup 'espotify--consult-lookup
+                       :category 'espotify-search-item
+                       :history 'espotify-consult-history
+                       :initial consult-async-default-split
+                       :require-match t)))
+  #+end_src
+
+  where we can write an asynchronous generator of search results
+  with the helper function:
+
+  #+begin_src emacs-lisp
+    (defun espotify--search-generator (type filter)
+      (thread-first (consult--async-sink)
+        (consult--async-refresh-immediate)
+        (consult--async-map #'espotify--format-item)
+        (espotify--async-search type filter)
+        (consult--async-throttle)
+        (consult--async-split)))
+  #+end_src
+
+  The above follows a generic consult pattern, where all functions
+  are pre-defined for us except ~espotify--async-search~, an
+  asynchronous dispatcher closure that must generate and handle a
+  list of candidates, responding to a set of action messages (init,
+  reset, get, flush, etc.) [fn:1]  Here's its definition in our
+  case:
+
+  #+begin_src emacs-lisp
+    (defun espotify--async-search (next type filter)
+      (let ((current ""))
+        (lambda (action)
+          (pcase action
+            ((pred stringp)
+             (when-let (term (espotify-check-term current action))
+               (setq current term)
+               (espotify-search-all
+                (lambda (x)
+                  (funcall next 'flush)
+                  (funcall next x))
+                current
+                type
+                filter)))
+            (_ (funcall next action))))))
+  #+end_src
+
+  We have introduced the convention that we're only launching a search
+  when the input string ends in "=", to avoid piling on HTTP
+  requests, and also played a bit with Levenshtein distance, both via
+  the function =espotify-check-search-term=:
+
+  #+begin_src emacs-lisp :tangle espotify.el
+    (defvar espotify-search-suffix "="
+      "Suffix in the search string launching an actual Web query.")
+
+    (defvar espotify-search-threshold 8
+      "Threshold to automatically launch an actual Web query.")
+
+    (defun espotify-check-term (prev new)
+      (when (not (string-blank-p new))
+        (cond ((string-suffix-p espotify-search-suffix new)
+               (substring new 0 (- (length new) (length espotify-search-suffix))))
+              ((>= (string-distance prev new) espotify-search-threshold) new))))
+  #+end_src
+
+  In the consult case, a more natural choice for the search suffix is
+
+  #+begin_src emacs-lisp
+    (setq espotify-search-suffix consult-async-default-split)
+  #+end_src
+
+  When processing the results, we format them as a displayable
+  string, while hiding in a property the URI that will allow us to
+  play the item (and pass the formatter to ~consult-async--map~, in
+  ~espotify--search-generator~ above):
+
+  #+begin_src emacs-lisp :tangle espotify.el
+    (defun espotify--additional-info (x)
+      (mapconcat 'identity
+                 (seq-filter 'identity
+                             `(,(alist-get 'name (alist-get 'album x))
+                               ,(alist-get 'name (car (alist-get 'artists x)))
+                               ,(alist-get 'display_name (alist-get 'owner x))))
+                 ", "))
+
+    (defun espotify--format-item (x)
+      (propertize (format "%s%s"
+                          (alist-get 'name x)
+                          (if-let ((info (espotify--additional-info x)))
+                              (format " (%s)" info)
+                            ""))
+                  'espotify-item x))
+
+    (defun espotify--item (cand)
+      (get-text-property 0 'espotify-item cand))
+
+    (defun espotify--uri (cand)
+      (alist-get 'uri (espotify--item cand)))
+   #+end_src
+
+   and then we make sure that we access that original string when
+   consult looks up for it using the ~:lookup~ function, which we can
+   simply define as:
+
+   #+begin_src emacs-lisp
+     (require 'seq)
+     (defun espotify--consult-lookup (_input cands cand)
+       (seq-find (lambda (x) (string= cand x)) cands))
+   #+end_src
+
+
+   With that, when we receive the final result from ~consult--read~,
+   we can play the selected URI right away:
+
+   #+begin_src emacs-lisp :tangle espotify.el
+     (defun espotify--maybe-play (cand)
+       (when-let (uri (when cand (espotify--uri cand)))
+         (espotify-play-uri uri)))
+   #+end_src
+
+   And here, finally, are our interactive command to search and play
+   albums using consult:
+
+   #+begin_src emacs-lisp
+     (defun espotify-consult-album (&optional filter)
+       (interactive)
+       (espotify--maybe-play (espotify-consult-by 'album filter)))
+   #+end_src
+
+   And likewise for playlists, artists and combinations thereof:
+
+  #+begin_src emacs-lisp
+     (defun espotify-consult-artist (&optional filter)
+       (interactive)
+       (espotify--maybe-play (espotify-consult-by 'artist filter)))
+
+     (defun espotify-consult-track (&optional filter)
+       (interactive)
+       (espotify--maybe-play (espotify-consult-by 'track filter)))
+
+     (defun espotify-consult-playlist (&optional filter)
+       (interactive)
+       (espotify--maybe-play (espotify-consult-by 'playlist filter)))
+  #+end_src
+
+* Adding metadata to candidates using Marginalia
+  :PROPERTIES:
+  :header-args: :tangle espotify-consult.el
+  :END:
+
+  Let's add metadata fields to our candidates, so that packages like
+  [[https://github.com/minad/marginalia][Marginalia]] can offer it to consult or selectrum.
+
+  #+begin_src emacs-lisp
+    (defun espotify-marginalia-annotate (cand)
+      (when-let (x (espotify--item cand))
+        (marginalia--fields
+         ((alist-get 'type x "") :face 'marginalia-mode :width 10)
+         ((if-let (d (alist-get 'duration_ms x))
+              (let ((secs (/ d 1000)))
+                (format "%02d:%02d" (/ secs 60) (mod secs 60)))
+            ""))
+         ((if-let (d (alist-get 'total_tracks x)) (format "%s tracks" d) "")
+          :face 'marginalia-size :width 12)
+         ((if-let (d (alist-get 'release_date (alist-get 'album x x)))
+              (format "%s" d)
+            "")
+          :face 'marginalia-date :width 10))))
+
+    (add-to-list 'marginalia-annotators-heavy
+                 '(espotify-search-item . espotify-marginalia-annotate))
+  #+end_src
+
+* Embark actions
+  :PROPERTIES:
+  :header-args: :tangle espotify-embark.el
+  :END:
+
+  In addition to the default action (play the URI in the selected
+  candidate), we can use embark to define other operations.  For
+  instance, we could print the full item alist in its own buffer, or
+  always look for an album to play:
+
+  #+begin_src emacs-lisp
+    (require 'espotify-consult)
+    (require 'embark)
+
+    (defvar espotify--current-item nil)
+
+    (defun espotify--show-info (name)
+      "Show low-level info (an alist) about selection."
+      (interactive "s")
+      (pop-to-buffer (get-buffer-create "*espotify info*"))
+      (read-only-mode -1)
+      (delete-region (point-min) (point-max))
+      (insert (propertize name 'face 'bold))
+      (newline)
+      (when espotify--current-item
+        (insert (pp-to-string espotify--current-item)))
+      (newline)
+      (goto-char (point-min))
+      (read-only-mode 1))
+
+    (defun espotify--play-album (ignored)
+      "Play album associated with selected item."
+      (interactive "i")
+      (if-let (album (if (string= "album"
+                                  (alist-get 'type espotify--current-item ""))
+                         espotify--current-item
+                       (alist-get 'album espotify--current-item)))
+          (espotify-play-uri (alist-get 'uri album))
+        (error "No album for %s" (alist-get 'nmae espotify--current-item))))
+
+    (embark-define-keymap espotify-item-keymap
+      "Actions for Spotify search results"
+      ("a" espotify--play-album)
+      ("h" espotify--show-info))
+
+    (defun espotify--annotate-item (cand)
+      (setq espotify--current-item (espotify--item cand))
+      (cons 'espotify-search-item cand))
+
+    (add-to-list 'embark-transformer-alist
+                 '(espotify-search-item . espotify--annotate-item))
+
+    (add-to-list 'embark-keymap-alist
+                 '(espotify-search-item . espotify-item-keymap))
+  #+end_src
+
+* Search fronted using ivy
+  :PROPERTIES:
+  :header-args: :tangle espotify-counsel.el
+  :END:
+
+  #+begin_src emacs-lisp
+    ;;; counsel-espotify.el - counsel and spotify -  -*- lexical-binding: t; -*-
+    (require 'espotify)
+    (require 'ivy)
+  #+end_src
+
+  It is is also not too complicated to provide a counsel collection of
+  functions.  Here, we use =ivy-read= to access the completion
+  interface, with the flag =dynamic-collection= set.  Ivy will wait
+  until we call =ivy-candidate-updates= with our items.
+
+  #+begin_src emacs-lisp
+    (defun espotify-counsel--search-by (type filter)
+      (let ((current-term ""))
+        (lambda (term)
+          (when-let (term (espotify-check-term current-term term))
+            (espotify-search-all (lambda (its)
+                                   (let ((cs (mapcar #'espotify--format-item its)))
+                                     (ivy-update-candidates cs)))
+                                 (setq current-term term)
+                                 type
+                                 filter))
+          0)))
+  #+end_src
+
+  With that, we can define our generic completing read:
+
+  #+begin_src emacs-lisp
+
+    (defun espotify-counsel--play-album (candidate)
+      "Play album associated with selected item."
+      (interactive "s")
+      (let ((item (espotify--item candidate)))
+        (if-let (album (if (string= "album" (alist-get 'type item ""))
+                           item
+                         (alist-get 'album item)))
+            (espotify-play-uri (alist-get 'uri album))
+          (error "No album for %s" (alist-get 'name item)))))
+
+    (defun espotify-search-by (type filter)
+      (ivy-read (format "Search %s: " type)
+                (espotify-counsel--search-by type filter)
+                :dynamic-collection t
+                :action `(1 ("a" espotify-counsel--play-album "Play album")
+                            ("p" espotify--maybe-play ,(format "Play %s" type)))))
+  #+end_src
+
+  and our collection of searching commands:
+
+  #+begin_src emacs-lisp
+    (defun espotify-counsel-album (&optional filter)
+      (interactive)
+      (espotify-search-by 'album filter))
+
+    (defun espotify-counsel-artist (&optional filter)
+      (interactive)
+      (espotify-search-by 'artist filter))
+
+    (defun espotify-counsel-track (&optional filter)
+      (interactive)
+      (espotify-search-by 'track filter))
+
+    (defun espotify-counsel-playlist (&optional filter)
+      (interactive)
+      (espotify-search-by 'playlist filter))
+  #+end_src
+
+  Simpler than our initial consult, although it's true that we already
+  had part of the job done. The nice "split search" that counsult
+  offers out of the box, though, is much more difficult to get.
+
+* Postamble
+
+  #+begin_src emacs-lisp
+    (provide 'espotify)
+  #+end_src
+
+  #+begin_src emacs-lisp :tangle espotify-consult.el
+    (provide 'espotify-consult)
+  #+end_src
+
+  #+begin_src emacs-lisp :tangle espotify-embark.el
+    (provide 'espotify-embark)
+  #+end_src
+
+  #+begin_src emacs-lisp :tangle espotify-counsel.el
+    (provide 'espotify-counsel)
+  #+end_src
+
+* Footnotes
+
+[fn:1] This is an elegant strategy i first learnt about in SICP, many,
+many years ago, and i must say that it is very charming to find it
+around in the wild!
-- 
cgit v1.2.3