spotatui

一款使用 Rust 编写、由 Ratatui 驱动的终端音乐播放器。
支持 Spotify 原生流媒体播放、同步歌词、实时音频可视化，以及本地文件、Subsonic/Navidrome、网络电台、YouTube 和 Qobuz 音乐源；在 macOS 上还支持 Apple Music。Spotify 并非必需。

这是一个由社区维护、积极开发的 spotify-tui 分支，目前已在多个方面与上游项目有所不同。

主要区别	spotify-tui	spotatui
Spotify 后端	外部 Connect 设备（spotifyd、官方客户端等）	内置原生客户端
音乐源	Spotify	Spotify、YouTube、本地文件、Subsonic、Navidrome、网络电台、Qobuz、Apple Music（macOS）

• 多音乐源，Spotify 可选。 可播放 Spotify、本地文件、Subsonic/Navidrome 服务器、网络电台、YouTube、Qobuz 或 macOS 上的 Apple Music。免费音乐源无需 Spotify 账号；随时按 d 切换。
• 原生流媒体播放。 直接播放 Spotify 音频，无需官方应用或 spotifyd；spotatui 本身会显示为一个 Spotify Connect 设备（需要 Premium）。
• 同步歌词。 歌词逐行跟随播放进度。
• 实时音频可视化。 系统级 FFT 可视化工具（按 v）会响应正在播放的音频；对于 Spotify 曲目，还提供原版 spotify-tui 的音高视图。
• 跨音乐源播放队列。 在任意曲目上按 z 即可加入队列；队列会跨音乐源播放，然后恢复当前播放上下文。
• 播放列表同步。 将一个播放列表设为主列表，并镜像到 Spotify、Qobuz、Subsonic 或 YouTube。同步在启动时运行，也可通过 spotatui sync 运行。
• Lua 插件。 使用事件钩子、命令、快捷键、弹窗和主题扩展 spotatui。
• 收听历史与回顾。 spotatui 在本地保存播放历史，还可生成可分享的 HTML 回顾（spotatui history recap）。
• 完整 CLI。 界面中的大多数操作都可编写脚本，包括播放、搜索、播放列表和 shell 补全。运行 spotatui --help 查看。
• 轻量。 流媒体播放时内存占用约 78 MB，相比之下完整的 Electron 客户端更为庞大。参见性能部分。

Spotify 可选。 首次启动时，spotatui 会询问你想使用哪个音乐源。YouTube、Subsonic/Navidrome、网络电台、本地文件、Qobuz 和 Apple Music（macOS）均无需 Spotify 账号。只有 Spotify 音乐源需要 Spotify Premium；你可以随时从 d 菜单添加。

sh

One-line installer — macOS, Linux, WSL. Grabs the prebuilt binary for your

system, verifies its checksum, and puts spotatui on your PATH. No Rust needed.

curl -fsSL https://spotatui.com/install.sh | bash

Homebrew (macOS only)

brew tap LargeModGames/spotatui brew install spotatui

Cargo — compile from crates.io …

cargo install --locked spotatui

… or fetch the prebuilt binary without compiling

cargo binstall spotatui

Arch Linux (AUR) — prebuilt binary (faster)

yay -S spotatui-bin

…or build from source

yay -S spotatui

Void Linux (unofficial repo)

echo repository=https://raw.githubusercontent.com/Event-Horizon-VL/blackhole-vl/repository-x86_64 | sudo tee /etc/xbps.d/20-repository-extra.conf sudo xbps-install -S spotatui

One-line installer — Windows PowerShell

irm https://spotatui.com/install.ps1 | iex

…or via Winget

winget install spotatui

NixOS (Flake, recommended for NixOS)

Add spotatui to your flake inputs:

inputs = { spotatui = { url = "github:LargeModGames/spotatui"; inputs.nixpkgs.follows = "nixpkgs"; }; }

Add the spotatui package from your inputs to your config:

{ inputs, ...}:{

Your other configurations

environment.systemPackages = with pkgs; [ inputs.spotatui.packages.${pkgs.stdenv.hostPlatform.system}.default ]; }

Flake 会处理所有依赖项，但音频后端仍需自行设置。如果使用 ALSA：

nix hardware.alsa.enable = true;

如果使用 PipeWire：

