exiftool-immich

name	exiftool-immich
description	Write EXIF/IPTC/XMP metadata to photos and videos for Immich sync, including albums (keywords), favorites (rating), description, GPS location, and date/time. Handles diff-based updates with proper removal of metadata.
allowed-tools	Shell, Read, Write

ExifTool for Immich EXIF Writer

This Skill teaches you how to use exiftool (via PyExifTool wrapper) to write metadata to photos and videos for the Immich EXIF Writer project.

Use this Skill when working with:

• Writing albums as IPTC Keywords
• Setting/removing favorite status (XMP Rating)
• Writing/clearing descriptions
• Setting/removing GPS coordinates
• Updating date/time metadata
• Handling differences between photo and video metadata tags

---

1. Core Principles

1.1 Metadata Fields to Write

Field	Photo Tags	Video Tags	Notes
Albums	IPTC:Keywords	IPTC:Keywords	Each album = separate keyword
Favorite	XMP:Rating=5	QuickTime:Rating=5	Only when favorited
Description	EXIF:ImageDescription, XMP:Description	QuickTime:Description	Write both for photos
Location	GPS:GPSLatitude, GPS:GPSLongitude	GPS:GPSLatitude, GPS:GPSLongitude	Same for both
Date/Time	EXIF:DateTimeOriginal, EXIF:CreateDate	QuickTime:CreateDate, QuickTime:ModifyDate	ISO format

1.2 File Handling

• Use -overwrite_original to modify files in place (no backups needed for this project)
• Always check file exists before attempting to write
• Parameters must come BEFORE the filename in exiftool commands

---

2. Keywords (Albums) - CRITICAL

2.1 Each Album is a Separate Keyword

CORRECT - Each album as individual keyword:

exiftool -IPTC:Keywords=Family -IPTC:Keywords=Vacation -IPTC:Keywords=2024 photo.jpg

WRONG - DO NOT use semicolon-delimited:

# NEVER DO THIS
exiftool -IPTC:Keywords="Family;Vacation;2024" photo.jpg

2.2 Adding Keywords

To add keywords without removing existing ones:

exiftool -IPTC:Keywords+=NewAlbum photo.jpg

2.3 Replacing Keywords (Handling Removals)

When albums have changed (some removed, some added), you MUST clear all keywords first, then re-add current ones:

# Clear all keywords, then add current albums
exiftool -IPTC:Keywords= -IPTC:Keywords=Family -IPTC:Keywords=2024 photo.jpg

This is critical for handling album removals - you cannot selectively remove one keyword, you must clear and re-add.

2.4 Reading Current Keywords

To check what keywords exist:

exiftool -j -IPTC:Keywords photo.jpg

---

3. Favorite Status (Rating)

3.1 Setting Favorite (Rating = 5)

Photos:

exiftool -XMP:Rating=5 photo.jpg

Videos:

exiftool -QuickTime:Rating=5 video.mp4

3.2 Removing Favorite (Clear Rating)

Photos:

exiftool -XMP:Rating= photo.jpg

Videos:

exiftool -QuickTime:Rating= video.mp4

Setting to empty string clears the tag.

---

4. Description

4.1 Writing Description

Photos (write to both EXIF and XMP for compatibility):

exiftool -EXIF:ImageDescription="Beach vacation" -XMP:Description="Beach vacation" photo.jpg

Videos:

exiftool -QuickTime:Description="Beach vacation" video.mp4

4.2 Clearing Description

Photos:

exiftool -EXIF:ImageDescription= -XMP:Description= photo.jpg

Videos:

exiftool -QuickTime:Description= video.mp4

---

5. GPS Location

5.1 Writing GPS Coordinates

Same for both photos and videos:

exiftool -GPS:GPSLatitude=37.7749 -GPS:GPSLongitude=-122.4194 file.jpg

5.2 Clearing GPS Coordinates

exiftool -GPS:GPSLatitude= -GPS:GPSLongitude= file.jpg

5.3 GPS Coordinate Format

• ExifTool accepts decimal degrees (e.g., 37.7749)
• ExifTool handles hemisphere/reference tags automatically
• Negative values for South/West are handled correctly

---

6. Date/Time

6.1 Writing Date/Time

Photos:

exiftool -EXIF:DateTimeOriginal="2024:01:15 14:30:00" -EXIF:CreateDate="2024:01:15 14:30:00" photo.jpg

Videos:

exiftool -QuickTime:CreateDate="2024:01:15 14:30:00" -QuickTime:ModifyDate="2024:01:15 14:30:00" video.mp4

Date Format: YYYY:MM:DD HH:MM:SS (note colons in date)

6.2 Converting ISO Format to EXIF Format

If you have ISO format like 2024-01-15T14:30:00, convert to EXIF format:

• Replace T with space
• Replace hyphens in date with colons
• Result: 2024:01:15 14:30:00

---

7. Combining Multiple Updates

7.1 Single Command for Multiple Changes

You can combine multiple tag updates in one exiftool call:

