Re-encode Many Videos for the Web From a Jobs Table

Re-encode many videos into a widely compatible, web-friendly form, using one jobs table. This is the batch form of format_for_web(), 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. Each command uses the same fixed H.264, AAC and +faststart steps as format_for_web(), with no per-row settings. The glossary in vignette("tidymedia") explains media terms such as codec and re-encode.

Usage

format_for_web_batch(
  jobs,
  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 _web to the input's base name, with an .mp4 extension. The web re-encode always writes H.264 in mp4. For example, clip.mkv becomes clip_web.mp4. Two rows with the same destination path are refused before any row runs. That happens with a repeated output, or with two derived names that match. For example, clip.mov and clip.mkv both give clip_web.mp4. An optional numeric audio_stream column overrides the audio_stream argument for each row. NA keeps every audio track in that row. A numeric quality column overrides the quality argument per row (see quality). Any other columns are ignored, video_codec and audio_codec included. The sibling batch functions read those two columns as per-row overrides, but this one does not. The web recipe fixes which codecs the output uses: H.264 video and AAC audio. For per-row codecs, use a function that has them, such as standardize_video_batch or crop_video_batch.
hardware: The encoder backend for every row. "none" (default) uses software libx264. "nvenc" uses NVIDIA GPU H.264 encoding, and "videotoolbox" uses Apple GPU H.264 encoding. It applies to the whole batch and is not read as a column. See has_hardware_encoder. 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.
fallback: A logical. When a hardware other than "none" is requested but its encoder is unavailable, TRUE re-encodes with software libx264 and a message. FALSE (default) aborts instead. A video_codec in a family that the backend has no encoder for is a wrong argument, not an absent encoder. So it aborts whatever fallback says.
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 format_for_web() 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.

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
jobs <- tibble::tibble(input = c(video, video), output = c("a.mp4", "b.mp4"))
format_for_web_batch(jobs, run = FALSE)
#> # A tibble: 2 × 3
#>   input                                                        output command   
#>   <chr>                                                        <chr>  <chr>     
#> 1 /home/runner/work/_temp/Library/tidymedia/extdata/sample.mp4 a.mp4  "-y -i \"…
#> 2 /home/runner/work/_temp/Library/tidymedia/extdata/sample.mp4 b.mp4  "-y -i \"…

Usage

Arguments

Value

See also

Examples