Table of Contents

Class VFPSearch

Namespace
VisioForge.Core.VideoFingerPrinting
Assembly
VisioForge.Core.dll

Provides static methods for building and analyzing video fingerprints for content matching.

public static class VFPSearch

Inheritance

Inherited Members

Remarks

The VisioForge.Core.VideoFingerPrinting.VFPSearch class is the main entry point for video fingerprint search operations. It provides methods to process video frames, build fingerprints from the processed data, and search for matching content between different fingerprints. All methods are static and interact with the native video fingerprinting library through P/Invoke calls.

Methods

Build(out long, ref VFPSearchData)

Builds a fingerprint from the accumulated frame data.

public static nint Build(out long length, ref VFPSearchData video)

Parameters

length long

When this method returns, contains the length of the fingerprint data in bytes.

video VFPSearchData

The VisioForge.Core.VideoFingerPrinting.VFPSearchData instance containing the processed frame data.

Returns

nint

A pointer to the newly allocated memory containing the fingerprint data. The caller is responsible for freeing this memory using FreeCoTaskMem(IntPtr).

Remarks

This method should be called after all frames have been processed using the VisioForge.Core.VideoFingerPrinting.VFPSearch.Process(System.IntPtr,System.Int32,System.Int32,System.Int32,System.TimeSpan,VisioForge.Core.VideoFingerPrinting.VFPSearchData@) method. The returned fingerprint can be saved to disk or used for searching operations. The method allocates new memory for the fingerprint data which must be freed by the caller.

Process(nint, int, int, int, TimeSpan, ref VFPSearchData)

Processes a single video frame for fingerprint generation.

public static int Process(nint ptr, int w, int h, int s, TimeSpan time, ref VFPSearchData video)

Parameters

ptr nint

Pointer to the RGB24 frame data in native memory.

w int

Width of the frame in pixels.

h int

Height of the frame in pixels.

s int

Stride (row pitch) of the frame data in bytes.

time TimeSpan

The timestamp of the frame relative to the start of the video.

video VFPSearchData

The VisioForge.Core.VideoFingerPrinting.VFPSearchData instance accumulating fingerprint data.

Returns

int

Returns 1 if processing was successful, 0 if invalid parameters were provided.

Remarks

This method should be called for each frame of the video in chronological order. The frame data must be in RGB24 format. Invalid dimensions or stride values will result in the method returning 0 without processing the frame.

Search(VFPFingerPrint, int, VFPFingerPrint, int, out double, int)

Searches for a video fragment within another video using fingerprint matching with automatic mirror detection.

public static int Search(VFPFingerPrint fp1, int skip1, VFPFingerPrint fp2, int skip2, out double difference, int maxDiff)

Parameters

fp1 VFPFingerPrint

The fingerprint of the video fragment to search for (needle).

skip1 int

Number of seconds to skip from the beginning of the first fingerprint.

fp2 VFPFingerPrint

The fingerprint of the video to search within (haystack).

skip2 int

Number of seconds to skip from the beginning of the second fingerprint.

difference double

When this method returns, contains the calculated difference score between the best match found. Lower values indicate better matches.

maxDiff int

The maximum allowed difference threshold. Matches with differences exceeding this value will not be considered valid.

Returns

int

The position (in seconds) within fp2 where fp1 was found, or MaxValue if no match was found within the difference threshold.

Remarks

This method performs a sliding window search to find the best match location. The search is optimized for finding video fragments that may have undergone slight modifications such as compression, scaling, or minor edits.

Enhanced with automatic mirror detection (v15.8.4+):

The search now automatically detects and matches video fragments that have been transformed:

  • Horizontally flipped (mirrored left-right)
  • Vertically flipped (mirrored top-bottom)
  • Rotated 180 degrees (both flips combined)

This enhancement dramatically improves the ability to find matching content in videos that have been intentionally modified to avoid detection, such as:

  • Copyright infringement attempts using mirrored uploads
  • Social media videos flipped to bypass content matching
  • Surveillance footage from different camera orientations

