Spotify Mini Player is a sleek, lightweight, semi-transparent HUD and desktop companion for Spotify on Linux. Built with GTK4 & Libadwaita, it provides real-time bi-directional MPRIS controls, volume synchronization, native LevelDB queue parsing, smart OSD auto-hide behavior, and automated multi-language localization.
- 📋 Real Spotify Queue Parsing: Reads directly from Spotify's local LevelDB storage. Displays genuine upcoming tracks, currently playing songs, and previously played tracks with correct sequence numbering and full context (playlist/album) naming.
- 🔊 Bi-directional Volume Sync: Real-time volume slider synchronized with Spotify via MPRIS D-Bus. Adjust volume seamlessly using the slider or mouse scroll wheel over the player.
- 👁️ Intelligent OSD HUD Mode: Pops up smoothly when tracks change or media keys are pressed, and fades out automatically after 3.5 seconds. Automatically hides when Spotify Desktop is in focus to avoid screen clutter.
- 📌 Always-on-Top Pinning: Pin button keeps the player always visible above other windows.
- 🌍 Seamless Auto-Localization (i18n): Automatically detects Spotify's active UI language (
ru,en,de,es,fr) and auto-restarts instantly on language change. - 🫧 Glassmorphism Aesthetic: Dark frosted glass theme (
rgba(18, 18, 22, 0.85)), animated audio visualizer bars, and smooth revealer animations.
- Operating System: Linux (Ubuntu 22.04+, Debian 12+, Arch, Fedora)
- Python: 3.10 or newer
- Spotify Desktop: Official Linux client
- System Packages:
sudo apt install python3 python3-gi python3-gi-cairo gir1.2-gtk-4.0 gir1.2-adw-1 libx11-6
- Clone the repository:
git clone https://github.com/Xronni/spotify-mini-player.git cd spotify-mini-player - Run the launcher:
./run.sh
- (Optional) Install desktop shortcut to your application menu:
./install.sh
Tip
Running ./install.sh registers Spotify Mini Player in your GNOME/desktop applications launcher and dashboard.
- D-Bus MPRIS Integration: Communicates over
org.mpris.MediaPlayer2.spotifyfor low-latency playback controls, metadata synchronization, and album artwork caching. - LevelDB Queue Engine: Reverse-scans Spotify's internal cache records to reconstruct active playlist names, upcoming track queues, and history without requiring Spotify Web API developer tokens.
- Smart Visibility Guard: X11 window polling monitors whether the native Spotify desktop client is on-screen or minimized, ensuring the Mini Player never gets in your way.
| Action / Gesture | Target | Result |
|---|---|---|
| Hover | Mini Player Card | Pauses auto-hide timer; keeps window fully visible |
| Mouse Scroll | Player or Volume Slider | Smoothly raises or lowers Spotify volume |
| Click | Album Cover / Logo | Raises and focuses the Spotify Desktop window |
| Click | 📋 Queue Button | Slides down the scrollable queue drawer with auto-centering |
| Click | 📌 Pin Button | Toggles "Always on Top" pinned mode |
| Click | ▶ Track Row | Plays the selected queue track silently via MPRIS |
| Global Media Keys | Keyboard | Triggers instant smooth OSD pop-up |
- 📋 Парсинг настоящей очереди Spotify: Прямое чтение локального хранилища LevelDB Spotify. Отображение актуального списка очереди, истории («Ранее играли») и играющего трека со сквозной нумерацией и точным названием плейлиста/альбома.
- 🔊 Двусторонняя синхронизация громкости: Мгновенный отклик ползунка громкости и кнопки Mute/Unmute через системный протокол MPRIS D-Bus. Поддержка регулировки колесиком мыши.
- 👁️ Умный OSD HUD режим: Плавное всплывание при переключении треков или паузе глобальными горячими клавишами. Автоскрытие через 3.5 секунды. Автоматически скрывается, когда развернуто основное окно Spotify.
- 📌 Закрепление поверх всех окон (Pin): Фиксация мини-плеера на экране в любой удобной позиции.
- 🌍 Автоматическая локализация (i18n): Распознавание языка интерфейса Spotify (
ru,en,de,es,fr) с мгновенным автоперезапуском при смене языка в настройках Spotify. - 🫧 Стильный дизайн (Glassmorphism): Полупрозрачное матовое стекло, тонкие границы, акцентная анимация частот и плавное раскрытие очереди.
- ОС: Linux (Ubuntu 22.04+, Debian, Arch, Fedora)
- Python: 3.10 или выше
- Spotify Desktop: Официальный клиент для Linux
- Зависимости:
sudo apt install python3 python3-gi python3-gi-cairo gir1.2-gtk-4.0 gir1.2-adw-1 libx11-6
- Клонируйте репозиторий:
git clone https://github.com/Xronni/spotify-mini-player.git cd spotify-mini-player - Запустите плеер:
./run.sh
- (Опционально) Установите ярлык в системное меню приложений GNOME:
./install.sh
Tip
Скрипт ./install.sh регистрирует мини-плеер в системном меню приложений, связывая его с официальной иконкой и автозапуском.
- Интеграция с MPRIS: Взаимодействие с сервисом
org.mpris.MediaPlayer2.spotifyбез задержек и без использования внешних API/токенов разработчика. - Движок очереди LevelDB: Поиск и десериализация актуальных записей плейлиста и очередей прямо из локального дискового кэша Spotify.
- Умный контроль фокуса: Постоянный опрос X11-окон предотвращает дублирование интерфейса, если активно официальное окно Spotify.
| Действие / Жест | Элемент | Результат |
|---|---|---|
| Наведение курсора | Карточка плеера | Сброс таймера автоскрытия, плеер остается видимым |
| Колесико мыши | Карточка или ползунок | Быстрая плавная регулировка громкости Spotify |
| Клик | Обложка / Логотип | Разворачивает и фокусирует главное окно Spotify |
| Клик | 📋 Кнопка очереди | Раскрывает панель очереди с автоцентрированием на текущем треке |
| Клик | 📌 Кнопка булавки | Фиксация мини-плеера поверх всех окон (Always on Top) |
| Клик | ▶ Строка трека | Мгновенный тихий запуск трека из очереди |
| Медиа-клавиши | Клавиатура | Вызов всплывающего OSD-виджета на 3.5 секунды |
If you find this project useful, you can support further development:
Если вам понравился мини-плеер, вы можете поддержать разработку:
Released under the MIT License.