# VisioForge Video Fingerprinting .Net API Documentation

The VisioForge Video Fingerprinting namespace provides powerful functionality for video content identification, comparison, and search operations. It enables applications to:

• Generate unique fingerprints from video files for content identification
• Compare videos to determine similarity and detect duplicates
• Search for video fragments within larger videos (e.g., finding commercials, intros, or specific scenes)
• Compare individual images for similarity detection (Windows only)
• Process video frames directly to generate fingerprints from streams or generated content

The main entry point for video fingerprinting operations, providing high-level static methods for analysis, comparison, and search.

• DebugDir (string): Directory path for debug output. Set to null to disable debug output.

public static void SetLicenseKey(string vfpLicense)

Sets the license key for Video Fingerprinting SDK. Must be called before using any fingerprinting features.

public static async Task<VFPFingerPrint> GetComparingFingerprintForVideoFileAsync(
    VFPFingerprintSource source,
    VFPErrorCallback errorDelegate = null,
    VFPProgressCallback progressDelegate = null)

Generates a fingerprint optimized for whole-video comparison operations.

Parameters:

• source: Video source configuration including file path, time range, and processing options
• errorDelegate: Optional callback for error messages
• progressDelegate: Optional callback for progress updates (0-100)

Returns: Generated fingerprint or null if an error occurred

Use Case: Comparing entire videos or large segments to determine overall similarity

public static async Task<VFPFingerPrint> GetSearchFingerprintForVideoFileAsync(
    VFPFingerprintSource source,
    VFPErrorCallback errorDelegate = null,
    VFPProgressCallback progressDelegate = null)

Generates a fingerprint optimized for fragment search operations.

Parameters:

• source: Video source configuration
• errorDelegate: Optional error callback
• progressDelegate: Optional progress callback

Returns: Generated fingerprint or null if an error occurred

Use Case: Creating fingerprints of short clips to locate within full-length videos

public static int Compare(VFPFingerPrint fp1, VFPFingerPrint fp2, TimeSpan shift)

Compares two video fingerprints to determine similarity.

Parameters:

• fp1: First fingerprint
• fp2: Second fingerprint
• shift: Maximum time shift allowed during comparison

Returns: Difference score (lower = more similar), or Int32.MaxValue if either fingerprint is null

public static List<TimeSpan> Search(
    VFPFingerPrint fp1,
    VFPFingerPrint fp2,
    TimeSpan duration,
    int maxDifference,
    bool allowMultipleFragments)

public static Task<List<TimeSpan>> SearchAsync(
    VFPFingerPrint fp1,
    VFPFingerPrint fp2,
    TimeSpan duration,
    int maxDifference,
    bool allowMultipleFragments)

Searches for occurrences of a video fragment within a larger video.

Parameters:

• fp1: Fragment fingerprint (needle)
• fp2: Video to search within (haystack)
• duration: Fragment duration (prevents overlapping matches)
• maxDifference: Maximum allowed difference (typical: 5-20)
• allowMultipleFragments: Find all occurrences vs. first match only

Returns: List of timestamps where matches were found

Represents a video fingerprint with metadata.

• Data (byte[]): Raw fingerprint data
• Duration (TimeSpan): Fingerprint duration
• ID (Guid): Unique identifier
• OriginalFilename (string): Source file name
• OriginalDuration (TimeSpan): Total duration of source video
• Tag (string): Optional user-defined tag
• Width (int): Source video width
• Height (int): Source video height
• FrameRate (double): Video frame rate
• IgnoredAreas (List<Rect>): Regions excluded from fingerprinting

public static VFPFingerPrint Load(string filename)
public static VFPFingerPrint Load(byte[] data)

Loads a fingerprint from file or memory.

public void Save(string filename)
public byte[] Save()

Saves fingerprint to file or memory. Default extension: .vsigx

Configuration for video fingerprinting operations.

public VFPFingerprintSource(string filename)

Creates a new source configuration. Throws FileNotFoundException if file doesn't exist.

• Filename (string): Path to source video file
• StartTime (TimeSpan): Start time for fingerprinting (default: 0)
• StopTime (TimeSpan): Stop time for fingerprinting (default: video duration)
• CustomCropSize (Rect): Crop rectangle (Left, Top, Right, Bottom distances)
• CustomResolution (Size): Target resolution (Empty = no resize)
• IgnoredAreas (List<Rect>): Regions to exclude (e.g., logos, timestamps)
• OriginalDuration (TimeSpan): Total video duration (auto-populated)

Database for managing collections of fingerprints.

• Items (List<VFPFingerPrint>): Collection of stored fingerprints

public void Save(string filename)
public static VFPFingerPrintDB Load(string filename)

Persists/retrieves database to/from disk.

public bool ContainsFile(VFPFingerprintSource source)

Checks if database contains a fingerprint for the specified source.

public VFPFingerPrint GetFingerprint(VFPFingerprintSource source)

Retrieves fingerprint matching the source configuration.

Creates fingerprints from individual image frames.