nix services.pipewire = { enable = true; alsa.enable = true; #your other settings };

该 Flake 提供 x86_64-linux、aarch64-linux 和 aarch64-darwin 构建。nixpkgs 26.11 已不再支持 Intel Mac（x86_64-darwin），因此这些设备请使用 Homebrew formula、一行安装脚本或下方的发行版 tarball。

也可以从 GitHub Releases 下载预构建二进制文件。

哪些构建包含哪些音乐源？ Linux、macOS 和 Windows 的预构建二进制文件（一行安装脚本、GitHub Releases 和 cargo binstall）以及桌面应用，均包含额外音乐源：本地文件、Subsonic、网络电台、YouTube 和 Qobuz；macOS 版本还包含 Apple Music。YouTube 需要安装 yt-dlp（建议同时安装 ffmpeg）。直接运行 cargo install --locked spotatui 不会启用这些音乐源；请使用 --features local-files,subsonic,internet-radio,youtube,qobuz 启用（macOS 上再添加 apple-music）。

有关各平台的具体要求和从源码构建的方法，请参阅安装 Wiki。

spotatui 也提供桌面应用：同一款播放器运行在独立窗口中，采用 Spotify 风格布局，包括首页、专辑和艺术家页面、音乐库及歌词。它与终端应用共用登录信息、设置和历史记录，两者同一时间只能运行一个。关闭窗口即退出应用。

预览版支持 Spotify（需要 Premium）、本地文件、Subsonic、网络电台、YouTube 和 Qobuz，macOS 上还支持 Apple Music。与终端应用一样，YouTube 需要安装 yt-dlp（建议同时安装 ffmpeg）。通过 Windows 安装程序、macOS 应用或 AppImage 安装后，应用会自动更新；通过 .deb 或 .rpm 安装的版本需要从 GitHub Releases 下载新版本更新。behavior.disable_auto_update 和 behavior.auto_update_delay 设置可控制更新，也可在应用的设置页面中调整。

系统	文件
Windows 10/11（64 位）	spotatui-desktop_<version>_x64-setup.exe
macOS，Apple Silicon	spotatui_<version>_aarch64.dmg
macOS，Intel	spotatui_<version>_x64.dmg
Debian/Ubuntu	spotatui-desktop_<version>_amd64.deb 或 _arm64.deb
Fedora	spotatui-desktop-<version>-1.x86_64.rpm 或 .aarch64.rpm
其他 Linux	spotatui-desktop_<version>_amd64.AppImage 或 _aarch64.AppImage

安装程序尚未签名，因此系统在首次启动时会发出警告：

• Windows： SmartScreen 会提示“Windows 已保护你的电脑”。点击更多信息，然后点击仍要运行。
• macOS： 首次打开时，macOS 会拒绝启动应用。关闭对话框，打开系统设置 > 隐私与安全性，在 spotatui 提示旁点击仍要打开并确认。如果 macOS 提示应用已损坏，请运行一次 xattr -dr com.apple.quarantine /Applications/spotatui.app。

在 Linux 上，应用需要 glibc 2.39 和 WebKitGTK 4.1（webkit2gtk-4.1）：支持 Ubuntu 24.04 或更新版本、Debian 13、Fedora 40 或更新版本以及 Arch。如果在使用 NVIDIA GPU 的 Wayland 环境中窗口一直空白，请使用 GDK_BACKEND=x11 spotatui-desktop 启动。除非你自行设置，否则应用会自动设置 WEBKIT_DISABLE_DMABUF_RENDERER=1。

如需让编程 Agent 通过 MCP 控制桌面应用，还须安装终端版 spotatui：Agent 会启动 spotatui mcp，而该命令仅存在于终端二进制文件中。

运行 spotatui。首次启动时，程序会询问要设置哪个音乐源：

text Welcome to spotatui! Choose your music source:

1. Spotify (needs login)
2. YouTube (free, needs the yt-dlp binary)
3. Subsonic (free, needs a Subsonic/Navidrome server)
4. Internet Radio (free)
5. Local Files (free)
6. Qobuz (paid subscription, logs in through the browser)
7. Apple Music (macOS Music app, needs Automation permission)

选择免费音乐源即可完全跳过 Spotify；也可以选择 Spotify 登录：spotatui 会显示一个代码，并在浏览器中打开 Spotify 配对页面，供你确认代码。无需开发者应用或客户端 ID。Spotify 需要 Premium 账号。列表中只会显示当前构建中已编译的音乐源。进入应用后：

• 按 ? 打开应用内帮助菜单，查看所有按键操作。
• 按 d 打开音乐源与设备选择器，切换音乐源。
• 在曲目上按 z 将其加入队列；按 Shift+Q 打开队列。
• 运行 spotatui --help 查看 CLI。所有快捷键请参阅快捷键 Wiki。

使用默认按键搜索并播放结果的方法：

1. 按 /，输入搜索词，再按 Enter 提交。Ctrl+L 可清除已有查询。
2. 使用方向键选择歌曲结果面板，按 Enter 将焦点移至其列表。
3. 使用 Up/Down 选择曲目，再按 Enter 播放。Space 切换播放/暂停。

选择结果面板本身不会开始播放。

以下是几个 CLI 入门示例：

sh spotatui --completions zsh # Shell completions (bash, powershell, and more supported) spotatui play --name "Your Playlist" --playlist --random # Play a random song from a playlist spotatui playback --toggle # Play/pause current playback spotatui list --liked --limit 50 # List your liked songs spotatui history recap --period 30d --output ./recap.html # Generate a shareable listening recap

先选择了免费音乐源，之后又想使用 Spotify？按 d 打开音乐源与设备选择器。如果焦点位于设备面板（包括显示“未找到设备”时），按 Tab 将焦点移至音乐源，选择 Spotify 并按 Enter。Spotatui 会在状态栏显示配对代码，并打开浏览器登录，无需重启。浏览、播放列表和控制其他设备的功能会立即可用。原生（librespot）流媒体播放仍需重启，因为它随应用启动。

spotatui 是一款通用音乐播放器，而不仅仅是 Spotify 客户端。按 d 打开音乐源与设备选择器；侧边栏和搜索范围会切换到当前音乐源。这些音乐源通过 spotatui 自身的音频引擎播放，因此音量控制和可视化效果与 Spotify 完全一致，且都不需要 Spotify Premium。

音乐源	功能	需求
本地文件	浏览和播放

spotatui

A terminal music player written in Rust, powered by Ratatui
Native Spotify streaming, synced lyrics, a real-time audio visualizer, local file,
Subsonic/Navidrome, Internet Radio, YouTube, and Qobuz sources, plus Apple Music on macOS. Spotify is optional.

A community-maintained, actively developed fork of spotify-tui that has since diverged on multiple fronts.

Key differences	spotify-tui	spotatui
Spotify backend	external Connect device (spotifyd, official client, ...)	built-in native client
Source(s)	Spotify	Spotify, YouTube, local, Subsonic, Navidrome, Internet Radio, Qobuz, Apple Music (macOS)

• Multiple sources — Spotify optional. Play from Spotify, Local Files, a Subsonic/Navidrome server, Internet Radio, YouTube, Qobuz, or Apple Music on macOS. The free sources need no Spotify account; press d to switch between them at any time.
• Native streaming. Play Spotify audio directly, no official app or spotifyd required — spotatui appears as its own Spotify Connect device (Premium required).
• Synced lyrics. Line-by-line lyrics that follow playback.
• Real-time audio visualizer. A system-wide FFT visualizer (press v) that reacts to whatever is playing, and for Spotify tracks the pitch view of the original spotify-tui.
• Cross-source play queue. Press z on any track to queue it — the queue plays across every source before your current context resumes.
• Playlist sync. Link one playlist as the master and mirror it onto Spotify, Qobuz, Subsonic or YouTube. Runs at startup and from spotatui sync.
• Lua plugins. Extend spotatui with event hooks, commands, keybindings, popups, and theming.
• Listening history & recap. spotatui keeps a local play history and can generate a shareable HTML recap (spotatui history recap).
• Full CLI. Most of what the UI does is scriptable — playback, search, playlists, shell completions. Run spotatui --help.
• Lightweight. ~78 MB RAM while streaming, versus a full Electron client. See Performance.

Spotify is optional. On first launch spotatui asks which source you want to use. YouTube, Subsonic/Navidrome, Internet Radio, Local Files, Qobuz, and Apple Music (macOS) all work with no Spotify account. Spotify Premium is only needed for the Spotify source; you can add it anytime from the d menu.

# One-line installer — macOS, Linux, WSL. Grabs the prebuilt binary for your
# system, verifies its checksum, and puts spotatui on your PATH. No Rust needed.
curl -fsSL https://spotatui.com/install.sh | bash

# Homebrew (macOS only)
brew tap LargeModGames/spotatui
brew install spotatui

# Cargo — compile from crates.io …
cargo install --locked spotatui
# … or fetch the prebuilt binary without compiling
cargo binstall spotatui

# Arch Linux (AUR) — prebuilt binary (faster)
yay -S spotatui-bin
# …or build from source
yay -S spotatui

# Void Linux (unofficial repo)
echo repository=https://raw.githubusercontent.com/Event-Horizon-VL/blackhole-vl/repository-x86_64 | sudo tee /etc/xbps.d/20-repository-extra.conf
sudo xbps-install -S spotatui


# One-line installer — Windows PowerShell
irm https://spotatui.com/install.ps1 | iex

# …or via Winget
winget install spotatui


# NixOS (Flake, recommended for NixOS)

# Add spotatui to your flake inputs:
inputs = {
  spotatui = {
    url = "github:LargeModGames/spotatui";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

# Add the spotatui package from your inputs to your config:
{ inputs, ...}:{
  # Your other configurations
  environment.systemPackages = with pkgs; [
    inputs.spotatui.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

The flake will take care of all the dependencies for you, except for setting the audio backend. If you use alsa:

 hardware.alsa.enable = true;

Or if you use pipewire:

 services.pipewire = {
     enable = true;
     alsa.enable = true;
     #your other settings
 };

The flake provides x86_64-linux, aarch64-linux, and aarch64-darwin. nixpkgs 26.11 dropped Intel Macs (x86_64-darwin), so on those use the Homebrew formula, the one-line installer, or the release tarball below.

Or download pre-built binaries from GitHub Releases.

Which build has which sources? The prebuilt Linux, macOS, and Windows binaries (the one-line installer, GitHub Releases, and cargo binstall) and the desktop app include the extra music sources: Local Files, Subsonic, Internet Radio, YouTube, and Qobuz, and the macOS ones also Apple Music. YouTube needs yt-dlp installed (ffmpeg recommended). A plain cargo install --locked spotatui does not; enable them with --features local-files,subsonic,internet-radio,youtube,qobuz (on macOS, add apple-music).

See the Installation Wiki for platform-specific requirements and building from source.

spotatui also comes as a desktop app: the same player in its own window, with a Spotify-style layout (Home, album and artist pages, Your Library, lyrics). It uses the same login, settings and history as the terminal app, and only one of the two runs at a time. Closing the window quits it.

The preview plays Spotify (Premium required), Local Files, Subsonic, Internet Radio, YouTube and Qobuz, and on macOS also Apple Music. As in the terminal app, YouTube needs yt-dlp installed (ffmpeg recommended). Installed from the Windows installer, the macOS app or the AppImage, it updates itself; a .deb or .rpm install updates with a new download from GitHub Releases. The behavior.disable_auto_update and behavior.auto_update_delay settings, also on the app's Settings page, control the updates.

System	File
Windows 10/11 (64-bit)	spotatui-desktop_<version>_x64-setup.exe
macOS, Apple Silicon	spotatui_<version>_aarch64.dmg
macOS, Intel	spotatui_<version>_x64.dmg
Debian/Ubuntu	spotatui-desktop_<version>_amd64.deb or _arm64.deb
Fedora	spotatui-desktop-<version>-1.x86_64.rpm or .aarch64.rpm
Other Linux	spotatui-desktop_<version>_amd64.AppImage or _aarch64.AppImage

The installers are not signed yet, so your system warns on the first start:

• Windows: SmartScreen says "Windows protected your PC". Click More info , then Run anyway.
• macOS: macOS refuses to open the app the first time. Close the dialog, open System Settings > Privacy & Security, click Open Anyway next to the spotatui message, and confirm. If macOS says the app is damaged, run xattr -dr com.apple.quarantine /Applications/spotatui.app once.

On Linux the app needs glibc 2.39 and WebKitGTK 4.1 (webkit2gtk-4.1): Ubuntu 24.04 or newer, Debian 13, Fedora 40 or newer, or Arch. If the window stays blank on Wayland with an NVIDIA GPU, start it with GDK_BACKEND=x11 spotatui-desktop. The app already sets WEBKIT_DISABLE_DMABUF_RENDERER=1 unless you set it yourself.

To drive the desktop app from a coding agent over MCP, also install the terminal spotatui: the agent starts spotatui mcp, which only the terminal binary has.

Run spotatui. On the first launch it asks which source to set up:

Welcome to spotatui! Choose your music source:

  1) Spotify        (needs login)
  2) YouTube        (free, needs the yt-dlp binary)
  3) Subsonic       (free, needs a Subsonic/Navidrome server)
  4) Internet Radio (free)
  5) Local Files    (free)
  6) Qobuz          (paid subscription, logs in through the browser)
  7) Apple Music    (macOS Music app, needs Automation permission)

