How to Configure the Frame Deduplication Threshold in Claude Video

Set the DEDUP_THRESHOLD constant in skills/watch/scripts/frames.py to control how aggressively Claude Video collapses near-duplicate frames, or use the --no-dedup flag to disable filtering entirely.

Claude Video, an open-source video processing tool in the bradautomates/claude-video repository, automatically removes redundant frames to reduce processing load. The frame deduplication threshold determines how similar two consecutive frames must be before one is discarded. Understanding how to configure this value lets you balance between video fidelity and processing efficiency.

Where the Threshold Is Defined

The deduplication threshold is hard-coded as a module-level constant in skills/watch/scripts/frames.py. According to the source code at lines 31-40, you will find two related constants that control the deduplication behavior:

DEDUP_THUMB = 16               # size of the thumbnail (16 × 16)

DEDUP_THRESHOLD = 2.0          # mean-pixel difference below which frames are collapsed

DEDUP_THUMB sets the resolution of the grayscale thumbnail used for comparison (16×16 pixels), while DEDUP_THRESHOLD sets the maximum allowed mean per-pixel difference between thumbnails. When the computed difference falls at or below this value, the frame is considered a duplicate.

How the Deduplication Logic Works

The filtering logic is implemented in the _dedupe_by_deltas function (lines 80-99 of frames.py). The process works as follows:

1. Each video frame is converted to a 16×16 grayscale thumbnail.
2. The _frame_delta helper computes the mean absolute difference between the current thumbnail and the last kept thumbnail.
3. If the computed difference is ≤ DEDUP_THRESHOLD, the frame is considered a near-duplicate and discarded.
4. If the difference exceeds the threshold, the frame is retained and becomes the new reference for subsequent comparisons.

This approach ensures that only visually distinct frames are processed downstream, significantly reducing redundant data while preserving meaningful visual changes.

Adjusting the Threshold Value

To change how aggressively Claude Video drops frames, modify the DEDUP_THRESHOLD value in skills/watch/scripts/frames.py.

Effect of different values:

• Lower values (e.g., 1.0): More aggressive deduplication; drops frames with subtle changes.
• Higher values (e.g., 5.0): Less aggressive; preserves more frames including minor variations.
• 0.0: Would theoretically drop only identical frames (not recommended for most use cases).

You can edit the file manually or use a command-line tool:

# Using sed to set threshold to 3.5

sed -i 's/^DEDUP_THRESHOLD = .*/DEDUP_THRESHOLD = 3.5/' \
  skills/watch/scripts/frames.py

Or open skills/watch/scripts/frames.py in your editor and change line 32:

DEDUP_THRESHOLD = 3.5  # Modified from default 2.0

Rebuilding the Skill Bundle

If you are running Claude Video as a compiled skill bundle rather than from source, you must rebuild the package after modifying the threshold. Navigate to the scripts directory and execute the build script:

cd skills/watch/scripts
./build-skill.sh

This produces dist/watch.skill, which you can reinstall in Claude Code, Codex, or other compatible hosts. Without rebuilding, the compiled bundle will continue using the previous threshold value.

Temporarily Disabling Deduplication

For one-off runs where you want to process every frame without modifying source code, pass the --no-dedup flag to the watch command. This option is handled in watch.py at line 64 and bypasses the threshold logic entirely:

claude-video watch /path/to/video.mp4 --no-dedup

This is useful when you need maximum frame fidelity for detailed motion analysis or when debugging the deduplication behavior itself.

Summary

• The frame deduplication threshold is controlled by the DEDUP_THRESHOLD constant in skills/watch/scripts/frames.py, defaulting to 2.0.
• Lower values make the filter more aggressive by dropping frames with smaller differences; higher values preserve more frames.
• The logic compares 16×16 grayscale thumbnails using _frame_delta and filters via _dedupe_by_deltas at lines 80-99.
• After modifying the threshold, run ./build-skill.sh in skills/watch/scripts to regenerate the skill bundle.
• Use the --no-dedup command-line flag to disable deduplication temporarily without code changes.

Frequently Asked Questions

What is the default frame deduplication threshold in Claude Video?

The default value is 2.0, defined as the DEDUP_THRESHOLD constant in skills/watch/scripts/frames.py. This represents the maximum mean per-pixel difference (on a 0-255 scale) between 16×16 grayscale thumbnails before a frame is considered unique enough to keep.

How do I completely disable frame deduplication without editing code?

Pass the --no-dedup flag when running the watch command. As implemented in watch.py at line 64, this flag prevents the _dedupe_by_deltas function from being called, ensuring every frame is processed regardless of similarity to previous frames.

Why does Claude Video use 16×16 thumbnails for deduplication?

The DEDUP_THUMB = 16 constant configures a 16×16 pixel grayscale representation of each frame. This resolution provides enough detail to detect meaningful visual changes while remaining computationally inexpensive to compare, keeping the _frame_delta calculations fast enough for real-time video processing.

Do I need to rebuild the skill after changing DEDUP_THRESHOLD?

Yes, if you are using the compiled skill bundle format. After editing skills/watch/scripts/frames.py, run ./build-skill.sh in the skills/watch/scripts directory to regenerate dist/watch.skill. If you are running the Python scripts directly from source, no rebuild is necessary.

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