espotify: first cut

2 files changed, 358 insertions, 0 deletions

diff --git a/media/espotify.org b/media/espotify.org
new file mode 100644
index 0000000..fb50dba
--- /dev/null
+++ b/media/espotify.org
@@ -0,0 +1,353 @@
+#+title: consulting spotify
+#+date: <2021-01-08>
+#+filetags: emacs
+#+PROPERTY: header-args :tangle yes :comments no :results silent
+
+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"
+                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
+    (espotify--make-search-url "dream blue turtles" '(album))
+  #+end_src
+
+  #+RESULTS:
+  : https://api.spotify.com/v1/search?q=dream%20blue%20turtles&type=album
+
+  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))
+                                   (json-read)))))))
+  #+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-search (callback term types &optional filter)
+      (let ((query-url (espotify--make-search-url term types filter)))
+        (espotify--with-auth-token
+         (lambda (token)
+           (espotify--with-query-results token query-url callback)))))
+  #+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
+
+  #+RESULTS:
+  : t
+
+  #+begin_src emacs-lisp :load no :tangle no
+    (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                    |              |      |     |
+
+* 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
+
+  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
+    (defun consult-spotify-by (type &optional filter)
+      (consult--read (format "Search %ss: " type)
+                     (espotify--search-generator type filter)
+                     :lookup 'espotify--consult-lookup
+                     :category 'spotify-query-result
+                     :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-timer)
+        (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 (candidates)
+        (lambda (action)
+          (pcase action
+            ((or 'setup 'refresh) (funcall next action))
+            ('destroy (setq candidates nil) (funcall next 'destroy))
+            ((pred stringp)
+             (espotify-search*
+              (lambda (x)
+                (setq candidates (mapcar 'espotify--format-item x))
+                (funcall next candidates))
+              action ;; when we receive a string as the action,
+                     ;; it's the user input
+              type
+              filter))
+            ('get candidates)
+            (_ (funcall next action))))))
+  #+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:
+
+  #+begin_src emacs-lisp
+    (defun espotify--format-item (x)
+      (propertize (format "%s (%s%s%s)"
+                    (alist-get 'name x)
+                    (or (alist-get 'name (car (alist-get 'artists x))) "")
+                    (if-let (d (alist-get 'total_tracks x))
+                        (format ", %s tracks" d) "")
+                    (if-let (d (alist-get 'release_date x))
+                        (format ", %s" d)
+                      ""))
+                  'espotify-uri (alist-get 'uri x)))
+   #+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
+     (defun espotify--maybe-play (x)
+       (when-let (uri (get-text-property 0 'espotify-uri x))
+         (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 consult-spotify-album (&optional filter)
+       (interactive)
+       (espotify--maybe-play (consult-spotify-by 'album filter)))
+   #+end_src
+
+* Exercises for the reader
+
+  - Defining new interactive commands for other types and queries,
+    as well as standard filters.
+  - Pagination when we receive more than the standard 20 results.
+  - Metadata set for Marginalia.
+
+* 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!
diff --git a/readme.org b/readme.org
index 0aa5362..a4f124d 100644
--- a/readme.org
+++ b/readme.org
@@ -9,4 +9,9 @@
   - *sys* generic utilities for external programs
   - *bmk* a web bookmark manager
 
+  Libraries in literate emacs lisp:
+
+  - [[file:net/signel.org][Signel]] a simplistic Signal client, using the signal-cli java lib.
+  - [[file:media/espotify.org][Espotify]] searching and playing Spotify using counsel.
+
   See also my [[https://jao.io/cgit/emacs][emacs custom files]].