spotify_player

Table of Contents

• Introduction
• Examples
• Installation
• Authentication
• How authentication works
• Why you may be asked to authenticate twice
• Client ID and rate limits
• Using a custom client ID
• Features
• Spotify Connect
• Streaming
• Audio Visualization
• Media Control
• Image
• Notify
• Mouse support
• Daemon
• Fuzzy search
• CLI commands
• Commands
• Configurations
• Caches
• Logging
• Acknowledgement

Introduction

spotify_player is a fast, easy to use, and configurable terminal music player.

Features

• Minimalist UI with an intuitive paging and popup system.
• Highly configurable
• Feature parity with the official Spotify application.
• Support remote control with Spotify Connect.
• Support streaming songs directly from the terminal.
• Support audio visualization.
• Support synced lyrics.
• Support cross-platform media control.
• Support image rendering.
• Support desktop notification.
• Support running the application as a daemon
• Offer a wide range of CLI commands

Examples

A demo of spotify_player v0.5.0-pre-release on youtube or on asciicast:

Checkout examples/README.md for more examples.

Installation

By default, the application's installed binary is spotify_player.

Requirements

A Spotify Premium account is required.

Dependencies

Windows and MacOS

• Rust and cargo as the build dependencies

Linux

• Rust and cargo as the build dependencies
• install openssl, alsa-lib (streaming feature), libdbus (media-control feature).

• For example, on Debian based systems, run the below command to install application's dependencies:

  shell sudo apt install libssl-dev libasound2-dev libdbus-1-dev

• On RHEL/Fedora based systems, run the below command to install application's dependencies :

  shell sudo dnf install openssl-devel alsa-lib-devel dbus-devel

  or if you're using yum:

  shell sudo yum install openssl-devel alsa-lib-devel dbus-devel

Binaries

Application's prebuilt binaries can be found in the Releases Page.

Note: to run the application, Linux systems need to install additional dependencies as specified in the Dependencies section.

Homebrew

Run brew install spotify_player to install the application.

Scoop

Run scoop install spotify-player to install the application.

Cargo

Install via Cargo:

cargo install spotify_player --locked

Arch Linux

Install via Arch Linux:

pacman -S spotify-player

Note: Defaults to PulseAudio/Pipewire. For a different backend, modify the official PKGBUILD and rebuild manually. See Audio Backends.

Void Linux

Install via Void Linux:

xbps-install -S spotify-player

FreeBSD

Install via FreeBSD:

pkg install spotify-player

NetBSD

Install via NetBSD:

pkgin install spotify-player

Build from source on NetBSD:

cd /usr/pkgsrc/audio/spotify-player
make install

NixOS

spotify-player is available as a Nix package. Install via:

nix-shell -p spotify-player

To build from source locally, run nix-shell in the root of the source checkout. The provided shell.nix will install prerequisites.

Docker

Note: The streaming feature is disabled in the Docker image.

Download the latest Docker image:

docker pull aome510/spotify_player:latest

Run the Docker container:

docker run --rm -it aome510/spotify_player:latest

To use your local config and cache folders:

docker run --rm \
-v $APP_CONFIG_FOLDER:/app/config/ \
-v $APP_CACHE_FOLDER:/app/cache/ \
-it aome510/spotify_player:latest

Authentication

spotify_player requires a Spotify Premium account and authenticates against the Spotify Web API using the OAuth 2.0 authorization code flow with PKCE. No client secret is stored or required.

