Omarchy Spotify

Spotify in Quickshell—not Chromium.

Omarchy Spotify brings the Spotify experience you already know into a fast, beautiful Omarchy plugin. It uses about 60 MB of RAM instead of roughly 950 MB for the Spotify desktop client, follows your active Omarchy theme, and keeps your music close with an integrated mini player.

Pair it with Omasing and lyrics for the song you are playing are fetched for you, ready when you want them.

Install

omarchy plugin add https://github.com/stappmus/Omarchy-Spotify.git --enable

Requires Omarchy 4 and a personal Spotify Premium account.

Why you will love it

• Lightweight by design. Enjoy your music without keeping a browser-sized desktop client running.
• Made for Omarchy. Every color follows your current theme automatically, including light themes.
• Always within reach. Play, pause, skip, seek, change volume, or open lyrics from the mini player in your bar. Your last song stays loaded, so Play picks up where you left off even after the player has gone idle.
• Your full music library. Search Spotify, browse artists and albums, manage playlists and the queue, and move playback between Spotify Connect devices.
• Lyrics with Omasing. Open the current song in Omasing and let it find the right lyrics and playback position automatically.

Familiar from the first click

The layout is inspired by the Spotify client, so there is almost nothing new to learn. Your library and playlists live in the sidebar, search stays at the top, the player stays at the bottom, and artist and album names take you straight to their pages.

Prefer to keep your hands on the keyboard? The whole app is designed for that too.

The first shortcut, Tab, or opening the player from the keyboard lights matching controls with the next key. Hold Ctrl, Shift, or Alt to see those chords; the matching hints remain until you release the held modifiers. While hints are visible, the header keeps a Ctrl+H · Hide hints action in reach. It turns hints off until you enable them again in Settings.

The mini-player takes keyboard focus when it is opened from a shortcut. Use Tab or the arrow keys to select every control, Enter to activate buttons, left/right to adjust a selected slider, and Esc to close. The playback shortcuts above work there too; Ctrl+S toggles shuffle, Ctrl+R cycles repeat, Ctrl+Shift+L opens lyrics, Ctrl+Shift+A and Ctrl+Shift+B open the current artist or album in the full player, and O expands the full player.

See it in action

Your playlists, instantly familiar

Everything is where you expect it to be—just faster, lighter, and dressed in your Omarchy theme.

Everything from an artist, in one view

Top albums and EPs sit beside the artist's ten biggest songs, with their This Is playlist and full catalog only a search away.

Lyrics, already matched to the song

One click sends the current track to Omasing, where the lyrics are fetched and lined up with your playback position—ready to auto-scroll as you listen.

A mini player that belongs in your desktop

The essentials are always one click away, without reopening the full app.

Set it up

To replace Omarchy's existing Super+Shift+M · Music binding, add this to ~/.config/hypr/bindings.lua:

  hl.unbind("SUPER + SHIFT + M") -- previously: Music
  o.bind("SUPER + SHIFT + M", "Omarchy Spotify",
    "omarchy shell -q quickshell.spotify.player togglePlayer")

Run hyprctl reload and check hyprctl configerrors after saving. Until the binding is replaced, Omarchy's stock Music binding stays active and the Settings choice below has no effect on the shortcut.

In Omarchy Spotify's Settings, choose whether that shortcut launches Omarchy's Music app, toggles the full player, or toggles the mini-player. Separate bindings can call toggleMiniPlayer or toggleFullPlayer on the same quickshell.spotify.player target.

Raise or lower Spotify volume from a keybinding without opening the player:

omarchy shell -q quickshell.spotify.player volumeUp
omarchy shell -q quickshell.spotify.player volumeDown

Each step is 5%, the same as Ctrl+Up / Ctrl+Down. This changes Spotify's own volume, including speakers, not the computer's output level.

Click the Spotify icon on the left side of the bar. The mini-player asks you to Set up and continue, then Spotify sign-in finishes in your browser. You can move the widget later with Omarchy's bar controls.

Local playback installs an exact-version backend only after its GitHub build provenance matches this plugin version's tag and the checkout's backend inputs still match that tagged source. If verification is unavailable, setup builds the locked Rust source locally or offers Omarchy's packaged spotifyd fallback instead of executing an unverified download.

Seeing "Spotify is busy." or slow searches?

The plugin's Spotify Web API client ID is shared by every install worldwide, and Spotify rate-limits requests per app, not per user. When that shared quota runs out you see Spotify is busy. Try again in N seconds. and searches that stall even though nothing is wrong on your side.

You can use a personal Spotify Developer app with a separate quota. This does not provide unlimited requests or restore restricted endpoints.

1. Add http://127.0.0.1:8989/login as the app's redirect URI.
2. Set Spotify Developer app client ID in the plugin settings. Leave it empty to use the shipped app. Invalid IDs produce an error.
3. Authorize the selected app. Changing the ID clears the current session and account data; stored sessions are isolated by client ID.

Development apps require an eligible Premium owner and allowlisted users, and have endpoint restrictions. See Spotify's quota modes. The local Connect authorization remains separate.

Remove it completely

Run the bundled uninstaller from outside the plugin directory:

cd "$HOME" && "$HOME/.config/omarchy/plugins/quickshell.spotify/scripts/uninstall.sh"

It disables and removes the plugin, stops and removes both user services, restarts the shell, and deletes all plugin-owned configuration, cached audio, backend build files, installed binaries, playback state, runtime sockets, old configuration backups, and matching GNOME Keyring entries.

If you prefer to inspect and paste the main steps individually:

plugin_dir="$HOME/.config/omarchy/plugins/quickshell.spotify"
cd "$HOME"
omarchy plugin disable quickshell.spotify 2>/dev/null || true
"$plugin_dir/scripts/remove-runtime.sh" --purge
omarchy plugin remove quickshell.spotify --yes
omarchy restart shell

The cleanup deliberately leaves unrelated software alone. A source checkout outside Omarchy's plugin directory, separate plugins such as Omasing, and the spotifyd package remain in place. If this plugin was the only reason you installed the fallback package, remove it with:

omarchy pkg drop spotifyd

Very old installation instructions may also have added a custom Hyprland shortcut. The uninstaller reports any such references without rewriting your personal configuration. Check both the live config and, when applicable, its chezmoi source:

rg -n 'quickshell\.spotify|Omarchy Spotify' \
  "$HOME/.config/hypr" "$HOME/.local/share/chezmoi" 2>/dev/null

Remove only the matching custom lines, apply the dotfiles change, and run hyprctl reload. Omarchy's stock Super+Shift+M Music shortcut will then be used again.

More music, less app

• Discover Weekly, Release Radar, Daily Mixes, daylist, and more in Discover.
• Browse Liked Songs, saved albums, followed artists, podcasts, and books.
• Create playlists, add songs, reorder tracks, and turn followed playlists into your own editable copies when Spotify makes their contents available.
• Build a queue, start track radio, use shuffle and repeat, or set a sleep timer.
• Listen on this computer or switch to another Spotify Connect speaker or player.
• Choose the mini-player or full player independently for the bar icon and keyboard shortcut, use optional spinning vinyl artwork in the mini-player, show the title, artist, or both, and softly scroll overflowing text at an adjustable speed.
• Choose up to 320 kbps for local playback.

Your Spotify password is entered only on Spotify's own page. Omarchy Spotify stores your saved session in GNOME Keyring and clears it when you log out.

Want the details? Read the technical notes or see the memory benchmark.

Omarchy Spotify is an independent project and is not affiliated with Spotify. Spotify is a trademark of Spotify AB.

Licensed under the MIT License.