blackdetect finds runs of black frames in a video and prints the start and end time of each run.

Basic Command

ffmpeg -i input.mp4 -vf blackdetect -f null /dev/null

No file is written. The black ranges are printed to stderr (the terminal).

Reading the Output

[Parsed_blackdetect_0 @ 0x...] black_start:0 black_end:2.04 black_duration:2.04
[Parsed_blackdetect_0 @ 0x...] black_start:123.5 black_end:126 black_duration:2.5
Field Description
black_start Start of the black segment (seconds)
black_end End of the black segment (seconds)
black_duration Length of the black segment (seconds)

Tuning Parameters

Defaults

Parameter Default Description
black_min_duration (d) 2.0 Only black runs at least this many seconds long are reported
picture_black_ratio_th (pic_th) 0.98 A frame counts as black when ≥98% of its pixels are black
pixel_black_th (pix_th) 0.10 A pixel counts as black if its brightness (luminance, on a 0–1 scale) is ≤ this value

Example: Detect Black Runs of 0.5 s or More

ffmpeg -i input.mp4 -vf "blackdetect=d=0.5:pic_th=0.95:pix_th=0.10" -f null /dev/null
  • Lower d: catches short black runs, such as those at commercial breaks
  • Lower pic_th: a frame can contain more non-black pixels and still count as black
  • Higher pix_th: slightly brighter pixels also count as black

Example: Detect Commercial Boundaries in a TV Recording

If a TV recording has black frames between the program and the commercials, blackdetect finds the breaks. These black runs can be short, so lower d: d=0.1 reports black runs of 0.1 s (3 frames at 30 fps) or longer.

ffmpeg -i recording.mp4 -vf "blackdetect=d=0.1:pix_th=0.10" -f null /dev/null 2>&1 | grep black_

Save the Output to a Text File

ffmpeg -i input.mp4 -vf blackdetect -f null /dev/null 2>&1 | grep black_ > black_segments.txt

Combining blackdetect and silencedetect

Black runs that coincide with silence (found with silencedetect) mark scene boundaries more reliably than black frames alone. A short shell or Python script can match the times from the two filters.

Frequently Asked Questions

What threshold should I use for blackdetect?

The defaults, d=2:pix_th=0.10 (runs of 2 s or more; pixels with luminance ≤ 0.10 count as black), catch black screens that last at least 2 seconds. For shorter ones, lower d. For stricter detection, lower pix_th to 0.05.

Why does blackdetect miss a black frame I can see?

The black part may be shorter than 2 seconds. With the default d=2, shorter black runs are not reported at all, so lower d, for example to d=0.1. For a single black frame, use d=0. The frame may also be dark grey rather than pure black. Pixels brighter than pix_th (0.10 by default) do not count as black, so raise pix_th to 0.15 and try again. If only part of the picture is not black (a logo or a caption), lower pic_th instead.

Can I split a video at every black frame automatically?

Yes. Feed the blackdetect output to a script that turns it into -ss ranges and runs FFmpeg on each segment with -c copy. Because -c copy does not re-encode, a segment can start at the keyframe before the cut point. For frame-accurate cuts, drop -c copy and re-encode.

Partly. select='gt(scene,0.4)' flags any large change in the picture. blackdetect looks only for black or nearly black runs, which often mark chapter boundaries.

Does it work on still images?

Yes, with d=0. A single image counts as a black run of 0 seconds, so with the default d=2 nothing is printed. For a black image, ffmpeg -i image.png -vf blackdetect=d=0 -f null /dev/null prints black_start:0 black_end:0 black_duration:0.