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.

How it Works

The filter uses a multi-stage approach to detect and save unique frames:

1. Frame Input Stage

   • Receives video frames from the input source
   • Supports both file-based and stream-based input
   • Can process frames in real-time or from a video file

2. Hash-based Detection Stage

   • Computes three types of image hashes:
     • Perceptual Hash (pHash): Detects structural changes using DCT
     • Average Hash (aHash): Detects overall image changes
     • Difference Hash (dHash): Detects edge and gradient changes
   • Compares current frame hashes with previous frame hashes
   • Detects significant changes based on hash differences

3. Motion Detection Stage

   • Analyzes pixel-level differences between consecutive frames
   • Uses absolute difference and thresholding to detect motion
   • Helps identify frames with significant movement

4. SSIM-based Refinement Stage

   • Uses Structural Similarity Index (SSIM) for detailed comparison
   • Provides a more nuanced similarity score between frames
   • Helps prevent saving frames that are too similar

5. Frame Selection Criteria A frame is saved if it meets ALL of these conditions:

   • Hash differences exceed the threshold OR motion is detected
   • SSIM score is below the threshold (frames are different enough)
   • Minimum time has elapsed since the last saved frame

6. Output Stage

   • Saves selected frames to the specified output directory
   • Maintains a counter for frame numbering
   • Updates timing information for frame selection

Structure

The filtering pipeline is composed of multiple stages:

• Video Input (VideoIn): Reads the input video file
• HashFrameProcessor: Processes frames to detect motion or significant hash changes
• SSIMProcessor: Further refines the frame selection by comparing SSIM scores
• Output: Saves selected frames to the specified directory

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.