Draw Rectangles, Lines, and Grids with the FFmpeg drawbox Filter

Q: Does drawing several boxes slow things down a lot?

A. For a handful of boxes the `drawbox` cost is tiny; most of the runtime is the re-encode. Comma-chained boxes are simply processed one after another.

Q: How do I label a bounding box?

A. Chain `drawbox` and `drawtext` with a comma. As in the "labeled bounding box" example above, placing `drawtext` just above the box reads well.

Q: My grid lines are too heavy.

A. `thickness=1` is the minimum for `drawgrid`. Make the color semi-transparent, e.g. `color=white@0.3`, to soften the lines without changing the width.

Q: Can a fill completely hide a region?

A. Yes — `color=black:t=fill` (no opacity) hides the underlying video. If you want to obscure the content rather than cover it, `boxblur` looks more natural than a solid fill.

What You Will Learn

The command for drawing a rectangle with the drawbox filter
How to specify coordinates, size, color, line width, and fill
How to overlay a grid with the drawgrid filter
Applying it to visualize video-analysis and object-detection results

Tested with: FFmpeg 6.1 (verified against real FFmpeg)
Target OS: Windows / macOS / Linux

Tested with: FFmpeg 6.1 (verified against real FFmpeg)

Basic Commands

Draw a Red Rectangle (Outline Only)

ffmpeg -i input.mp4 \
  -vf "drawbox=x=50:y=50:w=200:h=100:color=red:t=3" \
  output.mp4

t=3 is the line width in pixels.

Filled Rectangle

ffmpeg -i input.mp4 \
  -vf "drawbox=x=50:y=50:w=200:h=100:[email protected]:t=fill" \
  output.mp4

t=fill fills the rectangle (you can specify an opacity on color). If you want to obscure rather than cover the region, consider applying a box blur to it instead of a solid fill.

Parameter Details

Parameter	Description	Example
`x`	Top-left X coordinate	`x=50`
`y`	Top-left Y coordinate	`y=50`
`w`	Width (use `iw` for the input width)	`w=200`
`h`	Height (use `ih` for the input height)	`h=100`
`color`	Color (name or HEX, `@opacity` allowed)	`[email protected]`
`t`	Line width in pixels, or `fill`	`t=3` / `t=fill`

How to Specify Colors

# Specify by color name
ffmpeg -i input.mp4 -vf "drawbox=x=10:y=10:w=100:h=50:color=green:t=2" output.mp4

# Specify by HEX
ffmpeg -i input.mp4 -vf "drawbox=x=10:y=10:w=100:h=50:color=0xFF0000:t=2" output.mp4

# Specify as semi-transparent
ffmpeg -i input.mp4 -vf "drawbox=x=10:y=10:w=100:h=50:[email protected]:t=fill" output.mp4

Draw a Border Around the Entire Frame

ffmpeg -i input.mp4 \
  -vf "drawbox=x=0:y=0:w=iw:h=ih:color=yellow:t=5" \
  output.mp4

Using iw (input width) and ih (input height), you can draw a border that matches the video dimensions. If you need to isolate the subject and replace the background rather than box it, green-screen compositing with chromakey is the better approach.

Draw Crosshairs in the Center

ffmpeg -i input.mp4 \
  -vf "drawbox=x=iw/2-1:y=0:w=2:h=ih:color=white:t=fill, \
       drawbox=x=0:y=ih/2-1:w=iw:h=2:color=white:t=fill" \
  output.mp4

Combine a horizontal line and a vertical line to create crosshairs.

Draw Multiple Rectangles

ffmpeg -i input.mp4 \
  -vf "drawbox=x=20:y=20:w=150:h=80:color=red:t=3, \
       drawbox=x=200:y=100:w=120:h=60:color=blue:t=3" \
  output.mp4

You can chain multiple drawbox filters with commas.

Overlay a Grid with the drawgrid Filter

drawgrid draws an evenly spaced grid.

ffmpeg -i input.mp4 \
  -vf "drawgrid=width=100:height=100:thickness=1:[email protected]" \
  output.mp4

