feat(spotify): SP badge, unavailable-track modal, docs, vergen note

- Add an SP service badge in the playback header (Spotify green),
  alongside YT/SC/HM.
- A directly-requested single Spotify track that's unavailable now shows
  the "track unavailable" modal instead of playing silence. resolve()
  probes librespot's AudioItem availability (which accounts for the
  user's country and relinked alternatives) and returns an error, which
  the existing resolve_url_with_startup -> Failed path turns into the
  modal. Playlist/album tracks are still dropped at resolve. The modal
  detail text is now service-neutral ("track", not "video").
- Document the vergen 9.0.6 pin in Cargo.toml and the Makefile so a
  future `cargo update` that reintroduces the build break is easy to fix.
- Document Spotify throughout README.md and CLAUDE.md: the librespot
  model, Premium requirement, login flow, in-process decode, looping,
  album art, caches, and caveats.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: program247365

CLAUDE.md

@@ -18,13 +18,18 @@ But `--url` now accepts:
 - YouTube tracks and playlists
 - SoundCloud tracks and playlists
 - HypeM URLs
+- Spotify tracks, playlists, and albums (`https://open.spotify.com/...` or
+  `spotify:...`), via librespot — **Spotify Premium required**
 
 Behavior:
 
 - local files: play directly
 - single tracks: loop forever
 - playlists: play each track once, then loop the whole playlist
 
+Spotify needs a one-time `looper spotify login` (OAuth browser flow, credentials
+cached). See "Spotify playback model" below.
+
 ## Commands
 
 ```bash
@@ -50,13 +55,16 @@ cargo test
 
 ## External Runtime Dependencies
 
-Remote playback requires:
+YouTube / SoundCloud / HypeM playback requires:
 
 - `yt-dlp`
 - `ffmpeg`
 
 If YouTube playback fails with `403`, updating `yt-dlp` is the first thing to try.
 
+Spotify requires **neither** `yt-dlp` nor `ffmpeg` (librespot decodes in-process)
+— only a Spotify Premium account and a one-time `looper spotify login`.
+
 ## Install via Homebrew
 
 ```bash
@@ -77,6 +85,13 @@ Tap repo: https://github.com/program247365/homebrew-tap
 - `stream-download` — HTTP/process-backed stream readers
 - `tokio` — runtime used by streamed/process-backed audio inputs
 - `structopt` — CLI parsing
+- `librespot-core` / `-playback` / `-metadata` / `-oauth` — Spotify session,
+  in-process decode, metadata, and OAuth login. `librespot-playback` is built
+  with `default-features = false` so its bundled (older) rodio backend stays out
+  of the tree — looper feeds a custom `Sink` instead. **`vergen` is pinned to
+  9.0.6 in `Cargo.lock`**; a `cargo update` that pulls vergen 9.1.0 breaks
+  librespot-core's build script (vergen-lib trait mismatch) — re-pin with
+  `cargo update -p vergen --precise 9.0.6` (also noted in `Cargo.toml`/`Makefile`).
 
 ## Architecture
 
@@ -90,7 +105,10 @@ Tap repo: https://github.com/program247365/homebrew-tap
 - `src/tui.rs` — playback TUI and loading TUI rendering
 - `src/download.rs` — loading/progress state models and helpers for formatting bytes/speed/ETA
 - `src/plugin/` — remote service resolution and `yt-dlp` integration
-- `src/playback_input.rs` — playback input abstraction (`File`, `HttpStream`, `ProcessStdout`) plus pending-download metadata
+- `src/spotify/` — Spotify via librespot: shared session, OAuth login, metadata
+  resolution, the librespot-`Sink`→rodio-`Source` bridge. `main.rs` routes the
+  `spotify login` subcommand here. See "Spotify playback model" below.
+- `src/playback_input.rs` — playback input abstraction (`File`, `HttpStream`, `ProcessStdout`, `Spotify`) plus pending-download metadata
 
 ### Remote playback model
 
@@ -114,13 +132,45 @@ The project now uses a hybrid remote architecture.
 - `src/plugin/hypem.rs`
   - prefers stream-first resolution and falls back to download-first
 
