spotatui: A Terminal Player for Spotify and Other Music Sources

spotatui's Multi-Source Terminal Design

spotatui addresses a specific fragmentation problem. Spotify clients tend to center on Spotify, while local libraries, self-hosted Subsonic servers, internet radio, YouTube, and Qobuz often require separate applications. spotatui places those sources behind one terminal interface and a queue that the README says can mix tracks from them. The intended users are people who already have varied music sources and want a keyboard-driven player that runs in a terminal or terminal multiplexer.

Spotify is optional rather than mandatory. Local Files need a music folder, Subsonic or Navidrome needs a server account, internet radio needs no account, YouTube requires `yt-dlp` on `PATH`, and Qobuz needs a paid account. Spotify requires Premium because spotatui uses its own built-in login client. Apple Music is limited to macOS and the Music app. These source requirements should determine whether the apparent all-in-one interface fits a particular setup.

The repository is a Rust project built around version 0.46.0 and Rust 1.90. Its repository layout separates the terminal application, desktop application, GUI-related work, documentation, plugins, examples, and the `spotatui-librespot` integration. The result is broader than a narrow Spotify terminal client, but it also has more configuration paths and more external system dependencies.

Playback Paths Inside spotatui

Playback does not use one identical path for every source. Local Files, Subsonic, internet radio, YouTube, and Qobuz use spotatui's own audio engine. YouTube depends on the external `yt-dlp` executable, which means terminal setup alone is not enough. Apple Music follows a different model entirely: it plays in Apple's Music app, while spotatui acts as its remote.

Spotify has several documented destinations. It can play in spotatui itself, on any Spotify Connect device, or on Cast and Connect speakers on the network. Its native streaming and Spotify Connect support runs on the project's `spotatui-librespot` fork. Based on the repository layout, terminal behavior is split across Rust source modules, while the separate `desktop/` and `gui/` entries support the desktop application. The README describes that desktop app as being in preview.

Above playback, the application exposes synced lyrics, a real-time audio visualizer, search, a mixed-source play queue, listening history, statistics, and shareable recaps. It also documents playlist synchronization between Spotify, Qobuz, Subsonic, and YouTube. Lua plugins can add commands, key bindings, popups, and themes. An AI DJ and MCP interface are documented as separate extension paths rather than basic playback requirements.

Installing spotatui and Choosing the Correct Build

For macOS, Linux, and WSL, the README gives this installer command. It downloads and executes the project's `install.sh` script through a shell pipeline, so users who inspect installations before execution should review that script first.

curl -fsSL https://spotatui.com/install.sh | bash

On Windows, either PowerShell command from the README can install the application:

irm https://spotatui.com/install.ps1 | iex

The documented `winget` alternative is:

winget install spotatui

Arch Linux users can install the packaged binary with:

yay -S spotatui-bin

A Rust toolchain can install the published crate:

cargo install --locked spotatui

Build selection is a real constraint here. According to the README, prebuilt terminal binaries include every source, the MCP server, and the AI DJ. In contrast, `cargo install` builds Spotify only unless the relevant Cargo features are added, and the Nix flake also builds Spotify only. A user who chooses the Cargo route for a local Subsonic library, radio, Qobuz, or YouTube must check the installation guide's feature list before assuming those sources are present. The desktop app is distributed separately through the latest GitHub release rather than through these terminal commands.

First Launch and the spotatui Key Workflow

Start the terminal player with the same executable name as the package:

spotatui

On the first launch, spotatui asks which sources should be configured. If Spotify is selected, the application displays a code and opens Spotify's pairing page for confirmation. The README does not document an offline Spotify login flow, and it explicitly says that Spotify requires Premium.

For a real first use, press `?` to view the available keys. Press `/` to open search, use the arrow keys to choose the Songs panel, press `Enter` to enter it, and press `Enter` again to play a selected track. Press `d` to switch the current source and device. Press `z` to queue a track, then press `Shift+Q` to inspect the queue. This sequence exercises search, playback initiation, source control, and queue management rather than stopping at displaying the interface.