Parameter	Description
`width`	Grid cell width
`height`	Grid cell height
`thickness`	Grid line thickness
`color`	Grid line color

Draw Rule-of-Thirds Composition Guidelines

ffmpeg -i input.mp4 \
  -vf "drawgrid=width=iw/3:height=ih/3:thickness=1:[email protected]" \
  output.mp4

Useful as a guideline for checking shot composition or for post-production.

Combine with drawtext for a Labeled Bounding Box

ffmpeg -i input.mp4 \
  -vf "drawbox=x=100:y=80:w=200:h=120:color=lime:t=2, \
       drawtext=text='Object':x=102:y=60:fontsize=20:fontcolor=lime" \
  output.mp4

Display Only Within a Specific Time Range

You can set time conditions using FFmpeg expressions.

ffmpeg -i input.mp4 \
  -vf "drawbox=x=50:y=50:w=200:h=100:color=red:t=3:enable='between(t,2,5)'" \
  output.mp4

enable='between(t,2,5)' displays the box only between 2 and 5 seconds.

Notes

x, y, w, and h accept FFmpeg expressions such as iw and ih (the input size).
Adding an opacity (@value) to color makes it semi-transparent, but you use it together with t=fill.
You can chain multiple drawbox filters in a -vf filter chain (comma-separated).

Measured Example

Drawing a few boxes and one guide line over a 1080p/30fps, 2-minute H.264 video is usually light work for the drawbox filter itself.

ffmpeg -i input.mp4 \
  -vf "drawbox=x=50:y=50:w=300:h=180:color=red:t=4,drawbox=x=0:y=ih/2:w=iw:h=2:[email protected]:t=fill" \
  -c:v libx264 -crf 23 -preset medium -c:a copy \
  output.mp4

The video still has to be re-encoded because pixels are changed. On a typical 8-core desktop, processing is usually close to a normal H.264 re-encode, perhaps slightly slower. Large filled boxes can simplify the image and reduce size at the same CRF. Results vary by environment.

If the goal is only to check coordinates, export a 10-second sample with -t 10 first before processing the whole file.

Common Pitfalls

Symptom: you asked for a semi-transparent fill but get an opaque solid color. Cause: [email protected] is set but t=fill was forgotten, or it is still an outline (t=number). Fix: a fill requires t=fill. Specify both, e.g. [email protected]:t=fill.
Symptom: the box runs off the frame or lands in the wrong place. Cause: hard-coded x/y values reused on a clip with a different resolution. Fix: use relative values with iw and ih. A full-frame border is x=0:y=0:w=iw:h=ih, and a center crosshair is x=iw/2-1, which keeps it resolution-independent.
Symptom: the line looks too thick or too thin. Cause: t is not scaled to the frame size. Fix: at 1080p, t=3 to t=5 is a good range. To look the same at 4K, roughly double it (around t=8).
Symptom: enable='between(t,2,5)' is ignored and the box shows the whole time. Cause: the quotes were stripped by the shell. Fix: keep the whole filter in "..." and the expression in '...', preserving the nested-quote structure.

FAQ

Q. Can I avoid re-encoding with drawbox? A. No. Because pixels are changed, the video is re-encoded. You can keep the audio with -c:a copy. If you only need to check coordinates, export a short -t 10 sample to nail the position first.

Q. Does drawing several boxes slow things down a lot? A. For a handful of boxes the drawbox cost is tiny; most of the runtime is the re-encode. Comma-chained boxes are simply processed one after another.

Q. How do I label a bounding box? A. Chain drawbox and drawtext with a comma. As in the “labeled bounding box” example above, placing drawtext just above the box reads well.

Q. My grid lines are too heavy. A. thickness=1 is the minimum for drawgrid. Make the color semi-transparent, e.g. [email protected], to soften the lines without changing the width.

Q. Can a fill completely hide a region? A. Yes — color=black:t=fill (no opacity) hides the underlying video. If you want to obscure the content rather than cover it, boxblur looks more natural than a solid fill.

drawtext — Drawing text
drawgrid — Drawing a grid
overlay — Overlaying another video