Near-Duplicate Frame Threshold in Claude-Video: Understanding the 2.0 Pixel Difference Limit

The near-duplicate frame threshold in claude-video is defined by the constant DEDUP_THRESHOLD with a fixed value of 2.0, representing the maximum allowed mean absolute per-pixel difference (on a 0‑255 scale) between successive 16×16 grayscale thumbnails.

The bradautomates/claude-video repository removes visually identical frames during video processing to ensure only distinct shots are retained for analysis. This deduplication logic relies on a specific numeric threshold that determines when two frames are considered near-duplicates worthy of removal.

Where the Threshold Is Defined

In skills/watch/scripts/frames.py, the threshold is declared as a module-level constant at lines 31‑38:

DEDUP_THRESHOLD = 2.0

This value represents the upper inclusive bound for the mean absolute difference calculation. When the computed delta between two frame thumbnails is less than or equal to 2.0, the later frame is discarded as a near-duplicate.

How the Threshold Is Calculated

The deduplication pipeline processes frames through three specific stages to apply this threshold:

Thumbnail Generation

Each extracted JPEG frame is downscaled to a DEDUP_THUMB × DEDUP_THUMB (16×16) grayscale thumbnail. This occurs in the _thumb_frames function via ffmpeg, reducing high-resolution video frames to compact 256-pixel representations (16×16) that enable fast pixel-level comparison.

Delta Computation

The _frame_delta function (lines 15‑22) computes the mean absolute per-pixel difference between two thumbnails. For each pixel position, it calculates the absolute difference between corresponding grayscale values (0‑255 range), then averages these differences across all 256 pixels.

Deduplication Logic

During processing in _dedupe_by_deltas (lines 90‑98), the algorithm compares each computed delta against DEDUP_THRESHOLD:

• If delta <= 2.0: The frame is classified as a near-duplicate and dropped
• If delta > 2.0: The frame is retained as visually distinct

This conservative threshold ensures only essentially static content—such as frozen terminal windows, static slides, or intentional pauses—is removed, while preserving subtle motions and scene transitions.

Implementation Example

You can manually verify whether two frames exceed the threshold using the internal utilities:

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

# Generate 16x16 grayscale thumbnails

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(f"Delta {delta:.2f} ≤ 2.0: Near-duplicate – drop second frame")
    else:
        print(f"Delta {delta:.2f} > 2.0: Distinct – keep both frames")

CLI Usage

The deduplication feature is controlled via the skills/watch/scripts/watch.py entry point. By default, the threshold is active:

# Enable near-duplicate removal (default behavior)

python -m skills.watch.scripts.watch \
    --url "https://youtu.be/example" \
    --dedup

# Disable deduplication to retain all frames

python -m skills.watch.scripts.watch \
    --url "https://youtu.be/example" \
    --no-dedup

Test Coverage

The inclusive nature of the threshold (delta == 2.0 triggers removal) is verified in tests/test_dedup.py, ensuring that boundary values are handled consistently across the codebase.

Summary

• The near-duplicate frame threshold is hardcoded as DEDUP_THRESHOLD = 2.0 in skills/watch/scripts/frames.py
• The threshold operates on 16×16 grayscale thumbnails generated via ffmpeg
• Only frames with a mean absolute per-pixel difference ≤ 2.0 (0‑255 scale) are discarded
• The logic is implemented in _frame_delta for calculation and _dedupe_by_deltas for filtering
• Deduplication is enabled by default via the --dedup flag in the CLI

Frequently Asked Questions

What exactly does the 2.0 threshold represent?

The value 2.0 represents the mean absolute per-pixel difference between two 16×16 grayscale thumbnails on a 0‑255 intensity scale. If the average absolute difference across all 256 pixels is 2.0 or less, the frames are considered near-duplicates. This low threshold ensures only visually identical frames are removed while preserving content with any meaningful variation.

How do I disable near-duplicate detection when processing videos?

Pass the --no-dedup flag to the watch script in skills/watch/scripts/watch.py. By default, the --dedup flag is enabled, but explicitly disabling it bypasses the _dedupe_by_deltas function entirely, retaining all extracted frames regardless of similarity.

Why does the code use 16×16 thumbnails specifically?

The DEDUP_THUMB = 16 constant balances computational efficiency with detection accuracy. Sixteen-by-sixteen pixels provide sufficient granularity to detect meaningful visual changes while keeping memory usage low and processing speed high when computing deltas across thousands of video frames.

Does this threshold remove all duplicate frames or only near-duplicates?

The threshold specifically targets near-duplicates—frames that are visually identical but may have minor encoding variations or noise. It does not remove intentional duplicates like intentional freeze-frames unless they are truly pixel-identical (within the 2.0 tolerance). Scene cuts, camera movements, and subtle animations will exceed the threshold and be preserved.

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