Initial Application

README.md

@@ -0,0 +1,88 @@
+# 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.