Plasma Dynamic Wallpaper

Use Apple Dynamic Desktop HEIC wallpapers on KDE Plasma while preserving the embedded apple_desktop:h24 timeline—or align the same frames with local dawn, solar noon, and dusk.

Highlights

• Decodes Apple Dynamic Desktop metadata directly.
• Supports embedded and solar-aware schedules.
• Extracts frames once and reuses source-aware caches.
• Reconciles the active wallpaper after login, resume, display changes, and Plasma Shell restarts.
• Handles active multi-monitor layouts and ignores detached containments.
• Includes a managed local wallpaper library.
• Provides user-level systemd timer and watchdog services.
• Offers diagnostics, status, cache maintenance, and dry-run commands.
• Uses atomic state and configuration writes.
• Requires no root access for normal operation.

Quick start

pipx (recommended)

Install the Python package in an isolated environment:

pipx install plasma-dynamic-wallpaper
dynamic-wallpaper --setup

Import and activate a wallpaper:

dynamic-wallpaper install ~/Pictures/Fuji.heic --name fuji
dynamic-wallpaper use fuji
dynamic-wallpaper --force

From source

git clone https://github.com/dude297/plasma-dynamic-wallpaper.git
cd plasma-dynamic-wallpaper
./install.sh

Ubuntu and Kubuntu dependencies:

sudo apt install python3 libimage-exiftool-perl libheif-examples qdbus-qt6

See the installation guide for updating, uninstalling, and native package notes.

Common commands

Managed wallpapers

dynamic-wallpaper install ~/Pictures/Fuji.heic --name fuji
dynamic-wallpaper install ~/Pictures/Sonoma.heic --name sonoma
dynamic-wallpaper list
dynamic-wallpaper use sonoma
dynamic-wallpaper remove fuji

Each managed wallpaper receives an isolated source directory and cache. The active entry is marked with * in dynamic-wallpaper list.

Scheduling

Embedded schedule

The default mode follows the transition times stored in Apple's HEIC metadata:

SCHEDULE_MODE=embedded

Solar-aware schedule

Solar mode preserves the original frame order but maps its day anchors to local civil dawn, solar noon, and civil dusk:

SCHEDULE_MODE=solar
LATITUDE=37.3382
LONGITUDE=-121.8863

Coordinates are decimal degrees; west longitudes are negative. The calculation is local and does not require network access. At polar dates without civil dawn or dusk, the command reports an actionable error rather than silently choosing an incorrect frame.

Inspect the resolved timeline with:

dynamic-wallpaper --schedule
dynamic-wallpaper --current

Multi-monitor behavior

By default, all currently active Plasma screens are detected automatically. Detached containments reported as screen=-1 are ignored and retried when they become active again. To restrict updates, set explicit screen IDs:

SCREEN_IDS=0,1

Reliability services

dynamic-wallpaper --setup installs two user services:

• dynamic-wallpaper.timer reconciles the schedule every minute.
• dynamic-wallpaper-watch.service requests immediate recovery after Plasma returns on D-Bus or the machine resumes from sleep.

Useful checks:

systemctl --user status dynamic-wallpaper.timer --no-pager
systemctl --user status dynamic-wallpaper-watch.service --no-pager
journalctl --user -u dynamic-wallpaper.service -n 50 --no-pager
journalctl --user -u dynamic-wallpaper-watch.service -n 50 --no-pager

How it works

Apple HEIC
    │
    ▼
metadata decoder ──► embedded or solar scheduler
    │                         │
    ▼                         ▼
source-aware frame cache ─► selected PNG
                              │
                              ▼
                    Plasma D-Bus adapter
                              │
                              ▼
                 active desktop containments

The engine verifies Plasma's read-back response before saving state. Unique render aliases avoid stale image-provider caches, while active aliases are protected from cleanup.

More detail: Architecture.

Troubleshooting

Start with:

dynamic-wallpaper --doctor
dynamic-wallpaper --current

See Troubleshooting and FAQ.

Development

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

make check
python -m build
python -m twine check dist/*

Contribution and live-Plasma testing guidance:

• Contributing
• Testing
• Release process
• Packaging

Roadmap

• v0.3: release polish, native packaging, richer diagnostics.
• v0.4: native KDE configuration UI and previews.
• v0.5: optional GeoClue-based location discovery and additional desktop backends.

Automatic location discovery is intentionally deferred: solar mode currently uses explicit coordinates, stays offline, and avoids unexpected location access.

License

Released under the MIT License.