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
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-sessionlegs),AppAPI discipline (import fromcrate::core::app, mutate via methods/Action, no directviewwrites from producers) - Land: keep CI green across all legs, update
Cargo.lockwith anyCargo.tomledit, 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
#550: Treat related-artists 403/404 as empty SUPERSEDED by #752
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) andtry_sort_playlist_tracks_from_cached_pages(playlists.rs:526): both bail (false) unless the track table is active for that playlist andplaylist_track_pages.is_complete(). Caller falls back to the existing background network pagination.- Search path sets
pending_playlist_track_searchsoplaylist_track_search_is_currentpasses, then filters in memory (case-insensitive, every whitespace-separated term matched against title/album/artists) and applies viaapply_playlist_track_search_results. Sort path collects all cachedTrackInfoand applies viaSorter+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
Appstate 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.
Links
- Repo: https://github.com/LargeModGames/spotatui
- PR #356: https://github.com/LargeModGames/spotatui/pull/356
- PR #550: https://github.com/LargeModGames/spotatui/pull/550
- PR #577: https://github.com/LargeModGames/spotatui/pull/577
- PR #742: https://github.com/LargeModGames/spotatui/pull/742
- PR #754: https://github.com/LargeModGames/spotatui/pull/754
- Release v0.44.0: https://github.com/LargeModGames/spotatui/releases