FFmpeg 6.0.1
Since* 0.7
#

Overlay one video on top of another.

It takes two inputs and has one output. The first input is the "main" video on which the second input is overlaid.

It accepts the following parameters:

A description of the accepted options follows.

x, y

Set the expression for the x and y coordinates of the overlaid video on the main video. Default value is "0" for both expressions. In case the expression is invalid, it is set to a huge value (meaning that the overlay will not be displayed within the output visible area).

eof_action

See framesync.

eval

Set when the expressions for x, and y are evaluated.

It accepts the following values:

init

only evaluate expressions once during the filter initialization or when a command is processed

frame

evaluate expressions for each incoming frame

Default value is frame.

shortest

See framesync.

format

Set the format for the output video.

It accepts the following values:

yuv420

force YUV420 output

yuv420p10

force YUV420p10 output

yuv422

force YUV422 output

yuv422p10

force YUV422p10 output

yuv444

force YUV444 output

rgb

force packed RGB output

gbrp

force planar RGB output

auto

automatically pick format

Default value is yuv420.

repeatlast

See framesync.

alpha

Set format of alpha of the overlaid video, it can be straight or premultiplied. Default is straight.

The x, and y expressions can contain the following parameters.

main_w, W, main_h, H

The main input width and height.

overlay_w, w, overlay_h, h

The overlay input width and height.

x, y

The computed values for x and y. They are evaluated for each new frame.

hsub, vsub

horizontal and vertical chroma subsample values of the output format. For example for the pixel format "yuv422p" hsub is 2 and vsub is 1.

n

the number of input frame, starting from 0

pos

the position in the file of the input frame, NAN if unknown

t

The timestamp, expressed in seconds. It’s NAN if the input timestamp is unknown.

This filter also supports the framesync options.

Note that the n, pos, t variables are available only when evaluation is done per frame, and will evaluate to NAN when eval is set to init.

Be aware that frames are taken from each input video in timestamp order, hence, if their initial timestamps differ, it is a good idea to pass the two inputs through a setpts=PTS-STARTPTS filter to have them begin in the same zero timestamp, as the example for the movie filter does.

You can chain together more overlays but you should test the efficiency of such approach.

#

Commands

This filter supports the following commands:

x, y

Modify the x and y of the overlay input. The command accepts the same syntax of the corresponding option.

If the specified expression is not valid, it is kept at its current value.

#

Examples

  • Draw the overlay at 10 pixels from the bottom right corner of the main video:

    overlay=main_w-overlay_w-10:main_h-overlay_h-10

    Using named options the example above becomes:

    overlay=x=main_w-overlay_w-10:y=main_h-overlay_h-10
  • Insert a transparent PNG logo in the bottom left corner of the input, using the ffmpeg tool with the -filter_complex option:

    ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
  • Insert 2 different transparent PNG logos (second logo on bottom right corner) using the ffmpeg tool:

    ffmpeg -i input -i logo1 -i logo2 -filter_complex 'overlay=x=10:y=H-h-10,overlay=x=W-w-10:y=H-h-10' output
  • Add a transparent color layer on top of the main video; WxH must specify the size of the main input to the overlay filter:

    color=color=red@.3:size=WxH [over]; [in][over] overlay [out]
  • Play an original video and a filtered version (here with the deshake filter) side by side using the ffplay tool:

    ffplay input.avi -vf 'split[a][b]; [a]pad=iw*2:ih[src]; [b]deshake[filt]; [src][filt]overlay=w'

    The above command is the same as:

    ffplay input.avi -vf 'split[b], pad=iw*2[src], [b]deshake, [src]overlay=w'
  • Make a sliding overlay appearing from the left to the right top part of the screen starting since time 2:

    overlay=x='if(gte(t,2), -w+(t-2)*20, NAN)':y=0
  • Compose output by putting two input videos side to side:

    ffmpeg -i left.avi -i right.avi -filter_complex "
    nullsrc=size=200x100 [background];
    [0:v] setpts=PTS-STARTPTS, scale=100x100 [left];
    [1:v] setpts=PTS-STARTPTS, scale=100x100 [right];
    [background][left]       overlay=shortest=1       [background+left];
    [background+left][right] overlay=shortest=1:x=100 [left+right]
    "
  • Mask 10-20 seconds of a video by applying the delogo filter to a section

    ffmpeg -i test.avi -codec:v:0 wmv2 -ar 11025 -b:v 9000k
    -vf '[in]split[split_main][split_delogo];[split_delogo]trim=start=360:end=371,delogo=0:0:640:480[delogoed];[split_main][delogoed]overlay=eof_action=pass[out]'
    masked.avi
  • Chain several overlays in cascade:

    nullsrc=s=200x200 [bg];
    testsrc=s=100x100, split=4 [in0][in1][in2][in3];
    [in0] lutrgb=r=0, [bg]   overlay=0:0     [mid0];
    [in1] lutrgb=g=0, [mid0] overlay=100:0   [mid1];
    [in2] lutrgb=b=0, [mid1] overlay=0:100   [mid2];
    [in3] null,       [mid2] overlay=100:100 [out0]