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

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, 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:

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:

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, 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.
• 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 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 (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 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 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.

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