Configure FFmpeg Signature Filter Threshold and Format

This guide explains how to configure the match threshold and output format options in the FFmpeg signature video filter. By adjusting these settings, you can reliably export MPEG-7 video signatures to human-readable XML or compact binary files and fine-tune the filter's sensitivity to detect duplicate, trimmed, or altered video streams.

Key Configuration Parameters

The signature filter accepts several parameters to control detection behavior and export formats:

  • format: Defines the format of the output signature or evaluation file. It accepts two values:
    • binary: Exports the signature in a compact binary format (default).
    • xml: Exports detailed signature information and matching results as human-readable XML.
  • th: Sets the detection match threshold (default is 90). Lower values make matching stricter (fewer false positives, but may miss slightly altered frames), while higher values make matching more lenient (tolerates compression artifacts, scaling, or noise).
  • mode: Controls how signatures are evaluated. Options include off (just generates signature), full (full search comparison across inputs), and fast (quicker matching with lower resource usage).
  • filename: Specifies the path where the generated signature or matching log will be saved.

Exporting Signatures in XML or Binary Format

To generate and export a signature file for a single video, set the format option and provide an output path with filename:

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

To output in binary format instead, change the format parameter:

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

Configuring Match Threshold for Video Comparison

When comparing two video streams directly within FFmpeg, use filter_complex with nb_inputs=2. You can adjust the th parameter alongside the format parameter to evaluate similarity with custom sensitivity.

ffmpeg -i reference.mp4 -i candidate.mp4 -filter_complex "[0:v][1:v]signature=nb_inputs=2:mode=full:th=85:format=xml:filename=comparison_results.xml" -f null -

In this command:

  • nb_inputs=2 instructs the filter to compare the two incoming video streams.
  • mode=full searches the entire candidate stream against the reference to identify matching segments.
  • th=85 lowers the default match threshold to enforce a stricter matching criteria.
  • format=xml outputs frame-by-frame and sequence-level matching scores directly into the XML file specified by filename.