<- All projects

spotatui

An open-source, full-featured Spotify terminal and desktop client written in Rust. Official collaborator contributing for triaging issues, testing PRs, and writing QoL. PRs: #356 · #550 · #577 · #742 · #754

RustTokioratatuilibrespotOpen SourceLinux
5 min readSource

TL;DR

spotatui is a community-maintained terminal Spotify client in Rust (~129k LOC, 1,440 stars, 242 forks). I landed 5 merged PRs across playback integration, API resilience, and in-app performance, then earned triage + push/pull access. My work focuses on triaging issues, testing PRs, and writing QoL such as fixing stale MPRIS references and adding search to saved songs.

About the project

spotatui is a fork of spotify-tui that diverged significantly:

  • Native Spotify streaming via a maintained librespot fork (own Connect device, Premium required)
  • Optional sources: Local Files, Subsonic/Navidrome, Internet Radio, YouTube, Qobuz, Apple Music (macOS)
  • Ratatui TUI + full CLI (spotatui playback, play, list, search, sync, history recap), Lua plugins, MCP server, AI DJ, synced lyrics, FFT visualizer
  • One cargo package: core/ (App state, driver tick, Action vocabulary), infra/ (network, player, sources, OS integrations), tui/, gui/, cli/, runtime/

Relevant constraints: 8-leg CI feature matrix, --locked builds, cargo fmt + clippy -D warnings, coupling gates in src/gates.rs / tools/gates.count that may only fall.

My role: contributor -> maintainer

Started as external contributor, now hold push, pull, and triage access on LargeModGames/spotatui.

What that means in practice:

  • Triage: repro issues, label, close duplicates, verify fixes against main
  • Review: check generation-guards on background writes, feature-gate correctness (tui / streaming / spotify-session legs), App API discipline (import from crate::core::app, mutate via methods/Action, no direct view writes from producers)
  • Land: keep CI green across all legs, update Cargo.lock with any Cargo.toml edit, add colocated #[cfg(test)] tests

Selected work

#356: Fix stale MPRIS player reference after streaming recovery

Problem: handle_mpris_events captured the streaming_player Arc once at spawn time (src/runtime.rs). After a streaming recovery recreated the player, media keys kept dispatching to the dead instance.

Fix: fetch the current player on every MPRIS event instead of holding one reference for the loop lifetime. 18+/15- lines, no new unsafe, race window documented as harmless no-op.

Verified with ~24h of sleep/wake cycles + cargo fmt / clippy / test.

Takeaway: lifetime bugs in long-lived event loops; prefer fresh reads over captured Arcs for replaceable backends

Status: shipped Sep 2026, removed Oct 2026 by #752. No longer in main.

What it did at the time (src/infra/network/metadata.rs, src/tui/handlers/artist.rs, src/tui/ui/artist.rs): routed GET artists/{id}/related-artists 403/404 to empty list instead of handle_error, collapsed the 3-column layout to 50/50 when empty, skipped the missing pane in hover navigation.

Why it mattered then: the endpoint was already deprecated; without this the whole artist page bricked on a side-panel failure.

What #752 changed: Spotify no longer goes through the public Web API. src/infra/spotify/ answers from the internal API (extended metadata, playlist v2, collection v2, Pathfinder), and its own notes list "related artists are empty (the internal artist data has none)" as a known gap. The 403/404 path has nothing to handle anymore. The empty-layout handling concept survives (related_artists_visible() in src/tui/ui/artist.rs:19), but my refusal-mapping code is gone.

#577: Handle removed endpoints for Development Mode apps (fixes #567) SUPERSEDED by #752

Status: shipped Sep 2026, removed Oct 2026 by #752. src/core/spotify_access.rs (256 lines) and src/core/app/spotify_session.rs (124 lines) no longer exist in main. src/infra/network/recommend.rs is also gone.

