openmp3 is a fast, low-memory Spotify client for Windows that you sign into with your own Premium account. It starts in about half a second, plays 320 kbps audio through its own Rust engine, and its entire UI is a sandboxed theme you can replace.

Screenshots · Build & run · Themes · How it works · Theme guide

[!IMPORTANT] This is a personal-use project. It needs a Spotify Premium account; librespot quits on Free accounts. It is not affiliated with or endorsed by Spotify.

Why

The official desktop app is a full Chromium bundle that idles at hundreds of megabytes, nags, and adds itself to startup. openmp3 keeps only what's needed for everyday listening. It uses the system WebView2 for the UI and a native Rust engine for login, streaming, the queue and audio.

Measured on the dev PC (release build, Default theme, scripts/measure.ps1, 2026-10-07):

Screenshots

Search: songs, artists, albums, playlists and podcasts.	Artist and album pages, plus song radio and recommendations.
Ctrl+K command bar: run any action or jump to any song from the keyboard.	10-band EQ with presets, crossfade, normalization and cache size.
Themes replace everything: the bundled Spectrum example moves the player bar and adds a visualizer.	Mini player: always-on-top window. Closing the main window keeps music playing in the tray.

Features

All library, search, home and lyrics data comes from Spotify's internal endpoints through the librespot session. No developer app, client ID or Web API key is involved. The endpoint code is isolated in engine-api/src/endpoints.rs, so breakages are a one-file fix (reference).

Build and run

Download: grab the x64-setup.exe installer or the portable.exe from the latest release. Builds are unsigned, so Windows SmartScreen may ask you to confirm (More info → Run anyway). Checksums are in SHA256SUMS.txt.

Build from source requirements: Windows 11 (WebView2 is preinstalled), Rust (the repo pins the MSVC toolchain in rust-toolchain.toml), and the Visual Studio 2022 Build Tools with the C++ workload.

git clone https://github.com/Hero62/openmp3.git
cd openmp3/src-tauri
cargo build --release

Then run src-tauri/target/release/openmp3.exe (about 11 MB). On first launch, click Log in to Spotify in the sidebar. The sign-in happens in your browser through Spotify's own OAuth page; openmp3 never sees your password and caches only Spotify's reusable token in %APPDATA%\openmp3.

scripts/rebuild-run.sh                      # debug build with DevTools protocol on :9222
node scripts/cdp.mjs shot out.png           # screenshot the running UI
node scripts/cdp.mjs eval "mp3.nowPlaying" frame   # run JS inside the theme sandbox
cd src-tauri && cargo test --workspace      # unit tests

Themes

The whole interface is a theme running in a sandboxed iframe. The built-in Default theme uses exactly the same public API as any theme you install, so anything it does, yours can do or replace.

A .theme file is a zip with up to four layers:

The Themes page imports .theme files, and can apply, duplicate, export or edit them. It can also live-link a folder that hot-reloads on every save, copy the full theme guide (handy for pasting into an AI agent), and show a performance meter. The examples/visualizer theme (examples/Spectrum.theme) uses all four layers.

[!NOTE] Themes are sandboxed and can't reach the network, your files, Tauri APIs or your Spotify credentials. Every command is checked against a whitelist twice: by the host page, then by the Rust bridge. Windows asks for your OK before a third-party theme can edit theme files, change global hotkeys, turn on lyrics translation or change the cache size. A frozen or crashing theme is replaced with Default automatically, and Ctrl+Shift+D always resets to Default.

How it works

flowchart LR
  subgraph UI["WebView2 (system)"]
    host["Host page<br/>relay · whitelist · watchdog"]
    theme["Theme sandbox<br/>(iframe, strict CSP)<br/>runtime + Default theme"]
    theme <-- postMessage --> host
  end
  subgraph Engine["openmp3.exe (Rust)"]
    bridge["engine-bridge<br/>validated commands"]
    api["engine-api<br/>internal endpoints + SQLite cache"]
    queue["engine-queue"]
    audio["engine-audio<br/>librespot → EQ → cpal"]
    session["engine-session<br/>OAuth · reconnect"]
    connect["engine-connect<br/>Spotify Connect"]
  end
  host <-- Tauri IPC --> bridge
  bridge --> api & queue & audio
  session --> api & audio
  connect --> audio
  audio --> speakers(("🔊 WASAPI"))

The engine is a Cargo workspace in src-tauri/crates. Requirements live in SPEC.md, per-stage status and how each item was verified in PLAN.md, and current state, measurements and known issues in HANDOFF.md.

Known limitations

• Premium accounts only (a librespot restriction).
• Search, the home feed and parts of artist pages use Spotify GraphQL query hashes that change occasionally; they're kept in one table in endpoints.rs.
• Spotify's reusable login token is stored unencrypted in %APPDATA%\openmp3\credentials (librespot's format). Any program running under your Windows account can read it.
• Japanese kanji and Chinese characters aren't romanized (that needs a dictionary).
• No lossless, offline downloads, Jam, DJ, video podcasts or Canvas. These are out of scope for v1.

Credits

Built on librespot for Spotify playback and the Connect protocol, Tauri for the shell, and cpal for audio output. Endpoint research drew on go-librespot and Spotify's web player.

Released under the MIT License. Spotify is a trademark of Spotify AB.