pad

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

# 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)