For shell-oriented use, the README also directs users to the command documentation:

spotatui --help

The interface is keyboard-first. That makes it suitable for an existing terminal workflow, but the documented control model also means mouse-first desktop interaction is not its primary design.

Configuration, Extensions, and Operational Constraints

Configuration extends beyond source credentials. The documentation includes dedicated files for general configuration, keybindings, themes, native Spotify streaming, playlist synchronization, AI DJ behavior, MCP setup, CLI commands, scripting, and logging. An example configuration file is available as `examples/config.example.yml`, while `examples/plugins/` demonstrates the Lua plugin area. That organization gives users concrete places to inspect rather than requiring all customization to be discovered inside the terminal interface.

Some features introduce additional dependencies. YouTube needs `yt-dlp` on `PATH`. The AI DJ and MCP workflows have their own documentation, and the prebuilt terminal binary includes them. A Spotify-only Cargo build does not automatically match the feature set of that binary. Plugins add another execution surface, so users who require plugins should read `PLUGINS.md` and `docs/scripting.md` and confirm compatibility with their installed version.

Updates add another operational decision. The README says the terminal application updates itself, but installations managed by a package manager should set `behavior.disable_auto_update: true`. This avoids two possible update authorities: the application's updater and the package manager. The desktop installer follows a separate release path, so terminal and desktop applications should not be assumed to share one update mechanism.

spotatui Compared With Apple Music App Control

Apple Music on macOS is the clearest real alternative in the project because it covers the same source without presenting it as one item in a multi-source terminal system. That alternative plays through the Music app, whereas spotatui also acts as a remote for it. The practical difference is the interface and source scope: spotatui adds terminal search, queues, keyboard controls, themes, plugins, and other providers around that integration.

This comparison exposes a boundary in spotatui's design. A user whose only need is controlling and playing an existing Apple Music library on macOS may have no reason to add a terminal client, especially if they do not want a mixed queue or a keyboard-driven interface. Conversely, the Apple Music route does not serve as evidence that every other source has identical playback capabilities inside spotatui. Local files, self-hosted servers, Spotify, YouTube, Qobuz, radio, and Apple Music follow different documented paths.

For Spotify listening, spotatui also offers alternatives within its own source model: native playback, Spotify Connect devices, and network Cast or Connect speakers. Users should choose the destination based on where audio should actually play. Installing the application does not force every track through the terminal machine's own audio engine.

Maintenance, Release Cadence, and the MIT License

The repository is not archived, and its last push was on 2026-10-16. Releases v0.44.0, v0.45.0, and v0.46.0 were published on 2026-10-11, 2026-10-12, and 2026-10-14 respectively. These dates indicate recent repository activity at the time of this review, but they do not by themselves define the upgrade burden inside a deployment.

The practical maintenance costs come from several moving parts. Spotify streaming depends on the separate `spotatui-librespot` fork. YouTube depends on the installed `yt-dlp`. The desktop app is described as a preview and has a separate installer. Plugins use a scripting API that must remain compatible with the host version. Package-managed installations also require disabling the built-in updater to prevent competing update paths. These are concrete operational considerations for someone deciding whether a single executable is sufficient.

The Cargo manifest identifies the project license as MIT. The repository includes a `LICENSE` file. Anyone redistributing code or incorporating it into another product should review that file and retain any required notices. This is a license-compliance check, not a claim about trademark rights, service terms, or the licenses of Spotify, Qobuz, YouTube, Apple Music, or server software.

Editorial conclusion

Adopt spotatui if your music spans terminal-friendly sources and you want playback, search, queues, lyrics, and source switching in one keyboard interface. Do not choose it if Apple Music on macOS is your only requirement, YouTube is mandatory without `yt-dlp`, or a stable desktop application is your first requirement. Verify first that your intended source is present in the build you install, because `cargo install` differs from the prebuilt terminal binary.

Frequently asked questions

Official sources

1. LargeModGames/spotatui on GitHub
2. License: MIT
3. Project website
4. README
5. Releases