A Spotify client for Emacs built on consult, embark, and marginalia.

spot integrates Spotify into the standard Emacs completion ecosystem. Search results appear as consult multi-sources with marginalia annotations and embark actions — the same workflow you use for buffers, files, and grep.

• Multi-source search — Search albums, artists, tracks, playlists, shows, episodes, and audiobooks simultaneously with narrowing keys
• Embark actions — Play, inspect data, list album/artist tracks, add tracks to playlists
• Marginalia annotations — See artist, duration, release date, popularity, and other metadata inline
• Player controls — Play, pause, next, previous via Spotify Connect (works with any device)
• Mode-line — Currently playing track displayed in the mode-line
• Playlist management — Browse your playlists and add tracks to them

(use-package spot
  :ensure (:host github :repo "chiply/spot")
  :config
  (spot-mode 1))

(use-package spot
  :straight (:host github :repo "chiply/spot")
  :config
  (spot-mode 1))

Clone the repository and add it to your load-path:

(add-to-list 'load-path "/path/to/spot")
(require 'spot)
(spot-mode 1)

Register a Spotify application at https://developer.spotify.com/dashboard and set your credentials:

(setq spot-client-id "your-client-id"
      spot-client-secret "your-client-secret")

Set the redirect URI in your Spotify application to https://spotify.com.

spot-mode is a global minor mode that registers embark keymaps, marginalia annotators, and starts the mode-line update timer:

(spot-mode 1)

Add the spot lighter to your mode-line:

(setq-default mode-line-format
              (append mode-line-format '((:eval (spot-mode-line-string)))))

The mode-line face can be customized:

(set-face-attribute 'spot-mode-line nil :foreground "#1db954")

Run M-x spot-authorize. This opens the Spotify authorization page in your browser. After granting access, copy the code from the redirect URL and paste it into the minibuffer prompt.

To refresh an expired token: M-x spot-refresh.

M-x spot-consult-search opens a multi-source search. Type to search, then use narrowing keys to filter by type:

Pass Spotify Search API parameters after a -- separator, in --key=value form:

j dilla -- --limit=50 --market=US

Values outside the valid range (e.g. --limit=200) are rejected by the Spotify API and surface as an empty result set.

Do not pass --type=; spot hardcodes the type parameter internally to enable multi-source search. To narrow to a single type, use the narrowing keys above.

The q= parameter itself also accepts Spotify field filters — these go before the -- separator since they are part of the query string, not URL parameters:

artist:Radiohead year:2000-2010 -- --market=GB --limit=50
album:"Kid A"
genre:jazz year:1960-1970
tag:new

Supported field filters include artist:, album:, year: (single or range), genre:, tag:hipster, tag:new, isrc:, upc:.

Press embark-act (default C-.) on any search result:

• M-x spot-player-play
• M-x spot-player-pause
• M-x spot-player-next
• M-x spot-player-previous

• M-x spot-consult-search-current-user-playlists — browse your playlists
• M-x spot-consult-search-playlist-tracks — browse tracks in a playlist
• M-x spot-add-current-track-to-playlist — add the currently playing track to a playlist

spot focuses on deep integration with the consult/embark/marginalia ecosystem. It provides a unified multi-source search where all content types are searched simultaneously (rather than separate commands per type), with rich embark actions and marginalia annotations for every result. Playback uses the Spotify Connect API, so it works across platforms and controls any active device.

• Emacs 29.1+
• consult 1.0+
• embark 0.23+
• marginalia 1.0+
• ht 2.3+
• dash 2.19+

spot uses consult--multi and consult--dynamic-collection to build its multi-source async search. These are the established extension points for consult-based packages and are used by many packages in the consult ecosystem (consult-dir, consult-gh, consult-flycheck, etc.). The minimum consult version is pinned to 1.0 to ensure API stability.

GPL-3.0-or-later