Originally published at ffmpeg-micro.com

You need to put one video on top of another, and FFmpeg's documentation reads like a math textbook. The overlay filter is one of the most used filters in FFmpeg, but getting the positioning, scaling, and timing right takes more trial and error than it should.

This guide covers the overlay filter from basic image-on-video compositing to timed picture-in-picture with multiple streams.

How the FFmpeg Overlay Filter Works

The overlay filter takes two video inputs and stacks one on top of the other. The first input is the background (main video), and the second is the foreground (the overlay). You control placement with x and y coordinates.

The basic syntax inside filter_complex:

ffmpeg -i main.mp4 -i logo.png -filter_complex "[0:v][1:v]overlay=10:10" output.mp4

This places logo.png at 10 pixels from the left and 10 pixels from the top of main.mp4. Two inputs, one filter, x and y coordinates.

You need -filter_complex instead of -vf whenever you're working with multiple inputs.

Position Variables for Dynamic Placement

Hardcoding pixel values breaks the moment your input resolution changes. FFmpeg gives you position variables that reference the dimensions of each stream at runtime:

• W and H refer to the main video's width and height
• w and h refer to the overlay's width and height

Bottom-right corner with 10px padding:

ffmpeg -i main.mp4 -i watermark.png -filter_complex "[0:v][1:v]overlay=W-w-10:H-h-10" output.mp4

Center the overlay:

ffmpeg -i main.mp4 -i overlay.png -filter_complex "[0:v][1:v]overlay=(W-w)/2:(H-h)/2" output.mp4

FFmpeg Picture-in-Picture with Scaling

Chain a scale filter before the overlay:

ffmpeg -i main.mp4 -i pip.mp4 -filter_complex \
  "[1:v]scale=320:180[pip];[0:v][pip]overlay=W-w-20:20" \
  output.mp4

Video-on-Video vs. Image-on-Video

When overlaying video on video, set eof_action to handle duration mismatches:

ffmpeg -i main.mp4 -i overlay.mp4 -filter_complex \
  "[0:v][1:v]overlay=10:10:eof_action=pass" output.mp4

Timed Overlays

Show overlays only during specific time windows:

ffmpeg -i main.mp4 -i lower_third.png -filter_complex \
  "[0:v][1:v]overlay=0:H-h:enable='between(t,5,15)'" output.mp4

Running Overlays via API

FFmpeg Micro runs your overlay commands as API calls. Same filter syntax, no infrastructure:

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {"url": "https://storage.example.com/main.mp4"},
      {"url": "https://storage.example.com/overlay.png"}
    ],
    "outputFormat": "mp4",
    "options": [
      {"option": "-filter_complex", "argument": "[0:v][1:v]overlay=W-w-10:H-h-10"}
    ]
  }'

Common Pitfalls

• Pixel format mismatches: Use format=auto on the overlay filter for PNG transparency
• Missing audio: Add -map 0:a -c:a copy to carry audio through
• Using -vf instead of -filter_complex: -vf only works with a single input

FAQ

How do I put a logo in the corner of a video? Use overlay=W-w-10:H-h-10 for bottom-right placement.

Can I overlay video on video? Yes, same syntax. Use eof_action=pass if the overlay is shorter.

How do I make picture-in-picture? Scale first, then overlay: [1:v]scale=320:180[pip];[0:v][pip]overlay=W-w-20:20