FFmpeg Cropdetect: How to Detect Video Black Borders

Detecting and removing black borders (letterboxing or pillarboxing) from a video is a common task in video processing. This article explains how to use FFmpeg's cropdetect filter to automatically identify black borders, interpret the console output, and apply the resulting parameters to crop your video.

Understanding the Cropdetect Filter

The cropdetect filter in FFmpeg analyzes video frames to find the dimensions of the non-black active video area. It outputs the suggested crop parameters to the console, which you can then use with the crop filter to remove the borders.

To run cropdetect without generating a new video file, use the following command:

ffmpeg -i input.mp4 -vf "cropdetect=limit=24:round=16:reset=0" -f null -

Parameter Breakdown:

  • limit: Specifies the intensity threshold for what is considered "black." A value of 24 is generally recommended for digital video to account for compression noise. Lower values require a darker black, while higher values tolerate more gray.
  • round: Ensures the output width and height are divisible by the specified value (default is 16). Keeping this at 16 or 8 ensures compatibility with most video encoders (like H.264).
  • reset: Determines how many frames to wait before resetting the detection. Setting this to 0 (or a high number) ensures the filter keeps the smallest bounding box found across the entire video.

Reading the Output

When you run the command, FFmpeg will print configuration lines to your terminal for analyzed frames. Look for lines that look like this:

[parsed_filter_0_cropdetect @ 0x55bfd2d1cb00] x1:0 x2:1919 y1:138 y2:941 w:1920 h:804 x:0 y:138 ...
  • w:1920: The detected width of the active video area.
  • h:804: The detected height of the active video area.
  • x:0: The horizontal starting offset (X coordinate).
  • y:138: The vertical starting offset (Y coordinate).

The final printed values before the command finishes represent the optimal cropping dimensions for the entire video.

Cropping the Video

Once you have identified the w, h, x, and y values, you can apply them to the crop filter to produce your final, borderless video.

Using the values from the output example above (1920:804:0:138), run the following command to encode the cropped video:

ffmpeg -i input.mp4 -vf "crop=1920:804:0:138" -c:v libx264 -crf 23 -c:a copy output.mp4

This command crops the video to the precise dimensions of the active picture area while preserving the audio track without re-encoding.