Omarchy-Spotify README

The project's README from github.com/stappmus/Omarchy-Spotify. As one markdown file: README.md.

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

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.

Shortcut What it does
Ctrl+F or / Search
Ctrl+F or / again Toggle this area / all of Spotify
Tab / F6 Move between sidebar, search, the song list, and the player
Arrow keys Move to a control; Enter activates
C Row actions; arrows or Enter choose
Space Play or pause
Ctrl+Left / Ctrl+Right Previous or next song
Shift+Left / Shift+Right Seek 10 seconds
Ctrl+Up / Ctrl+Down Change volume
M Mute or restore volume
Ctrl+Shift+A Open the current song's artist
Ctrl+Shift+B Open the current song's album
Ctrl+/ See every keyboard shortcut
Ctrl+H Hide visible shortcut hints

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.

Shortcut hints guiding focus down the Recently played song list

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.

Vietnam War Music playlist in Omarchy Spotify

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.

Red Hot Chili Peppers artist page with Under the Bridge playing

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.

Omarchy Spotify beside Omasing lyrics for Under the Bridge

A mini player that belongs in your desktop

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

Omarchy Spotify mini player playing Under the Bridge

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

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.

Omarchy-Spotify (stappmus/Omarchy-Spotify)

Searching Database…

234 ·GitHub
Omarchy-Spotify
Что это?Omarchy Spotify — лёгкий клиент Spotify, созданный специально для рабочего стола Omarchy Linux: он работает внутри Quickshell, а не в обёртке на Chromium, поэтому потребляет намного меньше памяти, чем официальное десктопное приложение.
Это отдельное приложение или что-то встраиваемое?Это плагин Omarchy на QML для Quickshell, а не отдельное браузерное приложение — он живёт в панели Omarchy, следует вашей теме Omarchy и включает встроенный мини-плеер.
Как его настроить?Нажмите на значок Spotify слева на своей панели Omarchy; мини-плеер предложит «Set up and continue», после чего вход в Spotify завершится в вашем браузере.
Что нужно перед установкой?Нужны Omarchy 4 и личный аккаунт Spotify Premium; для локального воспроизведения дополнительно нужен бэкенд, собранный на Rust (или запасной spotifyd из пакета), который установка проверяет или собирает автоматически.
Почему иногда появляется «Spotify is busy» или медленный поиск?Плагин поставляется с одним общим client ID для Spotify Web API, который используют все установки по всему миру, а Spotify ограничивает частоту запросов по приложению, а не по пользователю, поэтому глобальный спрос может замедлять всех; вы можете зарегистрировать собственное приложение Spotify Developer и получить отдельную, но всё равно ограниченную квоту.
Видит ли он мой пароль от Spotify?Нет — пароль вводится только на собственной странице входа Spotify; плагин хранит полученную сессию в GNOME Keyring и стирает её при выходе из аккаунта.
Что такое Omasing и при чём он тут?Omasing — сопутствующее приложение Omarchy, которое автоматически подтягивает и выстраивает текст песни для играющего в Omarchy Spotify трека, готовый к автопрокрутке вслед за позицией воспроизведения.
Можно ли управлять воспроизведением, не открывая плеер?Да — отдельные сочетания клавиш повышают или понижают собственную громкость Spotify шагами по 5% и переключают мини-плеер или полный плеер, и почти у каждого действия (воспроизведение/пауза, пропуск, перемотка, без звука, перемешивание) есть своё сочетание клавиш.
Какое качество звука доступно для локального воспроизведения?Локальное воспроизведение можно настроить до 320 kbps.
Как полностью его удалить?Запустите встроенный деинсталлятор вне каталога плагина — он отключает плагин, останавливает его сервисы и удаляет все конфиги, кэш, бинарники и записи в keyring, принадлежащие плагину, не трогая Omasing и запасной пакет spotifyd.
What are similar projects?omarchy-lock-explorer, omastorm, serpantinum, shell, omarchy-pods, omarchy-workspace-layout, dots-hyprland, omamail
Which topics is it in?quickshell, qml, arch-linux, hyprland, spotify, window-manager, music-player, keyboard, qt, lua, lightweight, music
Creator
stappmus
Size
20.8 MB
Stars
234
Updated
CommitSep 13Releasev1.0.3Aug 26
Age
2mo
Commits · 90 Days