Getting Started with Video Fingerprinting SDK C++¶

Welcome to the VisioForge Video Fingerprinting SDK for C++! This comprehensive guide will walk you through everything you need to get started, from installation to your first working application. By the end of this guide, you'll have a solid foundation for building high-performance video fingerprinting applications in C++.

Note: If you're already familiar with the .NET SDK, you'll find the C++ SDK follows similar concepts with native performance benefits. See our SDK Comparison for details.

Quick Start Summary¶

If you're looking to get up and running quickly:

Download the SDK package from VisioForge
Extract the files to your project directory
Include the headers: #include <VisioForge_VFP.h> and #include <VisioForge_VFP_Types.h>
Link the appropriate library: VisioForge_VideoFingerprinting.lib (x86) or VisioForge_VideoFingerprinting_x64.lib (x64)
Copy runtime DLLs to your output directory
Set your license key (if purchased): VFPSetLicenseKey(L"license-key");
Generate your first fingerprint using the examples below

Prerequisites and System Requirements¶

For detailed system requirements including supported platforms, hardware specifications, and performance considerations, please see our comprehensive System Requirements guide.

C++-Specific Requirements¶

Windows Compiler: Visual Studio 2019+ (recommended) or MinGW-w64
Linux Compiler: GCC 7+ or Clang 6+
macOS Compiler: Xcode 12+ with Command Line Tools
Build Tools: CMake 3.10+ (optional but recommended for Linux/macOS)

SDK Package Contents¶

After downloading the SDK, you'll find the following structure:

VideoFingerprinting_CPP_SDK/
├── include/
│   ├── VisioForge_VFP.h           # Main API header
│   └── VisioForge_VFP_Types.h     # Type definitions
├── lib/
│   ├── VisioForge_VideoFingerprinting.lib      # x86 import library
│   └── VisioForge_VideoFingerprinting_x64.lib  # x64 import library
├── redist/
│   ├── VisioForge_VideoFingerprinting.dll      # x86 runtime DLL
│   ├── VisioForge_VideoFingerprinting_x64.dll  # x64 runtime DLL
│   ├── VisioForge_FFMPEG_Source.dll           # x86 media support
│   └── VisioForge_FFMPEG_Source_x64.dll       # x64 media support
├── demos/
│   ├── vfp_gen/        # Fingerprint generation demo
│   ├── vfp_compare/    # Video comparison demo
│   └── vfp_search/     # Fragment search demo
└── README.txt

Setting Up Your Development Environment¶

Visual Studio Setup (Windows)¶

Step 1: Create a New Project¶

Open Visual Studio 2019 or later
Click "Create a new project"
Select "Console App" (C++)
Name your project (e.g., "VFPExample")
Choose a location and click "Create"

Step 2: Configure Project Properties¶

Right-click your project in Solution Explorer
Select "Properties"
Configure the following settings:

Configuration Properties → C/C++ → General:

Additional Include Directories: $(ProjectDir)include

Configuration Properties → Linker → General:

Additional Library Directories: $(ProjectDir)lib

Configuration Properties → Linker → Input:

Additional Dependencies (x86): VisioForge_VideoFingerprinting.lib
Additional Dependencies (x64): VisioForge_VideoFingerprinting_x64.lib

Step 3: Add SDK Files¶

Copy the include folder to your project directory
Copy the lib folder to your project directory
Copy DLL files from redist to your output directory (e.g., Debug or Release)

Step 4: Configure Post-Build Events¶

Add a post-build event to automatically copy DLLs:

xcopy /y "$(ProjectDir)redist\*.dll" "$(OutDir)"

CMake Setup (Cross-Platform)¶

Create a CMakeLists.txt file:

cmake_minimum_required(VERSION 3.10)
project(VFPExample)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find SDK files
set(VFP_SDK_PATH "${CMAKE_CURRENT_SOURCE_DIR}/sdk")

# Include directories
include_directories(${VFP_SDK_PATH}/include)

# Platform-specific configuration
if(WIN32)
    # Windows configuration
    link_directories(${VFP_SDK_PATH}/lib)

    if(CMAKE_SIZEOF_VOID_P EQUAL 8)
        set(VFP_LIBRARIES VisioForge_VideoFingerprinting_x64)
        set(VFP_RUNTIME_LIBS 
            ${VFP_SDK_PATH}/redist/VisioForge_VideoFingerprinting_x64.dll
            ${VFP_SDK_PATH}/redist/VisioForge_FFMPEG_Source_x64.dll)
    else()
        set(VFP_LIBRARIES VisioForge_VideoFingerprinting)
        set(VFP_RUNTIME_LIBS 
            ${VFP_SDK_PATH}/redist/VisioForge_VideoFingerprinting.dll
            ${VFP_SDK_PATH}/redist/VisioForge_FFMPEG_Source.dll)
    endif()
