# Fastpotify **Spotify, native and fast.** A lightweight Spotify client written in Rust with [egui](https://github.com/emilk/egui), playing music through [librespot](https://github.com/librespot-org/librespot). It runs on Linux, macOS, and Windows, starts in well under a second, and stays small while it runs. There is no browser engine anywhere in the process. **Playing needs Spotify Premium.** Spotify only lets Premium accounts play music through another app, on the computer itself or on any other device. With a Free account Fastpotify can browse the library but not play it, and says so at sign-in. Fastpotify follows in the footsteps of [Omarchy Spotify](https://github.com/stappmus/Omarchy-Spotify) and [spotify-tui](https://github.com/Rigellute/spotify-tui): the familiar Spotify layout, access to your library, and a Spotify Connect receiver in one desktop application rather than a shell plugin. ![Fastpotify showing a playlist, with the queue open and a track playing on a remote speaker](docs/screenshot.png) **Documentation:** [fastpotify.rocks](https://fastpotify.rocks/): what it is, getting started, everyday use, and how it connects to Spotify. ## What it does - **Plays music on this computer.** Fastpotify is a Spotify Connect device. Pick it from your phone, or press play here. Gapless, up to 320 kbps, with optional volume normalisation and an on-disk audio cache. - **Controls other devices.** Move playback to a speaker, a phone, or another computer from the device picker, and keep controlling it: play, pause, skip, seek, shuffle, repeat, volume. - **Finds speakers on your network.** A librespot, spotifyd, or hardware receiver waiting on the LAN is invisible to Spotify's API until it has an account. Fastpotify discovers those over mDNS and connects them for you, after which they behave like any other Spotify Connect device. - **Library access.** Playlists, Liked Songs, saved albums, followed artists, podcasts, and saved episodes, filterable in the sidebar and as full pages. Sidebar rows pin to the top and drag into your own order. - **Search** across songs, artists, albums, playlists, podcasts, and episodes, with a top result and per-type views. - **Home** with Made for you, Recently played, your top artists and songs, and recommendations. - **Artist pages** with popular songs, a filterable discography, and related artists. **Album**, **playlist**, and **podcast** pages support playback from any row. - **Playlists you own** can be created, renamed, described, reordered, and edited: add from any row's menu or by dragging a song onto the playlist in the sidebar, remove from the playlist page. - **Queue** as a side panel or a page; add anything to it from a row menu. - **Album-art colour.** Pages and the player bar take a tint from the cover of what you are looking at or listening to. Turn it off in Settings. - **Light and dark**, or follow the system. - **Winamp mini player.** `Ctrl+M` turns the window into a tiny player that wears classic `.wsz` skins, drawn pixel for pixel at 1x to 4x, with the spectrum analyser, the playlist, and the equalizer hanging under it as they did; the logo in the skin brings the big window back. Drop a skin from the [Winamp Skin Museum](https://skins.webamp.org) on either window to add it. - **Equalizer.** Winamp's ten bands and presets over the music played on this computer, in Settings and in the skin. - **Keyboard-first.** Every common action has a shortcut (`Ctrl+/` or `?` lists them). - **Keeps playing when you close the window.** The window closes for real, the music and the process stay in the system tray (Linux status notifier), and clicking the tray, or your desktop's media controls, brings a window back. No compositor-specific tricks, so it behaves the same on any desktop. Quit from the tray menu or `Ctrl+Q`; turn the behaviour off in Settings if you prefer close-to-quit. On macOS the Dock icon stays present, and clicking it opens the window again. - **Visible network activity.** Pages show spinners while they load. An indicator appears in the top bar when a Spotify request takes more than a moment or is waiting for a rate limit. - **One instance.** Launching it again brings the existing window forward instead of starting a second copy, on every platform. - **Desktop integration.** MPRIS on Linux, so media keys, the shell, and `playerctl` see Fastpotify like any other player. On macOS and Windows, `fastpotify next` and its siblings drive the running app from a terminal, a launcher, or a hotkey. ## Install On Arch Linux, Fastpotify is in the AUR: ```bash yay -S fastpotify # the released build yay -S fastpotify-git # built from the latest commit ``` On macOS, with [Homebrew](https://brew.sh): ```sh brew install --cask crmne/tap/fastpotify ``` Everywhere else it is a single binary. Build it with a stable Rust toolchain (1.95 or newer): ```bash cargo install --path . ``` On Linux you also need the development packages for ALSA, PulseAudio (which covers PipeWire), and the usual windowing libraries, for example on Arch: ```bash sudo pacman -S --needed alsa-lib libpulse libxkbcommon wayland ``` and on Debian or Ubuntu: ```bash sudo apt install libasound2-dev libpulse-dev libxkbcommon-dev libwayland-dev ``` With [Nix](https://nixos.org), `nix develop` provides all of it, along with the exact toolchain `rust-toolchain.toml` pins. Titles in a script the interface font does not cover -- Chinese, Japanese, Korean, Arabic, Hebrew, Thai, the Indic scripts and a dozen more -- are drawn with a face borrowed from the system rather than bundled, which would cost more than ten megabytes for Chinese alone. macOS and Windows carry faces for the common ones; on Linux install the Noto families for the scripts you listen to, for example `noto-fonts` and `noto-fonts-cjk` (Arch) or `fonts-noto` and `fonts-noto-cjk` (Debian or Ubuntu). A script with no face installed still shows as empty boxes. A desktop entry is provided in `packaging/applications/fastpotify.desktop`. ## Sign in Press **Sign in with Spotify**. Your browser opens Spotify's own consent page (Authorization Code with PKCE); Fastpotify never sees your password. When Spotify redirects back to the app, your library, search, and control of other devices work immediately. The refresh token is stored in the platform's state directory (`~/.local/state/fastpotify` on Linux), so the browser is needed once per machine. Playing music **on this computer** is one more one-time browser approval. Spotify treats streaming as a separate grant for its own client identity, which is what librespot plays with. Take it from the device menu ("Play here, set up once") or Settings; it needs Spotify Premium, and librespot stores a reusable credential for later sessions. Browsing works on any account without this step; playing, here or on another device, does not, because Spotify's API only takes playback commands from Premium accounts. The Web API always keeps shared catalog coverage. You can also register a personal Spotify Development Mode app and paste its Client ID in Settings → Account; supported requests use its separate quota while complete playlist views, playlist-bearing search, external playlists, and unavailable operations continue through the shared app. ## Account safety We are not aware of a Spotify account being suspended for using Fastpotify or another librespot player with Premium. Sign-in happens on Spotify's own pages, audio uses the quality included with Premium, DRM stays intact, and Fastpotify does not rip tracks or block ads. Reported suspensions usually involve modded apps that remove ads from free accounts, track ripping, or stream manipulation. Fastpotify does none of those things, and [CONTRIBUTING.md](CONTRIBUTING.md) prohibits them. ## Keyboard shortcuts | Shortcut | What it does | | --- | --- | | `Space` | Play or pause | | `Ctrl+←` / `Ctrl+→` | Previous or next | | `Shift+←` / `Shift+→` | Seek 10 seconds | | `Ctrl+↑` / `Ctrl+↓` | Volume | | `M` | Mute | | `S` / `R` | Shuffle / cycle repeat | | `Q` | Queue panel | | `Ctrl+F` or `/` | Search | | `Ctrl+B` | Show or hide the sidebar | | `Alt+←` / `Alt+→` | Back or forward | | `Ctrl+H` / `Ctrl+L` | Home / Liked Songs | | `Ctrl+Shift+A` / `Ctrl+Shift+B` | Playing artist / album | | `Ctrl+M` | Winamp mini player | | `Ctrl+,` | Settings | | `Ctrl+/` or `?` | All shortcuts | | `Ctrl+Q` | Quit | On macOS, `Cmd` replaces `Ctrl`. ## Controlling it from outside On Linux, Fastpotify is an MPRIS player, so `playerctl --player=fastpotify play-pause` already works. macOS and Windows have no such bus, so the same verbs are subcommands. They talk to the instance already running and print nothing on success: ``` fastpotify play-pause fastpotify volume 40 fastpotify play fastpotify volume-up [percent] fastpotify pause fastpotify volume-down [percent] fastpotify next fastpotify mute fastpotify previous fastpotify shuffle [on|off] fastpotify seek 15 fastpotify repeat [off|context|track] fastpotify seek -- -15 fastpotify like fastpotify seek-to 90 fastpotify play-uri spotify:playlist:37i9… fastpotify show fastpotify transfer fastpotify now-playing [--raw] fastpotify devices [--raw] ``` `shuffle` and `repeat` toggle when asked for nothing in particular and set the state outright when given one, which is what a button that draws the current state wants: a missed update otherwise leaves the two disagreeing until the next press. `like` saves the playing track to your library, or takes it back out. `now-playing` prints one readable line; `--raw` prints the fields tab-separated (state, title, artists, album, position_ms, duration_ms, volume, shuffle, repeat, art_url, saved, device) for a script that wants one of them. `saved` is `yes`, `no`, or `unknown` while the answer is still on its way. The last three fields were added after the first nine, and appended rather than woven in, so a script written against the older shape still reads correctly. `devices` lists the Spotify Connect devices, id first, the active one marked with `*`; `--raw` prints them as JSON. The app only refreshes that list while its own picker is open, so asking for it also asks it to look again: on a cold list the first call can come back empty and the next one has it. A verb exits non-zero when Fastpotify is not running. Launchers such as Raycast or Alfred can use these commands to control playback. The Stream Deck plugin speaks the same channel, which is why the verbs cover more than a media key can ask for. ## Settings Settings live in one readable JSON file (`~/.config/fastpotify/settings.json` on Linux). They include the Connect device name, bitrate, normalisation, autoplay, gapless playback, the audio backend (PulseAudio/PipeWire or ALSA on Linux), audio cache size, theme, sidebar state, whether pages take colour from artwork, and the mini player's skin and size. Playback settings apply when you press **Apply and restart playback**. Caches (audio, artwork) live under the cache directory and can be deleted at any time without signing you out. ## How it is built - `src/player.rs`: the librespot session, player, mixer, and Spirc (Spotify Connect) wrapped into one engine that folds player events into a state snapshot for the interface. - `src/api/`: one routing gateway over independent shared and personal Web API sessions, each with bounded concurrency and coordinated `Retry-After` handling. Capability profiles select current endpoint contracts before a request is dispatched. - `src/backend.rs`: a tokio runtime on its own thread; the interface talks to it through channels and is woken with `request_repaint`, so the app is idle when nothing happens. - `src/images.rs`: album art as an egui bytes loader with a disk cache and time-based eviction, plus the accent-colour extraction. - `src/app.rs`, `src/model.rs`, `src/ui/`: state, navigation, and the views. Views collect `Action`s while drawing and the app applies them afterwards. - `src/mpris.rs`: Linux media controls on a dedicated thread. Fastpotify pins its Rust toolchain in `rust-toolchain.toml`; `cargo test` covers the API models, dual-session routing, PKCE, the player state machine, and a headless render of every page, panel, and dialog. To look at the interface without a Spotify account, build with the `demo` feature and start it with sample data: ```bash cargo run --features demo -- --demo --demo-page playlist:pl1 --demo-show queue ``` Demo mode never writes settings. `--demo-shot ` writes the window to a PNG and exits, which is how the screenshot above is made. ## Contributing Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request. It describes the project's design principles, product boundaries, and the complete local checks that every change must pass. ## Acknowledgements Fastpotify stands on [librespot](https://github.com/librespot-org/librespot), [egui](https://github.com/emilk/egui), the [Inter](https://rsms.me/inter/) typeface (OFL), and [Lucide](https://lucide.dev) icons (ISC). Fastpotify is an independent project and is not affiliated with Spotify. Spotify is a trademark of Spotify AB. Licensed under the [MIT License](LICENSE).