feat: split --write-metadata into xmp/exif variants

Add --write-metadata-xmp and --write-metadata-exif for independent
control of XMP sidecar generation and EXIF tag writing.

--write-metadata remains as shorthand for both. All three flags
accept category lists: all, rating, keywords, title, datetime,
dates, orientation, location. Omitting value defaults to 'all'.

New categories:
- datetime: DateTimeOriginal + CreateDate
- dates: datetime + ModifyDate (superset)

Deprecations (still functional, with warnings):
- --xmp-sidecar -> --write-metadata-xmp
- --set-exif-datetime -> --write-metadata-exif datetime

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: teh-hippo

src/icloudpd/base.py

@@ -252,8 +252,8 @@ def run_with_configs(global_config: GlobalConfig, user_configs: Sequence[UserCon
     # Create shared logger
     logger = create_logger(global_config)
 
-    # Check exiftool availability if any user has --write-metadata
-    if any(uc.write_metadata for uc in user_configs):
+    # Check exiftool availability if any user has --write-metadata-exif
+    if any(uc.write_metadata_exif for uc in user_configs):
         from icloudpd.metadata_writer import ExiftoolNotFoundError, check_exiftool
         try:
             ver = check_exiftool()
@@ -434,12 +434,12 @@ def password_provider(_username: str) -> str | None:
                     user_config.force_size,
                     global_config.only_print_filenames,
                     user_config.set_exif_datetime,
-                    user_config.write_metadata,
+                    user_config.write_metadata_exif,
                     user_config.skip_live_photos,
                     user_config.live_photo_size,
                     user_config.dry_run,
                     user_config.file_match_policy,
-                    user_config.xmp_sidecar,
+                    user_config.write_metadata_xmp,
                     lp_filename_generator,
                     filename_builder,
                     user_config.align_raw,
@@ -763,12 +763,12 @@ def download_builder(
     force_size: bool,
     only_print_filenames: bool,
     set_exif_datetime: bool,
-    write_metadata_config: frozenset[str],
+    write_metadata_exif: frozenset[str],
     skip_live_photos: bool,
     live_photo_size: LivePhotoVersionSize,
     dry_run: bool,
     file_match_policy: FileMatchPolicy,
-    xmp_sidecar: bool,
+    write_metadata_xmp: frozenset[str],
     lp_filename_generator: Callable[[str], str],
     filename_builder: Callable[[PhotoAsset], str],
     raw_policy: RawTreatmentPolicy,
@@ -982,13 +982,13 @@ def download_builder(
                             )
                     logger.info("Downloaded %s", truncated_path)
 
-        if xmp_sidecar:
+        if write_metadata_xmp:
             generate_xmp_file(logger, download_path, photo._asset_record, dry_run, dir_cache)
 
-        if write_metadata_config:
+        if write_metadata_exif:
             xmp_meta = build_metadata(logger, photo._asset_record)
             update = extract_metadata_update(photo._asset_record, xmp_meta)
-            write_file_metadata(download_path, update, set(write_metadata_config), dry_run)
+            write_file_metadata(download_path, update, set(write_metadata_exif), dry_run)
 
     # Also download the live photo if present
     if not skip_live_photos:

src/icloudpd/cli.py

@@ -34,7 +34,7 @@ def map_align_raw_to_enum(align_raw_str: str) -> RawTreatmentPolicy:
     return mapping[align_raw_str]
 
 
-_VALID_WRITE_METADATA = {"all", "rating", "keywords", "title", "dates", "orientation", "location"}
+_VALID_WRITE_METADATA = {"all", "rating", "keywords", "title", "dates", "orientation", "location", "datetime"}
 
 
 def _parse_write_metadata(value: str | None) -> frozenset[str]:
@@ -161,11 +161,40 @@ def add_options_for_user(parser: argparse.ArgumentParser) -> argparse.ArgumentPa
     cloned.add_argument(
         "--write-metadata",
         help=(
-            "Write iCloud metadata into file EXIF/XMP using exiftool. "
+            "Write iCloud metadata as both XMP sidecars and EXIF tags. "
+            "Shorthand for --write-metadata-xmp and --write-metadata-exif. "
             "Comma-separated list of field categories: "
-            "all, rating, keywords, title, dates, orientation. "
-            "Requires exiftool to be installed. Default: disabled."
+            "all, rating, keywords, title, datetime, dates, orientation, location. "
+            "Requires exiftool to be installed. "
+            "Default when specified without value: all."
         ),
+        nargs="?",
+        const="all",
+        default=None,
+    )
+    cloned.add_argument(
+        "--write-metadata-xmp",
+        help=(
+            "Write iCloud metadata as XMP sidecar files. "
+            "Comma-separated list of field categories: "
+            "all, rating, keywords, title, datetime, dates, orientation, location. "
+            "Default when specified without value: all."
+        ),
+        nargs="?",
+        const="all",
+        default=None,
+    )
+    cloned.add_argument(
+        "--write-metadata-exif",
+        help=(
+            "Write iCloud metadata into file EXIF/XMP tags using exiftool. "
+            "Comma-separated list of field categories: "
+            "all, rating, keywords, title, datetime, dates, orientation, location. "
+            "Requires exiftool to be installed. "
+            "Default when specified without value: all."
+        ),
+        nargs="?",
+        const="all",
         default=None,
     )
 
@@ -456,6 +485,37 @@ def format_help() -> str:
 
 
 def map_to_config(user_ns: argparse.Namespace) -> UserConfig:
+    # Resolve write-metadata flags
+    write_metadata_base = _parse_write_metadata(user_ns.write_metadata)
+    write_metadata_xmp = _parse_write_metadata(user_ns.write_metadata_xmp)
+    write_metadata_exif = _parse_write_metadata(user_ns.write_metadata_exif)
+
+    # --write-metadata sets both if specific variants not given
+    if write_metadata_base:
+        if not write_metadata_xmp:
+            write_metadata_xmp = write_metadata_base
+        if not write_metadata_exif:
+            write_metadata_exif = write_metadata_base
+
+    # --xmp-sidecar is deprecated alias for --write-metadata-xmp all
+    if user_ns.xmp_sidecar:
+        import logging
+
+        logging.getLogger("icloudpd").warning(
+            "--xmp-sidecar is deprecated, use --write-metadata-xmp instead"
+        )
+        if not write_metadata_xmp:
+            write_metadata_xmp = frozenset({"all"})
+
+    # --set-exif-datetime adds datetime to exif set
+    if user_ns.set_exif_datetime:
+        import logging
+
+        logging.getLogger("icloudpd").warning(
+            "--set-exif-datetime is deprecated, use --write-metadata-exif datetime instead"
+        )
+        write_metadata_exif = write_metadata_exif | frozenset({"datetime"})
+
     return UserConfig(
         username=user_ns.username,
         password=user_ns.password,
@@ -474,12 +534,12 @@ def map_to_config(user_ns: argparse.Namespace) -> UserConfig:
         list_libraries=user_ns.list_libraries,
         skip_videos=user_ns.skip_videos,
         skip_live_photos=user_ns.skip_live_photos,
-        xmp_sidecar=user_ns.xmp_sidecar,
         force_size=user_ns.force_size,
         auto_delete=user_ns.auto_delete,
         folder_structure=user_ns.folder_structure,
         set_exif_datetime=user_ns.set_exif_datetime,
-        write_metadata=_parse_write_metadata(user_ns.write_metadata),
+        write_metadata_xmp=write_metadata_xmp,
+        write_metadata_exif=write_metadata_exif,
         smtp_username=user_ns.smtp_username,
         smtp_password=user_ns.smtp_password,
         smtp_host=user_ns.smtp_host,

src/icloudpd/config.py

@@ -27,12 +27,12 @@ class _DefaultConfig:
     list_libraries: bool
     skip_videos: bool
     skip_live_photos: bool
-    xmp_sidecar: bool
     force_size: bool
     auto_delete: bool
     folder_structure: str
     set_exif_datetime: bool
-    write_metadata: frozenset[str]
+    write_metadata_xmp: frozenset[str]
+    write_metadata_exif: frozenset[str]
     smtp_username: str | None
     smtp_password: str | None
     smtp_host: str

src/icloudpd/metadata_writer.py

@@ -32,6 +32,7 @@ class MetadataUpdate:
     gps_longitude: float | None = None
     gps_altitude: float | None = None
     gps_h_accuracy: float | None = None
+    created_date: str | None = None  # format: "YYYY:MM:DD HH:MM:SS"
 
 
 class ExiftoolNotFoundError(RuntimeError):
@@ -112,6 +113,13 @@ def build_exiftool_args(
         if update.gps_h_accuracy is not None and update.gps_h_accuracy > 0:
             args.append(f"-GPSHPositioningError={update.gps_h_accuracy}")
 
+    if (write_all or "datetime" in config or "dates" in config) and update.created_date is not None:
+        args.append(f"-EXIF:DateTimeOriginal={update.created_date}")
+        args.append(f"-EXIF:CreateDate={update.created_date}")
+
+    if (write_all or "dates" in config) and update.created_date is not None:
+        args.append(f"-EXIF:ModifyDate={update.created_date}")
+
     return args
 
 
@@ -158,6 +166,10 @@ def extract_metadata_update(
         gps_altitude = xmp_metadata.GPSAltitude if xmp_metadata.GPSAltitude is not None else None
         # horzAcc is not in XMPMetadata — extract from raw locationEnc
         gps_h_accuracy = _extract_h_accuracy(asset_record)
+        # Extract created_date for datetime/dates categories
+        created_date_val = None
+        if xmp_metadata.CreateDate:
+            created_date_val = xmp_metadata.CreateDate.strftime("%Y:%m:%d %H:%M:%S")
         return MetadataUpdate(
             rating=rating,
             title=title,
@@ -168,6 +180,7 @@ def extract_metadata_update(
             gps_longitude=gps_longitude,
             gps_altitude=gps_altitude,
             gps_h_accuracy=gps_h_accuracy,
+            created_date=created_date_val,
         )
 
     # Fallback: extract from raw asset_record (same logic as xmp_sidecar.build_metadata)
@@ -182,12 +195,22 @@ def extract_metadata_update(
 
 
 def _read_existing_metadata(file_path: str) -> dict[str, str]:
-    """Read current metadata values using exiftool for comparison."""
+    """Read current metadata values using exiftool for comparison.
+
+    Uses -G to get group-prefixed keys, then normalises to unprefixed names.
+    For GPS, prefers XMP values (where we write for videos) over Composite
+    values (which read from QuickTime Keys and may differ in precision).
+    """
     cmd = [
-        "exiftool", "-json", "-s", "-n",
+        "exiftool", "-json", "-s", "-n", "-G",
         "-Rating", "-XPTitle", "-XPKeywords", "-ImageDescription",
-        "-Orientation#", "-GPSLatitude", "-GPSLongitude", "-GPSAltitude",
+        "-Orientation#",
+        "-GPSLatitude", "-GPSLongitude", "-GPSAltitude",
         "-GPSHPositioningError",
+        "-XMP-exif:GPSLatitude", "-XMP-exif:GPSLongitude",
+        "-XMP-exif:GPSAltitude", "-XMP-exif:GPSHPositioningError",
+        "-EXIF:DateTimeOriginal",
+        "-QuickTime:CreateDate",
         file_path,
     ]
     try:
@@ -196,7 +219,26 @@ def _read_existing_metadata(file_path: str) -> dict[str, str]:
             logger.debug("exiftool read failed for %s: %s", file_path, result.stderr.strip())
             return {}
         data = json.loads(result.stdout)
-        return data[0] if data else {}
+        if not data:
+            return {}
+        raw = data[0]
+        # Normalise: strip group prefix. Priority for GPS comparison:
+        # XMP > Composite > EXIF. XMP has our written values for videos.
+        # Composite has correctly-signed values. EXIF GPS stores unsigned
+        # values with separate Ref tags, so is unreliable for comparison.
+        priority = {"EXIF": 0, "Composite": 1, "XMP": 2}
+        sorted_items = sorted(
+            raw.items(),
+            key=lambda kv: priority.get(kv[0].split(":")[0], 1)
+        )
+        meta: dict[str, Any] = {}
+        for key, val in sorted_items:
+            if key == "SourceFile":
+                continue
+            parts = key.split(":", 1)
+            tag = parts[-1]
+            meta[tag] = val
+        return meta
     except (subprocess.TimeoutExpired, FileNotFoundError, ValueError) as e:
         logger.debug("Could not read existing metadata from %s: %s", file_path, e)
         return {}
@@ -241,6 +283,11 @@ def _needs_update(
         if update.gps_h_accuracy is not None and update.gps_h_accuracy > 0 and not _gps_close(existing.get("GPSHPositioningError"), update.gps_h_accuracy, tol=0.1):
             return True
 
+    if (write_all or "datetime" in config or "dates" in config) and update.created_date is not None:
+        existing_dt = existing.get("DateTimeOriginal") or existing.get("CreateDate")
+        if existing_dt is None:
+            return True
+
     return False
 
 
@@ -265,13 +312,6 @@ def write_metadata(
         True if metadata was written (or would be written in dry-run), False if
         no changes were needed or an error occurred.
     """
-    # Log deprecation warning for 'dates' category
-    if "dates" in config:
-        logger.warning(
-            "--write-metadata 'dates' is deprecated and has no effect. "
-            "Timezone data is managed by the camera EXIF."
-        )
-
     args = build_exiftool_args(update, config)
     if not args:
         return False
@@ -281,6 +321,16 @@ def write_metadata(
     if existing and not _needs_update(update, config, existing):
         return False
 
+    # Don't overwrite existing dates — the camera's value is ground truth;
+    # iCloud's assetDate may differ due to timezone/rounding.
+    # Check both EXIF (images) and QuickTime (videos) date tags.
+    if existing and (existing.get("DateTimeOriginal") is not None or existing.get("CreateDate") is not None):
+        args = [a for a in args if not a.startswith("-EXIF:DateTimeOriginal=")
+                and not a.startswith("-EXIF:CreateDate=")
+                and not a.startswith("-EXIF:ModifyDate=")]
+        if not args:
+            return False
+
     if dry_run:
         logger.info(
             "Would write metadata to %s: %s",
@@ -292,7 +342,7 @@ def write_metadata(
     cmd = ["exiftool", "-overwrite_original"] + args + [file_path]
     try:
         result = subprocess.run(
-            cmd, capture_output=True, text=True, timeout=120
+            cmd, capture_output=True, text=True, timeout=600
         )
         if result.returncode == 0 and "1 image files updated" in result.stdout:
             logger.info("Wrote metadata to %s", file_path)

tests/test_cli.py

@@ -211,12 +211,12 @@ def test_cli_parser(self) -> None:
                         list_libraries=False,
                         skip_videos=False,
                         skip_live_photos=False,
-                        xmp_sidecar=False,
                         force_size=False,
                         auto_delete=False,
                         folder_structure="{:%Y/%m/%d}",
                         set_exif_datetime=False,
-                        write_metadata=frozenset(),
+                        write_metadata_xmp=frozenset(),
+                        write_metadata_exif=frozenset(),
                         smtp_username=None,
                         smtp_password=None,
                         smtp_host="smtp.gmail.com",
@@ -252,12 +252,12 @@ def test_cli_parser(self) -> None:
                         list_libraries=False,
                         skip_videos=False,
                         skip_live_photos=False,
-                        xmp_sidecar=False,
                         force_size=False,
                         auto_delete=False,
                         folder_structure="{:%Y/%m/%d}",
                         set_exif_datetime=False,
-                        write_metadata=frozenset(),
+                        write_metadata_xmp=frozenset(),
+                        write_metadata_exif=frozenset(),
                         smtp_username=None,
                         smtp_password=None,
                         smtp_host="smtp.gmail.com",
@@ -329,12 +329,12 @@ def test_cli_parser(self) -> None:
                         list_libraries=False,
                         skip_videos=False,
                         skip_live_photos=False,
-                        xmp_sidecar=False,
                         force_size=False,
                         auto_delete=False,
                         folder_structure="{:%Y/%m/%d}",
                         set_exif_datetime=False,
-                        write_metadata=frozenset(),
+                        write_metadata_xmp=frozenset(),
+                        write_metadata_exif=frozenset(),
                         smtp_username=None,
                         smtp_password=None,
                         smtp_host="smtp.gmail.com",