# How Claude-Video Configures Near-Duplicate Frame Detection Thresholds

> Learn how Claude-Video configures near duplicate frame detection thresholds using a default mean pixel difference of 2.0 for efficient video processing.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-05

---

**Claude-Video uses a default mean pixel difference threshold of 2.0 on 16×16 grayscale thumbnails to identify and remove near-duplicate frames during video processing.**

The `bradautomates/claude-video` repository implements a perceptual deduplication stage to eliminate redundant frames before video analysis. Understanding how the near-duplicate frame detection threshold works allows you to tune the balance between processing speed and frame granularity when working with video content.

## The Perceptual Deduplication Pipeline

The deduplication process operates during the extraction phase, comparing downscaled representations of frames to detect visual similarity without processing full-resolution images.

### Thumbnail Generation

Every extracted frame is converted to a low-resolution grayscale thumbnail before comparison. In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the constant **`DEDUP_THUMB`** defines a default size of **16 × 16 pixels** (line 37). The helper function **`_thumb_frames`** handles this downscaling, creating tiny normalized representations that are robust to minor compression artifacts and lighting variations.

### Mean Pixel Difference Calculation

For each candidate frame after the first, the system computes the mean absolute per-pixel difference between the current thumbnail and the **last kept** thumbnail. This calculation occurs in the **`_frame_delta`** function, which returns a floating-point value representing the average pixel change across all 256 thumbnail pixels.

### Threshold Comparison Logic

The computed delta is compared against the constant **`DEDUP_THRESHOLD`**, defined as **2.0** in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (line 38). The comparison uses an **inclusive** check (`<=`) implemented in **`_dedupe_by_deltas`** (line 94), meaning any frame with a mean difference **at or below** 2.0 is classified as a near-duplicate and discarded. This conservative default ensures only virtually identical frames are removed, preserving meaningful visual changes in the sequence.

## Configuration Options

Claude-Video provides multiple interfaces for controlling deduplication behavior, from command-line flags to programmatic API calls.

### Default Threshold Characteristics

The **2.0** threshold represents a conservative value calibrated for typical video content. By operating on 16×16 grayscale thumbnails rather than full-resolution frames, the algorithm achieves high performance while maintaining sensitivity to actual scene changes versus minor encoding variations.

### Disabling Deduplication via CLI

Users can bypass deduplication entirely using the **`--no-dedup`** flag when invoking the watch command. This option is parsed in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (line 64) and passes a boolean `dedup` parameter to the extraction pipeline, preserving every extracted frame regardless of similarity.

### Custom Threshold Values

Advanced users can override the default threshold programmatically by calling **`dedupe_perceptual(frames, threshold=...)`** or the internal **`_dedupe_by_deltas(candidates, thumbs, threshold=...)`** function. Raising the threshold above 2.0 increases aggressiveness (dropping more frames), while lowering it preserves more frames at the cost of potential redundancy.

## Implementation Examples

The following patterns demonstrate how to interact with the deduplication system:

```python

# Standard usage with default threshold (2.0)

from skills.watch.scripts.frames import dedupe_perceptual

frames = [...]  # List of frame dictionaries from extraction

deduped, dropped = dedupe_perceptual(frames)
print(f"Dropped {dropped} near-duplicates")

```

```python

# Custom threshold - more aggressive deduplication

deduped, dropped = dedupe_perceptual(frames, threshold=5.0)

```

```bash

# Disable deduplication via command line

claude-video watch https://example.com/video.mp4 --no-dedup

```

## Summary

- **Default threshold**: 2.0 mean absolute pixel difference on 16×16 grayscale thumbnails.
- **Comparison logic**: Inclusive (`<=`) check in `_dedupe_by_deltas` drops frames at or below the threshold.
- **Performance optimization**: Thumbnail-based processing in `_thumb_frames` enables fast perceptual comparison without full-frame analysis.
- **User control**: Disable with `--no-dedup` flag in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), or override thresholds via the `dedupe_perceptual()` API.
- **File locations**: Core logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), with CLI handling in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

## Frequently Asked Questions

### What is the default near-duplicate frame detection threshold in claude-video?

The default threshold 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) (line 38). This value represents the mean absolute pixel difference between 16×16 grayscale thumbnails. Frames exhibiting a difference of 2.0 or less are considered near-duplicates and removed from the output sequence.

### How does claude-video determine if two frames are duplicates?

The system generates 16×16 pixel grayscale thumbnails for each frame using `_thumb_frames`, then calculates the mean absolute per-pixel difference via `_frame_delta`. This delta value is compared against the threshold using an inclusive comparison (`<=`). The algorithm tracks only the **last kept** frame as the comparison reference, creating a greedy deduplication chain rather than comparing against all previous frames.

### Can I disable near-duplicate detection entirely?

Yes. Pass the **`--no-dedup`** flag when running the watch command to skip the perceptual deduplication stage completely. This option is processed in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (line 64) and ensures all extracted frames are preserved regardless of visual similarity, which is useful when you require frame-perfect extraction for temporal analysis.

### What happens when a frame's mean difference equals exactly 2.0?

Frames with a mean difference **equal to** the threshold are **dropped**. The implementation in `_dedupe_by_deltas` uses an inclusive comparison (`if delta <= threshold`), meaning the threshold acts as a maximum allowable similarity bound. This conservative approach ensures that borderline cases are treated as duplicates rather than risking the retention of redundant frames.