Skip to main content

Module metadata

simple_gal

Module metadata 

Source
Expand description

Image metadata extraction and resolution.

Each image can carry metadata (title, description) from two independent sources:

§Filesystem sources (read during scan phase)

  • Title: Derived from the filename stem via the NNN-name convention. 001-My-Photo.jpg becomes “My Photo”. Simple, requires no tooling, and consistent with album and page naming.

  • Description: Read from a sidecar text file with the same stem as the image. 001-My-Photo.txt alongside 001-My-Photo.jpg. Follows the same pattern as info.txt for album descriptions — plain text, no special format.

§Embedded metadata sources (read during process phase)

  • Title: IPTC Object Name (IPTC:2:05). This is the “Title” field in Lightroom, Capture One, and most DAM (Digital Asset Management) software.

  • Description: IPTC Caption-Abstract (IPTC:2:120). The standard “Caption” field in Lightroom. This is by far the most-used text metadata field among photographers — “Headline” and “Extended Description” exist in the IPTC spec but are journalism holdovers rarely used in fine art workflows.

§Resolution priority

Each field is resolved independently. The first non-empty value wins:

  • Title: EXIF title → filename title → None
  • Description: sidecar .txt → EXIF caption → None

The rationale: embedded metadata represents deliberate curation in a photography tool (the photographer typed it into Lightroom on purpose) and should win over mechanical filename extraction. For descriptions, sidecar files are explicit overrides — the user created a file on purpose — so they trump embedded metadata.

§Title sanitization

Since resolved titles may end up in URLs and filenames (via the image page slug), EXIF-sourced titles are sanitized for safe use: truncated to a reasonable length, non-URL-safe characters replaced with dashes, consecutive dashes collapsed. This prevents filesystem errors from long titles and broken URLs from special characters.

Functions§

read_sidecar
Read a sidecar .txt file for an image.
resolve
Resolve a metadata field from multiple sources.
sanitize_slug
Sanitize a title string for use in URLs and filenames.