# spotatui

> spotatui is a free, open-source (MIT) terminal music player written in Rust with Ratatui. It streams Spotify natively (no spotifyd, no Spotify desktop app) and also plays YouTube, local files, Subsonic/Navidrome servers, internet radio and Qobuz in one cross-source queue. On macOS it can also control the Music app as an Apple Music source. Spotify is optional: every other source works with no Spotify account or Premium. It runs on Linux, macOS and Windows. It is the actively maintained fork of spotify-tui, which has had no release since 2021.

Key facts:

- Install: `curl -fsSL https://spotatui.com/install.sh | bash` (macOS, Linux, WSL), `irm https://spotatui.com/install.ps1 | iex` or `winget install spotatui` (Windows), `brew tap LargeModGames/spotatui && brew install spotatui` (macOS), `.deb` packages for Debian/Ubuntu (amd64, arm64) and a Linux ARM64 archive on GitHub Releases, `cargo install --locked spotatui` (Rust 1.90 or newer; add `--features local-files,subsonic,internet-radio,youtube,qobuz` for the non-Spotify sources, plus `apple-music` on macOS), AUR (`spotatui-bin`, `spotatui`), or the Nix flake `github:LargeModGames/spotatui`.
- Updates: the terminal UI checks GitHub Releases at start, verifies the download against its checksum, installs it and restarts. Set `disable_auto_update: true` under `behavior:` in `config.yml` when a package manager owns the install.
- Desktop app (preview): spotatui also comes as a desktop app for Windows, macOS and Linux, with a Spotify-style layout (Your Library, Home, album, artist and lyrics pages, a queue panel, a device picker). It shares the login, settings and history of the terminal app, and only one of the two runs at a time. The preview plays Spotify only (Premium). GitHub Releases carries a Windows installer, macOS .dmg files (Apple Silicon, Intel) and Linux .deb, .rpm and .AppImage packages (amd64, arm64). The installers are not code-signed yet, so SmartScreen and Gatekeeper warn on the first start. On Linux it needs glibc 2.39 and WebKitGTK 4.1 (Ubuntu 24.04+, Debian 13, Fedora 40+, Arch). Installed from the Windows installer, the macOS app or the AppImage, it updates itself from signed releases; a .deb or .rpm install updates with a new download. `spotatui mcp` is only in the terminal binary.
- Spotify setup: no Spotify developer app or client ID is needed. spotatui shows a code and opens Spotify's pairing page in the browser; you confirm the code once and the login is cached (`spotatui --reconfigure-auth` logs in again). Spotify in spotatui requires a Premium account: the login refuses a free account. spotatui uses its own Spotify session, so per-app API rate limits do not apply, and Spotify's own playlists in your library (Release Radar, daylist) show up in the sidebar.
- Other sources: YouTube (via yt-dlp), local files, Subsonic/Navidrome and internet radio are free. Qobuz needs a paid Qobuz account. Apple Music (macOS only) plays through the Music app with your own Apple Music login.
- Features: synced lyrics, real-time audio visualizer, cross-source play queue, playlist sync across services, Lua plugins, a scriptable CLI, local listening history with shareable recaps, Discord Rich Presence, themes, about 78 MB RAM while streaming.
- Optional AI DJ (Ctrl+J): a conversational DJ that reads local listening history and queues tracks. It can use an agent CLI (claude, codex, agy, copilot, opencode), the Anthropic API, or any OpenAI-compatible endpoint including local Ollama or LM Studio models.
- MCP server: spotatui exposes the player and your listening history as MCP tools, so Claude Code, Codex or another MCP client can act as the DJ with no API key. For Spotify, an agent can also list your playlists and Connect devices, move playback to a device, create a playlist, add or remove tracks, like or unlike tracks and follow artists. Removing a track is marked destructive, so the client asks you first. The release binaries include the MCP server; a cargo build needs `--features mcp-server`.
- Bug reports: run `spotatui --debug` and attach the log. spotatui prints the log path when it starts and when it quits. Tokens and request headers are never logged, but read the log before posting it.
- Migrating from spotify-tui: copy `~/.config/spotify-tui/` to `~/.config/spotatui/`; the binary is `spotatui` instead of `spt`.
- Compared with other terminal Spotify clients: spotify-player and ncspot are maintained Spotify-only clients that require Premium. spotatui is the pick when you want Spotify plus other music sources in one terminal player, or no Premium at all.

## Docs

- [Install](https://spotatui.com/install): every install method, the first-run setup and the desktop app
- [Music sources](https://spotatui.com/sources): Spotify, YouTube, local files, Subsonic/Navidrome, internet radio, Qobuz, Apple Music (macOS)
- [AI DJ](https://spotatui.com/dj): how the DJ works and which models it can use
- [Scripting](https://spotatui.com/scripting): the Lua plugin API and CLI automation
- [README](https://github.com/LargeModGames/spotatui/blob/main/README.md): full documentation, configuration and keybindings

## Comparisons

- [spotatui vs spotify-player vs ncspot vs spotify-tui](https://spotatui.com/compare): side-by-side table and which one to pick
- [spotify-tui alternative](https://spotatui.com/spotify-tui-alternative): what changed in the fork and how to migrate
- [Spotify terminal client](https://spotatui.com/spotify-terminal-client): playing Spotify from the terminal on Linux, macOS and Windows

## Optional

- [GitHub repository](https://github.com/LargeModGames/spotatui)
- [Releases](https://github.com/LargeModGames/spotatui/releases)
- [Español](https://spotatui.com/es)