How the Even Sampling Algorithm Retains First and Last Frames in Claude Video

The even sampling algorithm guarantees retention of the first and last frames by using a mathematical formula that maps index 0 to the first frame and index n-1 to the last frame, regardless of how many frames are selected.

The bradautomates/claude-video repository implements an intelligent frame selection strategy in its watch skill to manage video processing budgets. At the heart of this system lies the _even_indices helper function, which computes evenly-spaced indices while ensuring the temporal boundaries of the video are always preserved. This approach ensures that video analysis always includes the opening and closing visual context, even when aggressively downsampling high-frame-rate content.

Core Implementation of the Even Sampling Algorithm

The frame selection logic resides in skills/watch/scripts/frames.py and relies on two coordinated functions: _even_indices (lines 283-293) for index calculation and _even_sample (lines 401-413) for frame retrieval.

The _even_indices Helper Function

The _even_indices function implements a three-branch logic that handles different sampling scenarios while maintaining the first-last retention invariant:

def _even_indices(count: int, n: int) -> list[int]:
    """Indices of ``n`` evenly‑spaced items out of ``count`` (first + last kept)."""
    if n >= count:
        return list(range(count))           # all frames kept

    if n <= 1:
        return [0]                          # only the first frame kept

    return [round(i * (count - 1) / (n - 1)) for i in range(n)]

This implementation handles three distinct cases:

• Complete retention (n >= count): When the requested frame count exceeds or matches available frames, the function returns range(count), trivially including indices 0 and count-1.
• Single frame selection (n <= 1): When requesting one frame, the function returns [0], satisfying the "first equals last" condition.
• General sampling (1 < n < count): The list comprehension applies a scaling formula that ensures the first and last positions are mathematically locked.

Mathematical Guarantees for Frame Retention

The general case formula uses the expression:

[ \text{index}_i = \operatorname{round}!\Bigl( i \times \frac{(\text{count}-1)}{(n-1)} \Bigr) ]

This calculation guarantees boundary retention through specific boundary conditions:

• First frame guarantee: When i = 0, the expression evaluates to round(0) = 0, selecting the first frame.
• Last frame guarantee: When i = n-1, the expression evaluates to round(count-1) = count-1, selecting the final frame.

Intermediate indices are distributed uniformly across the range, creating a thinned subset that maintains visual continuity while respecting the max_frames constraint. The rounding operation prevents integer division artifacts without compromising the exact boundary positions.

Practical Implementation in _even_sample

The higher-level _even_sample function operationalizes these indices by mapping them back to actual frame data:

def _even_sample(candidates: list[dict], n: int) -> list[dict]:
    selected = [candidates[i] for i in _even_indices(len(candidates), n)]
    # … delete the un‑selected JPEGs and re‑index …

    return selected

This function feeds the candidate list length and desired cap into _even_indices, retrieves the corresponding dictionary objects, and discards unselected frames. Because _even_indices always includes indices 0 and len(candidates)-1 in its output, _even_sample preserves the opening and closing frames regardless of the downsampling ratio.

Working Examples of Even Sampling

Selecting 5 Frames from 12 Candidates

When downsampling a 12-frame sequence to 5 representative frames:

>>> candidates = list(range(12))               # pretend each number is a frame ID

>>> _even_indices(len(candidates), 5)
[0, 3, 6, 9, 11]                               # first (0) and last (11) kept

>>> _even_sample([{'id': i} for i in candidates], 5)
[{'id': 0}, {'id': 3}, {'id': 6}, {'id': 9}, {'id': 11}]

The algorithm selects indices 0, 3, 6, 9, and 11, maintaining equal spacing while anchoring the sequence boundaries.

Requesting More Frames Than Available

When the requested count exceeds available frames:

>>> _even_indices(4, 10)      # n > count

[0, 1, 2, 3]                  # returns every index, includes first & last

The function returns the full range, ensuring no artificial duplication occurs while still satisfying the boundary condition.

Single Frame Selection

When requesting a single representative frame:

>>> _even_indices(7, 1)
[0]                           # only the first frame (first = last)

The algorithm returns only the first frame, which serves as both the opening and closing visual for the sequence.

Summary

• The _even_indices function in skills/watch/scripts/frames.py (lines 283-293) uses the formula round(i * (count - 1) / (n - 1)) to compute evenly-spaced indices.
• The mathematical design ensures index 0 (first frame) and index count-1 (last frame) are always included in the output list.
• _even_sample (lines 401-413) translates these indices into actual frame selections, discarding unselected JPEGs while retaining boundary frames.
• Three edge cases—complete retention, single-frame selection, and general sampling—are all handled without breaking the first-last retention guarantee.
• Unit tests in tests/test_frames.py and tests/test_timestamps.py verify this behavior across various video processing scenarios.

Frequently Asked Questions

Why does the algorithm use (count - 1) / (n - 1) instead of count / n?

The denominator (n - 1) ensures that the final index i = n-1 maps exactly to count-1, the last frame. Using count / n would distribute frames across the range but would place the final sample at count - (count/n), missing the actual last frame. This adjustment creates an inclusive range that treats the first and last frames as fixed anchors.

What happens when max_frames exceeds the available frame count?

When n >= count, the _even_indices function returns list(range(count)), effectively keeping every available frame. This short-circuit prevents unnecessary computation and ensures the video is processed in its entirety when the budget allows, naturally including both boundary frames.

How does rounding affect frame selection accuracy?

The round() function maps floating-point calculations to valid integer indices. While rounding can occasionally cause two consecutive indices to collapse into the same value (particularly with small count values), the boundary indices 0 and count-1 are immune to this effect because they calculate to exact integers before rounding. This preserves the critical first and last frame guarantee even when intermediate spacing is imperfect.

Where is the even sampling algorithm used in the claude-video pipeline?

The algorithm is invoked by the watch skill when processing scene-change detections, key-frame extractions, or timestamp-driven candidate frames. According to the bradautomates/claude-video source code, _even_sample is called to enforce the user-specified max_frames budget while ensuring the resulting subset maintains temporal coverage from the video's start to its end.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}