v0.41RustmacOS · Linux · Windows
All your music.One queue.In the terminal.
spotatui plays Spotify natively and streams YouTube, your local files, Subsonic or Navidrome and 30,000+ internet radio stations from a single keyboard-driven player. 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 five integrations and one player. See every source.
Spotify plays inside spotatui.
No 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. Premium is required for Spotify. Everything else is free.
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 same tools are 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 free 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, columns, icons and format templates are all configurable. A typo never blocks startup.
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_changed", function(t)
spotatui.notify(t.artist .. " - " .. t.title)
end)
spotatui.command("accent_cycle", function()
spotatui.set_accent(next_color())
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@spotatuiPlugins 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.
brew tap LargeModGames/spotatui
brew install spotatui