Backward compatibility: Existing code works without modification. The method automatically checks all orientations and returns the best match. Performance impact is proportional to the search space but optimized to minimize overhead.

Note: If you need to know which specific mirror transformation was detected, use the VisioForge.Core.VideoFingerPrinting.VFPSearch.SearchMirror(VisioForge.Core.VideoFingerPrinting.VFPFingerPrint,VisioForge.Core.VideoFingerPrinting.VFPFingerPrint) method instead.

SearchMirror(VFPFingerPrint, VFPFingerPrint)

Searches for a video fragment within another video with explicit mirror detection information.

public static VFPComparisonResult SearchMirror(VFPFingerPrint fp1, VFPFingerPrint fp2)

Parameters

fp1 VFPFingerPrint

The fingerprint of the video fragment to search for (needle).

fp2 VFPFingerPrint

The fingerprint of the video to search within (haystack).

Returns

VFPComparisonResult

Search result including position, difference score, and the specific mirror mode detected.

Remarks

This method provides the same mirror detection capabilities as the standard VisioForge.Core.VideoFingerPrinting.VFPSearch.Search(VisioForge.Core.VideoFingerPrinting.VFPFingerPrint,System.Int32,VisioForge.Core.VideoFingerPrinting.VFPFingerPrint,System.Int32,System.Double@,System.Int32) method, but additionally returns detailed information about which mirror transformation was detected.

Use cases:

  • Content moderation systems that need to log how videos were modified
  • Forensic analysis requiring transformation documentation
  • Analytics dashboards showing common transformation patterns
  • Automated correction systems that can un-mirror detected content

The returned VisioForge.Core.VideoFingerPrinting.VFPComparisonResult includes:

  • TimeOffset: Position in seconds where the match was found
  • Difference: Match quality score (lower is better)
  • MirrorMode: The specific transformation (None, Horizontal, Vertical, or Both)
  • Success: Whether the search completed successfully

Note: The standard VisioForge.Core.VideoFingerPrinting.VFPSearch.Search(VisioForge.Core.VideoFingerPrinting.VFPFingerPrint,System.Int32,VisioForge.Core.VideoFingerPrinting.VFPFingerPrint,System.Int32,System.Double@,System.Int32) method uses this functionality internally for mirror detection but only returns the position and difference for backward compatibility.

SearchMirror(VFPFingerPrint, VFPFingerPrint, double, double)

Searches for a video fragment within another video with explicit mirror detection and duration optimization.

public static VFPComparisonResult SearchMirror(VFPFingerPrint fp1, VFPFingerPrint fp2, double duration1, double duration2)

Parameters

fp1 VFPFingerPrint

The fingerprint of the video fragment to search for (needle).

fp2 VFPFingerPrint

The fingerprint of the video to search within (haystack).

duration1 double

Duration of the first video in seconds for search optimization.

duration2 double

Duration of the second video in seconds for search optimization.

Returns

VFPComparisonResult

Search result including position, difference score, and the specific mirror mode detected.

Remarks

This overload accepts duration hints to optimize the search algorithm for better performance when video lengths are known in advance. The duration information helps:

  • Optimize memory allocation for search buffers
  • Improve search window calculations
  • Reduce unnecessary comparisons at video boundaries

Mirror detection modes returned:

  • None: Videos match in original orientation
  • Horizontal: Match found with horizontal flip
  • Vertical: Match found with vertical flip
  • Both: Match found with 180-degree rotation

Performance tip: Providing accurate duration values can improve search performance by up to 20% for long videos by eliminating impossible match positions early in the search process.

SetLicenseKey(string)

Sets the license key for the video fingerprinting library.

public static void SetLicenseKey(string licenseKey)

Parameters

licenseKey string

The license key string provided by VisioForge.

Remarks

A valid license key is required to use the video fingerprinting functionality without limitations. Call this method once during application initialization before using any other fingerprinting features.