Extract Still Frames From Many Videos From a Jobs Table

Save one still image for each row, across many input files, using one jobs table. This is the batch form of extract_frame(), for when your frames come from more than one input. Each row is one frame. The required columns name its source and the moment to capture. The function is a thin wrapper over ffm_batch. It builds one reproducible command for each frame. The glossary in vignette("tidymedia") explains media terms such as frame rate.

Usage

extract_frame_batch(jobs, format = "png", run = TRUE, parallel = FALSE, ...)

Arguments

jobs

A data frame with one row per frame. It needs at least an input column (source path). It also needs exactly one of a timestamp column and a frame column. A timestamp holds seconds, or FFmpeg time-duration strings. A frame holds whole frame numbers. The function converts each one to a timestamp with the input's frame rate, as extract_frame does. An optional output column names the destination image. When it is absent, the function derives one per row by appending _<n>.<format> to each input's basename. The frame number restarts at 1 for each input file. The function refuses two rows whose destination is the same path, before any row runs. That covers a repeated output, and two derived names that match. For example, clip.mp4 and clip.mkv both give clip_1.png. The function ignores any other columns.

format

A string giving the image file extension used when the function derives output. The function ignores it when jobs has an output column. (default = "png")

run

A logical: run each frame's command through FFmpeg (TRUE, default) or only build the commands for inspection (FALSE).

parallel

A logical passed to ffm_batch: save frames 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 frame at a time and warns.

...

Additional arguments forwarded to ffm_batch, such as verify, manifest, checksums, and progress.

Value

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

References

https://ffmpeg.org/ffmpeg-utils.html#time-duration-syntax

See also

extract_frame() for the single-frame form. ffm_batch() for the batch runner and the arguments passed on through .... segment_video_batch() for the batch function that cuts segments.

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(), format_for_web(), format_for_web_batch(), normalize_audio(), normalize_audio_batch(), picture_in_picture(), picture_in_picture_batch(), 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()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
jobs <- tibble::tibble(
  input     = c(video, video),
  output    = c("a.png", "b.png"),
  timestamp = c(0.25, 0.75)
)
# run = FALSE compiles one command per frame without calling FFmpeg
extract_frame_batch(jobs, run = FALSE)
#> # A tibble: 2 × 4
#>   input                                                 output timestamp command
#>   <chr>                                                 <chr>      <dbl> <chr>  
#> 1 /home/runner/work/_temp/Library/tidymedia/extdata/sa… a.png       0.25 "-y -s…
#> 2 /home/runner/work/_temp/Library/tidymedia/extdata/sa… b.png       0.75 "-y -s…