Spotatui：无需 Web API 速率限制的 Spotify TUI/GUI 终端播放器

一个用 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。 UI 所做的大部分事情都可脚本化——播放、搜索、播放列表、shell 补全。运行 spotatui --help。
轻量。 流媒体播放时约 78 MB 内存，而完整的 Electron 客户端则不然。参见性能。

安装

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

# 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：

 hardware.alsa.enable = true;

或者如果你使用 pipewire：

 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、一行安装脚本或下方的发布压缩包。

或者从 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。

要通过 MCP 用编码代理驱动桌面应用，还需安装终端版 spotatui：代理会启动 spotatui mcp，而只有终端二进制文件才有这个功能。

快速开始

运行 spotatui。首次启动时它会询问要设置哪个来源：

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 打开 Source & Device 选择器并切换来源。
在曲目上按 z 将其加入队列；用 Shift+Q 打开队列。
运行 spotatui --help 使用 CLI。查看 Keybindings Wiki 了解所有快捷键。

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

按 /，输入搜索词，然后按 Enter 提交。Ctrl+L 清除已有查询。
使用方向键选择 Songs 结果面板，然后按 Enter 聚焦其列表。
使用 Up/Down 选择曲目，然后再次按 Enter 播放。Space 切换播放/暂停。

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

几个 CLI 示例帮你上手：

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

一开始使用免费来源，现在也想要 Spotify？按 d 打开 Source & Device 选择器。如果 Devices 面板处于焦点状态（包括显示“No devices found”时），按 Tab 聚焦 Source，选择 Spotify，然后按 Enter。Spotatui 会在状态栏显示配对码并打开浏览器登录，无需重启。浏览、播放列表和其他设备的控制会立即生效。原生（librespot）流媒体仍需重启，因为它随应用启动。

音乐来源

spotatui 是通用音乐播放器，而不仅仅是 Spotify 客户端。按 d 打开 Source & Device 选择器；侧边栏和搜索会重新限定到当前活动来源。这些来源的播放通过 spotatui 自有的音频引擎运行，因此音量控制和可视化效果与 Spotify 完全一致——而且它们都不需要 Spotify Premium。

来源	功能	需求
Local Files	浏览并播放音频文件文件夹（FLAC、MP3、OGG、WAV……）	无；设置 `local_music_path` 或使用操作系统音乐目录
Subsonic	从任何兼容 Subsonic 的服务器（Navidrome、Gonic、Airsonic、Funkwhale……）浏览、搜索和流式播放	一个服务器账户
Internet Radio	播放 icecast/shoutcast 流，带实时正在播放元数据；搜索 radio-browser.info 目录（3 万多个电台）	无
YouTube	搜索 YouTube 并播放音频；创建存储在纯文本文件中的本地播放列表	在你的 `PATH` 上安装 `yt-dlp`（推荐 ffmpeg）
Qobuz	以配置的音质流式播放你的 Qobuz 库（收藏、播放列表、专辑、搜索），从 MP3 320 到 FLAC 24/192，通过 spotatui 自有引擎	付费 Qobuz 账户
Apple Music	浏览并搜索你的音乐库及其播放列表；由 Music 应用播放，spotatui 作为遥控器	macOS 和 Music 应用；你自己的 Apple Music 登录

恢复上次会话：在从非 Spotify 来源播放时退出，spotatui 会在下次启动时恢复该曲目及其位置，遵循 startup_behavior 设置（continue、play 或 pause）。

可用性：包含在 Linux、macOS 和 Windows 发布二进制文件中；Apple Music 仅在 macOS 版本中。从源码构建时，通过 cargo features 启用它们：

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

每个来源都有几个配置键；要点如下，完整参考见 Configuration Wiki。

Local Files

设置一个文件夹（默认为操作系统音乐目录），然后在 d 选择器中选择 Local Files：

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

Subsonic / Navidrome

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

建议通过 SPOTATUI_SUBSONIC_PASSWORD 环境变量设置密码，这样它就不会以明文形式留在配置文件中。

Internet Radio

在应用内搜索 radio-browser.info 目录（按 Enter 直接播放电台），然后按保存键（默认 F）将电台保留在侧边栏中。电台也可以在 config.yml 中预先配置；在应用内保存的电台存放在 state.yml 中。播放栏会显示一个 LIVE 徽章，其中包含该流的正在播放标题。

YouTube

