Use FFmpeg cropdetect to Detect Black Borders

This article explains how to use the FFmpeg cropdetect filter to automatically identify black borders (letterboxing or pillarboxing) in your video files. You will learn the basic command syntax, how to adjust detection parameters, and how to apply the resulting crop values to clean up your videos.

Step 1: Run the cropdetect Command

To find the black borders in a video, you need to run the cropdetect filter and output the results to the console. Since you only need to read the metadata and do not want to output a new video file yet, use the null muxer.

Run the following command in your terminal:

ffmpeg -i input.mp4 -vf cropdetect -f null -

As the command runs, FFmpeg will analyze the video frames and print lines to the console that look like this:

[Parsed_cropdetect_0 @ 0x55bee30] limit:24 round:16 x1:0 x2:1919 y1:138 y2:941 w:1920 h:800 x:0 y:140 pts:12543 t:0.522625

Step 2: Understand the Output

The console output provides the exact parameters you need to crop the video:

  • w (width): The width of the active video area without black borders (e.g., 1920).
  • h (height): The height of the active video area without black borders (e.g., 800).
  • x: The horizontal coordinate where the crop area starts (e.g., 0).
  • y: The vertical coordinate where the crop area starts (e.g., 140).

The final crop recommendation is represented in the format: crop=w:h:x:y (for example, crop=1920:800:0:140).

Step 3: Adjust cropdetect Parameters (Optional)

If the default detection is not accurate, you can fine-tune the filter using three main parameters: limit, round, and reset.

ffmpeg -i input.mp4 -vf cropdetect=limit=24:round=16:reset=0 -f null -
  • limit: Sets the black threshold. Higher values (e.g., 30 or 40) detect dark gray borders as black, while lower values require the border to be pure black. The default is 24.
  • round: Forces the width and height dimensions to be divisible by this value. The default is 16, which is ideal for video compatibility.
  • reset: Determines how many frames must pass before the crop area is recalculated. The default is 0, which keeps the largest detected crop area throughout the video.

Step 4: Apply the Crop to Your Video

Once you have identified the correct crop dimensions from the console output, run a second command to actually crop and encode the video:

ffmpeg -i input.mp4 -vf "crop=1920:800:0:140" -c:a copy output.mp4

Replace 1920:800:0:140 with the specific values generated from your cropdetect run. This command will crop the black borders and save the clean video as output.mp4 while copying the audio without re-encoding it.