| name | timemark-burn-in |
| description | Write joined Timemark field values permanently into the image files as XMP, so each photo is self-describing and survives being moved, copied or re-filed. Use after timemark-import has verified both halves are present. |
| allowed-tools | Read, Write, Bash(python3 *), Bash(exiftool *) |
Burning the values into the files
After the join, the values live in a manifest. That is a link, and links break:
move the file, let a sync tool touch it, and the photo is an anonymous JPEG
again. This writes the values into each image so the association travels with
the pixels.
Metadata, not pixels. Timemark already burns the values visibly into the
image at capture. This does the opposite and better thing — writes them where a
script can read them, changing no pixel.
Run it
python3 scripts/timemark_join.py photos/ \
--photosheet Photosheet_2026-08-26_to_2026-09-01.xlsx \
--sidecars --embed-xmp --manifest manifest.json
--embed-xmp writes fields into the JPEGs.--sidecars also writes IMG.jpg.json beside each image. Keep both: the
sidecar is diffable and reviewable, the XMP is what survives the file being
moved on its own.--dry-run with --embed-xmp prints the exiftool commands instead of running
them.
Requires exiftool. Take a copy first if the originals are the only copy —
-overwrite_original is used, and there is no undo.
Where the values land
Fields go to a custom XMP namespace, tags to standard dc:Subject:
[XMP-timemark] Item No : 1
[XMP-timemark] Item Description : Penguin
[XMP-dc] Subject : Test!
XMP is the right target precisely because it is XML and takes arbitrary
namespaces — a field called Item No is legal there rather than a hack. EXIF has
nowhere to put one, which is why Timemark resorted to an encrypted blob.
The namespace URI is written into the packet, so the tags read back on any
machine with a stock exiftool, no config file needed. Default URI is
http://ns.timemark-plugin.org/timemark/1.0/; override with --xmp-uri to use a
namespace you own. Nothing dereferences it — it is an identifier, not an address.
Verified after a write: pixels bit-identical (compare -metric AE = 0), and
Timemark's UserComment blob left intact.
The trap this handles for you
exiftool silently refuses to write an XMP tag it has never heard of.
$ exiftool -m -XMP-xmp:ItemNo=1 photo.jpg
$ exiftool -XMP:all photo.jpg
[XMP-x] XMP Toolkit : Image::ExifTool 13.50 # and nothing else
Exit code 0. No stderr. Nothing written. -m does not help — it suppresses minor
warnings, it does not permit undeclared tags. The tags must be declared in a
-config file, and since Timemark field names come from whatever the template
says, that config has to be generated per export. The script does that, then
reads the tags back to confirm they landed rather than trusting the exit
code.
If you ever hand-roll an exiftool call for these values, do the read-back too.
This failure mode looks exactly like success.
Check it worked
The manifest's xmp.results reports tags_written against tags_expected per
image. Any row where those differ, or ok is false, did not fully land.
exiftool -XMP:all -G1 photos/*.jpg | head
