A multi-platform, ultra-lightweight Spotify client built entirely from scratch in Rust.
⚡ Single process • 🦀 100% Rust • 🎵 Embedded librespot • 📦 No Electron • No Chromium • No Node.js
Spotifust started from a simple but slightly stubborn idea: why does a music player need to load an entire browser inside it? This project ditches heavy web engines (Electron/Chromium) and native OS wrappers (WinUI 3/WinRT) to deliver a single-process application with hardware-accelerated graphics and embedded audio streaming, straight from Rust.
No Node.js running behind the scenes, no full Chromium instance rendering four buttons. One binary, one process, and the GPU doing what it does best.
- 🎵 Native Spotify playback — Stream directly via embedded librespot, no browser engine
- 🖥️ Cross-platform — Windows (.msi), macOS (.dmg), and Linux (.tar.gz)
- ⚡ Ultra-lightweight — Target baseline under 25 MB RAM
- 🎨 GPU-accelerated UI — Powered by iced with tiny-skia rendering
- 🔐 Secure auth — PKCE OAuth flow, credentials stored in your OS keychain
- 🧩 Modular architecture — Clean MVU (Model-View-Update) following the Elm pattern
- 📦 Zero runtime dependencies — No Node.js, no JVM, no Python, no bundled browser
| Component | Technology | Description |
|---|---|---|
| GUI Framework | iced v0.14 |
Cross-platform GUI based on the Elm Architecture, focused on type-safety |
| Renderer | tiny-skia (via iced) |
Software 2D rendering with optional GPU acceleration |
| UI Layout | iced::widget::canvas |
Custom 2D canvas for draggable, resizable fluid cards |
| Spotify Web API | rspotify v0.16 |
Async Spotify Web API wrapper for search, playlists, metadata |
| Audio Streaming | librespot v0.8 |
Embedded engine for session management, DRM decryption, chunk fetching |
| Audio Playback | rodio v0.21 |
Cross-platform audio output to system sound drivers |
| Async Runtime | tokio v1.52 |
Multi-threaded async event loop for I/O-bound operations |
| Error Handling | thiserror v2 |
Derive macro for central AppError enum with per-subsystem variants |
| Credential Storage | keyring v4 |
OS-level secure credential store (Credential Manager / Keychain / Secret Service) |
Unlike traditional applications, Spotifust does not run separate sidecar processes. The entire ecosystem lives inside a single monolithic Rust binary:
┌─────────────────────────────────────────────────────────┐
│ Single Process │
│ │
│ ┌─────────────┐ Message ┌───────────────────┐ │
│ │ iced App │◄────────────►│ Model (State) │ │
│ │ View/Update│ └───────────────────┘ │
│ └──────┬──────┘ ▲ │
│ │ Canvas │ mpsc │
│ ┌──────▼──────┐ ┌─────────┴─────────┐ │
│ │ Card Layout│ │ tokio::spawn │ │
│ │ Engine │ │ ┌───────────────┐ │ │
│ └─────────────┘ │ │ librespot │ │ │
│ │ │ session │ │ │
│ │ └───────┬───────┘ │ │
│ │ │ PCM │ │
│ │ ┌───────▼───────┐ │ │
│ │ │ rodio sink │ │ │
│ │ └───────────────┘ │ │
│ └────────────────────┘ │
└─────────────────────────────────────────────────────────┘
- The Elm Engine (Model-View-Update):
iceddrives the state. TheModelholds the application data, theViewrenders the canvas primitives, and theUpdateprocesses incoming asynchronous events smoothly. - The Canvas Layout System: Instead of standard flexbox-style UI containers, the main dashboard uses a low-level
Canvaswidget with a custom spatial data structure tracking bounding boxes for each modular card, handling hardware input events directly for dragging and resizing. - In-Process Audio Core:
librespotis compiled directly as an internal module. It establishes direct TCP/TLS connections with Spotify's infrastructure, performs AES-128 DRM decryption internally, and feeds decoded PCM arrays directly into the system's hardware audio buffers via a bounded channel.
spotifust/
├── src/
│ ├── main.rs # Entry point & bootstrap
│ ├── app.rs # iced Application (MVU loop)
│ ├── error.rs # Central AppError enum (thiserror)
│ ├── api/
│ │ ├── mod.rs
│ │ └── auth.rs # PKCE OAuth flow & token management
│ ├── audio/
│ │ ├── mod.rs
│ │ ├── engine.rs # Playback control & track queue
│ │ ├── session.rs # librespot session management
│ │ └── sink.rs # rodio audio output sink
│ └── ui/
│ ├── mod.rs
│ ├── icons.rs # SVG icon definitions
│ ├── login.rs # Login screen view
│ ├── main_layout.rs # Main dashboard canvas layout
│ └── theme.rs # Color palette & styling
├── assets/ # App icons & resources
├── installer/ # WiX MSI installer sources
├── docs/ # Additional documentation
├── scripts/ # Developer & CI scripts
│ ├── build.sh # Unix packaging script
│ ├── build.ps1 # Windows packaging script
│ ├── test.sh # Unix test runner
│ └── test.ps1 # Windows test runner
├── install.sh # End-user Linux installation script
├── Cargo.toml
└── TODO.md # Development backlog & roadmap
- Rust 1.85 or later (2024 edition)
- A Spotify Premium account (required: Spotify's streaming API doesn't allow full playback on free accounts)
git clone https://github.com/gefydev/spotifust.git
cd spotifust
cargo build --releaseTip
Always build in --release mode. Debug builds with GPU rendering perform significantly worse and don't represent the real experience.
cargo run --releaseOn first launch, it'll ask for your Spotify Premium credentials to initialize the librespot session. Once authenticated, the session gets cached locally for future launches.
If you're registering your own app in the Spotify Developer Dashboard to use rspotify with your own API credentials:
export SPOTIFY_CLIENT_ID="your_client_id"Note
Spotifust uses the Authorization Code Flow with PKCE — no client secret is required for the desktop app's own auth.
Pre-built binaries are available on the Releases page with the following naming convention:
| Platform | File | Architecture |
|---|---|---|
| 🪟 Windows | spotifust-windows-x86_64-{version}.msi |
x86_64 |
| 🍎 macOS | spotifust-macos-aarch64-{version}.dmg |
Apple Silicon |
| 🍎 macOS | spotifust-macos-x86_64-{version}.dmg |
Intel |
| 🐧 Linux | spotifust-linux-x86_64-{version}.tar.gz |
x86_64 |
| 🐧 Linux | spotifust-linux-x86_64-{version}.deb |
Debian/Ubuntu |
Download the .tar.gz, extract it, and run the included ./install.sh script to install the app and register the spotifust:// protocol handler automatically. Alternatively, install the .deb package directly on Debian-based systems.
- Windows: Run
.\scripts\build.ps1in PowerShell. Requires the WiX v4 Toolset installed viadotnet tool install --global wix. - macOS: Run
./scripts/build.sh. Creates an.appbundle and packages it into a.dmg. - Linux: Run
./scripts/build.sh. Compresses the release binary into a.tar.gzarchive.
To ensure your code meets the quality standards of the project, we provide unified test scripts. They format the code, run clippy, run tests, and optionally perform dependency audits and typo checks.
# Unix
./scripts/test.sh
# Windows (PowerShell)
.\scripts\test.ps1The CI pipeline runs automatically on every push and PR:
| Workflow | Trigger | Purpose |
|---|---|---|
| CI | Push / PR | Build, clippy, tests |
| Release | Tag v* |
Build artifacts for all platforms & publish GitHub release |
| CodeQL | Push / PR / Schedule | Security & code quality analysis |
| Cargo Audit | Push / Schedule | Dependency vulnerability scanning |
| Cargo Deny | Push / PR | License & advisory compliance |
| Typos | Push / PR | Spell check across the codebase |
| Link Check | Push / PR | Verify all URLs in docs are alive |
Read TODO.md for the current development backlog and roadmap.
PRs are welcome! If you're planning to touch the audio core or the canvas engine, open an issue first to discuss the approach before sending code — those are the most delicate parts of the project.
Read CONTRIBUTING.md for guidelines.
This project is licensed under the GNU General Public License v3.0.
