From 87607971a317700a179b416c1e2c55d6e6acd854 Mon Sep 17 00:00:00 2001 From: jao Date: Sat, 9 Jan 2021 01:07:49 +0000 Subject: espotify: first cut --- media/espotify.org | 353 +++++++++++++++++++++++++++++++++++++++++++++++++++++ readme.org | 5 + 2 files changed, 358 insertions(+) create mode 100644 media/espotify.org 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]]. -- cgit v1.2.3