Getting Started
Where do I download Jukebox?
Download the latest release from the GitHub Releases page. Jukebox is distributed as a standard macOS .app bundle — drag it into your Applications folder and open it. There is no installer.
Once installed, Jukebox uses Sparkle to check for and offer updates automatically.
What are the system requirements?
macOS 13 Ventura or later is required. Jukebox is a menu bar-only application — it does not appear in the Dock.
What happens on first launch?
An onboarding window guides you through a two-step setup:
- Step 1 — Select your music app: Choose between Spotify and Apple Music using the segmented picker. You can change this later in Preferences.
- Step 2 — Grant permissions: Open your chosen music app, click “Enable permissions” in the onboarding window, then click “OK” on the macOS system dialogue that appears. This grants Jukebox Automation (AppleScript) access to your music app.
If your music app is not running, an alert will ask you to open it first. Once permission is granted, the “Continue” button enables and you can proceed to the main app.
What permissions does Jukebox need?
Automation (AppleScript) access to Spotify, Apple Music, or both. This is the only permission required.
Jukebox uses macOS ScriptingBridge to read track metadata (title, artist, album, artwork, duration, playback position, loved status) and to send playback commands (play/pause, next, previous, love/unlove).
Features
Menu Bar Display
See the current track title and artist scrolling in your menu bar alongside an animated “now playing” visualisation. The display hides automatically when music is paused to save space.
Now Playing Window
Click the menu bar item to reveal a detailed popover with large album art, track details, and elapsed/total duration — all at a glance without switching apps.
Playback Controls
Play, pause, skip forward, skip back, and love/unlove tracks (Apple Music only) directly from the hover overlay on the album art.
Floating Window
Pin the Now Playing view as a compact, borderless floating window. Drag it anywhere on screen — it remembers its position and joins all Spaces.
Spotify & Apple Music
Works with both Spotify and Apple Music. Switch between them at any time in Preferences — the change takes effect immediately.
Customisation
Choose your background style, toggle launch at login, enable always-on-top for the floating window, and pick your connected music app — all from Preferences.
Now Playing & Floating Window
What is the Now Playing popover?
When you left-click the menu bar item (and the floating window is not pinned), a popover drops down from the menu bar showing:
- Album art (240 x 240, rounded corners, drop shadow)
- Playback controls that appear on hover
- A pin button to switch to floating window mode
- Track details below (song title, artist, elapsed/total duration)
What is the floating window?
When you click the pin button, the popover is replaced by a compact 240 x 240 borderless floating window. It displays album art filling the entire frame, with playback controls appearing on hover.
The floating window is draggable anywhere on screen, remembers its position between sessions, joins all Spaces, and stays visible while you work in other apps.
How do I return to popover mode?
Click the pin button again (the filled pin icon in the bottom-right corner of the floating window) to unpin and return to the standard popover.
What background styles are available?
Two options, configurable in Preferences:
- Artwork (default) — the album art is used as a blurred background behind the main content, creating a tinted glassmorphism effect.
- None — standard system popover appearance with no custom background.
What does 'Keep floating window on top' do?
When enabled in Preferences, the floating window stays above all normal windows. When disabled, it can be obscured by other windows like any standard window.
Music App Support
Which music apps are supported?
Spotify and Apple Music. Both are controlled via macOS ScriptingBridge (AppleScript).
How do I switch between Spotify and Apple Music?
Right-click the menu bar item and select “Preferences…”. Use the segmented picker under “Connect Jukebox to” to switch. The change takes effect immediately.
Do I need to grant permissions again when switching apps?
Yes, if you have not previously granted Automation access for the other app. macOS requires separate Automation permission for each application Jukebox communicates with.
Is the Love button available for Spotify?
No. The Love/Unlove button is only available when connected to Apple Music. The Spotify ScriptingBridge API does not support this feature.
Customisation
How do I access Preferences?
Right-click the Jukebox menu bar item and select “Preferences…” from the context menu.
What settings are available?
Preferences offers four options:
- Launch at Login — toggle whether Jukebox starts automatically when you log in to your Mac.
- Keep floating window on top — toggle whether the floating window stays above all other windows.
- Connected music app — switch between Spotify and Apple Music.
- Background style — choose “Artwork” (blurred album art background) or “None” (standard system appearance).
Privacy & Permissions
What permissions does Jukebox require?
Jukebox requires Automation permission to control your music app via macOS ScriptingBridge. This is the standard macOS mechanism for inter-app communication via AppleScript. It is the only permission required.
Does Jukebox collect any data?
No personal data is collected, transmitted, or stored. All communication happens locally between Jukebox and your music app. Jukebox is open source — you can verify this in the source code.
Does Jukebox connect to the internet?
The only network requests Jukebox makes are:
- Album artwork from Spotify’s CDN — when connected to Spotify, artwork is downloaded from a remote URL.
- Sparkle update checks — the app periodically checks for new releases to offer automatic updates.
No analytics, telemetry, or tracking of any kind is included.
Where are settings stored?
All settings are stored locally in macOS UserDefaults. There is no cloud sync and no external storage.
Troubleshooting
'Permission denied' when trying to connect
You previously denied Automation access. Open System Settings > Privacy & Security > Automation, find Jukebox, and tick the checkbox next to Spotify or Music. You may need to quit and reopen Jukebox for the change to take effect.
'[App] is not open' when trying to enable permissions
The music app must be running before you can grant Automation access. Open Spotify or Apple Music first, then try again from the onboarding window.
The menu bar just shows the bars icon with no track info
This can happen for several reasons:
- The connected music app may not be running.
- Nothing may be playing — track info hides automatically after 30 seconds of pause.
- The wrong app may be selected in Preferences (e.g. Spotify is selected but you are playing music in Apple Music).
- Automation permissions may not have been granted.
Album art is not showing or displays a blank square
For Spotify, artwork is downloaded from a remote URL — check your network connection.
For Apple Music, artwork is read directly from the track data and may take a moment to become available. Try skipping to another track and back.
Play/pause, next, and previous buttons do nothing
This is almost always a permissions issue. Open System Settings > Privacy & Security > Automation and verify that Jukebox has Automation access to your chosen music app.
The Love button is missing
The Love/Unlove feature is only available with Apple Music. It is not supported by the Spotify ScriptingBridge API. If you are connected to Apple Music and still do not see it, ensure Automation permissions are granted.
The floating window disappeared
Left-click the menu bar item to toggle it back. If it does not reappear, try toggling pinned mode off and on to reset its position.
The floating window keeps going behind other windows
Open Preferences and enable “Keep floating window on top”. This keeps the floating window above all normal windows.
Jukebox is not appearing in my menu bar after launch
Jukebox is a menu bar-only application — it does not appear in the Dock. Look for the animated bars icon in the menu bar. If you have many menu bar items, macOS may have hidden it due to limited space. Try closing other menu bar apps or using a tool to manage menu bar overflow.