Лёгкий always-on-top оверлей для управления музыкой поверх любой игры — Windows и macOS.
Каждый трек подсвечивает интерфейс цветом своей обложки.
Маленькое (~480×170) полупрозрачное окно поверх всех окон, которое показывает текущий трек и даёт управлять плеером без alt-tab из игры. Дизайн меняется под каждую песню — обложка размывается в фон карточки, а прогресс-бар и play-кнопка перекрашиваются под её доминирующий цвет.
Работает с любым плеером, который умеет в системные media-controls:
- Windows — SMTC: Spotify, Yandex.Music, AIMP, foobar2000, Tidal, MusicBee, любой браузер с YouTube/SoundCloud
- macOS — MediaRemote: Apple Music, Spotify, Deezer, любой Now Playing-источник
- 🎮 Поверх любой игры — frameless, always-on-top, fade-in/out 220мс с easing
- 🎨 Cover-derived theming — обложка → blur backdrop, палитра → accent color
- 🎵 Управление play/pause/prev/next через системный API + горячие клавиши
- 🌍 Глобальный хоткей — настраивается, по умолчанию
Ctrl+Alt+S - 💜 Discord Rich Presence — статус «Слушает …» с обложкой, временем и кнопкой «Открыть трек»
- 🔗 Прямая ссылка на трек в Я.Музыке (через их публичный API), Spotify, YouTube Music, Apple Music
- 🖼️ Реальные обложки в Discord — байты загружаются на catbox.moe и подаются в presence как
large_image
Скачай OverlayMusic-Setup-X.Y.Z.exe из Releases и запусти.
Установка требует прав администратора (UAC-промпт). Это нужно, чтобы:
- Зарегистрировать оверлей с правами админа — иначе глобальный хоткей и foreground-вынос не работают над играми, запущенными от админа (CS, Valorant и др.)
- Создать Scheduled Task для автозапуска — оверлей будет запускаться при входе в Windows автоматически и без UAC-промпта (через
schtasks /RL HIGHEST /SC ONLOGON)
При установке можно снять галочку «Автозапуск при входе в Windows», если не нужен.
Файлы не подписаны Authenticode-сертификатом (он стоит €200-400/год — для опенсорс-проекта избыточно). При первом запуске Windows может показать одно из:
«Microsoft Defender SmartScreen предотвратил запуск неопознанного приложения» «Защитник Windows заблокировал запуск этого приложения»
Это штатное поведение для любого нового неподписанного приложения, а не индикатор вируса. Что делать:
Вариант 1 — через диалог SmartScreen:
- Нажми «Подробнее» в окне предупреждения
- Появится кнопка «Выполнить в любом случае» — жми её
Вариант 2 — заранее разблокировать файл:
- ПКМ по скачанному
.exe→ Свойства - Внизу вкладки «Общие» — галочка «Разблокировать» → ОК
- Запускай как обычно
После того как репутация файла наберётся у Microsoft (зависит от количества скачиваний и положительных запусков), предупреждение перестанет появляться у новых пользователей.
Можешь сверить SHA256 файла с тем, что указан в Releases — это гарантия что файл не был подменён.
- Скачай
OverlayMusic-arm64.dmgиз Releases - Открой .dmg, перетащи OverlayMusic в Applications
- Первый запуск: ПКМ → Open → подтверди (приложение не подписано Apple Developer ID — это безопасно, просто так требует Gatekeeper для не-AppStore приложений)
- Дай разрешение Accessibility в
System Settings → Privacy & Security → Accessibility— нужно для глобального хоткея
Если приложение совсем не запускается:
xattr -dr com.apple.quarantine /Applications/OverlayMusic.app| Действие | Hotkey | Где |
|---|---|---|
| Показать / скрыть оверлей | Ctrl+Alt+S (Win) / Cmd+Opt+S (Mac) |
Глобально |
| Предыдущий трек | ← |
В фокусе оверлея |
| Следующий трек | → |
В фокусе оверлея |
| Пауза / воспроизведение | ↓ |
В фокусе оверлея |
| Скрыть оверлей | Esc |
В фокусе оверлея |
| Настройки | ПКМ по иконке в трее | — |
Все хоткеи настраиваются в трее → Настройки.
По умолчанию используется встроенный Application ID. Чтобы поменять имя, которое отображается в Discord («Слушает X»), и иконку:
- Создай приложение на discord.com/developers/applications (1 минута, кнопка
New Application) - На странице приложения скопируй Application ID и опционально загрузи App Icon
- В оверлее: трей → Настройки → секция Discord → вставь ID
Кнопка-ссылка под presence-картой (Я.Музыка / Spotify / YouTube Music / Apple Music) настраивается там же.
git clone https://github.com/Loretiks/OverlayMusic.git
cd OverlayMusic
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS: source .venv/bin/activate
pip install -r requirements.txt
python overlay.pybuild.bat # генерит dist\OverlayMusic.exe
build-installer.bat # дополнительно собирает Inno Setup .exepip install pyinstaller
pyinstaller --noconfirm --windowed --name OverlayMusic \
--hidden-import _platform_mac --exclude-module _platform_win overlay.py
codesign --force --deep --sign - dist/OverlayMusic.appГотовые сборки для обеих ОС появляются автоматически в Releases после каждого тега вида v1.2.3 — собираются GitHub Actions.
| Файл | Назначение |
|---|---|
overlay.py |
UI (PySide6) + кросс-платформа: Discord, Я.Музыка search, обложки через iTunes/catbox, настройки |
_platform_win.py |
Windows-бекэнд: SMTC через winrt + RegisterHotKey + AttachThreadInput |
_platform_mac.py |
macOS-бекэнд: MediaRemote (private framework) + NSEvent global monitor |
overlay.py импортирует нужный бекэнд по sys.platform. У них одинаковый интерфейс: MediaController, HotkeyManager, force_foreground.
CI workflow в .github/workflows/build.yml:
- Windows job →
windows-latest→ PyInstaller → Inno Setup - macOS job →
macos-14(Apple Silicon) → PyInstaller → ad-hoc codesign → create-dmg
- Я.Музыка не репортит позицию в SMTC — оверлей считает время локально от смены трека. Первый трек после запуска оверлея может показывать неточную позицию; со второго трека всё точно.
- macOS требует Accessibility-разрешения для глобального хоткея (системная политика — не наш выбор).
- Mac-версия не подписана Apple Developer ID. При первом запуске нужен ПКМ → Open. Без warning-а — нужен Apple Developer ($99/год) и notarization.
- MediaRemote.framework на macOS — приватный API Apple. Стабилен годами (его используют Sleeve, NepTunes, Music Bar и др.), но официально не поддерживается.
MIT — пользуйся как хочешь.