# spotify-player: a full Spotify client inside your terminal

> spotify_player is a Rust TUI for Spotify Premium accounts, with streaming, Spotify Connect control, synced lyrics and image rendering. It is a serious client, but authentication and audio backends are where new users get stuck.

**aome510/spotify-player** — A Spotify player in the terminal with full feature parity

- Repository: https://github.com/aome510/spotify-player
- Stars: 7,244 · Forks: 389
- Language: Rust
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/aome510-spotify-player

## What spotify_player actually replaces

The README describes spotify_player as "a fast, easy to use, and configurable terminal music player" and claims feature parity with the official Spotify application. Read that claim carefully. Parity here means the command surface and the Connect surface, not the desktop app's window chrome. The project targets people who keep a terminal open all day and would rather type a search than alt-tab to a GUI. It also targets a second group: users on machines where the official client does not exist or behaves badly, which is why the README carries install instructions for Arch, Void, FreeBSD, NetBSD, Termux on Android and NixOS. A Spotify Premium account is required. That single sentence rules out free-tier accounts for playback, and it is stated as a requirement rather than a limitation, so treat it as a hard gate.

## How the client is put together

The repository is a Cargo workspace whose only member is spotify_player, with a separate lyric_finder directory at the top level. That split matters: lyrics are fetched by their own component rather than folded into the player crate. Authentication uses the OAuth 2.0 authorization code flow with PKCE against the Spotify Web API, and the README states plainly that no client secret is stored or required. The flow is loopback-based. On first use the app prompts for missing credentials, opens the Spotify authorization page, and Spotify redirects to login_redirect_uri, which defaults to http://127.0.0.1:8989/login, where the code is captured and exchanged for a token. Credentials land in the cache folder, so the browser round trip happens once per machine. Playback is split across two paths. Spotify Connect lets the app act as a remote control for another device, and the streaming feature plays audio locally through librespot. Those are different failure domains, and the README treats them separately, including a note that integrated streaming on Termux needs a librespot patch. The workspace lints deny unsafe_code and set clippy pedantic to deny, which tells you the maintainers hold the crate to a strict lint bar.

## Installing spotify_player on Debian, Arch and Cargo

Pick the path that matches your system. On Debian-based Linux the README lists the build dependencies as openssl, alsa-lib and libdbus, installed with the command below. The alsa-lib package is needed for the streaming feature and libdbus for media-control, so omitting them produces a build that cannot do those things.

```bash
sudo apt install libssl-dev libasound2-dev libdbus-1-dev
```

On Arch the package is already built, and the README notes it defaults to PulseAudio/Pipewire. If you use a different backend, the official PKGBUILD has to be modified and rebuilt by hand. Cargo works everywhere Rust does. The --locked flag is in the README and should stay, since it pins dependency versions to the committed lockfile.

```bash
cargo install spotify_player --locked
```

```bash
pacman -S spotify-player
```

## First run and the loopback login

First run is the real test. The binary is spotify_player. Launching it starts the credential prompts described above, and after you approve access in the browser, Spotify redirects to the loopback address on port 8989. If something else already holds that port, the redirect fails and the app cannot capture the code. The README's alternative is the authenticate subcommand, which forces fresh interactive logins and ignores cached credentials. That is the right call before starting a daemon or a headless session, because you want the token in the cache before there is no browser in front of you.

```bash
spotify_player
```

```bash
spotify_player authenticate
```

## The Premium wall and the Termux trap

The most concrete limitation is the one the README states up front: a Spotify Premium account is required. There is no free-tier mode documented. The second is platform-specific and easy to miss. On Termux the README says two default components need a JVM context that Termux processes lack: the default TLS backend, rustls-platform-verifier, panics during the auth token exchange, and the rodio audio backend, cpal's AAudio host, panics when streaming starts. The documented workaround is a rebuild with --no-default-features and the pulseaudio-backend, media-control and native-tls features, which restores authentication, the Web API and remote device control.

```bash
pkg install rust openssl pulseaudio
cargo install spotify_player --no-default-features --features pulseaudio-backend,media-control,native-tls
```