需要 yt-dlp 二进制文件（推荐 ffmpeg）。无需 Google 账号、API 密钥或 cookies——搜索和播放都是匿名的。如果 YouTube 变更后播放中断，更新 yt-dlp（yt-dlp -U）即可修复；无需更新 spotatui。

本地 YouTube 播放列表以 youtube_playlists.yml 的形式存放在 spotatui 配置目录中，这是一个纯文本、可人工编辑的文件，你可以备份或分享。从侧边栏创建一个，用 w 添加曲目，并用 Enter 将播放列表作为队列播放。

Qobuz

在首次运行选择器或 d 菜单中选择 Qobuz：spotatui 会在浏览器中打开 Qobuz 登录页面，并将令牌保存到配置目录中的 qobuz_credentials.yml（在 Unix 上仅限所有者；在 Windows 上该文件保留配置文件夹的权限）。无需应用注册。侧边栏会列出你喜欢的曲目、播放列表和喜欢的专辑；搜索可查找曲目。每首曲目在下载时播放：加密流被解密并重建为 FLAC 临时文件，在首批分段到达后开始播放，而跳转到已下载部分之后的位置会从那里继续下载。当从 Qobuz 列表播放曲目时，播放栏会显示 Qobuz 提供的格式，例如 FLAC 16/44.1。这可能低于配置的质量。

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

环境变量：SPOTATUI_QOBUZ_TOKEN 覆盖已保存的令牌。spotatui 在运行时从 Qobuz 网页播放器读取它所需的三个常量；当 Qobuz 更改其网页播放器且登录停止工作时，请从捆绑包中设置 SPOTATUI_QOBUZ_APP_ID、SPOTATUI_QOBUZ_APP_SECRET 和 SPOTATUI_QOBUZ_OAUTH_KEY，而不是等待发布。

Apple Music

仅限 macOS。在首次运行选择器或 d 菜单中选择 Apple Music。与其他来源不同，音频不经过 spotatui：Music 应用使用你自己的 Apple Music 登录和资料库播放歌曲，而 spotatui 从终端驱动它。Music 在后台启动，从不带到前台。首次使用时，macOS 会询问你的终端是否可以控制 Music；请允许（或稍后在系统设置 > 隐私与安全性 > 自动化中允许）。

侧边栏会列出 所有歌曲 和你添加到资料库的 Apple Music 播放列表等播放列表；搜索会查找你的资料库。播放/暂停、下一首、上一首、跳转、音量、媒体键和播放栏都跟随 Music。下一首和上一首会在启动歌曲所在的播放列表或搜索结果中切换，并遵循 Music 的随机播放设置。当你在 spotatui 内切换时，只有一个播放器可发声：从 spotatui 启动 Music 歌曲会暂停 Spotify 和其他来源，而启动那些来源之一会先暂停 Music。在另一个来源正在播放时，在 Music 应用本身中按下播放不会被检测到。

Apple Music 歌曲不支持：队列、随机播放和重复切换（在 Music 中更改它们）、喜欢和播放列表编辑。Music 无法播放的歌曲（不再可用，或本地文件缺失）会被列出，但选择其中一首会显示消息而不是播放它，下一首和上一首会跳过它们：Music 会用对话框回应它们，从而阻止之后的所有启动。出于同样的原因，spotatui 从不让 Music 的音量达到 0。

AI DJ

spotatui 可以根据你自己的收听历史为你挑选音乐。两种方式：

从你的编码代理驱动它（--features mcp-server）——spotatui 将播放器和你的收听历史暴露为 MCP 工具，因此 Claude Code、Codex、Gemini CLI 或任何 MCP 客户端都能成为 DJ。无需 API 密钥：它使用你已有的代理订阅。设置只需一行，交给你的代理即可：

阅读 spotatui 仓库中的 docs/mcp-setup.md，并为我设置 spotatui MCP 服务器，严格照做。

该文件是为代理编写的指令，而 spotatui mcp status 为每一步提供了安全、可检查的探测。完整指南：docs/mcp-setup.md。

支持代理插件的客户端可以一步完成整个注册，并随服务器获得一个 DJ 技能：在 Claude Code 中，/plugin marketplace add LargeModGames/spotatui 然后 /plugin install spotatui@spotatui；读取新 Agent Plugins 格式的客户端会从此仓库加载 agent-plugin/。（这些是代理插件，用于 AI 客户端——spotatui 的应用内 Lua 插件位于 PLUGINS.md。）

