ffm_overlay: Overlay One Video on Another in an FFmpeg Pipeline

In tidymedia: Media File Preprocessing and Metadata for the 'tidyverse'

Overlay One Video on Another in an FFmpeg Pipeline

Description

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, as a number of pixels or an FFmpeg expression. The default is 0.
y	The vertical position of the overlay's top edge, as a number of pixels or 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.

Details

x and y accept plain numbers or FFmpeg overlay expressions. A plain 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.

Value

object with an added instruction to draw the second input on the 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()

tidymedia documentation built on Oct. 11, 2026, 5:08 p.m.