v0.45RustmacOS · Linux · Windows
All your music.One queue.In the terminal.
spotatui plays Spotify natively and streams YouTube, your local files, Subsonic or Navidrome, Qobuz and 30,000+ internet radio stations from a single keyboard-driven player. On macOS it also drives Apple Music. Spotify is optional. So is the AI DJ.
curl -fsSL spotatui.com/install.sh | bashWelcome to spotatui! Choose your music sources: You can add or switch sources anytime from the `d` menu. > [ ] Spotify (needs login) [ ] YouTube (free, needs the yt-dlp binary) [ ] Subsonic (free, needs a Subsonic/Navidrome server) [ ] Internet Radio (free) [ ] Local Files (free) [ ] Qobuz (paid subscription, logs in through the browser) ↑/↓ move · space select · enter confirm · esc skip
live The radio is real: Z100, KEXP, NPR, SomaFM and more stream into your browser, and the bars are a real FFT of it; YouTube plays through its own player. Click the terminal, then press ? for the keys.
Press z on anything, anywhere.
A radio station, a YouTube result, an album on your Navidrome server, a Spotify playlist: z puts it in the same queue. It plays in order across sources with the same keys, volume and visualizer, and your context resumes when it runs out.
That is the difference between six integrations and one player. Apple Music on macOS plays through the Music app and stays out of the queue. See every source.
Spotify plays inside spotatui.
No Spotify desktop app, no spotifyd, no Connect device to babysit. spotatui streams Spotify itself and shows up as its own Connect device, with media keys, MPRIS on Linux and Now Playing on macOS.
It runs on a librespot fork we maintain, so fixes for Spotify's changing audio delivery ship in spotatui releases instead of waiting upstream. Logging in is a code you confirm on Spotify's own page, with no developer app, no client ID and no per-app rate limits. Spotify's own playlists, such as Release Radar and daylist, show up with the rest of your library. Premium is required for Spotify. Everything else is free.
Prefer a window? There is a desktop app.
The same player in its own window, laid out like the Spotify desktop client: Your Library on the left, Home, album, artist and lyrics pages in the middle, the playing track and the queue on the right, and a player bar with a device picker. Every song row has a heart and a menu to add it to a playlist or the queue.
It shares the login, settings and history of the terminal app. The preview plays Spotify only, so it needs Premium, and it updates itself from signed releases. Install the desktop app.
| Windows | 10/11 installer, 64-bit |
|---|---|
| macOS | .dmg for Apple Silicon and Intel |
| Linux | .deb, .rpm and .AppImage, amd64 and arm64 |
Not code-signed yet, so Windows and macOS warn on the first start.
A DJ that asks before it plays.
Tell it what you are in the mood for. It reads the listening history spotatui keeps on your machine, searches the catalogue, and queues what it finds, or asks a question first.
Bring your own brain: the agent CLI you already pay for (claude, codex, copilot, opencode), an API key, or a local model through Ollama or LM Studio, in which case nothing leaves the machine.
Only aggregate artist and track names ever reach a model. No identifiers, no timestamps, no account. The DJ's tools are also exposed over MCP, so Claude Code or Codex can DJ from your editor. How the DJ works.
Small, complete, yours.
Each of these is one key away, and each is configurable.
System-wide visualizer
A real-time FFT of whatever the machine is playing, drawn in the terminal.
Synced lyrics
Line by line from LRCLIB, for every source, with a fuzzy fallback when metadata is off.
Queue and resume
Quit mid-track from a non-Spotify source and it restores the track and position next launch.
Local history and recap
Plays are kept as plain JSONL on your disk. spotatui history recap renders a shareable HTML page.
Themes and layout
Dracula, Nord, Spotify and more, or your own. Cover art in the playbar or full screen.
Settings in-app
Keys, icons and themes in Settings; table columns (including an optional release year) and format templates in config.yml. Most invalid values fall back to the default with a warning.
Extend it in Lua. Drive it over MCP.
Plugins react to playback, add commands and keys, draw popups and whole screens, and make HTTP requests, through a small curated API. A plugin is a git repo with a main.lua. The scripting API.
spotatui.require_api(6)
spotatui.on("track_change", function(pb)
if pb and pb.track then
spotatui.notify(pb.track.name .. " - " .. table.concat(pb.track.artists, ", "))
end
end)
local accents, i = { "Magenta", "Cyan", "Green" }, 0
spotatui.register_command("cycle_accent", function()
i = (i % #accents) + 1
spotatui.set_theme({ selected = accents[i] })
end)spotatui plugin add owner/repo
spotatui plugin list
spotatui plugin new my-plugin| track-notifier | toast + playbar segment on every track change |
|---|---|
| now-playing | cover art beside synced lyrics, one custom screen |
| track-info-popup | a command that pops up the current track |
| accent-cycler | rotate the theme accent on demand |
| now-playing-webhook | POST a JSON payload whenever the track changes |
| session-stats | a directory plugin that tracks session plays |
# Claude Code, Codex, or any plugin-capable agent
/plugin marketplace add LargeModGames/spotatui
/plugin install spotatui@spotatuiOver MCP an agent can also work with your Spotify library: create playlists, add or remove tracks, like tracks, follow artists and move playback to another device. The in-app DJ does not get those tools.
Plugins run with spotatui's own privileges. Install ones whose source you have read or whose author you trust.
Show what you're playing, if you want to.
Create an account, paste the sync token into Settings, and your current track becomes a live card for your GitHub README. Turn on the rest when you feel like it: listening stats, friends, leaderboards.
Nothing is uploaded until you paste that token. Web companion.
Hang out in the spotatui Discord.
Install help, themes and Lua plugins, release news, feature requests, and a shared playlist you add to with /queue. It is the fastest way to reach the maintainers and other people running spotatui.
Ready in one command.
On first launch spotatui asks which source you want. Pick a free one and you never see a Spotify login. Pick Spotify and you confirm a code on Spotify's pairing page, with no developer app or client ID. Spotify needs Premium.
brew tap LargeModGames/spotatui
brew install spotatui