From 9a08a96a2c9ed8c8d4897e02bcbab7e8e8cbebf0 Mon Sep 17 00:00:00 2001 From: jao Date: Sat, 20 Mar 2021 02:50:11 +0000 Subject: obsolete espotify.org --- lib/media/espotify.org | 643 ------------------------------------------------- 1 file changed, 643 deletions(-) delete mode 100644 lib/media/espotify.org (limited to 'lib/media') 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 -- cgit v1.2.3