OBS Apple Music Progress Bar

A lightweight, transparent OBS overlay that shows the track currently playing in Apple Music / now-playing media sessions — complete with album artwork and a live progress bar.

English · 日本語

Windows users: no Python required — just grab the portable ZIP from the latest release and double-click the executable. See Windows portable ZIP.

A small Python backend polls the active provider for the current track — title, artist, album, playback position, duration, and artwork — and writes it to runtime/nowplaying.json. The bundled overlay.html reads that platform-neutral file and renders a clean, transparent overlay you can drop straight into an OBS Browser Source.

macOS uses Music.app through the built-in osascript and sips commands. Windows uses the OS media session API (SMTC) through an optional Python extra.

• Live "now playing" display for macOS Music / Apple Music and Windows media sessions
• Fully transparent overlay, ready for an OBS Browser Source
• Real-time progress bar with elapsed and total time
• Album artwork from Music.app or Windows SMTC when available, with an automatic iTunes Search API fallback
• Built-in scaling presets for 1080p and 4K layouts
• Demo mode for previewing the layout without playing anything

• macOS with Music.app / Apple Music, or Windows 10/11 with Apple Music for Windows
• Python 3.9 or later (not needed for the Windows portable ZIP)
• OBS Studio

macOS does not require additional Python packages. Windows support requires the optional windows extra, which installs winsdk.

Clone the repository and start the local server:

git clone https://github.com/m-shintaro/apple-music-obs-overlay.git
cd apple-music-obs-overlay
python3 nowplaying.py

Then, in OBS, add a Browser Source and point it at:

http://localhost:8765/overlay.html

Recommended source size:

The area around the card is transparent, so a larger OBS source size is perfectly fine.

Prefer not to install Python? Skip to the Windows portable ZIP below.

Otherwise, from the repository directory, install the optional Windows dependency once:

py -3 -m pip install ".[windows]"

Then start the same local server:

py -3 nowplaying.py

The OBS Browser Source URL is the same on both platforms:

http://localhost:8765/overlay.html

You don't need to install Python on Windows — download the portable build from the latest release:

1. Open the Releases page.
2. Under Assets, download OBSAppleMusicProgressBar-<version>-windows-<arch>.zip.
3. Extract the ZIP anywhere, then double-click OBSAppleMusicProgressBar.exe.

The console window prints the OBS Browser Source URL:

http://localhost:8765/overlay.html

The portable build writes its runtime/ folder next to the executable.

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-windows.ps1

For 4K streams, append ?profile=4k to the URL:

http://localhost:8765/overlay.html?profile=4k

Or set any custom scale factor:

http://localhost:8765/overlay.html?scale=1.75

Preview the layout without relying on a media provider:

python3 nowplaying.py --demo

Write the files to runtime/ once and exit:

python3 nowplaying.py --once

On first run, macOS may ask whether Terminal or Python is allowed to control Music.app.

If you accidentally denied it, re-enable access under System Settings → Privacy & Security → Automation and allow Terminal / Python to control Music.

Artwork is resolved in the following order:

1. Provider artwork — direct Music.app export on macOS, or SMTC thumbnail data on Windows.
2. iTunes Search API fallback — a lookup by artist + title, used only when provider artwork fails.

runtime/nowplaying.json includes artworkSource and artworkError fields. artworkSource: "music" means the macOS direct export succeeded, artworkSource: "smtc" means Windows SMTC thumbnail data was used, and artworkSource: "itunes" means the fallback was used.

Diagnose artwork retrieval:

python3 nowplaying.py --diagnose-artwork

Disable the network fallback entirely:

python3 nowplaying.py --no-network-artwork

While running, the tool writes the following files into runtime/:

Everything under runtime/ is ignored by .gitignore.

The JSON schema is documented in docs/nowplaying-json.md.

python3 nowplaying.py --port 8766

http://localhost:8766/overlay.html

This tool reads playback information from your local Music.app on macOS or from the Windows system media session API on Windows, then writes it to the local runtime/ directory.

By default, when provider artwork retrieval fails, the track title and artist are sent to the iTunes Search API to look up fallback artwork. Pass --no-network-artwork to disable this behavior.

Issues and pull requests are welcome. When reporting a bug, it helps to include your OS version, OBS version, provider (auto, macos, windows, or demo), and the output of python3 nowplaying.py --diagnose-artwork.

This project is released under the MIT License. See LICENSE for details.

• Creator — shin (GitHub: @m-shintaro, X: @xyzmiku)
• OBS Studio — streaming software and Browser Source runtime
• Apple Music / Music.app — source of playback information on macOS
• Windows Media Control / SMTC — source of playback information on Windows
• iTunes Search API — fallback artwork lookup

Disclaimer — This is not an official project by Apple Inc. or the OBS Project. Apple, Apple Music, iTunes, and macOS are trademarks of Apple Inc. OBS and OBS Studio are names of the OBS Project. Track metadata and artwork belong to their respective rights holders.