How to Use the drawbox Filter in FFmpeg

This guide explains how to use the FFmpeg drawbox filter to overlay colored rectangles and bounding boxes onto your videos. You will learn the fundamental syntax of the filter, understand its key parameters—such as coordinates, dimensions, color, and thickness—and see practical command-line examples that you can immediately apply to your video editing and processing tasks.

Understanding the drawbox Syntax

The drawbox video filter draws a colored box on an input image or video frame. The basic syntax for the filter is:

-vf "drawbox=x=val:y=val:w=val:h=val:color=val:t=val"

Here is a breakdown of the key parameters:

  • x: The x-coordinate of the top-left corner of the box. Default is 0.
  • y: The y-coordinate of the top-left corner of the box. Default is 0.
  • w (or width): The width of the box. Default is 0.
  • h (or height): The height of the box. Default is 0.
  • color (or c): The color of the box. You can use standard color names (like red, blue, black) or hexadecimal values (like 0xFF0000). You can also append an opacity value (e.g., black@0.5 for 50% transparency). Default is black.
  • t (or thickness): The thickness of the box's border. If set to fill, max, or left unset with specific configurations, it fills the entire box. Default is 3.

You can use mathematical expressions and variables inside these parameters, such as iw (input width), ih (input height), sar (sample aspect ratio), and dar (display aspect ratio).

Practical Examples

1. Draw a Simple Border Around a Specific Area

To draw a red outline box that is 300 pixels wide and 200 pixels high, positioned at coordinates (100, 150) with a border thickness of 5 pixels, use the following command:

ffmpeg -i input.mp4 -vf "drawbox=x=100:y=150:w=300:h=200:color=red:t=5" -c:a copy output.mp4

2. Draw a Filled Semi-Transparent Box

To draw a solid, semi-transparent black box (useful as a background for text or subtitles) that covers the bottom third of the video, use the fill value for thickness and input variables for dimensions:

ffmpeg -i input.mp4 -vf "drawbox=x=0:y=ih-ih/3:w=iw:h=ih/3:color=black@0.6:t=fill" -c:a copy output.mp4

In this example, ih-ih/3 sets the starting y-coordinate to two-thirds of the way down the video, iw sets the width to the full width of the video, and black@0.6 creates a black box with 60% opacity.

3. Draw a Centered Box

To place a 400x400 pixel blue box exactly in the center of your video frame, use mathematical formulas utilizing the input width (iw) and input height (ih):

ffmpeg -i input.mp4 -vf "drawbox=x=(iw-400)/2:y=(ih-400)/2:w=400:h=400:color=blue:t=4" -c:a copy output.mp4

4. Inverting the Box Colors

FFmpeg allows you to invert the colors of the video inside the box area instead of applying a solid color. Set the color parameter to invert:

ffmpeg -i input.mp4 -vf "drawbox=x=100:y=100:w=200:h=200:color=invert:t=fill" -c:a copy output.mp4