# 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](docs/BUILD.md) for full build instructions and
[docs/USAGE.md](docs/USAGE.md) for how to use the app once it's running.

## Quick start

```bash
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](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](docs/FILE_FORMAT.md) for details.