89 lines
3.9 KiB
Markdown
89 lines
3.9 KiB
Markdown
# 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.
|