nowPlayingDesktops

A glass-style album-art tile on your desktop wallpaper for whatever you are playing on Spotify (or another supported player in local mode).

Screenshots

Quick start (Windows)

1. Get the app — download now-playing-windows.exe from Releases, or install with pipx: pipx install now-playing-desktops
2. Run it — double-click the .exe, or run now-playing run --source local (pipx puts now-playing on your PATH)
3. Done — play something in the Spotify desktop app; pause or exit to restore your wallpaper

For macOS, Linux, Spotify Web API mode, or hacking on the code, see the sections below.

Install from source

git clone https://github.com/hippi345/nowPlayingDesktops.git
cd nowPlayingDesktops
python3.12 -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"     # add windows, linux, or macos extras as needed

Quick Start: Local mode

Local mode reads playback from the OS media session on this machine. Pick your OS:

Windows (local)

Prerequisites

• Python 3.12+ (requires-python in pyproject.toml; CI tests 3.12 and 3.13).
• Install: pip install -e ".[windows]" (WinRT optional deps for SMTC).
• Player: Spotify desktop app playing on this PC (System Media Transport Controls).

Run

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[windows]"
now-playing run --source local

Nice extra: When the lock screen is set to use the same picture as the desktop wallpaper, the composed tile can appear on the lock screen while a track is playing; it is restored when you pause (same restore path as the desktop).

Linux (local)

Prerequisites

• Python 3.12+
• Install: pip install -e ".[linux]" (dbus-next for MPRIS).
• D-Bus session: echo $DBUS_SESSION_BUS_ADDRESS should be set in your desktop session.
• Player: Spotify desktop or another app with MPRIS (org.mpris.MediaPlayer2.*). playerctl is not required by this app.
• Wallpaper backend (one of): GNOME family — gsettings; KDE — plasma-apply-wallpaperimage and/or qdbus6 / qdbus; other WMs — feh, swaybg, or nitrogen (plus xrandr or wlr-randr for screen size).

Run

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[linux]"
now-playing run --source local

macOS (local)

Prerequisites

• Python 3.12+
• Install: pip install -e ".[macos]" (appscript for Spotify AppleScript control).
• Player: Spotify.app playing on this Mac.
• Automation: macOS may prompt for Automation permission for your terminal or Python to control Spotify (System Settings → Privacy & Security → Automation).

Run

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[macos]"
now-playing run --source local

Optional PyObjC (pyobjc-framework-Cocoa) improves per-display wallpaper control; without it, osascript sets all screens.

Common run flags (local)

• -v / --verbose — debug logging
• --once — single poll/apply cycle
• --env-file PATH — load settings from a .env file
• --no-online-art — no internet art lookups (see Album art)
• --poll-interval SECONDS — default 2.5

YOUR_SPOTIFY_USERNAME on the command line is optional for local mode (only required for --source spotify).

Login autostart (local)

now-playing autostart enable --source local

enable forwards --source, --env-file, --no-online-art, and an optional username into the registered autostart command (Windows Run key, XDG autostart .desktop, or macOS LaunchAgent). Check status with now-playing autostart status; remove with now-playing autostart disable.

Album art in local mode

When online art is enabled (default), cover resolution is:

1. System media thumbnail when available (SMTC on Windows, MPRIS art on Linux, AppleScript artwork URL on macOS — URL download only if online art is enabled).
2. Apple iTunes Search API (public HTTPS; no iTunes app or Apple account) when the thumbnail is missing or small.
3. Generated placeholder (gradient + track title/artist) if nothing else is available.

If the iTunes lookup fails (network error, no match, timeout), the app logs a warning and continues with the system thumbnail or placeholder; the wallpaper still applies for that poll. A background thread may upgrade wallpaper art after the first apply when iTunes returns a larger image for the same playing track (see logs: Upgraded art Apply took …).

Disable online art (offline / privacy)

NOW_PLAYING_ONLINE_ART=0

Or on the CLI:

now-playing run --source local --no-online-art

When disabled: local thumbnails only, then placeholder; no iTunes requests, no Spotify art URL downloads, no background iTunes upgrader. (Spotify Web API mode still uses the network for playback and API album art unless you also pass --no-online-art, which skips art URL downloads and uses placeholders.)

The app loads .env from (first match wins, without overriding variables already set in the shell):