+`plugin::resolve_url` intercepts Spotify URLs/URIs **before** the `yt-dlp`
+availability check and dispatches to `crate::spotify::resolve`, so Spotify works
+without `yt-dlp` installed.
+
+### Spotify playback model
+
+Spotify is not a `yt-dlp` plugin — it has no downloadable audio. `src/spotify/`
+uses librespot:
+
+- `src/spotify/mod.rs`
+  - `is_spotify_url`, URL/URI parsing (`open.spotify.com/...`, `intl-xx`
+    prefixes, `spotify:` URIs)
+  - a shared, lazily-connected `Session` (`OnceLock`) built from cached OAuth
+    credentials; `login()` runs the `librespot-oauth` browser flow once.
+    `Session::new` calls `Handle::current()`, so it must be built **inside** the
+    runtime (`runtime.block_on`)
+  - `resolve()` → `Vec<TrackInfo>` for a track, playlist, or album, fetching
+    track metadata + album art concurrently (bounded batches). Album art is a
+    public `i.scdn.co` JPEG keyed by file id, cached under `spotify/art/`
+  - `ensure_track_available()` uses librespot's `AudioItem` availability to fail
+    a single unplayable track at resolve time, so `resolve_url_with_startup`
+    surfaces the "track unavailable" modal instead of playing silence
+- `src/spotify/sink.rs` — the bridge. librespot's `Player` pushes decoded PCM
+  into a custom `Sink`; a bounded channel carries it to a rodio `Source`. The
+  sink blocks under backpressure (throttling the decoder to real time); the
+  source yields silence on underrun. An `EndSignal` lets the source end on
+  demand: single tracks loop forever (listener re-`load`s on `EndOfTrack`),
+  playlist tracks finish so `play_loop`'s `sink.empty()` advances to the next.
+
 ### Playback inputs
 
 `PlaybackInput` currently supports:
 
 - `File(PathBuf)` — local files and cached remote tracks
 - `HttpStream { .. }` — direct HTTP-backed stream reader
 - `ProcessStdout { .. }` — process-backed stream through `stream-download`
+- `Spotify { track_uri }` — handled in `AudioPlayer::new` by the librespot
+  bridge (`src/spotify/`); never reaches the file/stream reader path. Pause works
+  via rodio backpressure; seek is a no-op
 
 Note that YouTube is intentionally on the cached-file path right now because direct/process streaming proved less reliable than download-first with current `yt-dlp` behavior.
 
@@ -152,7 +202,7 @@ There are now two major UI modes:
 
 - single local or remote track: `repeat_infinite()`
 - playlist: play each track once, then loop the playlist
-- `PrefetchWorker` in `play_loop.rs` uses a bounded channel and background thread to cache current/next tracks where applicable
+- `PrefetchWorker` in `play_loop.rs` uses a bounded channel and background thread to cache current/next tracks where applicable. **Spotify tracks are skipped** by the prefetcher (they stream in-process via librespot and have no `source_url` to download), so there is a brief loading screen between Spotify playlist tracks
 - remote playlists are re-resolved each full loop so expiring service URLs are less likely to be reused forever
 
 ### Threading model
@@ -163,6 +213,7 @@ There are now two major UI modes:
 - the visualizer reads from `sample_buf: Arc<Mutex<VecDeque<f32>>>`
 - prefetch uses a background worker thread
 - some stream-backed audio inputs create a Tokio runtime inside `AudioPlayer`
+- Spotify owns a process-wide Tokio runtime + connected `Session` in `src/spotify/` (`OnceLock`); librespot's `Player` and the end-of-track loop listener run on it. The bridge's end-of-track listener is aborted when the `AudioPlayer`'s `SpotifyPlayback` drops, releasing the `Player`
 - media-key events from `souvlaki` arrive on the OS-specific thread (macOS: main / AppKit; Linux: souvlaki's own DBus thread) and are forwarded to the TUI thread via an `mpsc::Receiver<KeyCommand>` drained inside `run_loop`
 
 ## Notable Design Decisions
@@ -179,6 +230,18 @@ There are now two major UI modes:
   (`SessionOutcome::BackToHistory`) rather than exiting. Quitting playback with
   `q` still exits the app (`SessionOutcome::Quit`). This is intentional — a
   "jukebox historian" accumulates links that inevitably rot.
+- Spotify playback uses librespot (reverse-engineered Spotify Connect),
+  **Premium-only**, with a custom librespot `Sink` feeding rodio so the
+  visualizer keeps working — rather than librespot's own rodio backend (which
+  would bypass the sample tap and also drag a second, incompatible rodio into
+  the tree). `librespot-playback` is therefore `default-features = false`.
+- `vergen` is pinned to `9.0.6` (`Cargo.lock`) to keep librespot-core's build
+  script compiling; see the note in `Cargo.toml`/`Makefile`. Re-pin after a
+  `cargo update` with `cargo update -p vergen --precise 9.0.6` if the build
+  fails with a vergen-lib trait mismatch.
+- a directly-requested **single** Spotify track that is unavailable is caught at
+  resolve (`ensure_track_available`) so it shows the modal; unavailable tracks
+  inside a playlist/album are silently dropped during concurrent metadata fetch.
 - `souvlaki` is wired with the `use_zbus` feature so Linux builds don't need `libdbus-1-dev`; macOS uses `MPRemoteCommandCenter` + `MPNowPlayingInfoCenter` directly. Windows is intentionally unwired (would need a hidden message-only HWND + a per-tick `pump_event_queue`).
 
 ## Tests

