What You’ll Learn
- How to detect runs of black frames with the
blackdetectfilter - How to configure
black_min_duration(minimum black-frame duration) - What
pic_th(pixel-black ratio threshold) means - How to tune
pix_th(per-pixel luminance threshold) - How to use it to find commercial breaks or chapter boundaries
Tested with: FFmpeg 6.1 (ubuntu-latest / CI verified)
Platform: Windows / macOS / Linux
Basic Command
ffmpeg -i input.mp4 -vf blackdetect -f null /dev/nullBlack-frame ranges are printed to stderr.
Reading the Output
[blackdetect @ 0x...] black_start:0 black_end:2.04 black_duration:2.04
[blackdetect @ 0x...] black_start:123.5 black_end:126.0 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 | 2.0 | Only report black runs at least this many seconds long |
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 luminance (normalized 0–1) is ≤ this |
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 frames (commercial breaks, etc.) - Lower
pic_th: Tolerates some non-black pixels in the frame - Higher
pix_th: Classifies slightly brighter pixels as “black”
Example: Detect Commercial Boundaries in a TV Recording
A common technique for TV broadcasts: about 2 seconds of black typically separates the program from a commercial.
ffmpeg -i recording.mp4 -vf "blackdetect=d=2.0: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.txtCombining blackdetect and silencedetect
Cross-referencing black-frame segments with silent audio segments yields more reliable scene-boundary detection. A small shell script or Python program can automate matching the two filter outputs.
Frequently Asked Questions
What threshold should I use for blackdetect?
d=2:pix_th=0.10 (≥2 s segments where ≤10% of pixels exceed black) catches most editorial black frames. Lower pix_th to 0.05 for stricter detection.
Why does blackdetect miss a black frame I can see?
Likely the frame is dark grey, not pure black. Pictures can read as ~5–8% lit due to compression noise — relax pix_th to 0.15 to include those.
Can I split a video at every black frame automatically?
Yes — pipe the blackdetect output into a script that emits -ss ranges and re-runs FFmpeg on each segment with -c copy.
Is blackdetect related to scene detection?
They overlap but differ — select='gt(scene,0.4)' flags any large pixel change, while blackdetect specifically targets black/near-black sequences typical at chapter boundaries.
Does it work on still images?
No — it only emits matches once a black sequence reaches the configured duration d. For a single still, sample one pixel and check brightness directly.
Related Articles
- Detect Silence — Find Quiet Segments with silencedetect
- Scene Change Detection — Find Cuts Automatically with select/scdet
Tested with ffmpeg 6.1 / Ubuntu 24.04 (GitHub Actions runner) Primary sources: ffmpeg.org/ffmpeg-filters.html#blackdetect / ffmpeg.org/ffmpeg-filters.html