overlay: Overlay Foreground onto Background

In compost: Video Compositing via 'FFmpeg'

Overlay Foreground onto Background

Description

Composite a PNG (with alpha) or video over a background video or image using FFmpeg's overlay filter.

Usage

overlay(background, foreground, output, x = 0, y = 0, scale = NULL,
        shortest = TRUE, overwrite = TRUE, dry_run = FALSE)

Arguments

background	Path to background video or image.
foreground	Path to foreground video or PNG (alpha supported).
output	Path for output video file.
x	Horizontal offset for overlay placement (default 0).
y	Vertical offset for overlay placement (default 0).
scale	Optional scale string for the foreground (e.g. "320:240" or "iw/2:ih/2").
shortest	If TRUE (default), end output when the shortest input ends.
overwrite	If TRUE (default), overwrite output file.
dry_run	If TRUE, return the FFmpeg command without executing.

Value

Invisibly returns the output path. If dry_run, returns command string.

Examples

## Not run: 
overlay("bg.mp4", "character.png", "out.mp4", x = 312, y = 580)
overlay("bg.mp4", "logo.png", "out.mp4", x = 10, y = 10, scale = "100:100")

## End(Not run)

compost documentation built on Aug. 4, 2026, 5:11 p.m.