v0.48RustmacOS · Linux · Windows
All your music.One queue.Desktop or terminal.
spotatui plays Spotify natively and streams YouTube, your local files, Subsonic or Navidrome, Qobuz and 30,000+ internet radio stations from a single player, in a desktop window or in your terminal. Spotify signs in with one pairing code, with no developer app and no client ID. On macOS it also drives Apple Music. Spotify is optional. So is the AI DJ.
Welcome 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.
The same player, in a window.
spotatui Desktop is 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. It plays the same sources as the terminal app, and it shares the login, settings and history.
Download the desktop app for Windows, macOS or Linux. It updates itself from signed releases.
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.
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


