How Claude-Video Configures Near-Duplicate Frame Detection Thresholds

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, 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 (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 (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:

# 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")

# Custom threshold - more aggressive deduplication

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

# 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, or override thresholds via the dedupe_perceptual() API.
• File locations: Core logic resides in skills/watch/scripts/frames.py, with CLI handling in 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 (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 (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.

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