crop_video_batch: Crop Many Videos From a Jobs Table

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

Crop Many Videos From a Jobs Table

Description

Crop many videos to a rectangular region, using one jobs table. This is the batch form of crop_video(), for when you have more than one file. Each row is one input. The function is a thin wrapper over ffm_batch. It builds one reproducible command for each input, with the same crop steps as crop_video(). This function checks each row's crop size and position before any command runs. So a bad cell is refused with an error that names this function. The glossary in vignette("tidymedia") explains media terms such as codec, container and stream copy.

Usage

crop_video_batch(
  jobs,
  width = NULL,
  height = NULL,
  x = "(in_w-out_w)/2",
  y = "(in_h-out_h)/2",
  video_codec = NULL,
  audio_codec = "copy",
  hardware = c("none", "nvenc", "videotoolbox"),
  fallback = FALSE,
  quality = NULL,
  audio_stream = NULL,
  run = TRUE,
  parallel = FALSE,
  ...
)

Arguments

jobs	A data frame with one row per input. It needs at least an input column, the source path. An optional output column names the destination. Without it, each row's output name adds _cropped to the input's base name and keeps its extension. For example, clip.mp4 becomes clip_cropped.mp4. A width, height, x or y column overrides that argument for each row. A dimension with no column uses the argument. A video_codec column overrides that argument for each row, and NA leaves the codec unset. That is the column form of the argument's NULL. An audio_codec column works the same way. An audio_stream column overrides that argument for each row, and NA keeps every audio track. That is the column form of that argument's NULL. Two rows with the same destination path are refused before any row runs. That happens with a repeated output, or with a repeated input when there is no output column. A numeric quality column overrides the quality argument per row (see quality). Any other columns are ignored.
width, height	The output crop size in pixels, for every row unless jobs has a column of the same name. Each is required: pass it as an argument or as a column. There is no default crop size.
x, y	The offset in pixels of the crop's left and top edge, for every row unless jobs has a column of the same name. The default centers the crop.
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 output audio codec, for every row when jobs has no audio_codec column. "copy" (default) stream-copies the audio. Name an encoder to transcode it. NULL leaves the codec unset, so each output keeps its container's default encoder.
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 crop_video(). 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 have a per-row width or height that is neither a positive number nor an FFmpeg expression. Such a call is refused for the value first, whether or not this machine has the encoder.
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 crop_video() for the encoders, their flags and ranges, and the values it refuses.
audio_stream	The audio track to carry into each output, as a number that counts from 0 among the audio tracks of each row's input. 0 is the first audio track and 1 is the second. Other streams in the file, such as video, do not count. NULL (default) carries every audio track. Without an audio_stream column, the argument applies to every row. An NA cell in that column means NULL for that row. It does not fall back to the argument. The every-track family reads NULL as every audio track: separate_audio_video, standardize_video, anonymize_video, crop_video, segment_video and format_for_web, and their _batch forms. The first-track family reads it as the first audio track only: extract_audio, convert_audio and normalize_audio, and their _batch forms. The function does not carry subtitle or data streams in either case. A track the input does not have gives an FFmpeg error, not an R one. See audio_stream for how this differs from audio_input, the input index on compare_videos and picture_in_picture. (default = NULL)
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

crop_video(), the single-input form it wraps; ffm_batch(), the batch runner; has_hardware_encoder() for the hardware toggle; standardize_video_batch() to re-encode in batch.

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(), 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(), 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(), extract_audio(), extract_audio_batch(), format_for_web(), format_for_web_batch(), normalize_audio(), normalize_audio_batch(), picture_in_picture(), picture_in_picture_batch(), 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(input = c(video, video), output = c("a.mp4", "b.mp4"),
                       width = c(160, 80), height = c(120, 60))
crop_video_batch(jobs, run = FALSE)

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