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:
  Terminal

  ─□✕

  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.