Run the FFmpeg Pipeline

Compile the instructions in the pipeline and run them all through FFmpeg.

Usage

ffm_run(object, verify = NULL)

Arguments

object

An FFmpeg pipeline (ffm) object created by ffm_files().

verify

An optional named list of the properties you expect the output to have, for example list(width = 1920, video_codec = "h264"). It is passed to verify_media. After a successful run, the output is probed. If a check fails, ffm_run() gives an error with the failed checks. It also gives an error when FFmpeg exits non-zero. NULL (the default) skips the checks.

Value

FFmpeg's standard output as a character vector, returned invisibly. On a non-zero exit ffm_run() gives an error instead of returning (see the section below). You call ffm_run() to write the output file, not for its return value. Each argument of the command is quoted with shQuote() before system2() runs it, and on Unix system2() passes the command to a shell. The quoting makes paths with spaces or special characters reach FFmpeg as written.

When FFmpeg exits non-zero

If FFmpeg refuses a run, ffm_run() gives an error of class tidymedia_ffmpeg_exit. A caller can catch a failed run without reading the error text:

tryCatch(
  ffm_run(pipeline),
  tidymedia_ffmpeg_exit = function(cnd) cnd$tm_status
)

The tm_status field is one integer, the exit status exactly as system2() reported it. If a signal stopped FFmpeg, the value depends on the signal and the platform. In runs with FFmpeg 9.0.2 on macOS (2026-10-18), SIGTERM, which FFmpeg catches, gave 255, the status FFmpeg chose when it stopped. SIGKILL, which no program can catch, gave 137, the shell's 128 plus the signal number 9.

Two other paths give this class and carry this field, so one handler covers all three:

• the loudnorm analysis pass of normalize_audio(two_pass = TRUE), when FFmpeg exits non-zero.

• the error about several audio tracks that separate_audio_video adds to a failed audio output.

Each of those two paths also gives a second, narrower class before this one. In the same order, they are tidymedia_loudnorm_no_measurement and tidymedia_multitrack_separation. Catch that class when you want only that failure.

Two related paths do not give this class, each for its own reason:

• normalize_audio(two_pass = TRUE) also gives an error when the analysis pass exits zero and prints no measurement block that can be read. FFmpeg did not exit non-zero there. So that error has only the class tidymedia_loudnorm_no_measurement, and no tm_status.

• normalize_audio_batch(two_pass = TRUE) reports in one error every row that failed in its analysis phase. The failed rows can include rows that exited zero and rows that FFmpeg refused. So a non-zero exit is one of its causes, not the fact it reports, and no single status can stand for the mix. It also has only the class tidymedia_loudnorm_no_measurement. It carries tm_rows, the failed rows counted from 1. It also carries tm_row_status, their exit statuses in the same order, with NA where a row exited zero.

So tidymedia_loudnorm_no_measurement is the one class that covers the analysis pass in both forms.

When the build lacks an encoder

After FFmpeg exits non-zero, ffm_run() looks at the video and audio codecs that ffm_codec set on the pipeline. A name is encodable if ffmpeg_encoders lists it, or if ffmpeg_codecs lists it as a codec this build can encode, such as "h264". If a codec is not encodable, the error also has the class tidymedia_encoder_unavailable, before tidymedia_ffmpeg_exit. It carries tm_encoder, the names, and tm_stream, which is "video" or "audio" for each name.

The message says that this build lists no such encoder. It does not say that the missing encoder made the run fail. FFmpeg uses no video encoder for an input that has no video, so a run can fail for another reason. When a task function such as standardize_video runs its command, the error names that function.

The check runs only after a failed run. A successful run, and a call with run = FALSE, never start it. It skips "copy", a codec the pipeline does not set, the hardware encoders that hardware_encoder names, and encoders given through ffm_output_options. It asks FFmpeg for the two lists, and the package remembers each list for the session once it reads it (see refresh_ffmpeg_capabilities). If the package cannot read a list, the check says nothing, and the error is the tidymedia_ffmpeg_exit error alone. If reading a list reaches the tidymedia.timeout limit, a warning of class tidymedia_probe_timeout also says so, once per call. ffm_batch gives one tidymedia_encoder_unavailable warning for all its rows instead of an error for each.

See also

ffm_compile() to get the command without running it, ffm_batch() to run many files, and verify_media() for the verify list.

Other pipeline functions: ffm_batch(), ffm_codec(), ffm_compile(), ffm_concat(), ffm_copy(), ffm_crop(), ffm_drawbox(), ffm_drop(), ffm_files(), ffm_fps(), ffm_hstack(), ffm_jobs(), ffm_loudnorm(), ffm_map(), ffm_output_options(), ffm_overlay(), ffm_pixel_format(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
out <- tempfile(fileext = ".mp4")
ffm_files(video, out) |>
  ffm_scale(width = 160, height = 120) |>
  ffm_codec(video = "libx264", audio = "aac") |>
  ffm_run(verify = list(width = 160, height = 120))