Skip to content

Apple Photos captions do not travel with icloudpd

URL: https://mkdocs.justinsforge.com/memory/general/reference_apple_photos_caption_ingest/

Correction logged 2026-06-17 (earlier in-session claim that captions ride inside the file was WRONG).

  • The caption typed in Apple Photos (the Description field) and the Favorite flag live in the Photos library database (Photos.sqlite) + the iCloud asset record, NOT embedded in the .mov/.mp4. Asset bytes and this metadata are separate records.
  • icloudpd downloads the file bytes + basic EXIF (capture date, sometimes GPS). It does NOT pull the typed description or favorite. A plain icloudpd run = videos with correct dates and zero captions.
  • Album membership IS partially reachable via icloudpd (it can organize the download by album), but captions/favorites are not.

Hard constraint (2026-06-17): Michael has NO Mac, only iPhone + Windows.

That rules out osxphotos (Mac-only). So do NOT rely on extracting Apple Photos captions via a Mac.

Decided approach: decouple bytes from captions

  1. Bytes: icloudpd pulls all 5-10k videos from iCloud to the NVMe (needs only Michael's Apple ID app-specific password, no Mac, headless).
  2. Human captions/favorites: captured in our own app (clips.justinsforge.com iPhone PWA) in a fast review mode designed to match the Apple Photos swipe-down speed (big preview, tap heart = favorite, type one line, swipe next). Lands straight in our DB. One surface for old library + future clips. HARD requirement: it must be one easy step (thumb-speed) or Michael won't do it.
  3. Salvage option: DROPPED. Michael has only typed ~50 captions in Apple Photos, so re-adding those in our app is trivial; not worth the fragile iCloud-web-API pull. (Kept here for the record: the caption+favorite do sync via Apple's undocumented iCloud API, so a pyicloud pull could fetch them with no Mac if a large body of Apple captions ever needed rescuing.)

Future capture (new shoots, not in iCloud): copy clip to server then caption in app, or an iOS Shortcut that uploads selected clips + a typed note in one share-sheet tap.

Note: human captions only needed for favorites/hero clips; AI (content recognition + transcript + dates) covers the bulk, so the manual burden is bounded. Decision deferred to ingest time; clips is a module of the workspace suite built AFTER the base. See memory/plans/gus-clip-library-mam-2026-06-15.md and the suite plan memory/plans/workspace-suite-architecture-and-rebuild-plan-2026-06-17.md.

[Claude Code]