# What Is the Near-Duplicate Frame Threshold in Claude Video and How Is It Calculated?

> Discover the near-duplicate frame threshold in Claude Video, set at 2.0. Learn how this metric calculates and removes redundant frames to optimize your video processing.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: internals
- Published: 2026-07-11

---

**The near-duplicate frame threshold in Claude Video is defined by the constant `DEDUP_THRESHOLD` set to `2.0`, representing the maximum mean absolute per-pixel difference (on a 0-255 scale) between 16×16 grayscale thumbnails of consecutive frames, where values at or below this threshold trigger the removal of the later frame as a duplicate.**

Claude Video, an open-source video processing tool from the `bradautomates/claude-video` repository, automatically removes visually identical frames to streamline analysis. The near-duplicate frame threshold determines exactly when two consecutive frames are considered duplicates and one should be discarded during the extraction pipeline.

## Understanding the Near-Duplicate Frame Threshold

Inside [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the threshold is hardcoded as the constant `DEDUP_THRESHOLD` with a value of `2.0` (lines 31-38). This value represents the maximum allowable **mean absolute per-pixel difference** between two successive frames when compared as grayscale thumbnails. Because pixel values range from 0 to 255, a threshold of 2.0 is extremely strict—only frames that are virtually identical will trigger deduplication.

## How the Threshold Is Calculated in Claude Video

The calculation follows a three-stage pipeline designed for efficiency using low-resolution thumbnails rather than full-frame comparisons.

### Step 1: Thumbnail Generation via `_thumb_frames`

First, each extracted JPEG frame is downscaled to a 16×16 grayscale thumbnail using ffmpeg. The `_thumb_frames` function handles this conversion, creating manageable `DEDUP_THUMB` × `DEDUP_THUMB` representations that preserve the essential visual structure while minimizing computational overhead.

### Step 2: Computing Frame Differences with `_frame_delta`

Next, the `_frame_delta` function (lines 15-22) calculates the mean absolute difference between corresponding pixels of two consecutive thumbnails. This involves computing the absolute value of the difference for each pixel pair and averaging these values across the entire 16×16 grid.

### Step 3: Applying the Threshold in `_dedupe_by_deltas`

Finally, during the deduplication phase, the `_dedupe_by_deltas` function (lines 90-98) compares each computed delta against `DEDUP_THRESHOLD`. If the delta is less than or equal to 2.0, the later frame is classified as a near-duplicate and discarded from the output sequence.

## Why the Threshold Is Set to 2.0

The value 2.0 is intentionally conservative. It effectively filters static content—such as presentation slides, frozen terminal windows, or fade transitions—while preserving frames with subtle motion or scene changes. This ensures that only truly redundant visual information is removed, maintaining the narrative flow of the video while reducing redundant data.

## Working with the Near-Duplicate Threshold in Code

You can interact with the threshold programmatically or via the command line. The following example demonstrates manual duplicate detection using the internal API:

```python
from pathlib import Path
from skills.watch.scripts.frames import _thumb_frames, _frame_delta, DEDUP_THRESHOLD

thumbs = _thumb_frames([Path('frame_0001.jpg'), Path('frame_0002.jpg')])
if thumbs and len(thumbs) == 2:
    delta = _frame_delta(thumbs[0], thumbs[1])
    if delta <= DEDUP_THRESHOLD:
        print("Near-duplicate – drop second frame")
    else:
        print("Distinct – keep both frames")

```

To process a full video with deduplication enabled (the default behavior), use the CLI:

```bash
python -m skills.watch.scripts.watch \
    --url "https://youtu.be/example" \
    --dedup        # enabled by default; use --no-dedup to disable

```

The deduplication logic is thoroughly tested in [`tests/test_dedup.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_dedup.py), which verifies that frames with deltas exactly equal to the threshold are correctly treated as duplicates.

## Summary

- The near-duplicate frame threshold in Claude Video is defined by `DEDUP_THRESHOLD` with a value of `2.0` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).
- It represents the maximum mean absolute per-pixel difference between 16×16 grayscale thumbnails of consecutive frames.
- The calculation involves `_thumb_frames` for thumbnail generation, `_frame_delta` for difference computation, and `_dedupe_by_deltas` for threshold comparison.
- Frames with deltas ≤ 2.0 are discarded as near-duplicates, effectively removing static shots while preserving scene changes.
- The threshold is tested in [`tests/test_dedup.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_dedup.py) and can be toggled via the `--dedup`/`--no-dedup` CLI flags.

## Frequently Asked Questions

### What is the exact value of the near-duplicate frame threshold in Claude Video?

The exact value is `2.0`, defined as the constant `DEDUP_THRESHOLD` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 31-38). This value operates on a 0-255 pixel scale, representing the maximum mean absolute difference allowed between two frame thumbnails before they are considered distinct.

### How does Claude Video calculate the difference between two frames?

Claude Video calculates differences using the `_frame_delta` function, which computes the mean absolute per-pixel difference between two 16×16 grayscale thumbnails. These thumbnails are generated by the `_thumb_frames` function using ffmpeg, creating lightweight representations that make the comparison computationally efficient while preserving visual similarity metrics.

### Can I adjust the near-duplicate threshold when processing videos?

Currently, the threshold is hardcoded as a constant in the source code. While you cannot adjust it via command-line arguments, you can modify the `DEDUP_THRESHOLD` value directly in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) before running the extraction, or disable deduplication entirely using the `--no-dedup` flag if you need to preserve all frames regardless of similarity.

### What happens if a frame's delta equals exactly 2.0?

According to the test suite in [`tests/test_dedup.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_dedup.py) and the implementation in `_dedupe_by_deltas`, frames with a delta exactly equal to 2.0 are treated as near-duplicates and are discarded. The comparison uses `<= DEDUP_THRESHOLD`, making the threshold inclusive for duplicate detection.