# How bradautomates/claude-video Frame Deduplication Works: Mean Absolute Difference Threshold Explained

> Discover how bradautomates/claude-video achieves frame deduplication with its Mean Absolute Difference threshold explanation. Learn about its efficient algorithm.

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

---

**bradautomates/claude-video removes duplicate video frames using a Mean Absolute Difference (MAD) threshold of 2.0 on 16×16 grayscale thumbnails, comparing each frame to the last kept frame in a greedy deduplication algorithm.**

The `claude-video` repository implements a lightweight, ffmpeg-based frame extraction system designed to collapse visually identical frames before sending video data to Claude. Understanding how the **mean absolute difference threshold** drives this process reveals why the tool can efficiently handle static slides, frozen screens, and redundant footage without external dependencies.

## The Three-Step MAD Deduplication Pipeline

The frame deduplication logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) and operates as a pure-Python pipeline using raw pixel data from ffmpeg. The process compresses video frames into tiny thumbnails and mathematically compares them using Mean Absolute Difference.

### Step 1: Thumbnail Generation with ffmpeg

Before comparison, every candidate JPEG is down-scaled to a **16 × 16 grayscale thumbnail**. The constant `DEDUP_THUMB = 16` defines this resolution, chosen to minimize memory footprint while preserving enough visual information to detect true duplicates.

The function `frames._thumb_frames` (lines 424–460) orchestrates this in a single ffmpeg pass, converting extracted frames into 256-byte grayscale arrays. This standardization ensures that the subsequent MAD calculation operates on uniform data regardless of the original video resolution.

### Step 2: Computing the Mean Absolute Difference

The core mathematical operation lives in `frames._frame_delta` (lines 315–322). This function accepts two thumbnail byte-arrays, `a` and `b`, and calculates the Mean Absolute Difference using the formula:

```

MAD = sum(|a[i] - b[i]|) / number_of_pixels

```

Because the thumbnails are 8-bit grayscale (values 0–255), the resulting MAD score ranges from **0.0** (identical) to **255.0** (completely inverted). This deterministic calculation requires no external libraries and executes in microseconds per comparison.

### Step 3: Greedy Duplicate Detection

The deduplication algorithm implemented in `frames._dedupe_by_deltas` (lines 380–400) uses a greedy approach to preserve distinct visual moments. Starting with the first candidate frame, it compares each subsequent thumbnail to the **last kept** thumbnail using `_frame_delta`.

If the calculated MAD is **less than or equal to 2.0** (the `DEDUP_THRESHOLD`), the frame is deleted as a duplicate. If the MAD exceeds 2.0, the frame becomes the new "last kept" reference. This strategy prevents cascade errors where a series of slightly shifting frames might accidentally collapse into a single representative.

## The DEDUP_THRESHOLD Constant and Its Value

The `DEDUP_THRESHOLD` is hardcoded to **2.0** in the source. This conservative value ensures that only truly identical or near-identical frames (such as static presentation slides or buffering screens) are removed, while genuine scene transitions and motion are preserved.

