cue.frame_select

Frame selector for the digest pipeline.

Picks up to N keyframes from a candidate pool, protecting start / middle / end anchors through dedupe so the narrative arc isn't collapsed by a near-duplicate. Scoring favors window changes, user- event spikes, visual scene changes, and text density. Visual change catches scrolling / tab switches that don't move the title bar.

Pure-function design: callers pass the candidate list + the event timeline + a paused-interval predicate. The selector doesn't read the filesystem index directly so tests can drive it with synthetic keyframes.

keyframe_ts_ns

keyframe_ts_ns(path: Path) -> int

Recover the capture timestamp encoded in keyframe_<ts_ns>.jpg. Canonical parser — cue.digest and cue.llm both alias this.

select_digest_frames

select_digest_frames(candidates: list[Path], *, events: list[dict] | None = None, max_frames: int = 10, paused_predicate: Callable[[int], bool] | None = None) -> list[Path]

Pick up to max_frames keyframes for the digest backend.

candidates is the pool of keyframes inside the digest window (caller is responsible for windowing). events optionally provides MCAP-shape events used to score window-change and user-spike relevance. paused_predicate(ts_ns) returns True for any timestamp that fell inside a privacy-pause interval — those frames are dropped before any scoring.

Anchors (first / middle / last of the surviving candidates) are protected from the dedupe pass — they're load-bearing for the narrative arc and a near-duplicate elsewhere shouldn't evict them. Output is sorted chronologically.