The simplest way to authenticate is to just run the application — on first use it prompts for whichever credentials are not yet cached. Each prompt opens the Spotify authorization page in your browser; after you approve access, Spotify redirects to a local loopback address (login_redirect_uri, default http://127.0.0.1:8989/login) where spotify_player captures the authorization code and exchanges it for an access token. Credentials are cached in the application's cache folder, so this is a one-time step per machine.

Alternatively, run the spotify_player authenticate CLI command to authenticate both credentials up front — useful for setting things up ahead of a daemon or headless launch. Unlike a normal launch, authenticate always forces a fresh interactive login for both credentials, ignoring any cached tokens, so it can also be used to re-authenticate from scratch.

How authentication works

Two distinct credentials are involved:

• A Web API token, used for all REST calls (playback control, library, search, playlists, etc.). This is obtained through the OAuth flow above.
• A librespot session, used for the streaming feature (direct playback and Spotify Connect device registration).

Both authenticate through your Spotify account; the only thing that differs is the client ID presented to Spotify (see below).

Why you may be asked to authenticate twice

With the streaming feature enabled (the default), the first launch can open the Spotify authorization page twice — once for each credential described above, in this order:

1. The Web API token, presented under the configured client_id (ncspot's by default). This is cached as user_client_token.json.
2. The librespot session credentials, presented under Spotify's official client ID. These are cached as credentials.json.

These are two independent OAuth flows with two different client IDs, so Spotify requires a separate approval for each, and each token is cached separately in the cache folder. This is a one-time step per machine — once both tokens are cached, subsequent launches reuse and silently refresh them, and you will not be prompted again unless the cache is cleared or a token is revoked.

The spotify_player authenticate command runs both flows in one go (forcing a fresh login for each). If the streaming feature is disabled, the librespot session is not needed, so you are prompted just once (step 1).

Client ID and rate limits

Every request to the Spotify Web API is attributed to a Spotify application, identified by a client ID. The client ID — not your account — determines the API quota you are subject to.

By default, spotify_player uses ncspot's client ID. This is intentional: that client ID is registered in extended quota mode and predates Spotify's November 2024 Web API changes. As a result it has a much higher rate limit and access to endpoints (browse, personalized content, generated playlists, …) that newly-registered applications can no longer use.

[!IMPORTANT] You almost certainly should not configure your own client_id. Any application you register today starts in Spotify's restricted default quota mode. Using such a client ID commonly leads to 429 Too Many Requests and 403 Forbidden errors and missing browse/personalized data. This was the root cause of several reported issues (e.g. #890, #893, #912, #913), and switching to the bundled default client ID (#918) resolved them.

The recommended setup is to leave client_id unset so the bundled default is used.

Using a custom client ID

A custom client ID is only worthwhile if you have a specific reason — for example an application that has been granted extended quota mode by Spotify, or organizational policy requiring your own registered app.

If you do need one, register an application on the Spotify developer dashboard, add your login_redirect_uri (default http://127.0.0.1:8989/login) to the app's allowed redirect URIs, then set client_id (or client_id_command) in app.toml. See the Client id command section of the configuration docs for details.

After changing the client ID, re-run spotify_player authenticate to refresh the cached token.

Features

Spotify Connect

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:

cargo install spotify_player --no-default-features --features pulseaudio-backend

Notes:

• Use --no-default-features to disable the default rodio-backend.
• Additional dependencies may be required for some backends. See Librespot documentation.

To disable streaming, build with:

cargo install spotify_player --no-default-features

Audio Visualization

Real-time audio visualization is displayed in the playback window as a frequency-band bar chart (64 log-scale bands from bass (left) to treble (right)) while music is streamed locally via the integrated librespot player. The visualization area is hidden when playback is on an external Spotify Connect device or when the playback is not playing.

Set enable_audio_visualization to true in your config to enable this feature. See config docs.

Media Control

Media control is enabled by default. Set enable_media_control to true in your config to use it. See config docs.

Media control uses MPRIS DBus on Linux and OS window events on Windows and macOS.

Image

To enable image rendering, build with the image feature (disabled by default):

cargo install spotify_player --features image

Image rendering is powered by ratatui-image, which auto-detects the terminal's graphics protocol (Kitty, iTerm2, Sixel) on startup. Terminals without any graphics protocol support fall back to block characters.

Notes:

• Protocol detection queries the terminal via stdio. In nested terminals (e.g. Neovim's floating terminal), the query does not reach the outer terminal emulator, so the protocol falls back to block characters.

Image rendering examples:

• iTerm2:

• Kitty:

• Sixel (foot terminal):

• Others:

Pixelate

For a pixelated look, enable the pixelate feature (also enables image):

cargo install spotify_player --features pixelate

Adjust the pixelation with the `cover_img_pix