Pick a free source to skip Spotify entirely, or pick Spotify to log in: spotatui shows a code and opens Spotify's pairing page in your browser, where you confirm the code. No developer app or client ID is necessary. Spotify needs a Premium account. Only sources compiled into your build are listed. Once you're in:

• Press ? for the in-app help menu of all key events.
• Press d to open the Source & Device picker and switch sources.
• Press z on a track to queue it; open the queue with Shift+Q.
• Run spotatui --help for the CLI. See the Keybindings Wiki for every shortcut.

To search and play a result with the default keys:

1. Press /, type a search phrase, and press Enter to submit it. Ctrl+L clears an existing query.
2. Use the arrow keys to choose the Songs result panel and press Enter to focus its list.
3. Use Up/Down to select a track, then press Enter again to play it. Space toggles play/pause.

Selecting a result panel does not start playback.

A few CLI examples to get you started:

spotatui --completions zsh                                # Shell completions (bash, powershell, and more supported)
spotatui play --name "Your Playlist" --playlist --random  # Play a random song from a playlist
spotatui playback --toggle                                # Play/pause current playback
spotatui list --liked --limit 50                          # List your liked songs
spotatui history recap --period 30d --output ./recap.html # Generate a shareable listening recap

Started with a free source and want Spotify too? Press d to open the Source & Device picker. If the Devices panel has focus (including when it says "No devices found"), press Tab to focus Source , select Spotify , and press Enter. Spotatui shows a pairing code in the status line and opens your browser to log in without a restart. Browsing, playlists, and the control of other devices work at once. Native (librespot) streaming still requires a restart , because it starts with the app.

