FFmpeg’s cropdetect output is a candidate crop, not a verdict that the detected area is disposable. Accept it only when the proposed boundaries stay consistent across the relevant footage and visual review confirms they exclude fixed bars without cutting into the scene. If the boundary shifts, a subject or other meaningful detail reaches it, or you cannot tell whether dark pixels belong to the picture, keep the original frame and review manually.
Read the candidate as geometry
The FFmpeg filters documentation describes cropdetect as detecting the bounds of a video area that is more than a specified number of black pixels, and gives an example that prints crop suggestions. This explains why dark picture content can confuse the result: detection is based on image characteristics, not on editorial intent or an understanding of what matters in a scene.
A suggested width and height describe the proposed crop size; the associated offsets locate the crop within the frame. A plausible aspect ratio is not evidence that the crop is safe. Compare the proposed rectangle with the actual picture, including all four edges. Consult FFmpeg’s `cropdetect` documentation and examples for its options and output behavior, and the `crop` filter documentation when reviewing how a crop is specified.
Review in this order
- Run
cropdetecton representative footage and record the reported width, height, and offsets alongside the time. Do not apply the first line of output as a final decision. - Sample the opening, middle, and ending of each shot or other interval with a meaningful change in lighting or composition. Add samples around transitions: a single sample can miss a boundary that moves or content that briefly reaches the edge.
- At each sample, compare the candidate rectangle with the image. Check top, bottom, left, and right separately. Note whether a dark region is a continuous band outside the composed image, or whether scene detail, a shadow, hair, clothing, a prop, or on-screen text enters the proposed crop.
- Compare candidates within each interval. Matching dimensions and offsets across those samples support a fixed-boundary interpretation, but do not prove it. A dark scene can persist; inspect what the edge represents, not just whether the numbers repeat.
- Decide per interval: accept a fixed crop, reject it and retain the original frame, or split the work into intervals for manual review if the boundary changes. Do not use one crop for the whole clip merely because it fits one shot.
- Apply an accepted crop to a separate output and inspect both the resulting dimensions and the decoded picture. Confirm that the intended bars are gone and no meaningful edge content was removed. A correct output size alone does not establish correct framing.
Example: stable bars or a changing image?
The following figures and observations are hypothetical, not test results. Suppose a 1920×1080 source produces a candidate of 1920×800 at offsets 0,140 in three samples from a dialogue shot. Playback shows dark bands above and below the composed image, and faces, subtitles, and other meaningful details remain inside the candidate rectangle. That is evidence to consider the same crop for that shot, followed by output review.
Now suppose the next shot proposes 1920×760 at 0,160, and a performer’s head approaches the top edge. Even if the edge is mostly dark in a still frame, the candidate differs and may intrude on the action. Reject a single clip-wide automatic crop. Keep the original frame while reviewing this shot; if the footage supports it, assess a separate crop for the first interval and a different decision for the second.
| Hypothetical review point | Candidate | Edge observation | Decision |
|---|---|---|---|
| Dialogue shot, start/middle/end | 1920×800 at 0,140 each time | Continuous top and bottom bands; details stay inside | Consider per-shot crop; inspect output |
| Following shot, middle | 1920×760 at 0,160 | Head approaches top boundary; geometry differs | Reject shared automatic crop; review separately |
| Transition frame | Candidate not visually clear | Boundary and scene content are ambiguous | Retain original frame pending manual review |
When the evidence is weak
Changing candidates may reflect a real change in framing, not just detection noise. A dark wall, an unlit background, a shadow, or a fade can resemble a black border. Conversely, a genuine bar may not be perfectly black. The documented detector’s thresholds and options govern detection; they do not establish whether removing a region matches the creator’s intent.
If the candidate enters a face, a prop, text, or other intended picture content, reject it. If boundaries vary across a shot, review more frames and consider interval-specific decisions rather than averaging the dimensions. If you still cannot distinguish a bar from scene content, retaining the original frame is the safer editorial decision. cropdetect does not certify the meaning of pixels or guarantee that one crop is correct for an entire clip.
Common questions
If the same candidate repeats, can I apply it automatically? Repetition supports stability, but does not prove that the region is expendable. Inspect what touches the proposed boundaries before accepting it.
Should I raise the detection threshold until dark content is ignored? Do not treat threshold changes as semantic understanding. Check the filter’s documented options, then visually re-evaluate the candidate; a changed result still needs review.
What if bars occur only in some shots? Make a per-interval decision. A crop suitable for one shot may remove valid content in another; retain the original where the crop is uncertain.
Sources and next step
- FFmpeg Filters Documentation
- 11.48 cropdetect — FFmpeg official documentation
- 11.47 crop — 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.