When FFmpeg marks dark material, first ask whether you need evidence of a sustained interval or of individual frames. Use blackdetect to report a black interval that meets a minimum duration, with its start, end, and duration. Use blackframe to inspect frame-level candidates, including frame number, timestamp, and percentage of pixels below its threshold. These are different detection units; their readings are not interchangeable.
Choose the reading and run the appropriate check
- Define the decision. If you need to locate a continuous near-black section, choose
blackdetect. If you need to find individual frames whose pixels are mostly below a threshold, chooseblackframe. A single-frame result does not establish an interval, and an interval report is not a per-frame percentage report. - Set the parameters that match the question. For
blackdetect,black_min_duration(ord) is the minimum duration in seconds for an interval to be reported in the log.picture_black_ratio_th(orpic_th) is the minimum ratio of black pixels for a picture to count as black.pixel_black_th(orpix_th) sets the maximum luma value for an individual pixel to count as black; its scale depends on the input format and range. Forblackframe,threshold(orthresh) sets the pixel-value cutoff, whileamountsets the percentage of pixels that must fall below that cutoff for a frame to qualify. Do not treat similarly named options as equivalent. - Read the result in its own format.
blackdetectlogs start, end, and duration for intervals meeting the duration minimum, and can show per-frame analysis at debug level. It also attacheslavfi.black_startto the first frame of a segment andlavfi.black_endto the first frame after it ends, regardless of the duration minimum.blackframeoutputs frame number, blackness percentage, file position if known, and timestamp; itslavfi.blackframe.pblackmetadata contains the percentage below threshold. See the blackdetect documentation and blackframe documentation for the precise definitions. - Choose a review window based on the evidence. For a reported interval, inspect its boundaries and nearby footage to determine whether it is a deliberate transition or unwanted blank content. For a lone frame candidate, inspect adjacent frames and the surrounding shot. Record the parameters and whether the dark material is intended; the filter output alone does not establish editorial intent.
The official defaults are not universal acceptance criteria. In particular, duration minimum, pixel cutoff, and required pixel proportion answer different questions. Choose values for the footage and review purpose, and record them so another person can interpret the result.
Hypothetical acceptance worksheet
The following readings and decisions are hypothetical, not software test results or guaranteed FFmpeg output. They illustrate how to keep interval and frame evidence separate.
| Hypothetical observation | Evidence type and settings to record | Review decision | Acceptance note |
|---|---|---|---|
blackdetect reports start 12.4 s, end 14.8 s, duration 2.4 s | Interval; record black_min_duration, picture_black_ratio_th, and pixel_black_th | Review the boundary frames and surrounding footage, for example 11.9–15.3 s | Record whether the sustained dark interval is intentional; do not infer intent from its duration |
blackframe reports 99% at 9.6 s | Frame candidate; record amount and threshold | Review adjacent frames and the shot around 9.6 s | Record whether this is an isolated dark frame or part of a broader event; do not call it a sustained interval without interval evidence |
For either row, note the actual filter settings, the chosen review range, and the editing intent. The proposed time windows are review suggestions, not boundaries computed by FFmpeg or official pass/fail rules.
Limits and next steps when results disagree
A short dark event may fail to appear as a blackdetect log interval when it is shorter than the chosen minimum; that does not prove that no dark frames occurred. Conversely, a blackframe candidate says that the frame met its configured pixel criteria, not that the surrounding footage is a continuous black segment. If the two readings appear inconsistent, compare their settings and inspect the relevant frames rather than forcing one output to validate the other.
For blackdetect, pixel classification depends on luma and the input video format’s range. The documented calculation scales pixel_black_th according to the range; a threshold value should not be read as a fixed luma code across formats. blackframe documents a pixel-value threshold and a required percentage, but its cited filter description does not define those parameters as the same ratio-and-range calculation used by blackdetect. Do not assume the filters share a common threshold scale.
If logs do not show blackframe lines, check that the log level is at least info. If an interval needs frame-by-frame investigation, use the documented debug per-frame analysis or inspect the frames in a suitable viewer. If a detection does not match the editorial question, revise the relevant settings and repeat the review; these filters identify pixel-based candidates, not whether a fade, dark scene, or intentional cut is correct.
Three quick questions
Does a `blackframe` result mean the whole shot is black? No. It reports a qualifying frame and the percentage of pixels below its threshold. Inspect neighboring frames to assess continuity.
Why can `blackdetect` have boundary metadata without a logged interval? The documented start and end metadata are attached regardless of the minimum duration, while the interval log requires that the segment meet that minimum.
Which filter should I use for one suspicious timestamp? Use `blackframe` when you need a frame number, timestamp, and black-pixel percentage. Use `blackdetect` when the question is whether a qualifying black interval spans time.
Sources and next step
- 11.12 blackdetect, blackdetect_vulkan — FFmpeg official documentation
- 11.13 blackframe — FFmpeg official documentation
This guide interprets public documentation and uses explicitly hypothetical acceptance examples, not application tests. Controls and availability can change; verify the cited manual against your installed version.
For work created in Imagild, carry the input requirements and acceptance checklist into the film workspace. The external software controls discussed above belong to their respective products.