# XMP sidecars

Source: https://frameleaf.app/docs/using/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.

:::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 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](https://frameleaf.app/docs/using/editing/#edits-from-lightroom-and-darktable).

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](https://frameleaf.app/docs/using/date-and-time-doctor/) is written to the sidecar too, and undoing the fix puts the sidecar back.

### People in sidecars

**Save people's names in XMP sidecars**, on by default, saves the names of the [people](https://frameleaf.app/docs/using/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

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

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

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

### 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

For a photo you own, open **Information → Replace XMP sidecar**:

1. Select the **XMP file**.
2. 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.
3. 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

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, the copied sidecar is updated too.

## External libraries

For an [external library](https://frameleaf.app/docs/using/library/#photos-from-external-libraries), 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.** When Frameleaf can write to the folder, later changes, such as a rating or tags, are written back to the sidecar on disk.

:::note[Read-only folders]
In a read-only library, sidecars beside the photos are still read, but changes are never written back to the folder. Frameleaf saves them in a sidecar of its own instead. If you want your edits written into the folder, ask your administrator to add it as a writable library.
:::

## 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

- **Physical deduplication.** Sidecars always stay with their own item. When two accounts share one stored original, each keeps its own sidecar. See [Duplicates](https://frameleaf.app/docs/using/duplicates/#saving-disk-space-in-a-family-library).
- **Edited versions** have their own small record next to them, describing how they were made, kept apart from the XMP sidecar. See [Editing](https://frameleaf.app/docs/using/editing/#how-edits-are-stored).
- **Album exports and preservation packages** include your originals with their metadata and sidecars. See [Export an album](https://frameleaf.app/docs/using/preservation/#export-an-album).
- **Preservation packages** include a metadata file for every original. See [Preservation packages](https://frameleaf.app/docs/using/preservation/).