spotatui is a general music player, not just a Spotify client. Press d to open the Source & Device picker; the sidebar and search re-scope to the active source. Playback for these sources runs through spotatui's own audio engine, so volume control and the visualizer work exactly as they do for Spotify — and none of them need Spotify Premium.

Source	What it does	Needs
Local Files	Browse and play a folder of audio files (FLAC, MP3, OGG, WAV, …)	Nothing; set local_music_path or use the OS music dir
Subsonic	Browse, search, and stream from any Subsonic-compatible server (Navidrome, Gonic, Airsonic, Funkwhale, …)	A server account
Internet Radio	Play icecast/shoutcast streams with live now-playing metadata; search the radio-browser.info directory (30k+ stations)	Nothing
YouTube	Search YouTube and play audio; build local playlists stored in a plain file	yt-dlp on your PATH (ffmpeg recommended)
Qobuz	Stream your Qobuz library (favorites, playlists, albums, search) at the configured quality, MP3 320 up to FLAC 24/192, through spotatui's own engine	A paid Qobuz account
Apple Music	Browse and search your Music library and its playlists; the Music app plays them, spotatui is the remote	macOS and the Music app; your own Apple Music login

Resuming your last session: quit while playing from a non-Spotify source and spotatui restores that track and its position on the next launch, following the startup_behavior setting (continue, play, or pause).

