How the `--no-dedup` Option Preserves Near-Duplicate Frames in Claude-Video

The --no-dedup flag preserves near-duplicate frames by setting the internal dedup variable to False in skills/watch/scripts/frames.py, which bypasses the dedupe_perceptual() function that normally removes frames with a mean-pixel delta below 2.0.

The claude-video repository by bradautomates provides a /watch skill that extracts frames from video content for AI analysis. By default, this process eliminates visually similar frames to reduce token usage, but the --no-dedup command-line option overrides this behavior to retain every sampled frame, even those that are nearly identical.

Understanding the Default Deduplication Pipeline

Before exploring how --no-dedup works, you need to understand the three-stage deduplication process defined in skills/watch/scripts/frames.py.

Thumbnail Generation via FFmpeg

The system first generates compressed fingerprints of each extracted JPEG. In frames.py lines 44-50, the code invokes FFmpeg to downscale each frame to a 16×16 grayscale thumbnail using the DEDUP_THUMB constant. This creates a lightweight representation for comparison without processing full-resolution images.

Mean-Pixel Delta Calculation

Next, the _frame_delta function (lines 68-70) computes the average per-pixel absolute difference between the current thumbnail and the last kept thumbnail. If this delta falls below DEDUP_THRESHOLD (set to 2.0), the frame is flagged as a near-duplicate. This threshold determines how visually similar frames must be to trigger removal.

Greedy Removal in _dedupe_by_deltas

The _dedupe_by_deltas function (lines 80-100) implements a greedy chronological filter. It walks the frame list, drops any frame whose delta is less than or equal to the threshold, deletes the corresponding JPEG file, and re-indexes the survivors. This ensures only visually distinct frames remain for processing.

How --no-dedup Disables Deduplication

The --no-dedup option intercepts the deduplication logic before it executes, preventing the removal of similar frames.

Command-Line Flag Parsing

In skills/watch/scripts/frames.py lines 16-18, the argument parser detects --no-dedup and sets dedup = False. This boolean flag controls whether the deduplication pipeline runs at all.

Conditional Skip of dedupe_perceptual

After frame extraction completes, lines 102-104 and 117-119 check the dedup variable. When dedup is False, the code skips the call to dedupe_perceptual(), which normally orchestrates the thumbnail generation and delta filtering described above. Consequently, all extracted frames—including near-duplicates—are retained and passed to Claude for analysis.

Practical Usage and Code Examples

When using the /watch skill, you can observe the difference in behavior between the default and --no-dedup modes.

To run with default deduplication (removes near-duplicates):

watch.py https://example.com/video.mp4 --detail balanced

# Output shows: "8 near-duplicates dropped ..."

To preserve every frame including near-duplicates:

watch.py https://example.com/video.mp4 --detail balanced --no-dedup

# Output shows: "0 near-duplicates dropped" with higher frame count

The Python logic that enables this bypass looks like this:

# Argument parsing logic from frames.py

args = ["--no-dedup"]
dedup = True
i = 0
while i < len(args):
    if args[i] == "--no-dedup":
        dedup = False  # Disables the dedup step

        i += 1
    else:
        i += 1

# Later in the extraction pipeline...

if dedup:
    frames, dropped = dedupe_perceptual(frames)  # Skipped when --no-dedup is used

Summary

• Default behavior: The /watch skill generates 16×16 grayscale thumbnails and removes frames with a mean-pixel delta below 2.0 using _dedupe_by_deltas.
• Flag mechanism: --no-dedup sets dedup = False in skills/watch/scripts/frames.py lines 16-18.
• Result: Bypassing dedupe_perceptual() preserves all sampled frames, including near-duplicates, increasing the total frame count passed to Claude.
• Use case: Enable this option when you need to analyze subtle frame-to-frame variations that the default threshold of 2.0 would otherwise filter out.

Frequently Asked Questions

What threshold determines if frames are considered near-duplicates?

The deduplication logic uses a DEDUP_THRESHOLD of 2.0, defined in skills/watch/scripts/frames.py. The _frame_delta function calculates the mean absolute pixel difference between 16×16 grayscale thumbnails; frames with a delta at or below 2.0 are classified as near-duplicates and removed by default.

Does --no-dedup affect the frame extraction rate or sampling frequency?

No, --no-dedup only affects the post-extraction filtering phase. It does not change how frequently frames are sampled from the video (controlled by the --detail flag). It simply ensures that all sampled frames survive the perceptual deduplication check performed by _dedupe_by_deltas.

Why does the default behavior remove near-duplicate frames?

The default deduplication reduces token consumption and processing load by eliminating redundant visual information. According to the claude-video source code, removing near-identical frames prevents Claude from analyzing visually redundant content while keeping the distinctive frames that carry new information between timestamps.

Can I adjust the deduplication threshold instead of disabling it entirely?

The current implementation in skills/watch/scripts/frames.py uses a hardcoded DEDUP_THRESHOLD of 2.0. There is no command-line option to adjust this value; you must either accept the default filtering or use --no-dedup to disable it completely and handle deduplication manually in post-processing.

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