What it did at the time (1,301+/87-, 16 files): learned the client's API tier from real 403/404 refusals, persisted it per-client-ID in state.yml, short-circuited repeat calls locally. Artist pages kept available content, Discover/Recommendations degraded to status messages instead of error pages, navigation skipped empty sections.

Why it mattered then: Spotify's Nov 2024 + Feb 2026 removals broke artist pages, Discover, and Recommendations for every custom client ID. This unblocked those users without a new login flow.

What #752 changed: there is no client ID, no developer app, no per-app rate limit anymore. Login is Spotify's pairing page over the librespot session; the commit message explicitly lists "the client-key tier ratchet" under Removed. The whole tier-learning state machine became dead code by design.

#742: Instant playlist search and sort from the existing page store (revamped mid-PR)

Problem: Ctrl+f search and column sort inside a playlist re-downloaded the playlist from Spotify every time.

What landed (revamped, I deleted ~4h of earlier work mid-PR):

The first draft added a separate playlist_cache indexed by playlist ID + snapshot_id, with a new PlaylistTracksPage::Cached variant. I scrapped it. The final version reuses the pages opening the playlist already loaded — no new cache type, no disk-schema change.

  • src/core/app/scrollable_pages.rs::is_complete() (scrollable_pages.rs:88): true only when pages are cached contiguously from offset 0 through a terminal page (next.is_none()). Empty, gapped, or offset-0-missing stores return false.
  • src/core/app/playlists.rs::try_search_playlist_tracks_from_cached_pages (playlists.rs:496) and try_sort_playlist_tracks_from_cached_pages (playlists.rs:526): both bail (false) unless the track table is active for that playlist and playlist_track_pages.is_complete(). Caller falls back to the existing background network pagination.
  • Search path sets pending_playlist_track_search so playlist_track_search_is_current passes, then filters in memory (case-insensitive, every whitespace-separated term matched against title/album/artists) and applies via apply_playlist_track_search_results. Sort path collects all cached TrackInfo and applies via Sorter + apply_sorted_playlist_tracks_if_current.
  • Colocated tests in both modules: completeness (empty / single-terminal / contiguous multipage / gap / missing offset 0) and matcher (case-insensitive across fields, miss on absent term) plus search/sort false-on-incomplete, true-on-complete.

Result: once all pages load, search/sort answers synchronously with zero API calls. Incomplete stores use the old path unchanged. cargo test --locked: 1,913 passed.

Follow-ups by others prove the seam was right: #751 marks pages stale after add/remove so the next search/sort re-walks Spotify, #786 refetches on filter-clear when stale.

#754 Search Liked Songs from the cached page store

Builds on #742's contiguous-page pattern, applied to Saved Tracks (660+/46-, 11 files).

  • New InputContext::SavedTrackSearch ("Search Liked Songs"); Ctrl+F filters cached pages with no spinner
  • Back/Esc/q clears filter and restores cached view; reopening clears stale filter; shuffle on filtered view plays from the filtered set
  • Pause auto-refresh while filter active; if cache can't answer, table stays put with loading status

Files: src/core/app/library.rs, src/tui/handlers/input.rs, src/tui/handlers/track_table.rs, src/tui/handlers/mod.rs, src/tui/runner.rs, src/tui/ui/search.rs, src/infra/network/native_shuffle.rs

Outcomes

  • 5/5 PRs merged.
  • Artist pages survive deprecated-endpoint refusals instead of bricking.
  • Playlist search/sort went from N API round-trips to zero when fully loaded.
  • MPRIS media keys survive streaming-backend replacement on Linux.
  • Maintainer trust: triage + push/pull access for ongoing review and release hygiene.

What this proves

  • Rust async + TUI at scale: shared App state under lock, serial IoEvent pump, Ratatui immutable draw fns.
  • API resilience: tier learning, persisted restrictions, UI degradation over error pages.
  • Performance with correct invalidation: snapshot_id-keyed caches, bounded slices, no disk-schema change.
  • OSS maintenance: scoping, honest partial fixes, CI/gate discipline, docs.