sample_frames_batch: Sample frames from many videos at a fixed rate from a jobs...

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

Sample frames from many videos at a fixed rate from a jobs table

Description

Sample many videos into numbered image sequences, using one jobs table. This is the batch form of sample_frames(). Each row is one input video, sampled at a fixed rate into its own image sequence. The function is a thin wrapper over ffm_batch. It builds one reproducible command for each input. The glossary in vignette("tidymedia") explains media terms such as frame rate.

Usage

sample_frames_batch(
  jobs,
  fps = NULL,
  interval = NULL,
  outdir = NULL,
  format = "png",
  run = TRUE,
  parallel = FALSE,
  ...
)

Arguments

jobs	A data frame with one row per input. It needs at least an input column (source path). An optional outdir column gives the output directory for that row's sequence. When it is absent, the function derives one as <input-base>_frames beside each input. Optional fps and interval columns override the rate per row. The function ignores any other columns. The function refuses two rows whose image sequences would share a file-name pattern, before any row runs. Two rows share a pattern when they have the same output directory path and the same input file name without its extension. The directory path can come from the column, from the outdir argument, or from the derived name.
fps, interval	The sampling rate applied to every row, as in sample_frames(). A per-row column of the same name overrides it. Supply exactly one of the two (as an argument or a column). (default = NULL)
outdir	An optional single output directory for all rows. An outdir column overrides it. When both are absent, the function derives one directory per input. (default = NULL)
format	A string giving the output image file extension, as in sample_frames(). (default = "png")
run	A logical: run each input's command through FFmpeg (TRUE, default) or only compile them for inspection (FALSE).
parallel	A logical passed to ffm_batch: sample in parallel with furrr (TRUE) or one after another (FALSE, default). Parallel work follows the active future plan. TRUE under the default sequential plan runs one at a time and warns.
...	Additional arguments forwarded to ffm_batch, such as verify, manifest, checksums, and progress.

Details

Supply the sampling rate once as the single fps or interval argument, which applies to every row. Or supply it per row as an fps or interval column, which overrides the argument of the same name. Supply exactly one of the two, fps or interval, across arguments and columns.

Value

The tibble returned by ffm_batch: jobs with an added command column. When outdir was derived, it also has the resolved outdir column. When run = TRUE, it has a success column, plus any columns the forwarded arguments add, such as verified.

See Also

sample_frames() for the single-video form. ffm_batch() for the batch runner and the arguments passed on through .... extract_frame_batch() for the batch function that takes a list of frames.

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(), picture_in_picture_batch(), sample_frames(), segment_video(), segment_video_batch(), separate_audio_video(), separate_audio_video_batch(), standardize_video(), standardize_video_batch(), strip_metadata(), strip_metadata_batch()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
jobs <- tibble::tibble(
  input  = c(video, video),
  outdir = c(file.path(tempdir(), "a"), file.path(tempdir(), "b"))
)
# run = FALSE compiles one command per input without calling FFmpeg
sample_frames_batch(jobs, fps = 2, run = FALSE)

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