How to Use the FFmpeg Overlay Filter

The FFmpeg overlay filter is a powerful tool used to place one video or image on top of another. This article provides a straightforward guide on how to use this filter, covering basic syntax, coordinate positioning, watermarking, and practical command-line examples to help you master video layering in FFmpeg.

The Basic Syntax

To use the overlay filter, you must use FFmpeg's -filter_complex flag because the operation requires two distinct video inputs. The basic syntax is:

ffmpeg -i background.mp4 -i overlay.png -filter_complex "[0:v][1:v]overlay=X:Y[out]" -map "[out]" output.mp4

In this command:

  • [0:v] refers to the video stream of the first input (background.mp4).
  • [1:v] refers to the video stream of the second input (overlay.png).
  • overlay=X:Y defines the horizontal (X) and vertical (Y) coordinates where the top-left corner of the overlay image will be placed on the background.
  • [out] is the label assigned to the resulting output stream, which is then mapped to the output file using -map "[out]".

Positioning with Variables

FFmpeg provides built-in constants that make positioning overlays simple without needing to know the exact pixel dimensions of your files beforehand:

  • main_w (or W): Width of the main (background) input.
  • main_h (or H): Height of the main (background) input.
  • overlay_w (or w): Width of the overlay input.
  • overlay_h (or h): Height of the overlay input.

Using these variables, you can place your overlay in common positions:

  • Top-Left (Default): overlay=0:0

  • Top-Right: overlay=W-w:0

  • Bottom-Left: overlay=0:H-h

  • Bottom-Right (Common for Watermarks): overlay=W-w:H-h

  • Centered: overlay=(W-w)/2:(H-h)/2

Practical Examples

Adding a Watermark in the Bottom-Right with Padding

To place a logo in the bottom-right corner with a 10-pixel margin from the edges, use the following command:

ffmpeg -i input.mp4 -i logo.png -filter_complex "[0:v][1:v]overlay=W-w-10:H-h-10[out]" -map "[out]" -map 0:a? output.mp4

(Note: -map 0:a? ensures that any audio from the original video is copied to the output file).

Picture-in-Picture (PiP) Effect

If you want to overlay a smaller video onto a larger video in the top-right corner, you may need to scale the overlay video first:

ffmpeg -i main_video.mp4 -i pip_video.mp4 -filter_complex "[1:v]scale=320:-1[pip]; [0:v][pip]overlay=W-w-20:20[out]" -map "[out]" -map 0:a? output.mp4

In this command, the second video is scaled to a width of 320 pixels (preserving aspect ratio) before being overlaid 20 pixels from the top and right edges.

Showing an Overlay at a Specific Time

You can control when the overlay appears and disappears using the enable evaluation parameter:

ffmpeg -i input.mp4 -i logo.png -filter_complex "[0:v][1:v]overlay=10:10:enable='between(t,5,10)'[out]" -map "[out]" -map 0:a? output.mp4

This configuration displays the overlay at coordinates (10,10) only between the 5th and 10th seconds of the video.