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.
Sidecars let your descriptions, ratings and tags move freely between Frameleaf and your other photo apps, while your originals stay untouched. Frameleaf uses them 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.
Which fields are read and written
Section titled “Which fields are read and written”Frameleaf works with the fields below. When it writes, it merges them into the existing file, so everything else in the sidecar stays just as it was.
| Detail | Frameleaf writes | Frameleaf reads |
|---|---|---|
| Description | dc:description, tiff:ImageDescription |
dc:description, tiff:ImageDescription |
| Title | dc:Title |
Title, then ObjectName, then XPTitle |
| Artist | dc:Creator, tiff:Artist |
Creator, then Artist, then ByLine |
| Copyright | dc:Rights, tiff:Copyright |
Rights, then Copyright, then CopyrightNotice |
| Rating | xmp:Rating |
xmp:Rating |
| Date and time | exif:DateTimeOriginal |
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, dc:Subject, IPTC:Keywords |
| People | Names and face areas, as mwg-rs:Regions |
mwg-rs:Regions |
The read column uses the tag names shown in All metadata; a field can come from the original or its sidecar. Other fields stay in the sidecar for your other apps. Lightroom and darktable edit settings can also create an approximate Develop version.
Frameleaf writes the sidecar automatically after you edit a title, artist, copyright, description, rating, tags, date or location. A date or time zone fixed by the Date & Time Doctor is written to the sidecar too, and undoing the fix puts the sidecar back.
People in sidecars
Section titled “People in sidecars”Save people’s names in XMP sidecars, on by default, saves the names of the people in each photo, and where their faces are, beside the photo so other photo apps can read them. The sidecar is updated when you rename, hide or correct someone. Face areas are written the way the photo is shown, even when the file is stored turned. Locked photos are left out. When Frameleaf reads a sidecar that already names faces it knows, it matches them by name and position instead of adding them twice. An administrator can turn it off in Faces & identity.
See every tag
Section titled “See every tag”Open a photo and its Information panel, then choose All metadata. Tags from the original and sidecar are grouped by source and metadata family, including EXIF, IPTC, XMP, ICC and maker notes when present.
- Use Search to filter tag names and values, and Show more tags for a longer list.
- Copy to clipboard copies the matching tags.
- Camera make, model and lens values can open a library search. A keyword can open a search when it matches a tag already in your library.
This view is read-only. Very large tags can be left out; the panel tells you when that happens. It does not expose binary metadata or replace the editable fields in Information. On a shared link, this view follows the link’s metadata and original-location permissions. File paths and artist/creator identities are withheld from shared-link results.
Edit title and credits
Section titled “Edit title and credits”In Information, edit Title and the Artist and Copyright fields under Credits. To change several photos together, select them and choose Edit title and credits. Choose Change title, Change artist or Change copyright only for fields you want to replace. A chosen field left blank clears it; unchecked fields stay as they are.
In a shoot, Default credits supplies artist and copyright for new photos whose own credits are blank. It does not replace credits already recorded in a file.
Changes you make in Frameleaf are protected from later metadata rereads. Replacing a sidecar leaves these choices in place unless you explicitly choose to use the file’s values.
Naming
Section titled “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.
Attach a sidecar
Section titled “Attach a sidecar”Upload photos and sidecars together
Section titled “Upload photos and sidecars together”In the web app, use Upload or choose a folder containing both the photos and their .xmp files. Frameleaf pairs files in the same folder using the naming rules above. A sidecar is attached to its photo, rather than appearing as another item in your library. An unmatched or ambiguous sidecar is reported instead of being attached to the wrong photo. Use a valid XMP file no larger than 1 MiB.
Replace a photo’s sidecar
Section titled “Replace a photo’s sidecar”For a photo you own, open Information → Replace XMP sidecar:
- Select the XMP file.
- Leave Use values from this file off to keep fields you previously edited in Frameleaf protected. Turn it on to let the fields present in the replacement file take precedence, including title and credits.
- Choose Replace XMP sidecar. The message XMP sidecar saved. Metadata is updating. confirms that Frameleaf will reread it.
Replacement is available for an available, unlocked photo you own, not through a shared link. It changes the photo’s linked sidecar and leaves the original image untouched. Replacing a sidecar in a read-only library also leaves the source folder unchanged.
Command-line uploads
Section titled “Command-line uploads”When you upload with the command-line tool, Frameleaf looks for an .xmp file next to each photo:
- Detect. A sidecar next to the photo is found.
- 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.jpgandIMG_0001.jpg.xmp. - Read. The details in the table above are read from the sidecar.
- Keep in step. When you later change the description, rating or tags in Frameleaf, the copied sidecar is updated too.
External libraries
Section titled “External libraries”For an external library, the files stay where they are:
- Detect. Sidecars next to the photos in the folder are linked to them when the library is scanned. Nothing is moved or renamed.
- Read. The same fields are read from each sidecar.
- Write back. When Frameleaf can write to the folder, later changes, such as a rating or tags, are written back to the sidecar on disk.
Re-reading sidecars
Section titled “Re-reading sidecars”Edited sidecars in another app? An administrator can have Frameleaf pick up the changes. Go to Settings → Computers & background work → Background work, open Show all kinds of work and choose Manage next to Photo detail files:
| Action | What it does |
|---|---|
| Find detail files | Finds new .xmp files next to photos that don’t have one linked yet |
| Do it all again | Reads every linked sidecar again and updates Frameleaf, for example after edits in another app |
Sidecars and other features
Section titled “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, kept apart from the XMP sidecar. See Editing.
- Album exports and preservation packages include your originals with their metadata and sidecars. See Export an album.
- Preservation packages include a metadata file for every original. See Preservation packages.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.