How to Use FFmpeg cropdetect Filter

The cropdetect filter in FFmpeg is an automated tool used to identify black borders (letterboxing or pillarboxing) in a video and calculate the optimal coordinates for cropping them out. This article explains how to use the cropdetect filter to find these coordinates and how to apply them using the companion crop filter to produce a clean, borderless video.

Step 1: Detect the Crop Parameters

The cropdetect filter does not actually crop the video; instead, it analyzes the video frames and prints the suggested crop dimensions to your terminal. To run the detection without wasting time creating a new video file, output the results to a null muxer.

Run the following command in your terminal:

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

As the command runs, look at the terminal output. You will see repeated lines that look like this:

[parsed_cropdetect_0 @ 0x7f9a0c008000] x1:0 x2:1919 y1:138 y2:941 w:1920 h:800 x:0 y:142 pts:123 t:4.120000 limit:24 crop=1920:800:0:142

The most important part of this output is at the very end: crop=1920:800:0:142. This represents the detected width, height, and the X/Y coordinates needed to crop the video.

Step 2: Apply the Crop to Your Video

Once you have identified the correct crop parameters from the output (usually by letting the detection run for a few seconds or through the entire video to find the most consistent values), you can apply them using the crop filter.

Using the values from the example above (crop=1920:800:0:142), run the following command to output the cropped video:

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

In this command: * -vf crop=1920:800:0:142 applies the crop filter with the width (1920), height (800), X-offset (0), and Y-offset (142). * -c:a copy copies the audio stream without re-encoding to save time and maintain quality.

Fine-Tuning cropdetect Parameters

If the default detection is not accurate, you can pass specific parameters to cropdetect using the syntax cropdetect=limit:round:reset.

• limit: Sets the black threshold (default is 24). Higher values detect lighter shades of grey as black, which is useful for noisy analog videos.
• round: Forces the output width and height to be divisible by this value (default is 16). This is useful because many video codecs require dimensions divisible by 2, 8, or 16.
• skip: The number of initial frames to skip before starting detection (default is 2).

For example, to detect borders on a noisy video with a higher threshold and force the output to be divisible by 8, use:

ffmpeg -i input.mp4 -vf cropdetect=limit=30:round=8 -f null -