或使用 TUI 内置的 DJ（--features ai-dj）——按 Ctrl-j 打开带聊天提示的 DJ 界面，Ctrl-t 开启连续自动排队，Ctrl-y 切换氛围，Ctrl-o 选择“仅限我还没有的曲目”，Ctrl-g 选择使用哪个 AI 和模型。它驱动与 MCP 服务器相同的工具，因此可以搜索、检查你的队列并排队曲目，而且它会在播放任何内容之前先询问你真正想要什么，而不是对每条消息都排队。它的大脑是本地安装的代理 CLI（claude、codex、agy、copilot、opencode，无需密钥）、API 密钥，或通过 Ollama / LM Studio 使用的本地模型；首次访问时它会询问使用哪一个，因为代理 CLI 会消耗你已付费的编码订阅。完整指南：docs/ai-dj.md。

到达模型的是曲目、艺人和专辑名称：来自你本地历史的聚合数据、当前播放内容，以及你输入的对话。没有标识符，没有时间戳，没有账户。完整说明见 docs/ai-dj.md。

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

原生流媒体

spotatui 可以直接播放 Spotify 音频，无需 spotifyd 或官方应用——只需运行它，它就会作为 Spotify Connect 设备出现。

需要 Premium 账户
支持媒体键、MPRIS（Linux）和 macOS Now Playing
运行在我们维护的 librespot 分支上，该分支向后移植了上游针对 Spotify 不断演变的音频传输的修复（例如导致原生播放无声的 HTTP 530 CDN 问题）

设置详情请参阅 Native Streaming Wiki。

配置

当 XDG_CONFIG_HOME 设置为绝对路径时，配置文件位于 $XDG_CONFIG_HOME/spotatui/config.yml；未设置或不是绝对路径时，回退到 ${HOME}/.config/spotatui/config.yml。你也可以在应用内配置 spotatui，按 Alt-, 打开设置。

几乎一切都可以自定义：键位绑定、主题、图标、播放栏按钮标签、状态栏和窗口标题格式模板、表格列（重新排序/重命名/调整大小）、每个屏幕的默认排序、启动屏幕，以及布局（侧边栏/播放栏位置）。无效值会回退到默认值并记录警告——配置拼写错误绝不会阻止启动。

借助 cover-art 功能，设置中可为播放栏、全屏封面视图和插件封面组件提供可选的两种颜色抖动。在 config.yml 中，设置 behavior.cover_art_dither: true，使用默认的 stucki 算法（或使用 behavior.cover_art_dither_algorithm 选择 bayer8x8/atkinson），并将 behavior.cover_art_dither_pixel_scale 从 1 设为 3 以获得更大的视觉像素。缩放 1 在图形终端上使用每个输出像素，或在基础终端上使用每个盲文点。每个表面都以其自身的输出分辨率从原始解码图像生成其遮罩。theme.cover_art_dither_color 接受命名颜色或精确的 R, G, B 值；省略它或将其设为 auto 以跟随当前播放栏进度颜色，包括自适应主题变化。颜色覆盖在预设更改后仍然保留。抖动不会在原本禁用封面艺术的终端上启用封面艺术；behavior.draw_cover_art_forced 仍控制终端回退。

自定义指南：docs/configuration.md，附有带注释的 examples/config.example.yml
完整配置参考：Configuration Wiki
内置主题（Spotify、Dracula、Nord 等）：Themes Wiki

当 XDG_STATE_HOME 设置为绝对路径时，spotatui 还会在 $XDG_STATE_HOME/spotatui/history/listens.jsonl 存储本地收听历史，当未设置或不是绝对路径时回退到 ${HOME}/.local/state/spotatui/history/listens.jsonl。这为 spotatui history recap 提供支持。短暂或跳过的播放会被存储，但会从回顾统计中排除。

Discord Rich Presence

默认使用内置的 spotatui 应用程序 ID 启用，因此无需设置。可选的覆盖项：

behavior:
  enable_discord_rpc: true
  discord_rpc_client_id: "your_client_id"

你也可以通过 SPOTATUI_DISCORD_APP_ID 覆盖应用 ID，或在设置中或使用 behavior.enable_discord_rpc: false 禁用它。

匿名歌曲计数器

