FFmpeg Signature Filter for Video Fingerprinting

This guide explains how to generate and compare perceptual video fingerprints using the signature filter in FFmpeg. You will learn the exact command-line syntax required to extract MPEG-7 standard video signatures into XML or binary files, how to configure key filter parameters, and how to perform real-time matching between two video streams to detect duplicate or modified content.

Understanding the signature Filter

The FFmpeg signature filter calculates an MPEG-7 video signature for video frames. Unlike cryptographic hashes (such as MD5 or SHA-256) that change completely if a single bit is modified, perceptual fingerprints remain similar even if a video is re-encoded, scaled, compressed, or slightly trimmed. This makes the filter ideal for copyright detection, deduplication, and media monitoring.

Generating a Fingerprint File

To generate and export a fingerprint file from a video, pass the signature filter via the -vf option and direct the output to the null muxer since no video file needs to be encoded.

Exporting to an XML File

To generate a human-readable XML file containing the frame-by-frame signature data:

ffmpeg -i input.mp4 -vf "signature=format=xml:filename=output_signature.xml" -f null -

Exporting to a Binary File

Binary format is more compact, faster to parse, and recommended for large-scale storage:

ffmpeg -i input.mp4 -vf "signature=format=binary:filename=output_signature.bin" -f null -

Key Configuration Parameters

The signature filter supports several options to control output and matching behavior:

  • filename: The path where the generated signature file will be written.
  • format: Specifies the format of the output file. Accepted values are binary (default) or xml.
  • nb_inputs: The number of video inputs being processed simultaneously (default is 1).
  • detectmode: Sets the duplicate detection mode when comparing streams. Options include:
    • off: Default mode. Generates signatures without comparing streams.
    • full: Compares the inputs thoroughly to find matching segments.
    • fast: Compares inputs using an optimized, faster search method.
  • th: The matching threshold (default is 90). Lowering this makes detection stricter; raising it allows for more variation.

Comparing Two Videos Directly

You can compare two video files in real-time to determine if they match or share common scenes. To do this, provide both files as inputs, set nb_inputs=2, and enable a detection mode using -filter_complex:

ffmpeg -i original.mp4 -i modified.mp4 -filter_complex "[0:v][1:v]signature=nb_inputs=2:detectmode=full" -f null -

When a match is found during processing, FFmpeg will log detection messages directly to the terminal console, identifying the matching frame ranges and timestamps from both input streams:

[Parsed_signature_0 @ 0x...] matching of video 0 at ... and 1 at ...

Comparing Pre-Generated Signatures

If you have already exported .bin signature files for a media library, you can compare them offline without reprocessing the source video files by using FFmpeg's specialized signature matching tools or integrating the exported binary data into a custom matching algorithm using libavfilter's internal signature distance metrics.