Availability: included in the Linux, macOS, and Windows release binaries; Apple Music is in the macOS ones only. When building from source, enable them with cargo features:

cargo install --locked spotatui --features local-files,subsonic,internet-radio,youtube,qobuz
# macOS: add apple-music

Each source has a few config keys; the essentials are below, and the full reference lives in the Configuration Wiki.

Set a folder (defaults to the OS music directory), then pick Local Files in the d picker:

behavior:
  local_music_path: "/home/you/Music"


behavior:
  subsonic_url: "https://music.example.com"
  subsonic_username: "you"

Prefer setting the password via the SPOTATUI_SUBSONIC_PASSWORD environment variable so it never sits in the config file in plaintext.

Search the radio-browser.info directory in-app (Enter plays a station directly), and press the save key (F by default) to keep a station in your sidebar. Stations can also be preconfigured in config.yml; stations saved in-app live in state.yml. The playbar shows a LIVE badge with the stream's now-playing title.

Requires the yt-dlp binary (ffmpeg recommended). No Google account, API key, or cookies — search and playback are anonymous. If playback breaks after a YouTube change, updating yt-dlp (yt-dlp -U) is the fix; no spotatui update needed.

Local YouTube playlists live in the spotatui config directory as youtube_playlists.yml, a plain human-editable file you can back up or share. Create one from the sidebar, add tracks with w, and play a playlist as a queue with Enter.