spotatui 包含一个可选的全局计数器，显示全球所有用户已播放的歌曲数量（本 README 顶部的徽章和图表）。它完全匿名——不收集任何个人信息、歌曲名称、艺术家或收听历史；它只会在歌曲播放 30 秒后发送一个简单的增量，来自任何来源（Spotify、本地文件、Subsonic、Qobuz 或 YouTube）。网络电台每收听 2.5 分钟计为一首歌。它默认启用，可通过 config.yml 中的 enable_global_song_count: false 禁用。这纯粹是一个有趣的社区指标，对个人用户零追踪。

GitHub 个人资料组件

在你的 GitHub 个人资料上以实时卡片显示你正在收听的内容。在 spotatui.com 创建账户，将你的同步令牌粘贴到设置 → sync_token，然后选择一个公开用户名并在你的仪表板上启用该组件。将此添加到你的个人资料 README：

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

该卡片显示封面艺术、标题、艺术家、进度条，以及播放时的动画均衡器；网络电台会获得 LIVE 徽章。追加 ?theme=light 以获得浅色变体。只有你当前的曲目是公开的，并且仅在你选择加入后。

插件

spotatui 运行用户编写的 Lua 插件。它们响应播放事件、添加命令和键绑定、绘制弹出窗口和播放栏片段、重新设置主题样式，并发出异步 HTTP 请求。安装一个以 git 仓库形式发布的插件（需要 git）：

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

有关生态系统概述，请参阅 PLUGINS.md；有关可运行示例，请参阅 examples/plugins/；有关完整 API 参考，请参阅 docs/scripting.md。

性能

与官方 Electron 客户端相比，spotatui 极其轻量。

模式	内存使用
原生流媒体（基础）	~78 MB
带同步歌词	~78 MB
带系统级可视化器	~80 MB

在 Arch Linux（Hyprland）上测试。

播放要求

非 Spotify 来源（本地文件、Subsonic、网络电台、YouTube、Qobuz）通过 spotatui 自带的音频引擎播放，无需额外设置。Apple Music（macOS）则通过 Music 应用播放；参见 Apple Music。

Spotify 则不同：spotatui 像官方应用那样与 Spotify 通信，而该连接本身并不播放音频。要播放 Spotify 曲目，你需要以下其中一种方式：

原生流式播放：spotatui 使用其内置的流式播放功能直接播放音频。参见原生流式播放。（推荐。）
官方 Spotify 客户端：在你的电脑上打开官方应用。
spotifyd：一个轻量级的后台替代方案。

在 spotatui 中使用 Spotify 需要 Premium 账户：免费账户会被拒绝登录。spotatui 不需要 Spotify 开发者应用，也不需要 client ID。旧版本曾要求提供，spotatui 会将其 client.yml 保留在磁盘上，并把其流式播放设置和已保存设备复制到 config.yml 和 state.yml。

音频可视化器

音频可视化器（按 v）使用对你系统音频的本地实时 FFT 分析：

平台	状态	备注
Windows	开箱即用	使用 WASAPI 回环
Linux	开箱即用	使用 PipeWire/PulseAudio 监听设备
macOS	需要设置	需要虚拟音频设备（见下文）

macOS：macOS 原生不提供系统音频回环。安装一个虚拟音频设备，如 BlackHole（免费）或 Loopback（付费），将系统音频路由通过它，并将其设为你的默认输入设备。

注意：可视化器是系统级的：它会捕获你系统上的所有音频，因此也会对 YouTube 视频、游戏以及任何其他来源做出反应。

当 Spotify 曲目播放时，v 会改为打开 Spotify Pitch 视图，即原版 spotify-tui 的可视化器：十二个音级（C 到 B）的强度以 Cava 柱状条绘制，随音乐响度上升、随重力下落，并显示当前段落的速度、调性和拍号，数据来自 Spotify 自身的音频分析。它不需要音频捕获，因此当 Spotify 在另一台设备上播放时也能工作。按 V 在 Cava、柱状图和 Spotify Pitch 之间切换。

与 spotifyd 一起使用

注意：如果你使用原生流式播放，就不需要 spotifyd！

按照 spotifyd 文档进行设置。之后：

启动 spotifyd 守护进程。
启动 spotatui。
按 d 打开设备选择菜单——spotifyd 的“设备”应该会出现（如果没有，请查看这些文档）。

从 spotify-tui 迁移

如果你之前使用过原版 spotify-tui：