Cargo.toml

@@ -29,6 +29,16 @@ rodio = { version = "0.22", default-features = false, features = ["playback", "m
 souvlaki = { version = "0.8", default-features = false, features = ["use_zbus"] }
 structopt = "0.3.21"
 tokio = { version = "1", features = ["rt-multi-thread"] }
+# Spotify playback. `librespot-playback` has default-features off on purpose:
+# it keeps the bundled (older) rodio audio backend out of the tree so there is
+# only one rodio. We feed librespot's decoded PCM through our own custom Sink
+# (src/spotify/sink.rs) instead.
+#
+# NOTE: `vergen` is pinned to 9.0.6 in Cargo.lock. librespot-core's build script
+# pulls vergen-gitcl 1.0.8 (which needs vergen ^9.0.6), but vergen 9.1.0 bumps
+# its internal vergen-lib to 9.x and collides with vergen-gitcl's vergen-lib
+# 0.1.6, breaking the build. If `cargo update` ever reintroduces vergen 9.1.0,
+# re-pin with: cargo update -p vergen --precise 9.0.6
 librespot-core = "0.8"
 librespot-metadata = "0.8"
 librespot-oauth = "0.8"

Makefile

@@ -14,6 +14,11 @@ help: ## Show available targets
 	@awk 'BEGIN {FS = ":.*##"; printf "Usage: make \033[36m<target>\033[0m\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
 
 # ── Local development ─────────────────────────────────────────────────────────
+#
+# NOTE: `vergen` is pinned to 9.0.6 in Cargo.lock to keep librespot-core's build
+# script compiling (see the note in Cargo.toml). If a build fails with a
+# vergen-lib trait mismatch after `cargo update`, re-pin with:
+#   cargo update -p vergen --precise 9.0.6
 
 build: ## Build debug binary
 	cargo build

README.md

@@ -14,6 +14,7 @@ It supports:
 - YouTube URLs (including live streams)
 - SoundCloud URLs
 - HypeM URLs
+- Spotify tracks, playlists, and albums (Spotify Premium required)
 - single tracks and playlists
 - infinite looping for single tracks
 - whole-playlist looping for playlists
@@ -23,7 +24,7 @@ It supports:
 - default no-arg startup into playlist history
 - SQLite-backed playback history and favorites
 - remote download/loading UI with progress, speed, and ETA
-- small source badges in the TUI for supported services (`YT`, `SC`, `HM`)
+- small source badges in the TUI for supported services (`YT`, `SC`, `HM`, `SP`)
 - animated terminal/tab title with playback, pause, and loading status
 
 ## Install
@@ -121,6 +122,26 @@ looper play --url "https://hypem.com/track/2gq0d/CHVRCHES+-+Clearest+Blue"
 looper play --url "https://www.youtube.com/playlist?list=PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI"
 ```
 
+### Spotify
+
+Spotify requires a **Spotify Premium** account. Authorize looper once via your
+browser:
+
+```shell
+looper spotify login
+```
+
+This opens Spotify's authorization page, then caches credentials so you won't
+need to log in again. After that, play tracks, playlists, or albums:
+
+```shell
+looper play --url "https://open.spotify.com/track/4PTG3Z6ehGkBFwjybzWkR8"
+looper play --url "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
+looper play --url "https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy"
+```
+
+`spotify:` URIs work too. Spotify does **not** require `yt-dlp` or `ffmpeg`.
+
 ## How Remote Playback Works
 
 - startup opens the local SQLite database, runs embedded migrations, and then begins loading playback
@@ -139,6 +160,33 @@ Current behavior is intentionally pragmatic:
   fast with a helpful message instead of hanging
 - SoundCloud and HypeM prefer a stream-first path and fall back to cached download when needed
 
+## How Spotify Playback Works
+
+Spotify is fundamentally different from the `yt-dlp`-backed services. Spotify
+exposes no downloadable audio, so looper uses
+[librespot](https://github.com/librespot-org/librespot) — the open-source
+implementation of the Spotify Connect protocol — to play full tracks. This is
+the same library [spotify-player](https://github.com/aome510/spotify-player)
+uses, and it has real constraints:
+
+- **Premium is required.** librespot authenticates as a Spotify Connect device;
+  free accounts can't stream through it.
+- **OAuth login, once.** `looper spotify login` runs an OAuth browser flow and
+  caches reusable credentials under the cache directory. No password is stored.
+- **Audio is decoded in-process.** The DRM Ogg/Vorbis stream is decrypted and
+  decoded by librespot, and its PCM is bridged straight into looper's audio
+  pipeline and FFT visualizer. There is no MP3 on disk like the other services.
+- **Looping** re-loads the track when it ends (single track) or advances to the
+  next track and loops the whole collection (playlist/album).
+- **Album art** is fetched from Spotify's public image CDN and shown in the
+  visualizer, like the other services.
+- **Caveats:** there's a brief loading screen between playlist tracks (no
+  background prefetch for Spotify), and an unavailable track (removed or
+  region-locked) shows the "track unavailable" modal instead of playing.
+
+Note: librespot is a reverse-engineered client. Using it is for personal use and
+is technically outside Spotify's Terms of Service.
+
 ## Data and Cache Locations
 
 Remote tracks are cached locally after download:
@@ -148,6 +196,9 @@ Remote tracks are cached locally after download:
 | macOS | `~/Library/Caches/sh.kbr.looper/` |
 | Linux | `~/.cache/looper/` |
 
+Spotify keeps its cached credentials, encrypted audio cache, and album art in a
+`spotify/` subfolder of the cache directory above.
+
 Playback history and favorites live in a SQLite database (`looper.sqlite3`). Where it lives depends on your sync setup — see [Cross-Device Sync](#cross-device-sync) below.
 
 - startup applies pending embedded migrations automatically — no manual steps needed when upgrading

src/play_loop.rs

@@ -296,7 +296,7 @@ fn handle_unresolvable_replay(
         .title_for_replay_target(replay_target)?
         .unwrap_or_else(|| replay_target.to_string());
     let title = truncate_title(&title, 60);
-    let detail = "This video may be private, removed, or region-locked.";
+    let detail = "This track may be private, removed, or region-locked.";
     title_state.set("looper — track unavailable".to_string())?;
 
     loop {

src/spotify/mod.rs

@@ -24,6 +24,7 @@ use librespot_core::cache::Cache;
 use librespot_core::config::SessionConfig;
 use librespot_core::session::Session;
 use librespot_core::spotify_uri::SpotifyUri;
+use librespot_metadata::audio::AudioItem;
 use librespot_metadata::{Album, Metadata, Playlist, Track};
 use librespot_oauth::OAuthClientBuilder;
 use librespot_playback::config::PlayerConfig;
@@ -95,6 +96,7 @@ pub fn resolve(url: &str) -> Result<Vec<TrackInfo>> {
                 let track_uri = uri
                     .to_uri()
                     .map_err(|e| eyre!("failed to build Spotify track URI: {e}"))?;
+                ensure_track_available(&ctx.session, &uri).await?;
                 let thumbnail = download_cover(&HttpClient::new(), &track, &art_dir()?, 0).await;
                 Ok::<_, color_eyre::eyre::Report>(track_info(track, track_uri, None, thumbnail))
             })?;
@@ -233,6 +235,28 @@ async fn download_cover(
     Some(target)
 }
 
+/// Error if a track won't play for this account. librespot computes
+/// availability against the account's country and follows relinked
+/// alternatives, so this matches the player's own verdict: unavailable with no
+/// playable alternative. Surfacing it as an error lets the caller show the
+/// "track unavailable" modal instead of playing silence. Used only for a single
+/// directly-requested track; playlist/album tracks are dropped at resolve.
+async fn ensure_track_available(session: &Session, uri: &SpotifyUri) -> Result<()> {
+    let item = AudioItem::get_file(session, uri.clone()).await.map_err(|_| {
+        eyre!("this Spotify track couldn't be loaded (it may be removed or region-locked)")
+    })?;
+    let has_alternative = item
+        .alternatives
+        .as_ref()
+        .is_some_and(|alts| !alts.is_empty());
+    if item.availability.is_err() && !has_alternative {
+        return Err(eyre!(
+            "this Spotify track is unavailable (removed or region-locked)"
+        ));
+    }
+    Ok(())
+}
+
 fn art_dir() -> Result<PathBuf> {
     let dir = crate::plugin::cache_dir_path()?.join("spotify").join("art");
     std::fs::create_dir_all(&dir).wrap_err("failed to create Spotify art cache directory")?;

src/tui.rs

@@ -1165,6 +1165,7 @@ fn service_badge(service: &Option<String>) -> Span<'static> {
         Some("YouTube") => badge_span("YT", Color::Rgb(255, 90, 90)),
         Some("SoundCloud") => badge_span("SC", Color::Rgb(255, 150, 50)),
         Some("HypeM") => badge_span("HM", Color::Rgb(80, 200, 210)),
+        Some("Spotify") => badge_span("SP", Color::Rgb(30, 215, 96)),
         Some("Online") => badge_span("ON", Color::Rgb(180, 180, 200)),
         _ => Span::raw(""),
     }