aome510/spotify-player

This system is a terminal-based Spotify client built in Rust that provides core playback controls, library management, and device discovery via Spotify Connect. It features a modular, customizable TUI interface with support for themes, keybindings, and real-time audio visualization, while also exposing a UDP-based CLI for remote command execution. The application handles authentication, rate-limiting, and media integration, and includes a separate library for retrieving song lyrics via the Genius API.

9 changes.

This period established the foundational structure and initial release of the terminal-based Spotify Player, introducing core playback, authentication, and UI features. Subsequent work focused on refactoring the codebase into modular components for the UI, state management, and event handling, while adding extensive configuration options for themes and keybindings.

5 changes.

The project significantly restructured its UI state management to support new views like Lyrics and Browse, while introducing a dedicated lyric finder library. A new CLI interface was added to enable external control of playback and library management via UDP sockets, supported by CI improvements for cross-compilation.

An example CLI application has been added to demonstrate how to use the lyric\_finder library. Users can now run this example to search for song lyrics by passing a query as a command-line argument, which will display the track name, artists, and lyrics if found, or a message indicating the lyrics were not found.

_lyric\finder/examples · high confidence

Two new utility scripts are added to the \scripts\ directory. \theme\_parse\ fetches terminal color schemes from the iTerm2-Color-Schemes repository and converts them into the application's internal TOML theme format, allowing users to easily import external themes. \publish\ automates the release process by checking out the master branch, merging upstream changes, and running \cargo publish\ for the specified crate (defaulting to \spotify\_player\).

scripts · high confidence

This change introduces the initial version of the Spotify Player, a terminal-based client for Spotify. It provides core playback controls (play, pause, seek, volume), context navigation (playlists, albums, artists, tracks), and media library management (liked tracks, saved albums, followed artists). The application supports Spotify Connect for device discovery and control, integrates with system media controls (MPRIS on Linux, media keys on macOS/Windows), and includes a CLI for remote command execution. Authentication is handled via OAuth2 with token caching, and the UI is rendered using the ratatui library.

_spotify\player/src · high confidence

This change establishes the foundational structure for the spotify-player project. It introduces comprehensive documentation, including a detailed AGENTS.md file outlining the architecture, concurrency model, and coding conventions, alongside a THEMES.md file for community theme collections. It also adds configuration files for development tools (.dir-locals.el, .typos.toml), build systems (Dockerfile, Cross.toml, Nix flake), and a checklist for pre-release procedures.

(repo-wide) · high confidence

The application now supports full customization of its interface and behavior through external configuration files. Users can define custom keybindings for commands and actions in \keymap.toml\, create and switch between visual themes with specific color palettes and component styles in \theme.toml\, and adjust application parameters such as streaming options, playback formats, and logging paths in \app.toml\.

_spotify\player/src/config · high confidence

Users can now control the Spotify player and manage their library via a command-line interface. This change introduces a UDP-based socket mechanism that allows CLI commands to interact with a running Spotify player instance or start a new one if none is active. The CLI supports playback control (play, pause, next, previous, volume, seek, shuffle, repeat), device connection, and library management including liking/unliking tracks, searching, and playlist operations (create, delete, import, fork, sync, edit). It also includes commands for authentication, generating shell completions, and retrieving application state keys.

_spotify\player/src/cli · high confidence

Added a new \lyric\_finder\ crate that provides a \Client\ for retrieving song lyrics via the Genius API. The library includes functionality to search for songs, retrieve raw lyrics from a URL, and process the output to fix inconsistent newline spacing. It also features query improvement logic that strips 'remaster' and 'remix' metadata from search queries to improve result accuracy.

_lyric\finder/src · high confidence

The application's terminal UI has been restructured into a modular \ui\ crate, introducing dedicated modules for page layouts, playback windows, popups, and input handling. This refactor enables real-time audio visualization (FFT-based bar charts) for local streaming tracks and implements a robust, protocol-aware cover image rendering system that supports both \ratatui-image\ widgets and native iTerm2 inline images to prevent display artifacts. The new architecture also includes a custom single-line text input widget for search and playlist creation, support for bidirectional (RTL) text rendering, and configurable UI elements such as border styles, progress bar positions, and relative line numbers in lists.

_spotify\player/src/ui · high confidence

A new Dockerfile (ci/Dockerfile-cross) has been added to support cross-compilation within the CI pipeline. This file configures the build environment to install necessary architecture-specific dependencies (such as libssl, libasound, libdbus, and libxcb) required for building the application for different target architectures.

ci · high confidence

