Dynamic Wallpaper Creator

A small Swing (Java) desktop application for building your own macOS Dynamic Desktop wallpapers — the .heic files that automatically switch images as your Mac moves between Light and Dark appearance, or as the sun moves across the sky throughout the day.

You supply the images; the app assembles them into a single .heic file with the same embedded metadata Apple's own dynamic wallpapers use, so macOS recognizes and animates it exactly like a wallpaper from System Settings.

Features

• Light / Dark mode wallpapers — pick one image for Light appearance and one for Dark appearance.
• Sun-position (solar) wallpapers — add any number of images and tag each one with the sun's altitude and azimuth; macOS cross-fades between them based on your location and the real time of day. An "Auto-Distribute" button fills in a reasonable sunrise → noon → sunset → night arc for you.
• Set as Desktop Picture — apply the wallpaper you just built without leaving the app.
• Runs entirely locally. No image is uploaded anywhere.

Requirements

• macOS — Dynamic Desktop is a macOS-only feature; the app refuses to start on other platforms.
• Java 17+ to run the app.
• Xcode Command Line Tools (for swiftc) to build the app and on first run, so the bundled native helper can compile. Install with:

  xcode-select --install
  

• Maven to build from source.

See docs/BUILD.md for full build instructions and docs/USAGE.md for how to use the app once it's running.

Quick start

mvn package
java -jar target/dynamic-wallpaper-creator.jar

The first time you click Generate Wallpaper, the app compiles a small bundled Swift helper and caches the binary in ~/Library/Application Support/DynamicWallpaperCreator/ — this takes a few seconds once and is instant after that.

How it works, in one paragraph

A Dynamic Desktop wallpaper is just a HEIC (HEIF) file that stores several full-size images side by side inside one container, plus a small binary property list — describing which image belongs to which sun position or appearance — embedded as custom XMP metadata under Apple's private apple_desktop namespace. That embedding can only be done with Apple's own ImageIO/CoreGraphics frameworks, which aren't reachable from plain Java, so this app's Swing GUI hands the job off to a small bundled Swift command-line tool that does the actual file assembly. The exact byte-level format is documented in docs/FILE_FORMAT.md.

Project layout

pom.xml                                   Maven build definition
src/main/java/com/dynamicwallpaper/
  Main.java                               Entry point
  model/                                  Plain data types (WallpaperImage, WallpaperMode)
  core/                                   Native helper management, job building, sun-position math
  gui/                                    Swing UI (MainWindow + mode panels)
  util/                                   JSON writer, thumbnails, validation
src/main/resources/native/HeicBuilder.swift   Native HEIC/metadata helper (compiled on first run)
docs/
  BUILD.md                                Compiling and packaging the app
  FILE_FORMAT.md                          Full technical spec of the .heic wallpaper format
  USAGE.md                                Using the GUI

License / attribution

This project embeds metadata using Apple's apple_desktop XMP namespace, which is undocumented but has been independently reverse-engineered by several members of the macOS developer community. The exact key names used here (apr, solar, l, d, si, ap, i, a, z) were verified directly against a real Apple-shipped dynamic wallpaper file (/System/Library/Desktop Pictures/Sonoma.heic) during development — see docs/FILE_FORMAT.md for details.