feat: record-video returns a timeline sheet of the whole recording

Merged
HA
8d ago
+327-1

Summary

  • Stopping a recording now also returns a timeline sheet: one PNG of evenly spaced frames from the whole recording, so an agent can see what the recording showed from start to end without opening the video.

User Impact

  • Before: the stop response pointed only at the burst sheet, which covers about a second around one moment and is absent when nothing changed. An agent had no readable overview of a longer or still recording.
  • After: the stop response carries TimelineSheetPath (5 columns, top-left first), TimelineSheetColumns, and TimelineFrames (frame number and seconds of each tile). The sheet is written for any recording with at least one captured frame, including still ones.

Changes

  • Tiles are kept every half second. A recording's length is unknown while it runs, so when the tiles exceed 40, every other one is dropped and the interval doubles; the sheet stays within 40 tiles at a near-even pace and always starts at the first frame. The next tile is due one interval after the last kept one, so a slow Editor that missed a slot does not bunch tiles together.
  • Dropped tiles' arrays are reused, as in the burst buffer.
  • The sheet and its frame list are written beside the video as <stem>_timeline.png and in the sidecar JSON's Timeline.

Verification

  • uloop compile: 0 errors.
  • uloop run-tests (regex over the timeline sampler, session, session analysis, response mapper, burst buffer, sidecar, and last-recording store tests): 72 passed, 0 failed.
  • Mutations caught: not resetting the next-due time after thinning, writing the timeline only from two tiles, and releasing a kept tile's array during thinning each fail a test.
  • Live Editor check: a 12-second Game View recording gave 24 tiles about 0.5 s apart (0.03 s to 11.93 s), 5 columns, in time order from the top-left, with the last slot empty at the bottom-right.