obsolete espotify.org

1 files changed, 0 insertions, 643 deletions

diff --git a/lib/media/espotify.org b/lib/media/espotify.org
deleted file mode 100644
index ff5413a..0000000
--- a/lib/media/espotify.org
+++ /dev/null
@@ -1,643 +0,0 @@
-#+title: consulting spotify
-#+date: <2021-01-08 04:02>
-#+auto_tangle: t
-#+filetags: emacs norss
-#+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 four 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
-
-    Although we're not going to use them explicitly below, we can define
-  a couple more commands that may come in handy:
-
-  #+begin_src emacs-lisp
-    (defun espotify-play-pause ()
-      (interactive)
-      (espotify-call-spotify-via-dbus "PlayPause"))
-
-    (defun espotify-next ()
-      (interactive)
-      (espotify-call-spotify-via-dbus "Next"))
-
-    (defun espotify-previous ()
-      (interactive)
-      (espotify-call-spotify-via-dbus "Previous"))
-   #+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 (espotify--search-generator type filter)
-                       :prompt (format "Search %ss: " type)
-                       :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.). 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.  These actions need access to the
-  rich metadata attached to the candidate, and will therefore be
-  defined as regular one-argument functions, rather than interactive
-  commands (as is otherwise recommended for generic embark actions).
-
-  #+begin_src emacs-lisp
-    (require 'espotify-consult)
-    (require 'embark)
-
-    (defun espotify--show-info (candidate)
-      "Show low-level info (an alist) about selection."
-      (pop-to-buffer (get-buffer-create "*espotify info*"))
-      (read-only-mode -1)
-      (delete-region (point-min) (point-max))
-      (insert (propertize candidate 'face 'bold))
-      (newline)
-      (when-let (item (espotify--item candidate))
-        (insert (pp-to-string item)))
-      (newline)
-      (goto-char (point-min))
-      (read-only-mode 1))
-
-    (defun espotify--play-album (candidate)
-      "Play album associated with selected item."
-      (when-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--yank-url (candidate)
-      "Add to kill ring the Spotify URL of this entry"
-      (when-let (item (espotify--item candidate))
-        (if-let (url (alist-get 'spotify (alist-get 'external_urls item)))
-            (kill-new url)
-          (message "No spotify URL for this candidate"))))
-
-    (embark-define-keymap espotify-item-keymap
-      "Actions for Spotify search results"
-      ("y" espotify--yank-url)
-      ("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-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