public VFPFingerprintFromFrames(
    double frameRate,
    int width,
    int height,
    TimeSpan totalDuration)

public void Push(byte[] rgb24frame)
public void Push(Bitmap frame)
public void Push(IntPtr rgb24frame, int rgb24frameSize)

Adds frames to the fingerprint generation process. Frames must match configured dimensions.

public VFPFingerPrint Build()

Generates final fingerprint from processed frames.

Static class for comparing individual images.

public static double Compare(Bitmap image1, Bitmap image2)

Compares two images and returns similarity score (0-100, where 100 = identical).

Low-level fingerprint comparison functionality.

• SetLicenseKey: Sets SDK license
• Process: Processes RGB24 frames
• Build: Builds fingerprint from processed data
• Compare: Compares two fingerprints

Low-level fingerprint search functionality.

• SetLicenseKey: Sets SDK license
• Process: Processes video frames
• Build: Builds search fingerprint
• Search: Searches for fragments

Manages native memory for search operations. Implements IDisposable.

public delegate void VFPProgressCallback(int percent)

Reports progress during fingerprinting operations (0-100).

public delegate void VFPErrorCallback(string error)

Reports errors during fingerprinting operations.

// Set license
VFPAnalyzer.SetLicenseKey("your-license-key");

// Create sources
var source1 = new VFPFingerprintSource("video1.mp4");
var source2 = new VFPFingerprintSource("video2.mp4");

// Generate fingerprints
var fp1 = await VFPAnalyzer.GetComparingFingerprintForVideoFileAsync(source1);
var fp2 = await VFPAnalyzer.GetComparingFingerprintForVideoFileAsync(source2);

// Compare
int difference = VFPAnalyzer.Compare(fp1, fp2, TimeSpan.FromSeconds(5));
bool areSimilar = difference < 20; // Lower = more similar

// Create fragment source (e.g., 30-second commercial)
var fragmentSource = new VFPFingerprintSource("commercial.mp4");

// Create full video source
var videoSource = new VFPFingerprintSource("movie.mp4");

// Generate fingerprints
var fragmentFp = await VFPAnalyzer.GetSearchFingerprintForVideoFileAsync(fragmentSource);
var videoFp = await VFPAnalyzer.GetComparingFingerprintForVideoFileAsync(videoSource);

// Search for all occurrences
var matches = await VFPAnalyzer.SearchAsync(
    fragmentFp,
    videoFp,
    fragmentSource.OriginalDuration,
    maxDifference: 10,
    allowMultipleFragments: true);

foreach (var timestamp in matches)
{
    Console.WriteLine($"Fragment found at: {timestamp}");
}

var source = new VFPFingerprintSource("video.mp4");

// Ignore channel logo in top-right corner
source.IgnoredAreas.Add(new Rect(1700, 50, 1870, 150));

// Ignore timestamp overlay
source.IgnoredAreas.Add(new Rect(100, 950, 300, 1000));

var fp = await VFPAnalyzer.GetComparingFingerprintForVideoFileAsync(source);

// Load or create database
var db = File.Exists("fingerprints.db") 
    ? VFPFingerPrintDB.Load("fingerprints.db")
    : new VFPFingerPrintDB();

// Check if already processed
var source = new VFPFingerprintSource("new_video.mp4");
if (!db.ContainsFile(source))
{
    var fp = await VFPAnalyzer.GetComparingFingerprintForVideoFileAsync(source);
    db.Items.Add(fp);
    db.Save("fingerprints.db");
}

var fpBuilder = new VFPFingerprintFromFrames(
    frameRate: 30.0,
    width: 1920,
    height: 1080,
    totalDuration: TimeSpan.FromMinutes(5));

// Add frames (e.g., from video stream)
foreach (var frame in videoFrames)
{
    fpBuilder.Push(frame); // Bitmap or byte[]
}

var fingerprint = fpBuilder.Build();
fingerprint.Save("stream_fingerprint.vsigx");

• Core functionality: Cross-platform (Windows, macOS, Linux, iOS, Android)
• VFPImageCompare: Windows only
• VFPFingerprintFromFrames: Windows only

1. Fingerprint Generation: CPU-intensive process, use async methods
2. Memory Usage: Fingerprints are compact but source videos require significant memory during processing
3. Ignored Areas: Applied before resizing for better performance
4. Search Operations: Time complexity increases with video length

1. License Key: Set once during application initialization
2. Error Handling: Always provide error callbacks for production code
3. Progress Reporting: Use progress callbacks for user feedback on long operations
4. Fingerprint Storage: Save fingerprints to avoid regenerating them
5. Difference Thresholds:
   • 0-5: Nearly identical
   • 5-15: Very similar with minor differences
   • 15-30: Similar content with noticeable differences
   • 30+: Different content

• Fingerprint files: .vsigx (recommended) or .sig (legacy)
• Database files: Custom JSON format with Base64-encoded binary data

A valid VisioForge license key is required for production use. The SDK may operate with limitations in trial mode.