二进制文件名从 spt 改为 spotatui。
配置路径已更改：当 XDG_CONFIG_HOME 设置为绝对路径时为 ~/.config/spotify-tui/ -> $XDG_CONFIG_HOME/spotatui/，当未设置或不是绝对路径时为 ~/.config/spotatui/。

你可以复制现有配置：

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/"

首次使用时，可能会要求你重新通过 Spotify 进行身份验证。

歌曲历史

Star 历史

使用的库

ratatui - 终端 UI 框架
rspotify - Spotify 模型和 id 类型
librespot - Spotify Connect 流式播放（通过我们维护的分支 spotatui-librespot，该分支向后移植了针对 Spotify CDN 变更的修复）
tokio - 异步运行时
crossterm - 终端操作
clap - CLI 参数解析

开发

安装 OpenSSL
安装 Rust
安装 xorg-dev（剪贴板支持所需）
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.
克隆或复刻此仓库，然后 cd 到它
然后 cargo run

有关拉取请求指南，请参阅 CONTRIBUTING.md。

适用于 Linux 的 Windows 子系统

你可能会遇到链接错误。如果是这样，你可能需要安装剪贴板包所需的额外依赖项：

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

报告 Bug

用 --debug 再次运行出问题的东西，然后附上日志文件：

spotatui --debug

spotatui 在启动和退出时会打印日志路径——它位于你的临时目录中，文件名为 spotatui_logs/spotatuilog<pid>。使用 --debug 时，它会记录每个 Spotify 请求（方法、路径、状态、持续时间），这正是将“它不播放”变成可诊断问题的关键。

如果它崩溃了，状态目录中的 spotatui_panic.log 已经包含了 panic、回溯和日志尾部，都在一个文件里。

令牌和标头永远不会写入日志，已知的敏感字段会被脱敏——但日志仍可能包含你的显示名称，而 trace 日志可能包含你的国家/地区。公开发布前请快速检查一下。详情请参阅 docs/configuration.md。

需要帮助

spotatui 目前由一位独立开发者维护。非常欢迎更多贡献者——而且你不需要编写代码就能提供帮助：

给仓库加星，帮助其他人发现这个项目
在 Issues 中报告 Bug 或请求新功能
在 Discussions 中加入社区
为代码、文档或主题提交 PR

更多详情请参阅 CONTRIBUTING.md！

维护者

由 LargeModGames 维护（Twitter 上的 @LargeModGames）。

最初复刻自 Alexander Keliris 的 spotify-tui。

代码签名政策

免费代码签名由 SignPath.io 提供，证书由 SignPath Foundation 提供。

Windows 发布文件由 release workflow 在 GitHub 托管的运行器上从此仓库构建。每个签名请求都经过人工批准。

提交者和审核者：LargeModGames、ThatModGames、shilicioo、2570165831
批准者：LargeModGames

隐私：有关 spotatui 发送的数据以及如何关闭各部分，请参阅隐私政策。

spotatui 贡献者

正在寻找贡献者！spotatui 正在积极维护，但需要你的帮助。无论是 Bug 修复、新功能、文档还是测试——所有贡献都欢迎！

_{LargeModGames} 💻 📖 🚧 🤔 🚇 ⚠️	_{MysteriousWolf} 💻	_rawcode1337 💻 🐛	_copeison 📦	_jacklorusso 📖	_H41L33 📖	_LordMZTE 💻 📦
_{Sebastian Sarco} 💻	_{Sergio Tabernero Hernández} 💻 📦	_{David Novakovic} 💻	_Paul 🎨 💻	_{Arun Felix} 💻 🐛	_MaySeikatsu 💻 📖 📦	_{Lorenzo Bodini} 💻 🎨
_{Vi1i Petal} 💻 🐛	_{Will Sturgeon} 💻 🐛	_wfinken 💻 🐛	_Jacob 📦	_{Dominick Lee} 💻	_{Higor Prado} 💻	_{Vitali Kaplich} 📖
_knth 💻	_{Lorelei Noble} 💻	_{Ben Allen} 💻	_shilicioo 💻	_{Thomas Allan} 💻	_{Pratyoosh Prakash} 💻 🐛	_{Tahmid Ahmed} 💻
_Ritze 💻 🐛	_Hansen 📖	_{Yusuke Hayashi} 💻 📖	_Felix 💻	_{Dino Leung} 📦	_{Szabó István} 📖	_{Alessandro Zanni} 💻
_nohint404 💻	_TongTong0828 💻	_Hi-1mYara 💻 📖	_Oud 💻	_Yvoo 💻	_{Maurice Schmicking} 💻	_2570165831 💻
_{Tayfur Yıldız} 💻	_{Vladimir Babin} 💻	_Kratos 💻	_niukanen1 💻	_{Trevor Satori} 💻 🐛	_Y.B. 💻	_{Ufuk Emre Yücetürk} 💻
_{WaterWhisperer} 📖	_{Marc Bauer} 💻 💵	_RohithPariki 💻	_{Muaaz Bhyat} 💻	_점[dot] 💻	_Samuel 📖	_{TastyHeadphones} 📖
_Michael 💻	_Battlelamb 📖

