diff options
Diffstat (limited to 'lib/media/espotify.org')
| -rw-r--r-- | lib/media/espotify.org | 627 |
1 files changed, 627 insertions, 0 deletions
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! |