RaceTaggerRACE TAGGER
PricingDownload
Docs/IPTC/XMP metadata writing

IPTC/XMP metadata writing

RaceTagger can embed race numbers, participant names, and event information directly into your photo files as industry-standard IPTC and XMP metadata. This means the data travels with the photo — searchable in Lightroom, Photo Mechanic, and any DAM system.

RaceTagger embeds race numbers, driver/team names and event data directly into a photo's IPTC/XMP metadata (Keywords, Caption/Description, Title, Person Shown, Credit, Copyright, Location, Contact Info, and more), so the data is searchable in Lightroom, Photo Mechanic, Bridge, Capture One and any other tool that reads those standards. All writing goes through a single bundled ExifTool binary — there is no external install to manage. Two entry points exist: the lightweight write that happens as part of normal processing/corrections (race number, team, driver keywords), and IPTC Pro — a richer profile (credits, contact info, location, rights, per-participant Person Shown) configured on a preset or account default and applied in one batch pass from the Results screen. Per-pilot caption/keyword templates (the [[ ... ]] repeat-block syntax) are covered on the [[multi-pilot-captions]] page, not here.

settings screen

How to use it

  1. 1On the results page, if the active preset has an IPTC profile configured (iptc_metadata on the preset, or an…: account-level default template), the 📋 IPTC Pro button appears.
  2. 2Click it to open the IPTC Pro panel: review/edit Credits, Creator, Event & Caption, Location, Keywords, Person Shown and Rights fields (grouped in collapsible sections), choose Merge with existing keywords or Replace all keywords, and pick the scope — Matched files only or All files.
  3. 3Click IPTC Pro — Write N files to batch-write to the originals (JPEG in place, RAW to its .xmp sidecar):
  4. 4For exporting copies instead of writing originals, open the Export & IPTC modal and pick a mode: 📁 Export to Folder…: (copy to a destination, with optional ✏️ Rename Files using a pattern like {number}_{name}_{nationality}_{team}_{car_model}-{seq:2}, and optional subfolder organization) or 📋 Write to Originals (same IPTC form, no copy — modifies source files in place, with a confirmation warning).
  5. 5In both modals, ⚙️ Write Behavior controls two independent choices: how to handle a filename collision at the…: destination (Auto-rename, Overwrite, Skip) and how to handle metadata already on the target image (Merge — keep fields this preset doesn't set — or Replace — clear all IPTC/XMP first, then write only this preset).
  6. 6An IPTC profile can be imported from an existing .xmp file (Photo Mechanic or standard format) via Import from XMP……: , and saved as the account-level default from Settings → IPTC Pro Defaults.

Limits and known behaviour

  • RAW is never modified in place. For nef, arw, cr2, cr3, orf, raw, rw2, dng, all metadata goes to a .xmp sidecar next to the RAW file (created by ExifTool if missing); JPEG and other formats are written directly. This is the only thing that differs between the two paths — the same fields, the same values, just a different destination and (for keywords) a different tag name (IPTC:Keywords on a JPEG vs XMP dc:subject in a RAW sidecar).
  • Keyword append vs overwrite. The lightweight writer (writeKeywordsToImage) supports both modes: append reads back what's already on the file/sidecar and skips case-insensitive duplicates; overwrite clears the field first, then writes the new set. IPTC Pro's keyword mode ("Merge with existing keywords" / "Replace all keywords") maps to the same append/overwrite distinction at the writeFullMetadata level. A manual correction always writes in a single overwrite pass built from the union of all current (non-deleted) detections on the photo plus any visual-tag keywords (location, weather, scene, subjects, style, emotion) already embedded on the file — so correcting one detection on a multi-car photo does not wipe its siblings' keywords, and does not wipe the photographer's visual tags either (issue #167, fixed in app 1.1.11).
  • No racetagger marker keyword is written to delivered files. Keywords carry only the customer's race data (race number, team, driver, visual tags) — no tool-name literal. Files tagged by older app versions may still carry a leftover literal racetagger keyword; current code filters that value out wherever the keyword set is recomputed (visual-tag re-add on correction) rather than re-adding it.
  • IPTC:Keywords has a 64-character-per-value limit in some readers; the simplified keyword path lowercases, strips special characters, replaces spaces with underscores and truncates each token to 64 characters. Single-character tokens are dropped as noise, except single digits (so a car numbered #5 still keeps 5 as a keyword).
  • Person Shown never falls back to writing names as keywords. It always uses XMP-iptcExt:PersonInImage, on both JPEG and RAW-sidecar paths — an earlier RAW-only path that replaced dc:subject with names (silently wiping race-number/team keywords) has been removed; RAW and JPEG now produce the same document for the same input (see tests/metadata/jpeg-raw-parity.test.ts).
  • Replace mode clears IPTC IIM All plus six XMP namespaces (XMP-iptcCore, XMP-iptcExt, XMP-photoshop, XMP-dc, XMP-plus, XMP-xmpRights) before writing — EXIF (camera data, GPS, exposure) is never touched, since it's hardware-recorded, not editorial data. For a RAW sidecar the merge/replace distinction doesn't apply: the sidecar is always regenerated fresh from exactly the fields supplied.
  • Full IPTC/XMP write only applies fields the caller actually supplied — an empty or absent field is left untouched in merge mode, not blanked.
  • The filename-rename pattern ({number}, {name}, {surname}, {team}, {car_model}, {nationality}, {event}, {date} / {date:FORMAT}, {seq} / {seq:N}, {original}) only applies on Export to Folder — "Write to Originals" never renames files.
  • writeSpecialInstructions prefixes its value with RaceTagger: inside IPTC:SpecialInstructions (JPEG) / XMP-photoshop:Instructions (RAW sidecar), truncating to 256 characters total; it updates an existing RaceTagger: segment in place rather than duplicating it, and preserves any other content already in that field.
  • There is no strategy picker: the RAW-vs-JPEG destination choice is automatic and not user-selectable, and there is no "Both" mode.