Bring Spotify into your terminal — without sacrificing features
Ever wished you could control Spotify from the comfort of your terminal, with fast keyboard shortcuts, streaming, synced lyrics and even images? spotify_player is a Rust-based terminal music player that aims to deliver near feature parity with the official Spotify client while staying lightweight and configurable.
Note: A Spotify Premium account is required to use spotify_player.
What It Does
spotify_player provides a fast, minimalist terminal UI for interacting with Spotify. It is designed to be configurable and feature-rich while keeping a keyboard-focused experience. The project solves the pain of switching contexts between GUI apps and your terminal workflow by bringing Spotify functionality directly into the TTY.
Core functionality and problems it solves
- Stream music directly from Spotify inside your terminal (optional streaming feature).
- Control playback, volume, seeking and device switching.
- Browse playlists, albums, artists, saved items, and search Spotify with keyboard-driven pages and popups.
- Render album art as full-resolution images in capable terminals (Kitty, iTerm2) or as block characters otherwise.
- Run as a background daemon and expose a CLI for scripting and automation.
- Offer desktop notifications, MPRIS/OS media-control integration and fuzzy search support (feature-gated).
Who It’s For
spotify_player is aimed at developers, power users, and anyone who spends much of their day in the terminal and prefers keyboard control over GUI applications. Typical users include:
- Developers who want uninterrupted terminal workflows while controlling Spotify.
- System administrators and remote workers who use TTY-first environments.
- Users who enjoy customizing keymaps, themes and advanced feature flags.
Skill-level: basic knowledge of the terminal and installing packages is sufficient. Some advanced features (custom audio backends, daemon mode, or user-provided Spotify client integration) may require familiarity with building Rust crates or editing configuration files.
How It Works
The project is written in Rust and composes several strong community libraries to deliver functionality:
- UI: ratatui-based minimalist terminal interface with paging and popup system.
- Spotify API client: rspotify for API interactions and authentication flows.
- Streaming: librespot is used to create an integrated Spotify client to stream audio directly and register a “spotify-player” device for Spotify Connect.
- Audio backends: rodio is the default backend, but other backends (ALSA, PulseAudio, PortAudio, JACK, SDL, GStreamer, etc.) are supported via feature flags.
- Media control & notifications: MPRIS DBus on Linux and OS event listeners on Windows/macOS (feature gated).
Features are enabled or disabled at build/install time using Cargo feature flags, so you can tailor the binary precisely for your environment and needs.
Getting Started
The repository provides prebuilt binaries and supports many package managers. If you prefer to build from source with specific features, follow the examples below. If a configuration file is missing, spotify_player will create one with sensible defaults in $HOME/.config/spotify-player.
Install prerequisites on Debian/Ubuntu
sudo apt install libssl-dev libasound2-dev libdbus-1-dev
Install prerequisites on Fedora/RHEL
sudo dnf install openssl-devel alsa-lib-devel dbus-devel
# or using yum
sudo yum install openssl-devel alsa-lib-devel dbus-devel
Install with Cargo (default)
# Install the default binary (streaming & rodio-backend enabled by default)
cargo install spotify_player --locked
Install with a different audio backend (example: PulseAudio)
# Replace default features to select a specific backend
cargo install spotify_player --no-default-features --features pulseaudio-backend
Disable streaming
cargo install spotify_player --no-default-features
Enable image rendering
cargo install spotify_player --features image
Enable sixel images or pixelate style
# Sixel image support (also enables image)
cargo install spotify_player --features sixel
# Pixelated artwork
cargo install spotify_player --features pixelate
Run via Docker (streaming disabled)
docker pull aome510/spotify_player:latest
docker run --rm -it aome510/spotify_player:latest
# Use local config/cache when running the container
docker run --rm \
-v $APP_CONFIG_FOLDER:/app/config/ \
-v $APP_CACHE_FOLDER:/app/cache/ \
-it aome510/spotify_player:latest
Examples: scripting with the CLI
The CLI is JSON-friendly, so you can combine it with tools like jq for automation:
read -p "Search spotify: " query
spotify_player playback start track --id $(spotify_player search "$query" | jq '.tracks.[0].id' | xargs)
Key Features
- Spotify Connect support via a user-provided client_id and OAuth redirect (configure
login_redirect_uriashttp://127.0.0.1:8989/login). - Streaming through librespot to register an integrated speaker and play directly from the terminal.
- Multiple audio backends selectable with Cargo features (rodio, pulseaudio, alsa, etc.).
- Image rendering for album art in high-resolution terminals (Kitty, iTerm2) and block-character fallbacks.
- Daemon mode for background playback (feature-gated, not supported on Windows).
- Media-control & notifications via MPRIS on Linux and OS event hooks on macOS/Windows.
- Extensible CLI with subcommands like get, playback, search, connect, like, playlist and more.
Why It’s Worth Trying
spotify_player brings a near-complete Spotify experience to the terminal while allowing you to customize exactly which capabilities are included in your build. If you value speed, keyboard-driven interfaces, and the ability to script and automate your music workflow, spotify_player checks those boxes.
Built on top of strong libraries: ratatui, rspotify, librespot and others — inspired by projects like spotify-tui and ncspot.
Documentation and examples are included in the repository, and prebuilt binaries are available on the project’s Releases Page. If you prefer packaged installs, the project supports Homebrew, Scoop, Arch, Void, FreeBSD, NetBSD and NixOS.
Community metrics (GitHub stars, contributors, issue activity) were not provided in the supplied text; check the repository for up-to-date community information and release notes.
GitHub Link
The official repository and additional documentation (including configuration docs) are available on GitHub. The official link is bellow:
https://github.com/aome510/spotify-player
Final Thoughts
spotify_player is a flexible, feature-rich terminal Spotify client that caters to users who prefer TTY workflows without losing the capabilities of a full Spotify client. With streaming support via librespot, multiple audio backends, image rendering, daemon mode, and a powerful CLI, it’s a strong choice for developers and power users. If you rely on keyboard shortcuts, like to script your environment, or want to avoid context switching to a GUI music player — give spotify_player a try.
For configuration details, see the repository documentation and the configuration guide. If you run into issues, check the logs in your cache folder: $HOME/.cache/spotify-player.