picture_in_picture_batch: Inset One Video Over Another For Many Outputs From a Jobs...

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

Inset One Video Over Another For Many Outputs From a Jobs Table

Description

Composite an inset (overlay) video onto a main video for many outputs from a single jobs tibble. This is the batch (table-driven) form of picture_in_picture(), for when you have more than one to produce. Its two inputs have distinct roles, so jobs carries fixed main and overlay columns (not a list-column) plus an output column. This is a thin wrapper over ffm_batch: one reproducible overlay command per row, sharing the pipeline with picture_in_picture(). The glossary in vignette("tidymedia") explains media terms such as codec, encoder and stream copy.

Usage

picture_in_picture_batch(
  jobs,
  position = c("topright", "topleft", "bottomright", "bottomleft", "center"),
  scale = 0.25,
  margin = 16,
  audio_input = NULL,
  video_codec = NULL,
  audio_codec = "copy",
  hardware = c("none", "nvenc", "videotoolbox"),
  fallback = FALSE,
  quality = NULL,
  run = TRUE,
  parallel = FALSE,
  ...
)

Arguments

jobs	A data frame with one row per output and (at least) main (background path), overlay (inset path), and output (destination path) columns. Optional position, scale, margin, audio_input, video_codec, and audio_codec columns override the like-named arguments per row (a row omitting one falls back to the argument). In an audio_input column, NA means "drop audio", the column's way of writing the scalar's NULL. In a video_codec or audio_codec column, it means "leave the codec unset". A numeric quality column overrides the quality argument per row (see quality). Two rows given the same output path are refused before any row runs; other columns are ignored.
position, scale, margin	Defaults applied to every row lacking the corresponding column. position is one of "topright" (the default), "topleft", "bottomright", "bottomleft" or "center"; a position column is held to those same five values, per row. See picture_in_picture() for their fuller meaning.
audio_input	The input file whose audio to keep, as a number that counts from 0. 0 is the first file you pass and 1 is the second. This counts the function's inputs, not the audio tracks of one input. So it is a different index from audio_stream on the functions that take one input. NULL (default) selects no audio at all, so the output is silent. This differs from audio_stream = NULL, which still selects audio. An input number the call does not have gives an R error, before FFmpeg runs. Without an audio_input column, the argument applies to every row. An NA cell in that column means NULL for that row, so that output has no audio. See audio_stream. (default = NULL)
video_codec	A string naming the output video codec, applied to every row lacking a video_codec column. NULL (default) leaves it unset, so each output keeps its container's default encoder.
audio_codec	A string naming the codec for the carried audio track, applied to every row lacking an audio_codec column. "copy" (default) stream-copies it. Name an encoder to re-encode it, or NULL to leave the codec unset. A row carrying no audio emits no -codec:a, and naming an encoder on such a row is an error.
hardware, fallback	The encoder backend and its fallback behavior, applied to the whole batch. They are a property of the machine, not of a row, so neither is read as a jobs column. See picture_in_picture(). Resolving a hardware backend asks this FFmpeg build which encoders it has. So the first such call that re-encodes the video runs FFmpeg while the command is built, even under run = FALSE. The answer is remembered for the rest of the R session. See refresh_ffmpeg_capabilities to discard it. This function checks that the encoder is available before any row runs. So an unavailable encoder aborts naming this function, not the internal step that runs the rows. A call can also contradict itself by naming an audio_codec with no audio carried into the output. Such a call is refused for the contradiction first, whether or not this machine has the encoder. A per-row value error likewise reports ahead of the encoder check. Examples are a negative margin, an audio_input index outside the two inputs, and a position outside the five accepted values. A value error and a contradiction resolve the same way whether the value arrived as an argument or in a jobs column. The contradiction reports first.
quality	A number, or NULL (default), applied to each row unless jobs carries a numeric quality column. In that column, NA leaves that row's encoder default in place, whatever the argument says. The value is the encoder's own rate-control value, passed through unchanged. Each cell is checked against the encoder its own row resolves to. A wrong cell is refused before any row runs, and the error names this function and the row. See picture_in_picture() for the encoders, their flags and ranges, and the values it refuses.
run	A logical: run each command through FFmpeg (TRUE, default) or only compile them for inspection (FALSE).
parallel	A logical: process the jobs in parallel with furrr (TRUE) or one at a time (FALSE, default). See ffm_batch for the future plan requirement.
...	Additional arguments forwarded to ffm_batch (e.g. verify, manifest, progress).

Value

The jobs tibble with an added command column. When run = TRUE, it also has a success column, plus verified or a provenance manifest, each when requested through .... See ffm_batch.

See Also

picture_in_picture(), the one-output function it wraps; ffm_batch(), the batch runner; has_hardware_encoder() for the hardware argument. concatenate_videos_batch() and compare_videos_batch(), the other batch functions that take several inputs per row.

Other task functions: anonymize_video(), anonymize_video_batch(), compare_videos(), compare_videos_batch(), concatenate_videos(), concatenate_videos_batch(), convert_audio(), convert_audio_batch(), crop_video(), crop_video_batch(), extract_audio(), extract_audio_batch(), extract_frame(), extract_frame_batch(), format_for_web(), format_for_web_batch(), normalize_audio(), normalize_audio_batch(), picture_in_picture(), sample_frames(), sample_frames_batch(), segment_video(), segment_video_batch(), separate_audio_video(), separate_audio_video_batch(), standardize_video(), standardize_video_batch(), strip_metadata(), strip_metadata_batch()

Other audio selection functions: anonymize_video(), anonymize_video_batch(), audio_stream, compare_videos(), compare_videos_batch(), convert_audio(), convert_audio_batch(), crop_video(), crop_video_batch(), extract_audio(), extract_audio_batch(), format_for_web(), format_for_web_batch(), normalize_audio(), normalize_audio_batch(), picture_in_picture(), segment_video(), segment_video_batch(), separate_audio_video(), separate_audio_video_batch(), standardize_video(), standardize_video_batch()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
jobs <- tibble::tibble(main = video, overlay = video, output = "pip.mp4")
picture_in_picture_batch(jobs, run = FALSE)

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