Integrated streaming on Termux additionally requires patching librespot's compile-time OS identity to "linux", because a librespot built for target_os = "android" presents an Android-app identity that Spotify rejects for keymaster-minted credentials. That is a source patch, not a flag, and it is the clearest case where spotify_player is the wrong tool unless you are willing to maintain a fork. The Docker image carries its own gap: the README states the streaming feature is disabled in it, so the container is a remote control and browsing client, not a local player.

## spotify_player against ncspot

The search data pairs spotify_player with ncspot, and the architectural difference is worth stating. ncspot is a terminal client that plays audio through librespot directly. spotify_player does that too, but it also implements a Spotify Connect device, so it can drive playback on a phone, a speaker or another computer while showing the queue and controls in the terminal. The README lists Spotify Connect, streaming, audio visualization, media control, desktop notification, image rendering, a daemon mode and a wide range of CLI commands as separate features. If your only goal is playing music on the machine you are sitting at, the extra Connect surface buys you nothing. If you want the terminal to be the control plane for whatever device is actually producing sound, that is the reason to pick this one. The daemon feature pushes the same distinction further: it lets the client keep running in the background and accept CLI commands, which is a workflow ncspot does not present in the same shape.

## Config, caches, licence and what to check before adopting

Configuration lives in a config folder and is documented in docs/config.md, with examples/app.toml and examples/theme.toml in the repository as starting points. Credentials and other state live in the cache folder, which is why the Docker instructions mount $APP_CONFIG_FOLDER and $APP_CACHE_FOLDER into /app/config/ and /app/cache/. The Dockerfile is built from the distroless cc image and runs the binary with -c ./config and -C ./cache, so those two paths are the contract. The licence is MIT, which is permissive and places few obligations on you beyond retaining the copyright notice; the README also credits upstream projects, and if you redistribute a binary you should read the full LICENSE file rather than rely on that summary. Maintenance signals are current: the last push was on 2026-09-19, and v0.25.1 shipped on 2026-09-09. The upgrade cost is low if you install through a package manager, and moderate if you build from Cargo, where --locked keeps the dependency graph stable between upgrades. The thing to verify first is not the feature list. It is whether the loopback redirect on port 8989 works on the machine that will run the client, and whether your audio backend matches the one the package was built against.

## Conclusion

Adopt spotify_player if you already live in a terminal and hold a Spotify Premium account, especially on Arch, Void, FreeBSD or NetBSD where a package exists. Skip it if you need offline playback or a non-Premium account, since the README requires Premium and the Docker image ships with streaming disabled. Before committing, run spotify_player authenticate on the machine you plan to use as a daemon and confirm the login_redirect_uri port 8989 is free, because that loopback address is where the OAuth code is captured.

## FAQ

### What is spotify_player?

It is a terminal music player written in Rust that authenticates against the Spotify Web API and aims for feature parity with the official Spotify application. The README lists Spotify Connect, streaming, synced lyrics, image rendering and a daemon mode among its features.

### How do I install spotify_player on Linux?

On Debian-based systems the README installs libssl-dev, libasound2-dev and libdbus-1-dev first, then builds with cargo install spotify_player --locked. Arch users run pacman -S spotify-player, and the README notes that package defaults to PulseAudio/Pipewire.

### How do I use spotify_player in a terminal?

Run the spotify_player binary. On first use it prompts for the credentials it does not have cached, opens the Spotify authorization page in your browser, and captures the redirect at http://127.0.0.1:8989/login. The README also offers spotify_player authenticate to force fresh logins ahead of a daemon or headless launch.

### Why is spotify_player not working?

Two documented causes stand out. Authentication needs the loopback redirect on login_redirect_uri, default http://127.0.0.1:8989/login, so a busy port breaks the exchange, and the README requires a Spotify Premium account. On Termux the default TLS and audio backends panic, and the documented fix is a rebuild with native-tls and the pulseaudio backend.

## Sources

- [aome510/spotify-player on GitHub](https://github.com/aome510/spotify-player)
- [Issues](https://github.com/aome510/spotify-player/issues)
- [License: MIT](https://github.com/aome510/spotify-player/blob/master/LICENSE)
- [README](https://github.com/aome510/spotify-player/blob/master/README.md)
- [Releases](https://github.com/aome510/spotify-player/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aome510-spotify-player