Pick Qobuz in the first-run picker or the d menu: spotatui opens the Qobuz login page in your browser and saves the token to qobuz_credentials.yml in the config directory (owner-only on Unix; on Windows the file keeps the config folder's permissions). No app registration is needed. The sidebar lists your favorite tracks, playlists, and favorite albums; search finds tracks. Each track plays while it downloads: the encrypted stream is decrypted and rebuilt as a FLAC temporary file, playback starts after the first segments arrive, and a seek past the downloaded part continues the download from there. When a track plays from a Qobuz listing, the playbar shows the format that Qobuz delivered, for example FLAC 16/44.1. This can be lower than the configured quality.

behavior:
  qobuz_quality: 6   # 5 = MP3 320, 6 = FLAC 16/44.1, 7 = FLAC 24/96, 27 = FLAC 24/192

Environment variables: SPOTATUI_QOBUZ_TOKEN overrides the saved token. spotatui reads the three constants it needs from the Qobuz web player at runtime; when Qobuz changes its web player and the login stops working, set SPOTATUI_QOBUZ_APP_ID, SPOTATUI_QOBUZ_APP_SECRET, and SPOTATUI_QOBUZ_OAUTH_KEY from the bundle instead of waiting for a release.

macOS only. Pick Apple Music in the first-run picker or the d menu. Unlike the other sources, the audio does not go through spotatui: the Music app plays the songs with your own Apple Music login and library, and spotatui drives it from the terminal. Music is started in the background and never brought to the front. The first time, macOS asks whether your terminal may control Music; allow it (or later under System Settings > Privacy & Security > Automation).

The sidebar lists All songs and your playlists, including Apple Music playlists you added to your library; search looks through your library. Play/pause, next, previous, seek, volume, the media keys and the playbar follow Music. Next and previous step through the playlist or search results a song was started from, and follow Music's shuffle setting. Only one player is audible when you switch inside spotatui: starting a Music song from spotatui pauses Spotify and the other sources, and starting one of those pauses Music first. Pressing play in the Music app itself while another source is playing is not detected.

Not available for Apple Music songs: the queue, the shuffle and repeat toggles (change them in Music), likes, and playlist edits. Songs Music cannot play (no longer available, or a local file that is missing) are listed, but choosing one shows a message instead of playing it, and next and previous skip them: Music would answer them with a dialog that blocks every later start. spotatui never lets Music's volume reach 0 for the same reason.

spotatui can pick music for you, from your own listening history. Two ways in:

Drive it from your coding agent (--features mcp-server) — spotatui exposes the player and your listening history as MCP tools, so Claude Code, Codex, Gemini CLI, or any MCP client becomes the DJ. No API key : it uses the agent subscription you already have. Setup is one line you hand to your agent:

Read docs/mcp-setup.md in the spotatui repo and set up the spotatui MCP server for me, following it exactly.

That file is written as instructions for the agent , and spotatui mcp status gives it a safe, checkable probe of every step. Full guide: docs/mcp-setup.md.

Clients that support agent plugins can do the whole registration in one step, and get a DJ skill along with the server: in Claude Code, /plugin marketplace add LargeModGames/spotatui then /plugin install spotatui@spotatui; clients that read the new Agent Plugins format load agent-plugin/ from this repo. (These are agent plugins, for AI clients — spotatui's in-app Lua plugins live in PLUGINS.md.)

Or use the DJ built into the TUI (--features ai-dj) — press Ctrl-j for a DJ screen with a chat prompt, Ctrl-t for continuous auto-queue, Ctrl-y to shift the vibe, Ctrl-o for "only tracks I don't already have", Ctrl-g to choose which AI and model it uses. It drives the same tools as the MCP server, so it can search, check your queue and queue tracks, and it will ask what you actually want before it plays anything rather than queueing on every message. Its brain is a locally installed agent CLI (claude, codex, agy, copilot, opencode, no key), an API key, or a local model via Ollama / LM Studio; it asks which one on your first visit, since the agent CLIs spend the coding subscription you already pay for. Full guide: docs/ai-dj.md.

What reaches a model is track, artist, and album names : aggregates from your local history, what is playing now, and the conversation you typed. No identifiers, no timestamps, no account. Full breakdown in docs/ai-dj.md.

cargo install --locked spotatui --features mcp-server,ai-dj

spotatui can play Spotify audio directly, without spotifyd or the official app — just run it and it appears as a Spotify Connect device.

• Premium account required
• Works with media keys, MPRIS (Linux), and macOS Now Playing
• Runs on our maintained librespot fork, which backports upstream fixes for Spotify's evolving audio delivery (e.g. the HTTP 530 CDN issue that silenced native playback)

See the Native Streaming Wiki for setup details.

The config file is at $XDG_CONFIG_HOME/spotatui/config.yml when XDG_CONFIG_HOME is set to an absolute path, falling back to ${HOME}/.config/spotatui/config.yml when it is unset or not absolute. You can also configure spotatui in-app by pressing Alt-, to open Settings.

Nearly everything is customizable: keybindings, themes, icons, playbar button labels, status-line and window-title format templates, table columns (reorder/rename/resize), default sorting per screen, startup screen, and layout (sidebar/playbar position). Invalid values fall back to defaults with a logged warning — a config typo never blocks startup.

With the cover-art feature, Settings offers optional two-color dithering for the playbar, full-screen art view, and plugin cover-art widgets. In config.yml, set behavior.cover_art_dither: true, use the default stucki algorithm (or choose bayer8x8/atkinson with behavior.cover_art_dither_algorithm), and set behavior.cover_art_dither_pixel_scale from 1 to 3 for larger visual pixels. Scale 1 uses every output pixel on graphics terminals or every Braille dot on basic terminals. Each surface makes its mask from the original decoded image at its own output resolution. theme.cover_art_dither_color accepts a named color or an exact R, G, B value; omit it or set it to auto to follow the current playbar progress color, including adaptive-theme changes. The color override survives preset changes. Dithering does not enable cover art on a terminal where it is otherwise disabled; behavior.draw_cover_art_forced still controls the terminal fallback.

spotatui also stores local listening history at $XDG_STATE_HOME/spotatui/history/listens.jsonl when XDG_STATE_HOME is set to an absolute path, falling back to ${HOME}/.local/state/spotatui/history/listens.jsonl when it is unset or not absolute. This powers spotatui history recap. Short or skipped plays are stored but excluded from recap totals.

Enabled by default using the built-in spotatui application ID, so no setup is required. Optional overrides:

behavior:
  enable_discord_rpc: true
  discord_rpc_client_id: "your_client_id"

You can also override the app ID via SPOTATUI_DISCORD_APP_ID, or disable it in Settings or with behavior.enable_discord_rpc: false.

spotatui includes an opt-in global counter showing how many songs have been played by all users worldwide (the badge and chart at the top of this README). It is completely anonymous — no personal information, song names, artists, or listening history is collected; it only sends a simple increment once a song has played for 30 seconds, from any source (Spotify, local files, Subsonic, Qobuz or YouTube). Internet radio counts one song for every 2.5 minutes of listening. It is enabled by default and can be disabled with enable_global_song_count: false in config.yml. This is purely a fun community metric with zero tracking of individual users.

Show what you're listening to as a live card on your GitHub profile. Create an account at spotatui.com, paste your sync token into Settings → sync_token, then pick a public username and enable the widget on your dashboard. Add this to your profile README:

[![Now playing on spotatui](https://spotatui.com/widget/your-username.svg)](https://spotatui.com)

The card shows cover art, title, artist, a progress bar, and an animated equalizer while playing; internet radio gets a LIVE badge. Append ?theme=light for the light variant. Only your current track is public, and only after you opt in.

spotatui runs user-written Lua plugins. They react to playback events, add commands and key bindings, draw popups and playbar segments, restyle the theme, and make async HTTP requests. Install one published as a git repository (requires git):

spotatui plugin add owner/repo
spotatui plugin list
spotatui plugin update
spotatui plugin remove <name>

See PLUGINS.md for the ecosystem overview, examples/plugins/ for runnable examples, and docs/scripting.md for the full API reference.

spotatui is extremely lightweight compared to the official Electron client.

Mode	RAM Usage
Native Streaming (Base)	~78 MB
With Synced Lyrics	~78 MB
With System-Wide Visualizer	~80 MB

Tested on Arch Linux (Hyprland).

The non-Spotify sources (Local Files, Subsonic, Internet Radio, YouTube, Qobuz) play through spotatui's own audio engine and need no extra setup. Apple Music (macOS) plays through the Music app instead; see Apple Music.

Spotify is different: spotatui talks to Spotify the way the official app does, and that connection does not play audio itself. To play Spotify tracks you need one of:

1. Native Streaming : spotatui plays audio directly using its built-in streaming. See Native Streaming. (Recommended.)
2. Official Spotify Client : have the official app open on your computer.
3. spotifyd : a lightweight background alternative.

Spotify in spotatui requires a Premium account: the login refuses a free account. spotatui needs no Spotify developer app and no client ID. Older releases asked for one; spotatui leaves their client.yml on disk and copies its streaming settings and saved device into config.yml and state.yml.

The audio visualizer (press v) uses local real-time FFT analysis of your system audio:

Platform	Status	Notes
Windows	Works out of the box	Uses WASAPI loopback
Linux	Works out of the box	Uses PipeWire/PulseAudio monitor devices
macOS	Requires setup	Needs a virtual audio device (see below)

macOS: macOS doesn't natively expose system audio loopback. Install a virtual audio device like BlackHole (free) or Loopback (paid), route system audio through it, and set it as your default input device.

Note: The visualizer is system-wide : it captures all audio on your system, so it also reacts to YouTube videos, games, and any other source.

While a Spotify track plays, v opens the Spotify Pitch view instead, the visualizer of the original spotify-tui: the strength of the twelve pitch classes (C to B) drawn as Cava bars that rise with the loudness of the music and fall with gravity, with the tempo, key and time signature of the current section, from Spotify's own audio analysis. It needs no audio capture, so it also works when Spotify plays on another device. Press V to switch between Cava, Bar Graph and Spotify Pitch.

Note: If you're using native streaming, you don't need spotifyd!

Follow the spotifyd documentation to get set up. After that:

1. Start the spotifyd daemon.
2. Start spotatui.
3. Press d to open the device selection menu — the spotifyd "device" should appear (if not, check these docs).

Migrating from spotify-tui

If you used the original spotify-tui before:

• The binary name changed from spt to spotatui.
• Config paths changed: ~/.config/spotify-tui/ -> $XDG_CONFIG_HOME/spotatui/ when XDG_CONFIG_HOME is set to an absolute path, or ~/.config/spotatui/ when it is unset or not absolute.

You can copy your existing config:

case "${XDG_CONFIG_HOME:-}" in
  /*) config_home="$XDG_CONFIG_HOME" ;;
  *) config_home="$HOME/.config" ;;
esac
mkdir -p "$config_home/spotatui"
cp -r ~/.config/spotify-tui/* "$config_home/spotatui/"

You may be asked to re-authenticate with Spotify the first time.

1. Install OpenSSL

2. Install Rust

3. Install xorg-dev (required for clipboard support)

4. Linux only: Install ALSA + pkg-config for the default build. This applies to both glibc and musl targets: glibc uses the librespot alsa-backend, and both use cpal (audio visualization, and rodio on musl), which links ALSA on Linux. Package list matches docs/installation.md#prerequisites.

   # Debian/Ubuntu
   sudo apt-get install libasound2-dev pkg-config
   
   # Arch Linux
   sudo pacman -S alsa-lib pkg-config
   
   # Fedora
   sudo dnf install alsa-lib-devel pkg-config
   
   # NixOS
   nix develop github:LargeModGames/spotatui
   

Optional: --features audio-viz (and the Linux release / all-sources CI leg) need PipeWire dev packages — libpipewire-0.3-dev libspa-0.2-dev (Debian/Ubuntu), pipewire (Arch), pipewire-devel (Fedora). The slim --no-default-features --features telemetry,tui build needs neither ALSA nor PipeWire. 5. Clone or fork this repo and cd to it 6. And then cargo run

See CONTRIBUTING.md for pull request guidelines.

Windows Subsystem for Linux

You might get a linking error. If so, you'll probably need to install additional dependencies required by the clipboard package:

sudo apt-get install -y -qq pkg-config libssl-dev libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev

Run the thing that broke again with --debug, then attach the log file:

spotatui prints the log path on startup and on exit — it lives in your temp directory as spotatui_logs/spotatuilog<pid>. With --debug it records every Spotify request (method, path, status, duration), which is what turns "it doesn't play" into something diagnosable.

If it crashed instead, spotatui_panic.log in the state directory already has the panic, a backtrace, and the tail of the log in one file.

Tokens and headers are never written to the log, and known secret fields are redacted — but a log can still contain your display name, and a trace log your country. Have a quick look before posting it publicly. See docs/configuration.md for the details.

spotatui is currently maintained by a solo developer. More contributors would be hugely appreciated — and you don't need to write code to help :

• Star the repo to help others discover the project
• Report bugs or request features in Issues
• Join the community in Discussions
• Submit a PR for code, docs, or themes

See CONTRIBUTING.md for more details!

Maintained by LargeModGames (@LargeModGames on Twitter).

Originally forked from spotify-tui by Alexander Keliris.

Free code signing provided by SignPath.io, certificate by SignPath Foundation.

The Windows release files are built from this repository by the release workflow on GitHub-hosted runners. Each signing request is approved by hand.

Privacy: see the privacy policy for the data spotatui sends and how to turn each part off.

Looking for contributors! spotatui is actively maintained but could use your help. Whether it's bug fixes, new features, documentation, or testing - all contributions are welcome!

Want to see your name here? Check out ouropen issues or the Roadmap below!

---

Upstream Contributors (spotify-tui)

Thanks to all the contributors who built the original spotify-tui that this project is forked from:

This project follows the all-contributors specification. Contributions of any kind welcome!

The goal is to eventually implement almost every Spotify feature.

High-priority features:

• Scroll through result pages in every view

See the Roadmap Wiki for the full API coverage table.