想在这里看到你的名字？查看我们的开放议题或下方的路线图！

上游贡献者（spotify-tui）

感谢所有构建了本项目所分叉自的原始 spotify-tui 的贡献者：

_{Alexander Keliris} 💻 📖 🎨 📝 🤔 🚇 📦 👀	_{Mickael Marques} 💵	_{Grzegorz Koperwas} 📖	_{Austin Gassert} 💻	_{Calen Robinette} 💻	_MCO 🚇
_{Andrew Chin} 💻	_{Sam Naser} 💻	_Micha 💻	_neriglissar 💻	_Timon 💻	_echoSayonara 💻	_D-Nice 📖 🚇
_{Grzegorz Pawlik} 💻	_{Lennart Bernhardt} 💻	_{Arnaud Lefebvre} 💻	_tem1029 💻	_{Peter K. Moss} 💻	_{Geoff Shannon} 💻	_{Zachary Mayhew} 💻
_jfaltis 💻	_{Marcel Schramm} 📖	_{Fangyi Zhou} 💻	_Max 💻	_{Sven van der Vlist} 💻	_{jacobchrismarsh} 💻	_{Nils Rauch} 💻
_{Nick Stockton} 💻 🐛 🚧 💬 📖	_{Stuart Hinson} 💻	_{Sam Calvert} 💻 📖	_{Jeroen Wijenbergh} 📖	_{Kimberley Cook} 📖	_{Audrey Baxter} 💻	_Norman 📖
_{Peter Maatman} 💻	_AlexandreS 💻	_{Finn Vos} 💻	_{Carlos Hernandez} 📦	_{Pedro Alves} 💻	_jtagcat 📖	_{Benjamin Kitor} 💻
_{Aleš Najmann} 📖 📦	_{Jeremy Stucki} 💻	_(´⌣`ʃƪ) 💻	_{Artem Polishchuk} 📦	_{Chris Sosnin} 💻	_{Ben Buhse} 📖	_{Sean Li} 💻
_{TimotheeGerber} 💻 📖	_{Ferdinand Ratajczak} 💻	_{Sheel Choksi} 💻	_{Michael Hellwig} 📖	_{Oliver Daniel} 💻	_{Drew Fisher} 💻	_ncoder-1 📖
_{Macguire Rintoul} 📖	_{Ricardo Holguin} 💻	_{Keisuke Toyota} 💻	_{Craig Astill} 💻	_Onielfa 💻	_usrme 📖	_{Sergey A.} 💻
_{Hideyuki Okada} 💻	_kepae 💻 📖	_{Érico Nogueira Rolim} 💻	_{Alexander Meinhardt Scheurer} 💻	_{Ondřej Kinšt} 💻	_Kryan90 📖	_n-ivanov 💻
_bi1yeu 💻 📖	_May 💻	_{Bruno A. Muciño} 💻	_{Finn Hediger} 💻	_dp304 💻	_{Marco Micera} 📖	_{Marco Ieni} 🚇
_{Artúr Kovács} 💻	_{Antony Kellermann} 💻	_{Rasmus Pedersen} 💻	_noir-Z 📖	_{David Bailey} 📖	_sheepwall 💻	_Hwatwasthat 💻
_Jesse 💻	_Sang 📖	_{Yuuki Takahashi} 📖	_{Alejandro Angulo} 💻	_{Anton Kostin} 📖	_{Justin Sexton} 💻	_{Jiati Le} 📖
_{Matthew Cobbing} 💻	_Milo 🚇	_{Diego Veralli} 💻	_{Maja Bojarska} 💻