Add frame validation to `scan-frames`: detect duplicates and delta-based outliers

[Hackshaven]

Summary

Enhance the scan-frames (aka process metadata) command to validate frame quality, not just cadence. This includes:

• Duplicate detection (by timestamp or image content hash)
• Outlier detection via pixel delta (both low-delta and high-delta frames)

---

Motivation

Current scan-frames detects missing frames based on timestamp cadence, which is useful for time-aligned datasets. However, downstream workflows (e.g., video rendering, time-lapse storytelling) often suffer from:

• Repeated frames (timestamp duplicates or identical content)
• Frozen/static frames (little or no change between time steps)
• Corrupt/glitchy frames (sudden, excessive changes)

These degrade output quality and reduce confidence in visual outputs.

---

Proposed CLI Enhancements

zyra process scan-frames \
  --frames-dir ./frames \
  --datetime-format %Y%m%d%H%M%S \
  --period-seconds 60 \
  --detect-duplicates \
  --duplicate-mode timestamp|hash|both \
  --check-frame-deltas \
  --delta-metric mad|mse|ssim \
  --delta-lower-threshold 5.0 \
  --delta-upper-threshold 100.0

---

Behavior

1. Duplicate Detection:

   • timestamp: flag files with duplicate timestamps
   • hash: flag files with identical content
   • both: apply both checks

2. Delta Check:

   • Compare each frame to its predecessor
   • Compute pixel-wise change using the selected metric
   • Flag frames as:
     • "unchanged" if below --delta-lower-threshold
     • "outlier" if above --delta-upper-threshold

3. Output:

   • Extend metadata JSON to include:

     {
       "duplicates": [...],
       "frame_deltas": [
         { "frame": "frame_0001.jpg", "delta": 3.2, "status": "unchanged" },
         { "frame": "frame_0002.jpg", "delta": 115.4, "status": "outlier" }
       ]
     }

---

Implementation Notes

• Hashing: use SHA256 or perceptual hash libraries
• Delta metrics: start with MAD; optionally extend to SSIM, histogram diff
• Output: Remains compatible with pad-missing, enrich-metadata, or downstream workflows

---

Impact

Adds robust frame-level validation to early processing stages. Enables higher integrity for time-aligned video pipelines, anomaly detection, and quality-aware storytelling.