elseif(APPLE)
    # macOS configuration
    link_directories(${VFP_SDK_PATH}/lib)
    set(VFP_LIBRARIES VisioForge_VideoFingerprinting)
elseif(UNIX)
    # Linux configuration
    link_directories(${VFP_SDK_PATH}/lib)
    set(VFP_LIBRARIES VisioForge_VideoFingerprinting)
endif()

# Add executable
add_executable(vfp_example main.cpp)

# Link libraries
target_link_libraries(vfp_example ${VFP_LIBRARIES})

# Copy runtime libraries on Windows
if(WIN32)
    foreach(DLL ${VFP_RUNTIME_LIBS})
        add_custom_command(TARGET vfp_example POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
            ${DLL} $<TARGET_FILE_DIR:vfp_example>)
    endforeach()
endif()

Build the project:

mkdir build
cd build
cmake ..
cmake --build .

Linux Setup¶

Install Dependencies¶

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install build-essential cmake
sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
sudo apt-get install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad
sudo apt-get install gstreamer1.0-libav

Fedora/RHEL:

sudo dnf install gcc-c++ cmake
sudo dnf install gstreamer1-devel gstreamer1-plugins-base-devel
sudo dnf install gstreamer1-plugins-good gstreamer1-plugins-bad-free
sudo dnf install gstreamer1-libav

Build Configuration¶

Create a simple Makefile:

CXX = g++
CXXFLAGS = -std=c++11 -Wall -I./include
LDFLAGS = -L./lib -lVisioForge_VideoFingerprinting -Wl,-rpath,'$$ORIGIN/lib'

TARGET = vfp_example
SOURCES = main.cpp
OBJECTS = $(SOURCES:.cpp=.o)

all: $(TARGET)

$(TARGET): $(OBJECTS)
 $(CXX) $(OBJECTS) $(LDFLAGS) -o $(TARGET)

%.o: %.cpp
 $(CXX) $(CXXFLAGS) -c $< -o $@

clean:
 rm -f $(OBJECTS) $(TARGET)

.PHONY: all clean

macOS Setup¶

Install Xcode Command Line Tools¶

xcode-select --install

Build Configuration¶

Create a build script build.sh:

#!/bin/bash

# Compiler settings
CXX=clang++
CXXFLAGS="-std=c++11 -Wall -I./include"
LDFLAGS="-L./lib -lVisioForge_VideoFingerprinting"

# Set library path
export DYLD_LIBRARY_PATH=./lib:$DYLD_LIBRARY_PATH

# Build
$CXX $CXXFLAGS main.cpp $LDFLAGS -o vfp_example

echo "Build complete. Run with: ./vfp_example"

Make it executable and run:

chmod +x build.sh
./build.sh

Your First Application¶

Let's create a simple application that generates a fingerprint from a video file.

Step 1: Create main.cpp¶

#include <iostream>
#include <string>
#include <cstring>

#ifdef _WIN32
#include <Windows.h>
#endif

#include <VisioForge_VFP.h>
#include <VisioForge_VFP_Types.h>

int main(int argc, char* argv[])
{
    std::cout << "VisioForge Video Fingerprinting SDK - First Application\n";
    std::cout << "========================================================\n\n";

    // Check command line arguments
    if (argc != 2) {
        std::cout << "Usage: " << argv[0] << " <video_file>\n";
        std::cout << "Example: " << argv[0] << " sample.mp4\n";
        return 1;
    }

    // Convert filename to wide character (for Windows compatibility)
    wchar_t videoFile[256];
#ifdef _WIN32
    size_t converted;
    mbstowcs_s(&converted, videoFile, argv[1], 256);
#else
    mbstowcs(videoFile, argv[1], 256);
#endif

    // Step 1: Set license key
    std::cout << "Setting license key...\n";
    VFPSetLicenseKey(L"TRIAL");  // Use "TRIAL" for evaluation

    // Step 2: Configure the source
    std::cout << "Configuring source for: " << argv[1] << "\n";
    VFPFingerprintSource source{};
    VFPFillSource(videoFile, &source);

    // Optional: Configure processing parameters
    // source.StartTime = 0;      // Start from beginning
    // source.StopTime = 60000;   // Process first 60 seconds

    // Step 3: Generate fingerprint
    std::cout << "Generating fingerprint...\n";
    VFPFingerPrint fingerprint{};

    wchar_t* error = VFPSearch_GetFingerprintForVideoFile(source, &fingerprint);

    if (error != nullptr) {
        std::wcerr << L"Error: " << error << L"\n";
        return 1;
    }

    // Step 4: Display results
    std::cout << "\nFingerprint generated successfully!\n";
    std::cout << "=====================================\n";
    std::cout << "Video Information:\n";
    std::cout << "  Duration: " << (fingerprint.Duration / 1000.0) << " seconds\n";
    std::cout << "  Resolution: " << fingerprint.Width << "x" << fingerprint.Height << "\n";
    std::cout << "  Frame Rate: " << fingerprint.FrameRate << " fps\n";
    std::cout << "  Data Size: " << fingerprint.DataSize << " bytes\n";

    // Step 5: Save fingerprint to file
    wchar_t outputFile[256];
#ifdef _WIN32
    wcscpy_s(outputFile, videoFile);
    wcscat_s(outputFile, L".vfpsig");
#else
    wcscpy(outputFile, videoFile);
    wcscat(outputFile, L".vfpsig");
#endif

    std::cout << "\nSaving fingerprint...\n";
    VFPFingerprintSave(&fingerprint, outputFile);

    char outputFileAnsi[256];
#ifdef _WIN32
    size_t convertedOut;
    wcstombs_s(&convertedOut, outputFileAnsi, outputFile, 256);
#else
    wcstombs(outputFileAnsi, outputFile, 256);
#endif

    std::cout << "Fingerprint saved to: " << outputFileAnsi << "\n";

    std::cout << "\nSuccess! You can now use this fingerprint for:\n";
    std::cout << "  - Comparing with other videos for similarity\n";
    std::cout << "  - Searching for this video in longer broadcasts\n";
    std::cout << "  - Building a database of video fingerprints\n";

    return 0;
}