As verified in [`tests/test_dedup.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_dedup.py), the threshold is inclusive: a MAD of exactly 2.0 triggers deduplication. The test suite confirms this behavior through `test_dedupe_threshold_is_inclusive`, alongside tests proving that identical thumbnails score 0.0 and that distinct frames survive the filter.

## Implementation Details in frames.py

All higher-level extraction engines—including `extract_scene_or_uniform` and `extract_keyframes`—invoke `frames.dedupe_perceptual` (lines 360–368) when the `dedup=True` parameter is passed. This public API coordinates thumbnail generation and the greedy deduplication loop.

### Manual Deduplication of Frame Lists

You can invoke the deduplication logic directly on extracted frame metadata:

```python
from pathlib import Path
import frames

# Assume candidates is a list of frame dicts from an extractor

candidates = [
    {"index": 0, "timestamp_seconds": 0.0, "path": "frame_0000.jpg", "reason": "scene-change"},
    {"index": 1, "timestamp_seconds": 0.1, "path": "frame_0001.jpg", "reason": "scene-change"},
]

# Run MAD-based deduplication with default threshold of 2.0

survivors, dropped = frames.dedupe_perceptual(candidates)

print(f"Kept {len(survivors)} frames, dropped {dropped} duplicates.")

```

### Using High-Level Extraction with Deduplication

The deduplication step integrates seamlessly with the extraction pipeline:

```python
from pathlib import Path
import frames

video = "example.mp4"
out_dir = Path("frames_out")

# Extract with automatic MAD-based deduplication enabled

frames_out, meta = frames.extract_scene_or_uniform(
    video_path=video,
    out_dir=out_dir,
    fps=2.0,
    target_frames=50,
    max_frames=100,
    dedup=True,  # Triggers the MAD comparison

)

print(f"Engine: {meta['engine']}")
print(f"Deduped frames: {meta['deduped_count']}")

```

### Disabling Frame Deduplication

To retain all frames regardless of visual similarity, set `dedup=False`:

```python
frames_out, meta = frames.extract_scene_or_uniform(
    video_path=video,
    out_dir=out_dir,
    fps=2.0,
    target_frames=50,
    max_frames=100,
    dedup=False,  # No MAD comparison performed

)

```

## Why Mean Absolute Difference Works for Video Deduplication

The choice of MAD over perceptual hashing or feature detection reflects three engineering priorities in `claude-video`:

- **Computational Efficiency**: Calculating absolute differences on 256-byte thumbnails is orders of magnitude faster than computing perceptual hashes or running neural network inference.
- **Deterministic Behavior**: The greedy algorithm's reliance on only the last kept frame eliminates the complexity of global optimization, ensuring predictable performance across video types.
- **Precision Control**: The 0–255 scale provides intuitive threshold tuning. A value of 2.0 represents less than 1% difference across the thumbnail, effectively isolating true duplicates while preserving compression artifacts and minor noise as distinct frames.

## Summary

- **bradautomates/claude-video** uses a **Mean Absolute Difference (MAD)** algorithm to detect duplicate frames during video processing.
- The system downsizes frames to **16×16 grayscale thumbnails** (`DEDUP_THUMB = 16`) before comparison.
- The **deduplication threshold is 2.0** (`DEDUP_THRESHOLD = 2.0`), meaning frames with a MAD of 2.0 or less are considered duplicates.
- The greedy algorithm in `_dedupe_by_deltas` compares each frame only to the last kept frame, preventing accidental removal of distinct scenes.
- All deduplication logic is implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) with comprehensive test coverage in [`tests/test_dedup.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_dedup.py).

## Frequently Asked Questions

### What is the exact mean absolute difference threshold used?

The threshold is defined as the constant `DEDUP_THRESHOLD` with a value of **2.0**. This means any two frames with a Mean Absolute Difference of 2.0 or less on their 16×16 grayscale thumbnails are considered duplicates and the latter frame is discarded.

### How does claude-video handle near-duplicate frames?

The algorithm uses a **greedy comparison** strategy where each frame is only compared to the last frame that was kept. If the MAD exceeds 2.0, the current frame is preserved and becomes the new reference point. This ensures that sequences of gradually changing frames (such as slow pans or fades) are not collapsed into a single frame, while static or frozen frames are removed.

### Can I disable frame deduplication in claude-video?

Yes. All high-level extraction functions accept a boolean `dedup` parameter. Setting `dedup=False` bypasses the calls to `dedupe_perceptual`, ensuring that all extracted frames are retained regardless of their visual similarity to previous frames.

### Why does the algorithm use 16×16 thumbnails?

The **16×16 resolution** (256 pixels total) provides the minimal viable data needed to distinguish between truly distinct visual scenes while keeping the MAD calculation extremely fast. This size allows the algorithm to process thumbnails using standard Python operations without requiring image processing libraries like PIL or OpenCV, maintaining the repository's pure-stdlib approach.