Fastpotify

原生且快速的 Spotify 客户端。 一个用 Rust 编写的轻量级 Spotify 客户端，使用 egui 构建界面，通过 librespot 播放音乐。它可在 Linux、macOS 和 Windows 上运行，启动时间远低于一秒，运行期间保持小巧。整个进程内没有浏览器引擎。

Fastpotify 继承了 Omarchy Spotify 和 spotify-tui 的思路：熟悉的 Spotify 布局、完整曲库、Spotify Connect 接收器，作为一个普通桌面应用呈现，而不是 shell 插件。

文档： fastpotify.rocks：包含项目介绍、快速上手、日常使用以及如何连接 Spotify。

功能

• 在本机播放音乐。 Fastpotify 是一个 Spotify Connect 设备。你可以从手机端选中它，或直接在此处按下播放。支持无缝播放、最高 320 kbps，可选音量标准化和磁盘音频缓存。
• 控制所有其他设备。 通过设备选择器将播放转移到扬声器、手机或其他电脑，并持续控制：播放、暂停、跳过、快进/后退、随机、循环、音量。
• 发现网络中的扬声器。 局域网中等待的 librespot、spotifyd 或硬件接收器在关联账户之前对 Spotify API 不可见。Fastpotify 通过 mDNS 发现这些设备并替它们连接，之后它们就像任何其他 Spotify Connect 设备一样工作。
• 完整曲库。 播放列表、喜欢歌曲、保存的专辑、关注的艺人、播客、保存的单集，可在侧边栏筛选并完整展示。
• 搜索 歌曲、艺人、专辑、播放列表、播客和单集，带有最佳结果和分类视图。
• 主页 包含“为你推荐”、最近播放、最常听的艺人和歌曲，以及推荐内容。
• 艺人页面 包含热门歌曲、可筛选的唱片目录和相关艺人。专辑、播放列表和播客页面中的所有行均可播放。
• 可管理自己创建的播放列表：可从任意行菜单添加、在播放列表页面删除、重命名、修改描述和重新排序。
• 队列 可作为侧边栏或页面，可从行菜单添加任意内容。
• 专辑封面取色。 页面和播放器栏会从当前查看或收听的封面中提取色调。可在设置中关闭。
• 浅色和深色主题，或跟随系统。
• 键盘优先。 每个常见操作都有快捷键（Ctrl+/ 查看全部）。
• 关闭窗口时继续播放。 窗口真正关闭，但音乐和进程保留在系统托盘（Linux 状态通知器）中。点击托盘图标或桌面媒体控件可重新打开窗口。不使用任何合成器特定技巧，因此在任何桌面上行为一致。可从托盘菜单或 Ctrl+Q 退出；如果偏好关闭即退出，可在设置中关闭此行为。
• 网络状态透明。 页面加载时显示转圈，每当应用与 Spotify 通信时间稍长，顶部栏会出现静默指示器；如果 Spotify 要求应用退避，你会看到等待状态，而不是一次莫名暂停。
• 单实例。 再次启动会唤出已打开的窗口，而不是启动一个新的重复副本，在所有平台上均如此。
• 桌面集成。 Linux 上支持 MPRIS，媒体键、系统 shell 和 playerctl 可以像对待其他播放器一样识别 Fastpotify。

安装

在 Arch Linux 上，Fastpotify 位于 AUR：

yay -S fastpotify          # 发布版
yay -S fastpotify-git      # 基于最新提交构建

在 macOS 上，使用 Homebrew：

brew install --cask crmne/tap/fastpotify

其他平台为单一二进制文件。使用稳定版 Rust 工具链（1.95 或更新）构建：

cargo install --path .

在 Linux 上还需要 ALSA、PulseAudio（涵盖 PipeWire）以及常见窗口库的开发包，例如 Arch：

sudo pacman -S --needed alsa-lib libpulse libxkbcommon wayland

Debian 或 Ubuntu：

sudo apt install libasound2-dev libpulse-dev libxkbcommon-dev libwayland-dev

