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

> Learn how the --no-dedup option in Claude-Video preserves near-duplicate frames by disabling the dedupe_perceptual function. Keep more video data with this essential flag.

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

---

**The `--no-dedup` flag preserves near-duplicate frames by setting the internal `dedup` variable to `False` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

### Thumbnail Generation via FFmpeg

The system first generates compressed fingerprints of each extracted JPEG. In [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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):

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

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

```

To preserve every frame including near-duplicates:

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

```python

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