XMP sidecars

An XMP sidecar is a small .xmp file that sits next to a photo or video and stores details about it, such as a description, rating or keywords, without touching the original file.

Frameleaf uses sidecars in both directions:

• Reading. When Frameleaf reads a photo’s details, it also reads the sidecar next to it.
• Writing. When you change a description, rating or tags, Frameleaf writes the change to the sidecar too, so other apps can see it. Your original is never changed.

Tip

Lightroom, darktable, digiKam and many other photo apps can be set to write their changes to .xmp files instead of the original. Frameleaf picks those up.

Which fields are read and written

Frameleaf doesn’t use every field an XMP file can hold. When it writes, it merges its fields into the existing file rather than replacing the whole thing, so everything else stays.

Detail	Frameleaf writes	Frameleaf reads
Description	dc:description, tiff:ImageDescription	dc:description, tiff:ImageDescription
Rating	xmp:Rating	xmp:Rating
Date and time	exif:DateTimeOriginal, photoshop:DateCreated	The first it finds of exif:SubSecDateTimeOriginal, exif:DateTimeOriginal, xmp:SubSecCreateDate, xmp:CreateDate, xmp:CreationDate, xmp:MediaCreateDate, xmp:SubSecMediaCreateDate, xmp:DateTimeCreated
Location	exif:GPSLatitude, exif:GPSLongitude	exif:GPSLatitude, exif:GPSLongitude
Tags	digiKam:TagsList	The first it finds of digiKam:TagsList, lr:HierarchicalSubject, IPTC:Keywords

Everything else, such as the creator, source, other IPTC fields and Lightroom’s edits, stays in the .xmp file but isn’t searchable in Frameleaf.

Frameleaf writes the sidecar automatically after you edit a description, a rating or tags.

Naming

A sidecar must share the name of its photo or video:

File name	Recognised?
IMG_0001.jpg.xmp	Yes, and preferred
IMG_0001.xmp	Yes, as a fallback
myphoto_meta.xmp	No

If both IMG_0001.jpg.xmp and IMG_0001.xmp exist, Frameleaf uses IMG_0001.jpg.xmp.

Uploads

When you upload with the command-line tool, Frameleaf looks for an .xmp file next to each photo:

1. Detect. A sidecar next to the photo is found.
2. Copy. The photo and the sidecar are both copied into your library storage, and the sidecar is renamed to match the photo, for example IMG_0001.jpg and IMG_0001.jpg.xmp.
3. Read. The details in the table above are read from the sidecar.
4. Keep in step. When you later change the description, rating or tags in Frameleaf, both Frameleaf and the copied sidecar are updated.

External libraries

For an external library, the files stay where they are:

1. Detect. Sidecars next to the photos in the folder are linked to them when the library is scanned. Nothing is moved or renamed.
2. Read. The same fields are read from each sidecar.
3. Write back. If Frameleaf is allowed to write to the folder, later changes, such as a rating or tags, are written back to the sidecar on disk.

Read-only folders

If the folder is mounted read-only, Frameleaf can’t write the sidecar. Changes to descriptions, ratings and tags on those files may not be saved, without any warning. Ask your administrator whether your library is writable before relying on it.

Re-reading sidecars

If you change sidecars in another app, an administrator can ask Frameleaf to pick up the changes. In Settings, go to Compute & jobs, then Job manager, and find the Metadata sidecars queue:

Action	What it does
Discover sidecars	Finds new .xmp files next to photos that don’t have one linked yet
Synchronize all	Reads every linked sidecar again and updates Frameleaf, for example after edits in another app

Sidecars and other features

• Physical deduplication. Sidecars always stay with their own item. When two accounts share one stored original, each keeps its own sidecar. See Duplicates.
• Edited versions have their own small record next to them, describing how they were made. That’s separate from the XMP sidecar. See Editing.
• Preservation packages include a metadata file for every original. See Preservation packages.