Overlay One Video on Another in an FFmpeg Pipeline

Draw the second input (the overlay) on top of the first input (the main video) at position x and y. Like ffm_hstack, this is a pipeline function for several inputs. It forces the -filter_complex path and manages its own stream labels internally. It needs exactly two inputs. The first is the background, and the second is drawn over it. The glossary in vignette("tidymedia") explains media terms such as stream.

Usage

ffm_overlay(object, x = 0, y = 0, shortest = FALSE, scale = NULL)

Arguments

object

An FFmpeg pipeline (ffm) object created by ffm_files() with exactly two input files.

x

The horizontal position of the overlay's left edge, in pixels, as a double or a string, such as an FFmpeg expression. The default is 0.

y

The vertical position of the overlay's top edge, in pixels, as a double or a string, such as an FFmpeg expression. The default is 0.

shortest

A logical that says whether to end the output when the shorter input ends. The default is FALSE.

scale

An optional fraction (0 < scale <= 1). Before the overlay is drawn, it is resized to scale times the main video's width, and its aspect ratio is kept. NULL (the default) draws the overlay at its own size. When scale is set, overlay_w and overlay_h in x and y refer to the resized overlay.

Value

object with an added instruction to draw the second input on the first.

Details

x and y each take one double (an R number such as 16) of zero or more, or one string, such as an FFmpeg overlay expression. An integer such as 16L is refused, and so is NA. Any other string is not checked, and it goes into the FFmpeg command as written. A number counts pixels from the top-left of the main video. In an expression, main_w and main_h are the main video's dimensions. overlay_w and overlay_h are the overlay's dimensions. For example, x = "main_w-overlay_w-16" puts the overlay 16 pixels from the right edge.

When scale is set, the overlay is first resized to a fraction of the main video's width, and its aspect ratio is kept. The task function picture_in_picture uses this resize. Otherwise, to resize the overlay yourself, filter it in a separate pipeline first.

See also

picture_in_picture(), the task function built on this function.

Other pipeline functions: ffm_batch(), ffm_codec(), ffm_compile(), ffm_concat(), ffm_copy(), ffm_crop(), ffm_drawbox(), ffm_drop(), ffm_files(), ffm_fps(), ffm_hstack(), ffm_jobs(), ffm_loudnorm(), ffm_map(), ffm_output_options(), ffm_pixel_format(), ffm_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Draw the second input over the first, 16px in from the top-right corner
ffm_files(c(video, video), "output.mp4") |>
  ffm_overlay(x = "main_w-overlay_w-16", y = 16) |>
  ffm_compile()
#> [1] "-y -i \"/home/runner/work/_temp/Library/tidymedia/extdata/sample.mp4\" -i \"/home/runner/work/_temp/Library/tidymedia/extdata/sample.mp4\" -filter_complex \"[0:v][1:v]overlay=x=main_w-overlay_w-16:y=16:shortest=0[vout]\" -map \"[vout]\" \"output.mp4\""