使用 Nix 时，nix develop 会提供所有依赖，以及 rust-toolchain.toml 固定的精确工具链。

界面字体未覆盖的脚本语言标题——中文、日文、韩文、阿拉伯文、希伯来文、泰文、印度诸文字等十几种——会借用系统字体而非内置，否则仅中文就需要超过十兆字节。macOS 和 Windows 自带常见字体；在 Linux 上安装对应语言的 Noto 字体家族，例如 noto-fonts 和 noto-fonts-cjk（Arch）或 fonts-noto 和 fonts-noto-cjk（Debian 或 Ubuntu）。未安装字体的文字将显示为空方框。

桌面条目位于 packaging/applications/fastpotify.desktop。

登录

点击 使用 Spotify 登录。你的浏览器会打开 Spotify 官方的同意页面（授权码 + PKCE）；Fastpotify 永远不会看到你的密码。当 Spotify 重定向回应用后，曲库、搜索和控制其他设备的能力立即生效。刷新令牌存储在平台状态目录（Linux 上为 ~/.local/state/fastpotify），因此每台机器只需一次浏览器操作。

在本机播放音乐 还需要一次性浏览器授权。Spotify 将流媒体视为对其自有客户端身份（librespot 使用该身份进行播放）的单独授权。可通过设备菜单（“在此播放，一次性设置”）或设置中启用；需要 Spotify Premium，librespot 存储可复用凭据，因此也不会再次询问。浏览和远程控制无需此步骤，任何账户均可使用。

默认 Web API 使用与 spotify-player、ncspot 和 Omarchy Spotify 相同的共享公共应用。如果遇到速率限制，你可以注册自己的（免费）Spotify 应用，并在设置 → 账户中粘贴其客户端 ID。

键盘快捷键

在 macOS 上，Cmd 代替 Ctrl。

设置

所有设置存放在一个易读的 JSON 文件（Linux 上为 ~/.config/fastpotify/settings.json）：Connect 设备名称、比特率、标准化、自动播放、无缝播放、音频后端（Linux 上为 PulseAudio/PipeWire 或 ALSA）、音频缓存大小、主题，以及页面是否从封面取色。播放设置在点击 应用并重启播放 后生效。

缓存（音频、封面）存放在缓存目录下，随时可以删除，不会退出登录。

技术实现

• src/player.rs：将 librespot 会话、播放器、混音器和 Spirc（Spotify Connect）封装为一个引擎，把播放器事件折叠成界面所需的状态快照。
• src/api/：一个小型 Web API 客户端，具有有界并发、Retry-After 处理，以及 2026 年端点形态（/me/library、/playlists/{id}/items）与经典形态之间的自动回退。
• src/backend.rs：一个在独立线程上的 tokio 运行时；界面通过通道与其通信，并使用 request_repaint 唤醒，因此无事发生时应用处于空闲状态。
• src/images.rs：专辑封面作为 egui 字节加载器，带有磁盘缓存和时间淘汰，以及强调色提取。
• src/app.rs、src/model.rs、src/ui/：状态、导航和视图。视图在绘制时收集 Action，应用随后执行。
• src/mpris.rs：专用线程上的 Linux 媒体控制。

Fastpotify 在 rust-toolchain.toml 中固定了 Rust 工具链；cargo test 覆盖 API 模型、端点回退、PKCE、播放器状态机，以及每个页面、面板和对话框的无头渲染。

无需 Spotify 账户即可查看界面，可使用 demo 功能构建并附带示例数据启动：

cargo run --features demo -- --demo --demo-page playlist:pl1 --demo-show queue

演示模式绝不写入设置。--demo-shot <PATH> 将窗口写入 PNG 并退出，上面截图即如此生成。

致谢

Fastpotify 建立在 librespot、egui、Inter 字体（OFL）和 Lucide 图标（ISC）之上。

Fastpotify 是独立项目，与 Spotify 无关。Spotify 是 Spotify AB 的商标。

基于 MIT 许可证 发布。