feat: record-video returns frame sheets and change numbers an agent can read, around one action in one command

Merged
HA
7d ago
+7156-213

Summary

  • uloop record-video now returns evidence an agent can read without watching the video: a sheet of up to 32 consecutive frames around the trigger or the biggest change, a timeline sheet of the whole clip, and per-frame change numbers.
  • One command records a clip around one action (--seconds N --trigger '<uloop command>'), and a finished recording can be cut into an exact frame or a range sheet, even with Unity closed.

User Impact

  • Before: an agent could record a video but had no way to look at it, so flicker, one-frame glitches, and stutter were judged from a single screenshot, from code reading, or from hand-written probes and pixel scripts.
  • After: one call records around the action and returns sheets and numbers that tell a two-frame flicker apart from a smooth pulse. In a before/after trial on a planted flicker bug, agents with this branch reached a verified fix in 6.0 minutes on average versus 7.8, with roughly half the uloop calls, and all of them judged the fix from pixel-based numbers instead of inferred state.

Changes

  • Frame analysis during recording, the burst sheet around a mark or the largest change, and _frames.json (#3372)
  • One-shot --seconds / --trigger (#3373)
  • Timeline sheet of the whole recording (#3374)
  • ffmpeg extraction of an exact frame or a range sheet from a finished recording (--video with --frame-at or --sheet-from / --sheet-to), working without the Editor (#3375)
  • Skill, tool descriptions, READMEs, and an ADR describing the sheets and numbers and how to read them (#3376)

Verification

  • Each child PR passed its own CI and an independent review before merging into the integration branch.
  • Manual trial on a sample game project: a positive control (flicker 65 / 32 / 32 versus fixed 58 / 3 / 4 for changed frames / frames matching two back / top alternating cell count) and a six-run before/after comparison.