A customizable Apple Music now playing display for macOS.
- Shows currently playing Apple Music track on your stream with artwork.
- Ten versatile themes (5 rounded: Natural, Twitch, Dark, Pink, Light and 5 square: Transparent, Neon, Terminal, Retro, High Contrast).
- Adaptive or Fixed width display options.
- Automatically hides when no music is playing.
- Clean animated transitions between songs.
- Theme menu appears only on hover (invisible to viewers).
- Scene-specific settings saved between sessions.
- Menu bar app for easy access to server controls and scene management.
- One-click scene URL copying for easy OBS setup.
- Scrolling text marquee effect for long song/artist names.
- Automatic port selection if default port (8080) is in use.
- macOS (uses AppleScript to communicate with Apple Music).
- OBS Studio or similar streaming software with browser source support.
- Download the latest Jam Deck.app from the Releases page.
- Move to your Applications folder.
- Launch Jam Deck from your Applications folder.
- If you see a warning about an app from an unidentified developer, see Apple's guide.
- The app will appear in your menu bar with a musical note icon.
- The server starts automatically when you launch the app.
To continue, jump to Menu Bar App.
Requirements:
- Python 3.6 or later
Steps:
-
Clone this repository:
git clone https://github.com/yourusername/jam-deck.git cd jam-deck
-
Make sure the Python script is executable:
chmod +x music_server.py
-
Start the server:
./music_server.py
Once installed, the overlay will automatically display your currently playing Apple Music tracks.
Jam Deck's menu bar app provides easy access to all features directly from your Mac's menu bar:
-
Server Control
- Click "Start Server" to begin displaying your music.
- Click "Stop Server" when you're done streaming.
-
Scene Management
- Under "Copy Scene URL," select any scene to copy its URL to the clipboard.
- Each scene can have unique theme and width settings.
- Use "Add New Scene..." to create custom scenes for different parts of your stream.
- Use "Manage Scenes..." to rename or delete existing scenes.
-
Browser Integration
- Click "Open in Browser" to preview how the default overlay looks.
To add Jam Deck to your OBS scene:
- In OBS Studio, select the scene where you want to display your music.
- In the Sources panel, click the
+
button. - Select
Browser
from the list of sources. - Choose
Create New
and give it a name (e.g., "Now Playing Music"). - Click
OK
. - In the Browser Source properties:
- URL: Use the app to copy a scene-specific URL. The default URL is
http://localhost:8080/
- Width: 400 (recommended minimum)
- Height: 140
- Check "Refresh browser when scene becomes active."
- URL: Use the app to copy a scene-specific URL. The default URL is
- Click
OK
to add the browser source.
Hover over the overlay and right-click > Interact, or select the Source and press the Interact button below the preview to reveal the settings menu:
- Natural (default): Soft green theme with rounded corners.
- Twitch: Dark purple theme that matches Twitch aesthetics.
- Dark: Sleek black theme with cyan accents.
- Pink: Vibrant pink theme with friendly typography.
- Light: Clean white theme with blue accents.
- Transparent: Minimalist theme with no background, just text and artwork.
- Neon: Cyberpunk-inspired theme with glowing cyan text on black background.
- Terminal: Green-on-black theme reminiscent of classic computer terminals.
- Retro: Blue and yellow theme using pixel-style Press Start 2P font.
- High Contrast: Black and white theme with Atkinson Hyperlegible font optimized for maximum readability.
Note about Settings Storage: Theme and width preferences are stored separately in each browser's local storage. This means settings selected in your regular browser (Chrome, Safari, etc.) won't automatically appear in OBS. You'll need to configure your preferred settings once in each environment where you use Jam Deck.
In the settings menu:
- A: Adaptive width (only as wide as needed for the text).
- F: Fixed width (expands to fill the entire browser source width, default).
No music information appears
- Make sure the server is running.
- Make sure Apple Music is running.
- Try playing/pausing music to trigger an update.
Permission errors
- macOS may need permission to control Apple Music.
- Go to System Preferences → Security & Privacy → Automation.
- Ensure "Jam Deck" has permission to control Apple Music.
- If you see a permissions prompt when launching the app, click "OK" to allow access.
Using the Menu Bar App
If you're using the menu bar app (Option 1 installation):
- Go to System Preferences → Users & Groups → Login Items.
- Click the "+" button.
- Browse to your Applications folder and select "Jam Deck.app"
- The app will now start automatically at login.
Using the Manual Installation
If you're using the manual installation:
-
Create an Automator application:
- Open Automator.
- Create a new Application.
- Add a "Run Shell Script" action.
- Enter:
cd /path/to/jam-deck && ./music_server.py
- Save as "Start Jam Deck"
-
Add to Login Items:
- System Preferences → Users & Groups → Login Items.
- Add the Automator application you created.
Advanced users can modify the CSS in overlay.css
to create custom themes or change the layout.
The server automatically starts on port 8080. If this port is already in use, it will automatically find and use the next available port. The selected port will be displayed in the menu bar app and system notifications.
If you need to manually specify a different port (Manual installation only):
- Open
music_server.py
in a text editor. - Find the line near the top that says
PORT = 8080
- Change
8080
to your desired port number. - Save the file and restart the server.
- Update your browser source URL in OBS to use the new port.
Requirements:
- Python 3.6 or later
- macOS 10.14 or later
- create-dmg (optional, for creating DMG installers)
If you want to build the Jam Deck menu bar app from source:
-
Clone the repository:
git clone https://github.com/yourusername/jam-deck.git cd jam-deck
-
Install py2app:
pip install py2app
-
Option A - Using the build script (recommended):
chmod +x build.sh ./build.sh
Option B - Manual build:
python setup.py py2app
-
The built application will be available in the
dist
directory.
build.sh
: Automated build script that handles closing any running instances, cleaning previous builds, building the app, and creating a DMG installer.setup.py
: Main build configuration for py2app.collect_zmq.py
: Helper script to ensure ZeroMQ libraries are properly included in the build.
Ensure that your build script has execute permissions. You can set this by running chmod +x build.sh
in the terminal.
Make sure that the necessary tools (osascript, rm, python, create-dmg) are installed and accessible in your system's PATH. The create-dmg tool is only needed if you want to create DMG installers.
- The Retro theme uses Press Start 2P font by CodeMan38 (licensed under SIL Open Font License), with Retro Gaming font by Daymarius as fallback.
- The High Contrast theme uses Atkinson Hyperlegible font designed by the Braille Institute for improved readability.
- JetBrains Mono font is used as a monospaced font for the Terminal theme.
All fonts are licensed under the SIL Open Font License.