Frame Deduplication Filter

The FilterFrameDedup is a lightweight filter designed to reduce redundant frames in a video stream. It compares incoming frames using hashing and visual similarity, saving only frames that are significantly different from the last saved one.

Features

• Hash-Based Difference Detection
  Uses perceptual hashing to quickly determine if a new frame is significantly different from previous ones.

• SSIM Filtering
  After passing the hash/motion check, frames are further evaluated using SSIM to ensure visual uniqueness.

• Motion Sensitivity
  Discards frames below a configurable motion threshold to filter out camera shake or static noise.

• Minimum Time Between Saves
  Ensures saved frames are spaced apart using the min_time_between_frames parameter (in seconds).

• Region of Interest (ROI)
  Optionally restrict processing to a specified sub-region of the frame.

• Debug Mode
  Enables detailed logging of frame acceptance/rejection decisions.

Example Output

Saved frames are written to disk using sequential names:

/output/
├── frame_000001.jpg
├── frame_000002.jpg
└── ...

Only frames that pass all deduplication filters are saved.

When to Use

Use this filter when:

• You need to extract keyframes or snapshots from a long video
• You want to avoid duplicate-looking frames in downstream storage or processing
• You want a low-overhead way to sample frames from video streams

Configuration Reference

Key	Type	Default	Description
hash_threshold	int	5	Minimum hash difference to consider a frame unique
motion_threshold	int	1200	Minimum motion intensity to consider for processing
min_time_between_frames	float	1.0	Minimum time (in seconds) between saved frames
ssim_threshold	float	0.90	SSIM score threshold (lower = more dissimilar)
roi	tuple | null	None	ROI as (x, y, width, height) or None for full frame
output_folder	string	"/output"	Directory to save selected frames
debug	boolean	false	Enable detailed logging

Tip

Combining hash and SSIM checks ensures high precision in deduplication while maintaining speed.