Step 2: Build and Run¶

Windows (Visual Studio)¶

Press F7 to build the solution
Copy a test video file to your output directory
Open Command Prompt in the output directory
Run: VFPExample.exe testvideo.mp4

Windows (Command Line)¶

cl /EHsc /I.\include main.cpp /link /LIBPATH:.\lib VisioForge_VideoFingerprinting_x64.lib
copy redist\*.dll .
VFPExample.exe testvideo.mp4

Linux¶

g++ -std=c++11 -I./include main.cpp -L./lib -lVisioForge_VideoFingerprinting -o vfp_example
export LD_LIBRARY_PATH=./lib:$LD_LIBRARY_PATH
./vfp_example testvideo.mp4

macOS¶

clang++ -std=c++11 -I./include main.cpp -L./lib -lVisioForge_VideoFingerprinting -o vfp_example
export DYLD_LIBRARY_PATH=./lib:$DYLD_LIBRARY_PATH
./vfp_example testvideo.mp4

Understanding Fingerprint Types¶

The SDK provides two types of fingerprints optimized for different use cases. For a comprehensive explanation including technical details, performance characteristics, and decision guidance, see our Fingerprint Types Guide.

Quick Reference: - Search Fingerprints (VFPSearch_GetFingerprintForVideoFile()): For finding video fragments within larger videos (commercial detection, content monitoring) - Compare Fingerprints (VFPCompare_GetFingerprintForVideoFile()): For comparing entire videos for similarity (duplicate detection, version comparison)

Common Use Cases¶

Use Case 1: Duplicate Detection¶

// Generate fingerprints for two videos
VFPFingerPrint fp1{}, fp2{};
// ... generate fingerprints ...

// Compare them
double difference = VFPCompare_Compare(
    fp1.Data, fp1.DataSize,
    fp2.Data, fp2.DataSize,
    10  // Allow up to 10 seconds shift
);

if (difference < 100) {
    std::cout << "Videos are duplicates\n";
}

Use Case 2: Commercial Detection¶

// Load commercial and broadcast fingerprints
VFPFingerPrint commercial{}, broadcast{};
VFPFingerprintLoad(&commercial, L"commercial.vfpsig");
VFPFingerprintLoad(&broadcast, L"broadcast.vfpsig");

// Search for commercial
double diff;
int position = VFPSearch_Search2(
    &commercial, 0,
    &broadcast, 0,
    &diff, 300  // threshold
);

if (position != INT_MAX) {
    std::cout << "Commercial found at: " << position << " seconds\n";
}

Use Case 3: Content Verification¶

// Generate fingerprint with ignored areas for logos
VFPFingerprintSource source{};
VFPFillSource(L"video.mp4", &source);

// Ignore logo areas
source.IgnoredAreas[0] = {0, 0, 200, 100};        // Top-left logo
source.IgnoredAreas[1] = {1720, 980, 1920, 1080}; // Bottom-right watermark

VFPFingerPrint fingerprint{};
VFPSearch_GetFingerprintForVideoFile(source, &fingerprint);

Licensing¶

Trial Mode¶

For evaluation, use the trial license:

VFPSetLicenseKey(L"TRIAL");

Trial mode limitations:

Adds watermark to processed frames
Limited to 60 seconds of processing per session
Full functionality otherwise available

Commercial License¶

For production use, purchase a license from VisioForge:

VFPSetLicenseKey(L"YOUR-LICENSE-KEY-HERE");

License types:

Developer License: For development and testing
Deployment License: For distribution with your application
Server License: For server-based deployments

Troubleshooting¶

Common Issues and Solutions¶

Issue: DLL Not Found¶

Error: "The program can't start because VisioForge_VideoFingerprinting.dll is missing"

Solution:

Ensure DLLs are in the same directory as your executable
Or add the DLL directory to your PATH environment variable
Check you're using the correct architecture (x86 vs x64)

Issue: Unsupported Video Format¶

Error: "Unable to process video file"

Solution:

Ensure video codec is supported (H.264, H.265, VP8, VP9, AV1)
Install additional codec packs if needed
Try converting the video to a standard format

Issue: License Key Not Working¶

Error: "Invalid license key"

Solution:

Verify the license key is entered correctly
Ensure VFPSetLicenseKey() is called before any other SDK functions
Check that the license hasn't expired
Verify you're using the correct license for your platform

Issue: Memory Access Violation¶

Error: Access violation reading location

Solution:

Initialize all structures with {} before use
Check that pointers are valid before use
Ensure proper string buffer sizes
Don't free SDK-allocated memory manually

Issue: Poor Performance¶

Symptom: Processing is slower than expected

Solution:

Use Release build configuration, not Debug
Enable compiler optimizations (/O2 or -O2)
Process videos from local SSD, not network drives
Consider using multiple threads for batch processing
Reduce video resolution if quality permits

Debug Tips¶

Enable debug output: Set VFPAnalyzer.DebugDir to save intermediate results
Check return values: Always check for NULL/error returns
Use debug builds: Initially develop with debug symbols
Log operations: Add logging to track processing flow
Test with known files: Use reference videos to verify setup

Next Steps¶

Now that you have a working setup, explore these advanced topics:

Batch Processing: Process multiple files efficiently
Database Integration: Store fingerprints in a database
Real-time Processing: Generate fingerprints from live streams
Custom UI: Build graphical interfaces for your applications
Performance Optimization: Tune for your specific use case

Sample Projects¶

The SDK includes three complete sample projects:

vfp_gen - Fingerprint Generation¶

Demonstrates how to generate fingerprints with various options:

vfp_gen source.mp4 output.sig 0 0 0

vfp_compare - Video Comparison¶

Shows how to compare two videos for similarity:

vfp_compare video1.sig video2.sig 100 10

vfp_search - Fragment Search¶

Illustrates searching for video fragments:

vfp_search needle.sig haystack.sig 300

Study these examples to understand best practices and common patterns.

Support and Resources¶

Getting Help¶

Support Email: support@visioforge.com
Discord Community: Join for real-time help and discussions
GitHub Examples: Additional code samples and integrations

Reporting Issues¶

When reporting issues, please provide:

SDK version and platform
Minimal code example reproducing the issue
Error messages and stack traces
Sample video files (if applicable)
System specifications

Conclusion¶

You now have everything needed to start building video fingerprinting applications with the C++ SDK. The SDK provides powerful functionality with excellent performance, suitable for both desktop applications and server deployments.

Remember to:

Start with the provided examples
Test thoroughly with your target content
Optimize parameters for your use case
Reach out for support when needed

Happy coding with VisioForge Video Fingerprinting SDK!

Getting Started with Video Fingerprinting SDK C++¶

Quick Start Summary¶

Prerequisites and System Requirements¶

C++-Specific Requirements¶

SDK Package Contents¶

Setting Up Your Development Environment¶

Visual Studio Setup (Windows)¶

Step 1: Create a New Project¶

Step 2: Configure Project Properties¶

Step 3: Add SDK Files¶

Step 4: Configure Post-Build Events¶

CMake Setup (Cross-Platform)¶

Linux Setup¶

Install Dependencies¶

Build Configuration¶

macOS Setup¶

Install Xcode Command Line Tools¶

Build Configuration¶

Your First Application¶

Step 1: Create main.cpp¶

Step 2: Build and Run¶

Windows (Visual Studio)¶

Windows (Command Line)¶

Linux¶

macOS¶

Understanding Fingerprint Types¶

Common Use Cases¶

Use Case 1: Duplicate Detection¶

Use Case 2: Commercial Detection¶

Use Case 3: Content Verification¶

Licensing¶

Trial Mode¶

Commercial License¶

Troubleshooting¶

Common Issues and Solutions¶

Issue: DLL Not Found¶

Issue: Unsupported Video Format¶

Issue: License Key Not Working¶

Issue: Memory Access Violation¶

Issue: Poor Performance¶

Debug Tips¶

Next Steps¶

Recommended Reading¶

Sample Projects¶

vfp_gen - Fingerprint Generation¶

vfp_compare - Video Comparison¶

vfp_search - Fragment Search¶

Support and Resources¶

Getting Help¶

Reporting Issues¶

Conclusion¶