exiftool \
  -IPTC:Keywords= \
  -IPTC:Keywords=Family \
  -IPTC:Keywords=Vacation \
  -XMP:Rating=5 \
  -EXIF:ImageDescription="Beach trip" \
  -XMP:Description="Beach trip" \
  -GPS:GPSLatitude=37.7749 \
  -GPS:GPSLongitude=-122.4194 \
  -overwrite_original \
  photo.jpg

This is more efficient than multiple exiftool calls.

---

8. PyExifTool Wrapper Usage

When using PyExifTool in Python code:

8.1 Basic Pattern

import exiftool

with exiftool.ExifToolHelper() as et:
    params = [
        "-IPTC:Keywords=Family",
        "-IPTC:Keywords=Vacation",
        "-XMP:Rating=5",
        "-overwrite_original",
        "/path/to/file.jpg"
    ]
    et.execute(*params)

8.2 Building Parameters Dynamically

params = []

# Add keywords (albums)
params.append("-IPTC:Keywords=")  # Clear first
for album in ["Family", "Vacation", "2024"]:
    params.append(f"-IPTC:Keywords={album}")

# Add favorite
if is_favorite:
    params.append("-XMP:Rating=5")
else:
    params.append("-XMP:Rating=")

# Add description
if description:
    params.append(f"-EXIF:ImageDescription={description}")
    params.append(f"-XMP:Description={description}")
else:
    params.append("-EXIF:ImageDescription=")
    params.append("-XMP:Description=")

# Add location
if latitude and longitude:
    params.append(f"-GPS:GPSLatitude={latitude}")
    params.append(f"-GPS:GPSLongitude={longitude}")
else:
    params.append("-GPS:GPSLatitude=")
    params.append("-GPS:GPSLongitude=")

# Add file path and overwrite flag
params.append("-overwrite_original")
params.append(file_path)

# Execute
with exiftool.ExifToolHelper() as et:
    et.execute(*params)

---

9. Detecting File Type (Photo vs Video)

Determine which tags to use based on file extension:

Photo Extensions: .jpg, .jpeg, .png, .gif, .webp, .tiff, .tif, .heic, .heif, .dng, .cr2, .nef, .arw

Video Extensions: .mp4, .mov, .avi, .mkv, .m4v, .3gp, .webm

Use appropriate tags based on file type detected.

---

10. Diff-Based Updates

10.1 Principle

To properly handle metadata changes:

1. Compare current metadata to previous metadata
2. Detect what changed (additions, modifications, removals)
3. Build exiftool parameters accordingly

10.2 Handling Removals

For fields that can be removed:

Keywords (Albums):

• Always clear first (-IPTC:Keywords=)
• Then add current albums
• This ensures removed albums are gone

Rating (Favorite):

• If was favorite but now isn't: clear with -XMP:Rating=

Description:

• If had description but now doesn't: clear with -EXIF:ImageDescription= and -XMP:Description=

Location:

• If had location but now doesn't: clear with -GPS:GPSLatitude= and -GPS:GPSLongitude=

10.3 No Change Optimization

If metadata hasn't changed for a field, you can skip including those parameters. However, keywords should always be cleared and re-added if ANY album changed (to handle removals).

---

11. Error Handling

11.1 Check File Exists

Before calling exiftool, verify file exists:

import os
if not os.path.isfile(file_path):
    # Handle error

11.2 ExifTool Errors

PyExifTool will raise exceptions on errors. Wrap in try/except:

try:
    with exiftool.ExifToolHelper() as et:
        et.execute(*params)
    return True
except Exception as e:
    logger.error(f"ExifTool failed: {e}")
    return False

11.3 Unsupported Files

Some file formats may not support certain tags. Log but don't fail:

• RAW formats have limited EXIF write support
• Some video formats don't support all QuickTime tags

---

12. Performance Considerations

12.1 Batch Multiple Files

Instead of opening/closing exiftool for each file:

with exiftool.ExifToolHelper() as et:
    for file_path in files:
        params = build_params(file_path)  # Build params for this file
        et.execute(*params)

PyExifTool keeps exiftool process running, which is faster than multiple invocations.

12.2 Only Write When Changed

Check if metadata actually changed before calling exiftool:

if has_metadata_changed(asset_id, new_metadata):
    exif_writer.write_metadata(file_path, new_metadata, previous_metadata)

This avoids unnecessary file writes.

---

13. Testing & Verification

13.1 Read Written Metadata

After writing, verify with:

exiftool -j -IPTC:Keywords -XMP:Rating -EXIF:ImageDescription photo.jpg

13.2 Test Files

Create test files to verify behavior:

• Write metadata
• Read it back
• Modify (remove albums, clear rating)
• Read again to confirm removals worked

---

14. Common Pitfalls

1. Forgetting to clear keywords before re-adding: Results in old albums not being removed
2. Using semicolon-delimited keywords: Creates single keyword with semicolons instead of multiple keywords
3. Wrong tags for videos: Using EXIF tags on videos instead of QuickTime tags
4. Incorrect date format: Using ISO format instead of EXIF format (YYYY:MM:DD HH:MM:SS)
5. Parameters after filename: ExifTool parameters must come BEFORE the filename

---

This Skill provides everything needed to properly write Immich metadata to photo and video files using exiftool.