The client now includes a middleware that deduplicates concurrent GET requests and respects Spotify's Retry-After headers to mitigate rate-limiting issues. Additionally, the Web API client has been updated to preserve the refresh token during token rotation, preventing authentication loss caused by Spotify's updated token expiration policy.

_spotify\player/src/client · high confidence

The application's shared state has been restructured from a single monolithic file into a modular directory (\spotify\_player/src/state\) containing distinct modules for data (\data.rs\), models (\model.rs\), player state (\player.rs\), UI state (\ui.rs\), queue management (\queue.rs\), and constants (\constant.rs\). This change introduces a new \AppData\ structure that separates user data (playlists, saved albums, etc.) and memory caches (context, search, lyrics) from the UI and player states, and implements a \CustomQueue\ system to manage playback batches and shuffle modes independently of the underlying librespot player.

_spotify\player/src/state · high confidence

The terminal event handling logic in the \event\ module has been restructured into distinct files (\page.rs\, \popup.rs\, \window.rs\, and \clipboard.rs\) to improve maintainability. This change introduces a new clipboard system that replaces the previous library with a provider-based approach, supporting external commands (\pbcopy\/\pbpaste\, \wl-copy\/\wl-paste\, \xclip\, \xsel\) on Unix and native Windows APIs, while also adding mouse scroll support for volume adjustment and specific sorting commands for the library page.

_spotify\player/src/event · high confidence

The application's UI state has been reorganized into a modular structure (mod.rs, page.rs, popup.rs) to support a wider variety of views and interactions. This change introduces dedicated state models for new pages including Lyrics, Browse, Queue, Command Help, and Logs, while expanding the Library and Search pages with more granular focus states (e.g., separating tracks, albums, artists, shows, and episodes in search). It also adds support for playlist folders, a new playlist creation popup with name/description inputs, and confirmation popups for destructive actions like deleting tracks or library items. The state now tracks vim-style count prefixes for navigation and manages image rendering info for cover art, providing a more robust foundation for the terminal UI.

_spotify\player/src/state/ui · high confidence

The application is initialized as version 0.25.1, migrating to the Rust 2021 edition and upgrading the core audio backend to librespot v0.8.0. This release integrates the rspotify client library v0.16.1 for API interactions and the ratatui TUI framework v0.30.2 for the terminal interface. It introduces optional features for streaming audio (via librespot), media controls, image rendering, and daemon mode, while enforcing strict linting rules across the workspace.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 66 → 67 (+1.2)
• Rubric changed (rubric-2026.09.9 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 82 → 82 (+0.0)
• Architecture 100 → 89 (-11.0)
• Maturity 64 → 64 (+0.2)
• Readiness 59 → 62 (+2.8)
• Security 65 → 71 (+5.5)
• Event Sourcing 100 → 100 (+0.0)
• Performance 85 (new)

• Documentation: no usage examples (README.md)
• Hotspot: spotify_player/src/cli/client.rs (spotify_player/src/cli/client.rs)
• Hotspot: spotify_player/src/cli/handlers.rs (spotify_player/src/cli/handlers.rs)
• Hotspot: spotify_player/src/client/handlers.rs (spotify_player/src/client/handlers.rs)
• Hotspot: spotify_player/src/config/theme.rs (spotify_player/src/config/theme.rs)
• Hotspot: spotify_player/src/event/window.rs (spotify_player/src/event/window.rs)
• Hotspot: spotify_player/src/media_control.rs (spotify_player/src/media_control.rs)
• Hotspot: spotify_player/src/state/ui/page.rs (spotify_player/src/state/ui/page.rs)
• Off-boarding risk: anonymized user #1

• Ambiguous overlap between search and retrieval. 'search_songs' implies finding metadata/links, while 'get_lyric' implies fetching the content. However, both accept a raw string query. It is unclear if 'get_lyric' performs a search internally and then fetches, or if it expects a specific format. More critically, 'retrieve_lyric' exists which takes a URL, suggesting a separation of concerns (Search -> Retrieve) that 'get_lyric' bypasses or duplicates without clear distinction.
• Dependency hygiene PARTLY measured — Cargo dependencies read, dependency currency not (crates.io unreachable)
• Low cohesion: AppConfig (LCOM4 4) (spotify_player/src/config/mod.rs)
• Medium vulnerability: RUSTSEC-2026-0285 (Cargo.lock)
• Off-boarding risk: anonymized user #1
• Projects may be oversized for their cohesion

• 1 commits — 0 feature/other, 1 fixes

• (root) — 1 commit

• fix: Add TLS backend features (rustls-tls / native-tls) — fixes auth panic on Termux (#1060)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

aome510/spotify-player was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.