spotify_player is a fast, easy-to-use, and configurable terminal music player designed to provide a seamless Spotify experience directly from your command line.
Key Features:
Minimalist UI with an intuitive paging and popup system for navigation.
Full feature parity with the official Spotify application, including playlist management and search functionality.
Support for streaming songs directly from the terminal using librespot technology.
Synced lyrics display for enhanced listening experience.
Cross-platform media control support via MPRIS DBus on Linux and OS window event listeners on Windows and macOS.
Image rendering capabilities in terminals like Kitty and iTerm2, with optional sixel support for improved visual quality.
Audience & Benefit:
Ideal for users who value a distraction-free listening experience while maintaining full control over their Spotify library. spotify_player offers an efficient and immersive way to interact with your music directly from the terminal, eliminating the need for additional desktop applications.
The software can be installed via winget on Windows, making it easy to integrate into your workflow.
Control Spotify remotely with Spotify Connect. Press D to list devices, then enter to connect.
Streaming
Stream music directly from the terminal. The streaming feature is enabled by default and uses the rodio-backend audio backend unless otherwise specified.
The app uses librespot to create an integrated Spotify client, registering a spotify-player device accessible via Spotify Connect.
Audio backend
Default audio backend is rodio. Available backends:
alsa-backend
pulseaudio-backend
rodio-backend
portaudio-backend
jackaudio-backend
rodiojack-backend
sdl-backend
gstreamer-backend
To use a different audio backend, specify the --features option when building. For example:
For more details, run spotify_player -h or spotify_player {command} -h.
Notes
On first use, run spotify_player authenticate to authenticate the app.
CLI commands communicate with a client socket on port client_port (default: 8080). If no instance is running, a new client is started, which may increase latency.
Scripting
The command-line interface is script-friendly. Use the search subcommand to retrieve Spotify data in JSON format, which can be processed with tools like jq.
Example: Start playback for the first track from a search query:
Not all actions are available for every Spotify item. To see available actions, use ShowActionsOnCurrentTrack or ShowActionsOnSelectedItem, then press enter to trigger the action. Some actions may not appear in the popup but can be bound to shortcuts.
List of available actions:
GoToArtist
GoToAlbum
GoToRadio
AddToLibrary
AddToPlaylist
AddToQueue
AddToLiked
DeleteFromLiked
DeleteFromLibrary
DeleteFromPlaylist
ShowActionsOnAlbum
ShowActionsOnArtist
ShowActionsOnShow
ToggleLiked
CopyLink
Follow
Unfollow
Actions can also be bound to shortcuts. To add new shortcuts, see the actions section.
Search Page
When entering the search page, focus is on the search input. Enter text, use backspace to delete, and enter to search.
To move focus from the search input to other windows (track results, album results, etc.), use FocusNextWindow or FocusPreviousWindow.
Configurations
By default, configuration files are located in $HOME/.config/spotify-player. Change this with -c or --config-folder .
If no configuration file is found, one will be created with default values.
By default, cache files are stored in $HOME/.cache/spotify-player (logs, credentials, audio cache, etc.). Change this with -C or --cache-folder .
Logging
Logs are stored in $APP_CACHE_FOLDER/spotify-player-*.log. For debugging or issues, check the backtrace file in $APP_CACHE_FOLDER/spotify-player-*.backtrace.
Set the RUST_LOG environment variable to control logging level. Default is spotify_player=INFO.
