Adjust Scene Change Threshold in FFmpeg scdet

The FFmpeg scdet (scene detection) filter allows you to detect cut points and scene transitions within a video stream by analyzing differences between consecutive frames. By adjusting the detection threshold parameter, you can control the sensitivity of the filter, allowing you to catch subtle transitions or restrict detection to only drastic scene changes. This guide explains the threshold parameter syntax, how its values affect detection, and how to implement it in practical FFmpeg commands.

The threshold Parameter

The scdet filter relies on a single primary option to govern sensitivity: threshold (or its short alias t).

  • Option Name: threshold or t
  • Value Range: 0.0 to 100.0
  • Default Value: 10.0

The threshold represents the percentage of change required between consecutive frames to trigger a scene change event.

  • Lower values (e.g., 5.0): Increase sensitivity. The filter flags more subtle movements or lighting variations as new scenes, which may lead to false positives.
  • Higher values (e.g., 25.0): Decrease sensitivity. The filter requires significant visual differences to register a cut, reducing false positives but potentially missing soft cuts.

Basic Syntax and Usage

To specify a custom threshold, pass the threshold option into the -vf (video filter) argument:

ffmpeg -i input.mp4 -vf "scdet=threshold=15.0" -f null -

Using the shorthand parameter alias produces the same result:

ffmpeg -i input.mp4 -vf "scdet=t=15.0" -f null -

Logging Scene Changes

By default, scdet prints detection details to standard error. You can run the filter and filter the log output to inspect timestamps where scene changes occurred:

ffmpeg -i input.mp4 -vf "scdet=threshold=12.0" -f null - 2>&1 | grep "lavfi.scd.score"

When a frame surpasses the threshold, FFmpeg generates metadata logs indicating the frame number, timestamp, and the calculated score (percentage change).

Practical Applications

1. Exporting Timestamps to a Text File

You can combine scdet with the metadata filter to log scene changes directly to a file:

ffmpeg -i input.mp4 -vf "scdet=threshold=10.0,metadata=print:file=scene_cuts.txt:key=lavfi.scd.score" -f null -

2. Creating Keyframes at Scene Cuts

To force keyframe creation at detected cut points using a custom threshold:

ffmpeg -i input.mp4 -vf "scdet=threshold=8.0" -c:v libx264 -force_key_frames "expr:gte(t,n_forced*1)" output.mp4

Adjust the threshold incrementally based on your specific video content; fast-paced action or high-grain footage typically requires a higher threshold to avoid false detections, while static scenes benefit from a lower threshold.