-
-
Notifications
You must be signed in to change notification settings - Fork 5
Exif
kei reads capture dates from downloaded photos and can optionally write iCloud metadata back to local files or XMP sidecars.
After downloading a JPEG file, kei reads DateTimeOriginal. If present, it uses that value to set the file modification time so file managers sort photos by capture date.
When no embedded EXIF date is available, kei uses the creation date from iCloud for the file modification time.
File metadata writes are off by default. Enable only the fields you want in TOML:
[metadata]
set_exif_datetime = true
set_exif_rating = true
set_exif_gps = true
set_exif_description = true
embed_xmp = true
xmp_sidecar = true| TOML key | What it writes |
|---|---|
set_exif_datetime |
DateTime, DateTimeOriginal, DateTimeDigitized when missing |
set_exif_rating |
Rating tag from favorite flag or explicit rating |
set_exif_gps |
GPS tags from iCloud location, only when the file lacks GPS |
set_exif_description |
ImageDescription from iCloud description or title |
embed_xmp |
Full XMP packet with available metadata fields |
xmp_sidecar |
.xmp sidecar next to the media file, merged with existing sidecars |
Native JPEG and TIFF EXIF writes work in default builds. XMP sidecars, embedded XMP, and HEIC metadata writes require the default xmp Cargo feature.
| Format | EXIF tags | XMP embed | XMP sidecar |
|---|---|---|---|
| JPEG | yes | yes | yes |
| PNG | yes | yes | yes |
| TIFF | yes | yes | yes |
| MP4 | n/a | yes | yes |
| MOV | n/a | yes | yes |
| HEIC | n/a | yes | yes |
| HEIF | n/a | yes | yes |
| AVIF | n/a | yes | yes |
| RAW / other | no | no | yes |
For HEIC / HEIF / AVIF, the XMP packet is inserted as a MIME item inside the ISO-BMFF meta box through kei's mp4-atom writer. The encoded image bytes are not touched.
For JPEG / PNG / TIFF / MP4 / MOV XMP writes, default builds use Adobe's XMP Toolkit.
Unusual HEIC files with unsupported infe v1 metadata entries are reported as metadata rewrite failures. The media file still lands; kei does not panic on those files.
Use xmp_sidecar = true for formats without an in-place write path.
When iCloud metadata changes after download, kei detects the changed metadata hash on a later sync and queues a rewrite pass. It patches metadata in place without re-downloading the media bytes.
The rewrite marker clears on success and stays on failure so the next sync can retry.
Write-through paths use a sibling temp file and an atomic rename:
- Copy the downloaded file to a metadata temp path.
- Patch EXIF or XMP into the copy.
- Rename the temp file over the final path.
Sidecars, sync reports, and XMP Toolkit rewrites use the same atomic install helper. A crash can leave a temp file behind, but it won't expose a half-written destination.
xmp_sidecar = true parses an existing .xmp sidecar and layers kei's fields on top. Fields already set by the existing sidecar win on conflict, so local edits survive.
A malformed sidecar logs a warning and falls back to a fresh packet.
Metadata write failures are logged per file and counted in the sync session. The media download still counts as successful; only the metadata write failed.
The /metrics endpoint exposes metadata failure counters for service and watch deployments.