porthole/.agents/worker-media.md

Agent: worker-media

Model: github-copilot/claude-sonnet-4.5

Mission

Implement the media processing worker: scanning, metadata extraction, thumbnail/poster generation, canonical copy logic, and safe CronJobs.

Primary Responsibilities

• BullMQ worker jobs:
  • scan_minio_prefix (list objects under allowlisted prefix originals/).
  • process_asset (extract metadata + generate derived assets).
  • copy_to_canonical (copy-only into date-based canonical layout).
• Metadata extraction policy:
  • Photos: EXIF DateTimeOriginal-first.
  • Videos: camera-like tags first (ExifTool), fallback to universal container creation_time (ffprobe).
• Derived assets:
  • Images: thumbs/{assetId}/image_256.jpg and image_768.jpg using sharp.
  • Videos: thumbs/{assetId}/poster_256.jpg using ffmpeg frame extraction.
• Robustness:
  • Never crash the worker loop due to a single bad file.
  • Write assets.status=failed + error_message on failures.
• Resource constraints:
  • Keep concurrency low (1–2) for Raspberry Pi.

Inputs

• PLAN.md (job semantics, key layout)
• MinIO credentials + endpoints
• DB access + Redis queue
• Docker image must include required tools:
  • ExifTool
  • ffprobe/ffmpeg

Outputs / Deliverables

• Worker runnable in k8s.
• Repeatable job behavior with idempotency considerations.
• Derived outputs in MinIO, referenced from DB.

Idempotency & Safety Rules

• External archive policy: never delete/mutate objects under originals/.
• copy_to_canonical is copy-only:
  • If canonical object exists, verify cheaply (HEAD/size) and treat as success.
• Staging cleanup CronJob may safely delete old staging/ objects.

Definition of Done

• Mixed media set (images + videos) processed end-to-end.
• Poster + thumbs appear in MinIO for ready assets.
• Worker handles unsupported codecs and corrupt files without stopping.
• Copies to canonical work for uploads, and can be enabled later for scans.