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

> Learn how the even sampling algorithm in Claude Video retains first and last frames using a unique mathematical mapping. Ensure crucial video segments are always preserved.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-08

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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:

```python
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:

```python
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:

```python
>>> 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:

```python
>>> _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:

```python
>>> _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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/tests/test_frames.py) and [`tests/test_timestamps.py`](https://github.com/bradautomates/claude-video/blob/main/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.