1. --env-file / NOW_PLAYING_ENV_FILE
2. Per-user config: %APPDATA%\now-playing-desktops\.env (Windows), ~/Library/Application Support/now-playing-desktops/.env (macOS), $XDG_CONFIG_HOME/now-playing-desktops/.env (Linux, default ~/.config/now-playing-desktops/.env)
3. Current working directory .env

Quick Start: Spotify mode

Spotify mode uses the Web API (any device). Wallpaper setup is the same on every OS; playback detection does not need the [windows] / [linux] / [macos] extras.

Windows (Spotify)

Prerequisites

• Python 3.12+
• Install: pip install -e . (base package; wallpaper uses ctypes / WinRT desktop APIs already in the main install path).
• Spotify Developer app with Client ID in .env (see below).

Linux (Spotify)

Prerequisites

• Python 3.12+
• Install: pip install -e .
• Wallpaper backend (same as local): gsettings (GNOME), plasma-apply-wallpaperimage / qdbus6 / qdbus (KDE), or feh / swaybg / nitrogen on lightweight WMs.

macOS (Spotify)

Prerequisites

• Python 3.12+
• Install: pip install -e . (wallpaper via AppKit if PyObjC is installed, otherwise osascript).

1. Create a Spotify app

1. Open the Spotify Developer Dashboard and create an app.

2. Copy the Client ID (PKCE does not need a Client Secret).

3. Under Settings → Redirect URIs, add this exact URI (unless you override it):

   http://127.0.0.1:8897/callback

   This is the default from SPOTIPY_REDIRECT_URI / DEFAULT_REDIRECT_URI in auth.py. If port 8897 is in use, pick another loopback URL (for example http://127.0.0.1:8898/callback), set SPOTIPY_REDIRECT_URI to match, and register the same URI in the dashboard.

2. Configure credentials

Copy .env.example to .env or to the per-user config path (recommended for autostart):

Minimum for PKCE:

SPOTIPY_CLIENT_ID=your_client_id_here
SPOTIPY_CLIENT_USERNAME=your_spotify_username

Optional: NOW_PLAYING_SOURCE=spotify|local|auto (default auto).

3. Allowlist users (Development mode)

Apps in Development mode only work for users listed under the app’s Users Management (currently up to five users plus the owner). Add every Spotify account that will use the app.

4. Sign in once

now-playing login YOUR_SPOTIFY_USERNAME

Optional: --env-file PATH if your .env is not in the default config directory.

Token cache file: spotify-token-<username>.cache under the same config directory (config.spotify_token_cache_path).

5. Run

now-playing run YOUR_SPOTIFY_USERNAME --source spotify

Autostart:

now-playing autostart enable YOUR_SPOTIFY_USERNAME --source spotify

(enable requires Spotify credentials in the resolved .env when source is spotify or auto with Client ID present.)

Command reference

Stop a foreground run with Ctrl+C; the original wallpaper is restored automatically.

Wallpaper behavior

• Composes a blurred backdrop, glass panel, cover art, and track labels; restores your original wallpaper on pause or exit.
• Windows — multi-monitor aware; optional per-monitor wallpaper when IDesktopWallpaper is available.
• macOS — sets wallpaper on every display (AppKit / osascript).
• Linux — GNOME (gsettings), KDE (plasma-apply-wallpaperimage / qdbus), or fallbacks (feh, swaybg, nitrogen).

Session state: wallpaper-state.json in the config directory. If a previous run exited without restoring (session_active), the next startup restores immediately.

Which mode should I pick?

How auto resolves (see resolve_effective_playback_source in playback_source.py):

1. --source spotify or NOW_PLAYING_SOURCE=spotify → Spotify Web API.
2. --source local or NOW_PLAYING_SOURCE=local → local OS media session.
3. Otherwise (auto): if SPOTIPY_CLIENT_ID is set and non-empty in the environment (after .env load), effective mode is Spotify; if not, local.

A resolved Spotify run still needs a username (SPOTIPY_CLIENT_USERNAME or a run/login argument) and a usable token cache from now-playing login (or legacy client-secret flow). Online art (iTunes Search lookups and Spotify art URL downloads) applies to local mode by default; see Album art in local mode.

Legacy console scripts now-playing-macos and now-playing-windows behave like now-playing run … when you omit the run subcommand.

Troubleshooting

Development

pip install -e ".[dev]"
ruff check src tests
ruff format src tests
pytest -q

Profile compose at laptop resolution: python scripts/profile_compose.py.

License

MIT — see LICENSE. Copyright (c) 2026 Joel Shearon.