A Spotify miniplayer helper for macOS that follows you around.
Spot turns Spotify's miniplayer into a native-feeling music bar that knows where your windows are. It follows you — sit, stay, play.
🍎 macOS only (for now). A Windows version is technically very doable — Spotify's desktop app is the same Chromium core there, and Windows is actually more permissive about window management. If Spot gains traction, it's on the table: open an issue (or 👍 an existing one) if you'd use a Windows build.
- One global hotkey (default ⌃⌥M): launches Spotify, opens the miniplayer, starts playback, and snaps the bar into place — pixel-exact, ~120fps retargetable animation, zero mouse simulation.
- Follow mode (toggle hotkey, default ⌃⌥N): the bar attaches to your active window and rides along with zero lag while you drag — tucked under it, with a small gap so the window's resize handle stays grabbable.
- Window-aware placement:
- Split-screen panes host the bar flush beneath them (the pane ducks to make room; a hotkey press flips which side). When the bar leaves, the pane gets its full height back.
- Filled windows get a centered bottom strip, fitted above it; the hotkey cycles compact corner overlays instead.
- Floating windows are never resized — the bar hugs or overlays them.
- Follow off: the hotkey walks a fixed cycle — left mini, right mini, left half, right half, centered — fitting whatever's in the way for the wide states and healing it on the way out.
- Queue at a pull: a tiny chevron tab on the bar expands the miniplayer (upward from the bottom, downward from the top) to reveal Spotify's native queue, and tucks it back to a slim bar.
- Preferences hub: a small app for rebinding both hotkeys and toggling modes (follow style, reserve strip, bar-at-top).
- Nearly free to run: ~0.0% CPU and ~11MB resident while idle. Event-driven with adaptive polling; the 120Hz tracking loop runs only while a window is actually moving.
Spotify's desktop app is Chromium, so Spot launches it with a
--remote-debugging-port flag and controls the miniplayer's window over the
Chrome DevTools Protocol — the only reliable way to place that window
(Spotify ignores Accessibility resize/move requests). Window awareness comes
from the macOS window server (CoreGraphics) plus Accessibility for fitting
neighbor windows. A LaunchAgent keeps the daemon alive in the background.
See CLAUDE.md for the full battle log of macOS/Spotify quirks
this is built around — it is substantial.
Spot collects nothing. No telemetry, no analytics, no network
connections except to Spotify's local DevTools port on your own machine
(localhost). It never reads what you listen to, never stores account
information, and writes exactly one file of its own: your hotkey and mode
preferences in
~/Library/Application Support/Spotify Miniplayer/config.json, plus a local
log at ~/Library/Logs/spotify-miniplayer.log containing window-placement
events only. Nothing ever leaves your computer.
- The DevTools port is unauthenticated: any process running as your user can connect to it and script Spotify (read your session, control playback). Spot derives a per-user port instead of the well-known 9222 to avoid drive-by scans, but the port is still discoverable from the process list — this is inherent to the approach, not fixable by Spot. If your threat model includes untrusted local processes, don't run Spotify with a debug port (i.e., don't use this tool).
- The daemon needs an Accessibility grant to fit/heal neighbor windows
(the bar itself moves fine without it). Grants are tied to the code
signature — sign rebuilds with a stable identity or macOS silently drops
the grant (see
make_app.py). - Spot listens on no ports of its own and runs entirely as your user — no elevated privileges, no kernel extensions, no input monitoring.
git clone https://github.com/ConnerLM/spot.git && cd spot
swiftc -O spotify_miniplayer.swift -o spotify-miniplayer # build the daemon
python3 make_app.py # bundles the hub + daemon apps (needs Pillow)make_app.py puts the preferences hub in /Applications/Launchers/ and the
daemon (wrapped in an .app so the Accessibility list shows a real name/icon)
in ~/Library/Application Support/Spotify Miniplayer/. Create a LaunchAgent
pointing at the daemon binary with --daemon (RunAtLoad + KeepAlive), grant
it Accessibility once, and you're done.
Spot quits and relaunches Spotify (with the debug flag) if it's running without one — the first press after that takes a few seconds.
- macOS 13+ only for now (see the Windows note at the top). Tested on a 14" MacBook Pro; multi-display support is untested.
- Spotify updates could change the miniplayer's internals at any time.
- Not affiliated with or endorsed by Spotify. "Spotify" is referenced only to describe compatibility.
MIT — see LICENSE.