overlay - FFmpeg 1.2.12 / Filters / Video

Overlay one video on top of another.

It takes two inputs and one output, the first input is the "main" video on which the second input is overlayed.

This filter accepts a list of key=value pairs as argument, separated by ":". If the key of the first options is omitted, the arguments are interpreted according to the syntax x:y.

A description of the accepted options follows.

x, y

Set the expression for the x and y coordinates of the overlayed video on the main video. Default value is 0.

The x and y expressions can contain the following parameters:

main_w, main_h: main input width and height
W, H: same as main_w and main_h
overlay_w, overlay_h: overlay input width and height
w, h: same as overlay_w and overlay_h

format

Set the format for the output video.

It accepts the following values:

yuv420: force YUV420 output
yuv444: force YUV444 output
rgb: force RGB output

Default value is yuv420.

rgb (deprecated)

If set to 1, force the filter to accept inputs in the RGB color space. Default value is 0. This option is deprecated, use format instead.

shortest

If set to 1, force the output to terminate when the shortest input terminates. Default value is 0.

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

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

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=10:H-h-10,overlay=W-w-10:H-h-10' output
```
Add a transparent color layer on top of the main video, WxH specifies the size of the main input to the overlay filter:
```
color=red@.3: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'

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]
"

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]