pad: Scale to Fit and Pad onto a Canvas

In compost: Video Compositing via 'FFmpeg'

Scale to Fit and Pad onto a Canvas

Description

Scales input to fit within fit_width x fit_height (preserving aspect ratio, never upscaling past the box), then pads the result onto a width x height canvas at x,y filled with color. This is the ffmpeg scale=...:force_original_aspect_ratio=decrease,pad=... idiom for letterboxing media into a fixed frame (e.g. a square clip into 1080x1920 vertical shorts with the video at the top and a black caption strip below).

Usage

pad(input, output, width, height, fit_width = width, fit_height = height,
    x = "(ow-iw)/2", y = "(oh-ih)/2", color = "black", overwrite = TRUE,
    dry_run = FALSE)

Arguments

color	Pad color (default "black").
overwrite	Overwrite the output if it exists (default TRUE).
dry_run	If TRUE, return the ffmpeg command string instead of running.
input, output	Input and output media paths.
width, height	Final canvas dimensions (pixels).
fit_width, fit_height	Box to scale the input into before padding (default the canvas dimensions).
x, y	Position of the scaled input on the canvas as ffmpeg pad expressions. Default centers it ("(ow-iw)/2", "(oh-ih)/2"); pass 0, 0 to top-left align (e.g. video at the top of a taller canvas).

Value

The output path, invisibly (or the command string on dry_run).

Examples

## Not run: 
# Letterbox a square clip into vertical shorts, video at the top:
pad("clip.mp4", "shorts.mp4", 1080, 1920,
    fit_width = 1080, fit_height = 1080, x = 0, y = 0)

## End(Not run)

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