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.

Download the desktop appInstall in the terminal$curl -fsSL spotatui.com/install.sh | bash
spt - spotatuiclick to focus
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.

PlaysSpotifynative · PremiumYouTubeyt-dlp · no accountLocal filesFLAC, MP3, OGG, WAVSubsonic / Navidromeyour own serverInternet radio30,000+ stationsQobuzpaid · FLAC 24/192Apple MusicmacOS · remote for MusicSpotify optional. Four of these need no account at all.
Desktop app

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.

spotatui Desktop on an album page, with the playing track and the queue at the right
Nine visualizer styles
Nine visualizer styles
Search with albums, artists and playlists
Search with albums, artists and playlists
Listening stats from the history on your disk
Listening stats from the history on your disk

Not code-signed yet, so Windows and macOS warn on the first start.

zCross-source queue

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.

z
Queue (x remove · J/K move · Enter play · Esc back)
Now playing: SkyRadio Non-Stop - Sky Radio
Take Me Back - Kygo, Max McNown[Spotify]
Yes Ma'am - Dark Ardor[YouTube]
I'll Wait - Kygo[Qobuz]
The Nights - Avicii[Spotify]
Toothless Found - John Powell[Qobuz]
Up next from context:
Resumes: SkyRadio Non-Stop
dSource and device

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.

~78MBRAM while streaming, lyrics on
320kbpsnative stream, 96 or 160 if you ask
1binaryno Electron, no background service
CtrlJAI DJ

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.

AI DJ — claude
dj …thinking (1/4)
<Ctrl+t> auto-queue · <Ctrl+y> vibe shift · <Ctrl+o> fresh only · <Ctrl+g> AI/model · ↑↓ scroll · Enter send · Esc clear/back
Ask the DJ
▏
Everything else a player needs

Small, complete, yours.

Each of these is one key away, and each is configurable.

v

System-wide visualizer

A real-time FFT of whatever the machine is playing, drawn in the terminal.

B

Synced lyrics

Line by line from LRCLIB, for every source, with a fuzzy fallback when metadata is off.

Q

Queue and resume

Quit mid-track from a non-Spotify source and it restores the track and position next launch.

R

Local history and recap

Plays are kept as plain JSONL on your disk. spotatui history recap renders a shareable HTML page.

T

Themes and layout

Dracula, Nord, Spotify and more, or your own. Cover art in the playbar or full screen.

Alt+,

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.

spotatui plugin addExtend

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.

plugins/now-playing/main.lua
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)
shell
spotatui plugin add owner/repo
spotatui plugin list
spotatui plugin new my-plugin
Ships with these first-party examples
track-notifiertoast + playbar segment on every track change
now-playingcover art beside synced lyrics, one custom screen
track-info-popupa command that pops up the current track
accent-cyclerrotate the theme accent on demand
now-playing-webhookPOST a JSON payload whenever the track changes
session-statsa directory plugin that tracks session plays
MCP, one line
# Claude Code, Codex, or any plugin-capable agent
/plugin marketplace add LargeModGames/spotatui
/plugin install spotatui@spotatui

Over 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.

Web companion, opt-in

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.

README.md
[![Now playing on spotatui](https://spotatui.com/widget/you.svg)](https://spotatui.com)
867,933songs played through spotatui, counted anonymously
1,852GitHub stars
83contributors, plus 94 upstream
MITlicensed, a community fork of spotify-tui
Community

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.

Join the Discord

Install

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.

macos
brew tap LargeModGames/spotatui
brew install spotatui