Package {tidymedia}

Title:	Media File Preprocessing and Metadata for the 'tidyverse'
Version:	0.2.1
Description:	Batch preprocessing and metadata extraction for audio, video and image files, built on the command-line programs 'FFmpeg' (https://ffmpeg.org/) and 'MediaInfo' (https://mediaarea.net/en/MediaInfo). Trim, crop, scale, convert and standardize files one at a time or across a whole directory, and read container and stream metadata back as tibbles for use with the 'tidyverse'.
License:	GPL-3
URL:	https://github.com/jmgirard/tidymedia, https://jmgirard.github.io/tidymedia/
BugReports:	https://github.com/jmgirard/tidymedia/issues
Depends:	R (≥ 4.1.0)
Imports:	archive (≥ 1.1.1), cli (≥ 3.4.0), digest (≥ 0.6.37), dplyr (≥ 1.1.0), glue (≥ 1.6.2), purrr (≥ 1.0.0), rappdirs (≥ 0.3.3), rlang (≥ 1.2.0), tibble (≥ 3.1.4), tools, utils, withr (≥ 2.5.0)
Suggests:	furrr (≥ 0.3.0), future (≥ 1.30.0), knitr (≥ 1.40), rmarkdown (≥ 2.16), roxygen2 (≥ 7.2.0), spelling (≥ 2.2), testthat (≥ 3.0.0)
SystemRequirements:	FFmpeg (https://ffmpeg.org/), MediaInfo (https://mediaarea.net/en/MediaInfo)
VignetteBuilder:	knitr
Encoding:	UTF-8
Language:	en-US
Config/testthat/edition:	3
Config/roxygen2/version:	8.1.0
Config/Needs/website:	pkgdown
NeedsCompilation:	no
Packaged:	2026-09-29 16:06:56 UTC; jmgirard
Author:	Jeffrey Girard [aut, cre]
Maintainer:	Jeffrey Girard <me@jmgirard.com>
Repository:	CRAN
Date/Publication:	2026-10-10 10:30:02 UTC

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

Description

tidymedia prepares audio and video files for research. It trims, crops, converts and standardizes files, and reads file details back as tibbles. It runs the programs FFmpeg and MediaInfo. Start with vignette("tidymedia").

Details

Task functions, such as extract_audio(), do one common job in one call. Pipeline functions, such as ffm_files(), build an FFmpeg command one step at a time. Direct commands, ffmpeg(), ffprobe() and mediainfo(), pass your own arguments to the programs. probe_all() and get_duration() read file details.

See vignette("tidymedia") for the guided tour and a glossary of media terms. The other vignettes are "batch", "metadata", "verification" and "workflow".

Session options

A new option value takes effect at the next call. The workers of a parallel = TRUE run use your session's values.

• options(tidymedia.timeout = 600) sets a limit, in whole seconds, on each program the package starts. The default, 0, means no limit. See with_timeout().

• options(tidymedia.check_tracks = FALSE) turns off the dropped-track warning of extract_audio(), convert_audio(), normalize_audio() and their ⁠_batch⁠ forms. The default is TRUE. The check runs one FFprobe call for each different input, when run = TRUE and the call or job row names no audio_stream. Turning it off skips those calls. A value other than TRUE or FALSE gives an error that names the option, when the check would run.

• options(tidymedia.hardware_encoders = "h264_nvenc") names the hardware video encoders of this computer, so the package does not ask FFmpeg. character(0) means none.

Errors when FFmpeg fails

• tidymedia_ffmpeg_exit: FFmpeg exited non-zero in ffm_run(), or in the loudnorm analysis pass of normalize_audio(two_pass = TRUE). The task functions that run their command with ffm_run(), such as extract_audio() and separate_audio_video(), give it too. The tm_status field holds the exit status.

• tidymedia_loudnorm_no_measurement: the two-pass analysis gave no measurement. In the ⁠_batch⁠ form, tm_rows holds the rows, and tm_row_status holds each exit status or NA.

• tidymedia_multitrack_separation: separate_audio_video() could not write several audio tracks into one audio file. The ⁠_batch⁠ form gives a warning.

Author(s)

Maintainer: Jeffrey Girard me@jmgirard.com (ORCID)

Authors:

• Jeffrey Girard me@jmgirard.com (ORCID)

See Also

Useful links:

• https://github.com/jmgirard/tidymedia

• https://jmgirard.github.io/tidymedia/

• Report bugs at https://github.com/jmgirard/tidymedia/issues

Cover fixed regions of a video with opaque boxes

Description

Anonymize a video by covering one or more fixed rectangular regions with opaque filled boxes. For example, you can redact a face, a name badge, or a screen that stays in one place for the whole clip. The regions are fixed (there is no face or object tracking), so this suits footage where the areas to cover do not move. The glossary in vignette("tidymedia") explains media terms such as codec, pixel format and stream copy.

Usage

anonymize_video(
  infile,
  outfile,
  regions,
  color = "black",
  video_codec = "libx264",
  audio_codec = "copy",
  pixel_format = "yuv420p",
  hardware = c("none", "nvenc", "videotoolbox"),
  fallback = FALSE,
  quality = NULL,
  audio_stream = NULL,
  run = TRUE
)

Arguments

Details

regions is a data frame with one row per box and the columns x, y, width, and height. Each value is a pixel number or an FFmpeg expression such as "in_w/2". x and y give the top-left corner, and width and height give the size. An optional color column overrides the color argument for that row. Every box is a solid fill (FFmpeg's drawbox with t=fill). The function intentionally does not offer hollow outlines.

Because the function applies a filter, it re-encodes the video. The video_codec and pixel_format arguments set the encoding, and default to H.264 and yuv420p. The function floors odd source dimensions to even, so the output always encodes. yuv420p and libx264 require even dimensions, and the step changes nothing for input that is already even. The function stream-copies the audio unchanged (-c:a copy) unless audio_codec names an encoder. The same input and regions therefore always compile to a byte-identical command.

Value

The compiled FFmpeg command (invisibly when run = TRUE).

References

https://ffmpeg.org/ffmpeg-filters.html#drawbox

See Also

ffm_drawbox(), the pipeline function it wraps; has_hardware_encoder() for the hardware argument; anonymize_video_batch() for the many-file (batch) form.

Other task functions: 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(), 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_batch(), audio_stream, compare_videos(), compare_videos_batch(), convert_audio(), convert_audio_batch(), crop_video(), crop_video_batch(), 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")
# Cover two fixed regions with black boxes
regions <- data.frame(
  x = c(10, 200), y = c(10, 150),
  width = c(120, 80), height = c(90, 60)
)
anonymize_video(video, "anon.mp4", regions, run = FALSE)
# Carry only the second audio track instead of all of them
anonymize_video(video, "anon.mp4", regions, audio_stream = 1, run = FALSE)

Anonymize Many Videos From a Jobs Table

Description

Cover fixed rectangular regions of many input videos with opaque filled boxes from a single jobs tibble. This is the batch (table-driven) form of anonymize_video(), for when you have more than one video to redact. Each row is one input with its own regions. The required columns name the source (input) and the boxes to cover (regions). This is a thin wrapper over ffm_batch. It compiles one reproducible command per input. It shares the same box-fill pipeline (and per-region validation) as anonymize_video(). The glossary in vignette("tidymedia") explains media terms such as codec, pixel format and stream copy.

Usage

anonymize_video_batch(
  jobs,
  color = "black",
  video_codec = "libx264",
  audio_codec = "copy",
  pixel_format = "yuv420p",
  hardware = c("none", "nvenc", "videotoolbox"),
  fallback = FALSE,
  quality = NULL,
  audio_stream = NULL,
  run = TRUE,
  parallel = FALSE,
  ...
)

Arguments

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.

See Also

anonymize_video() for the single-input form. has_hardware_encoder() for the hardware argument. ffm_batch() for the batch runner and the arguments forwarded through .... standardize_video_batch() and segment_video_batch() for the other table-driven functions.

Other task functions: anonymize_video(), 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(), 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(), audio_stream, compare_videos(), compare_videos_batch(), convert_audio(), convert_audio_batch(), crop_video(), crop_video_batch(), 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"),
  regions = list(
    data.frame(x = 10, y = 10, width = 120, height = 90),
    data.frame(x = 200, y = 150, width = 80, height = 60)
  )
)
# run = FALSE compiles one command per input without calling FFmpeg
anonymize_video_batch(jobs, run = FALSE)

Audio track and audio input indices

Description

Two audio arguments in this package count different things: audio_stream and audio_input. Both count from 0, so 0 means the first one. This page explains which is which.

The glossary in vignette("tidymedia") explains media terms such as stream, container and codec.

Value

This page documents no function and returns no value. It explains two arguments the functions listed under See Also take. Each of those pages says what its own function returns.

The two indices

audio_stream counts the audio tracks of one input file. On extract_audio(), audio_stream = 1 is the second audio track of the file. Where that track sits among all the streams of the file does not matter. So audio_stream is not the index column of probe_audio(), which counts every stream, audio or not.

audio_input counts the input files of a function. The functions compare_videos() and picture_in_picture() combine several files into one output, so they must choose whose sound to keep. On these functions, audio_input = 1 is the second file. It says nothing about which track of that file is used.

You cannot work out one index from the other. So the package keeps two names, rather than one argument whose meaning depends on how many inputs a function takes.

What NULL means

audio_stream = NULL still selects audio. It does not mean "no audio". How much audio it selects depends on the function.

• The first-track family reads NULL as the first audio track only: extract_audio, convert_audio and normalize_audio, and their _batch forms. The every-track family reads it as every audio track: separate_audio_video, standardize_video, anonymize_video, crop_video, segment_video and format_for_web, and their _batch forms.

• The two readings have a reason. A function that writes one audio stream must pick one track when you name none. A function that carries audio through can keep all the tracks its container holds.

• On the functions that pass video through, an input with no audio gives an output with no audio, not an error. On separate_audio_video() and normalize_audio(), whose output is audio, that input gives an FFmpeg error.

audio_input = NULL is different: it selects no audio at all, so the output has no audio. A silent output is the default for compare_videos() and picture_in_picture(). With several inputs, no choice of which one to hear is better than another.

The two arguments also fail in different ways when a number is too large. An audio_input that names an input you did not pass gives an R error, before FFmpeg runs. An audio_stream that names a track the input does not have gives an FFmpeg error. The reason is that the number of tracks is a fact about the file, not about the call.

In a ⁠_batch⁠ jobs table

On a ⁠_batch⁠ function, both arguments follow one rule. The argument you pass is the default, and a jobs column with the same name overrides it row by row.

This rule is about these two arguments only. The arguments hardware, parallel and two_pass apply to the whole batch, and the function reads no column for them.

If the column is absent, the argument applies to every row. If the column is present, each row uses its own cell. An NA cell means NULL for that row. It does not fall back to the argument. So audio_stream = 2 with an NA cell in an audio_stream column gives that row the NULL reading of its family, not track 2.

The name audio alone is not an index

The pipeline functions use audio for two things that are not counts:

• an audio codec name on ffm_codec(), where audio = "aac" names an encoder;

• a logical on ffm_copy(), where audio = TRUE copies the audio stream without re-encoding it.

The input index is called audio_input, so that its name says what it counts, as audio_stream does.

See Also

extract_audio, convert_audio and normalize_audio read NULL as the first audio track. separate_audio_video, standardize_video, anonymize_video, crop_video, segment_video and format_for_web read it as every audio track. compare_videos() and picture_in_picture() take the input index. probe_audio() shows which audio tracks a file has.

Other audio selection functions: anonymize_video(), anonymize_video_batch(), compare_videos(), compare_videos_batch(), convert_audio(), convert_audio_batch(), crop_video(), crop_video_batch(), 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()

Build a side-by-side comparison video

Description

Stack two or more videos into a single comparison video. The videos go side-by-side (direction = "horizontal") or one above the other (direction = "vertical"). This is a common need when reviewing annotations or before/after processing. Built on the stacking pipeline functions (ffm_hstack / ffm_vstack). The glossary in vignette("tidymedia") explains media terms such as codec, encoder and stream copy.

Usage

compare_videos(
  infiles,
  outfile,
  direction = c("horizontal", "vertical"),
  resize = TRUE,
  audio_input = NULL,
  video_codec = NULL,
  audio_codec = "copy",
  hardware = c("none", "nvenc", "videotoolbox"),
  fallback = FALSE,
  quality = NULL,
  run = TRUE
)

Arguments

Details

By default the two inputs are resized to share an edge (equal heights for a horizontal stack, equal widths for a vertical one). Resizing currently supports exactly two inputs, so pass resize = FALSE to compare more. Audio is dropped unless audio_input names an input to carry; a carried track is stream-copied unless audio_codec names an encoder.

Value

The compiled FFmpeg command (invisibly when run = TRUE).

See Also

ffm_hstack() and ffm_vstack(), the pipeline functions it wraps; has_hardware_encoder() for the hardware argument; picture_in_picture() for insetting instead of stacking.

Other task functions: anonymize_video(), anonymize_video_batch(), 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(), 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_batch(), convert_audio(), convert_audio_batch(), crop_video(), crop_video_batch(), 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")
compare_videos(c(video, video), "compare.mp4", run = FALSE)

Build Many Comparison Videos From a Jobs Table

Description

Stack videos side by side for many outputs from a single jobs tibble. This is the batch (table-driven) form of compare_videos(), for when you have more than one comparison to produce. Each row carries an inputs list-column (each cell two or more video paths) plus an output column. This is a thin wrapper over ffm_batch: one reproducible stacking command per row, sharing the pipeline with compare_videos(). The glossary in vignette("tidymedia") explains media terms such as codec, encoder and stream copy.

Usage

compare_videos_batch(
  jobs,
  direction = c("horizontal", "vertical"),
  resize = TRUE,
  audio_input = NULL,
  video_codec = NULL,
  audio_codec = "copy",
  hardware = c("none", "nvenc", "videotoolbox"),
  fallback = FALSE,
  quality = NULL,
  run = TRUE,
  parallel = FALSE,
  ...
)

Arguments

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

compare_videos(), the one-output function it wraps; ffm_batch(), the batch runner; has_hardware_encoder() for the hardware argument. concatenate_videos_batch() and picture_in_picture_batch(), the other batch functions that take several inputs per row.

Other task functions: anonymize_video(), anonymize_video_batch(), compare_videos(), 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(), 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(), convert_audio(), convert_audio_batch(), crop_video(), crop_video_batch(), 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(inputs = list(c(video, video)), output = "compare.mp4")
compare_videos_batch(jobs, run = FALSE)

Combine video files using the concat demuxer

Description

Combine multiple video files one after another without needing to re-encode them by using the concat demuxer. This will be much faster than re-encoding but requires that the files have the same parameters (width, height, etc.) and formats/codecs. To concatenate videos using re-encoding, see the concat video filter. The glossary in vignette("tidymedia") explains media terms such as codec and re-encode.

Usage

concatenate_videos(infiles, outfile, run = TRUE)

Arguments

Value

The compiled FFmpeg command (invisibly when run = TRUE).

See Also

ffm_concat(), the pipeline function it wraps.

Other task functions: anonymize_video(), anonymize_video_batch(), compare_videos(), compare_videos_batch(), 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(), 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")
concatenate_videos(c(video, video), "joined.mp4", run = FALSE)

Concatenate Many Videos From a Jobs Table

Description

Join clips end to end for many outputs from a single jobs tibble. This is the batch (table-driven) form of concatenate_videos(), for when you have more than one concatenation to produce. Unlike the single-input batch functions, each row's inputs are many. So jobs carries an inputs list-column (each cell a character vector of source paths) plus an output column. This is a thin wrapper over ffm_batch: one reproducible concat-demuxer command per row, sharing the copy + map-0 pipeline with concatenate_videos().

Usage

concatenate_videos_batch(jobs, run = TRUE, parallel = FALSE, ...)

Arguments

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

concatenate_videos(), the one-output function it wraps; ffm_batch(), the batch runner; compare_videos_batch() and picture_in_picture_batch(), the other batch functions that take several inputs per row.

Other task functions: anonymize_video(), anonymize_video_batch(), compare_videos(), compare_videos_batch(), concatenate_videos(), 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(), 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(inputs = list(c(video, video)), output = "joined.mp4")
concatenate_videos_batch(jobs, run = FALSE)

Extract or convert a media file's audio track

Description

Write the audio stream of infile into outfile. By default (audio_codec = NULL), the output format follows the outfile file extension, at the highest VBR quality (-q:a 0). For example, an .mp3 extension gives an MP3. Pass audio_codec to set the output audio codec yourself, whatever the extension is. The glossary in vignette("tidymedia") explains media terms such as codec and stream.

Usage

convert_audio(
  infile,
  outfile,
  audio_codec = NULL,
  audio_stream = NULL,
  run = TRUE
)

Arguments

Details

When infile has more than one audio track, audio_stream names which one to take. With no audio_stream, the function takes the first one.

When no audio_stream is named and the input has tracks that the output will not carry, the function warns. The check costs one FFprobe call per distinct input, which is one call here, because this function takes a single infile. The warning is given when FFprobe is available and the input can be probed. Otherwise the check is skipped silently. It never runs under run = FALSE, and never changes the compiled command. Suppress it by naming a track with audio_stream, or by class with suppressWarnings(classes = "tidymedia_dropped_audio").

To switch the check off and skip its FFprobe call, use options(tidymedia.check_tracks = FALSE) for the session. Use withr::local_options(tidymedia.check_tracks = FALSE) for the rest of one function.

Value

The compiled FFmpeg command (invisibly when run = TRUE).

See Also

ffm_codec() and ffm_map(), the pipeline functions it wraps. extract_audio() to copy audio without re-encoding. convert_audio_batch() for the many-file form.

Other task functions: anonymize_video(), anonymize_video_batch(), compare_videos(), compare_videos_batch(), concatenate_videos(), concatenate_videos_batch(), 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(), 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_batch(), crop_video(), crop_video_batch(), 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")
convert_audio(video, "audio.mp3", run = FALSE)
convert_audio(video, "audio.m4a", audio_codec = "aac", run = FALSE)
# Convert the second audio track instead of the first
convert_audio(video, "audio.mp3", audio_stream = 1, run = FALSE)

Convert the Audio of Many Files From a Jobs Table

Description

Extract or re-encode the audio track of many input files, using one jobs table. This is the batch form of convert_audio(), for when you have more than one file. Each row is one input. The input and output columns are required. The function is a thin wrapper over ffm_batch. It builds one reproducible command for each input. Each command uses the same audio steps as convert_audio(), and the function checks each audio_codec value in the same way. The glossary in vignette("tidymedia") explains media terms such as codec and stream.

Usage

convert_audio_batch(
  jobs,
  audio_codec = NULL,
  audio_stream = NULL,
  run = TRUE,
  parallel = FALSE,
  ...
)

Arguments

Details

When a row names no audio_stream and its input has tracks that the output will not carry, the function warns once for the whole batch. The warning names every affected row. The check costs one FFprobe call per distinct input it has to probe. A repeated input is probed once, and a row that names a track is not probed at all. The warning is given when FFprobe is available and the input can be probed. Otherwise the check is skipped silently. Those probes run one at a time, before any row starts, so parallel does not reach them. A sweep long enough to look like a hang reports its progress. The check never runs under run = FALSE, never changes any compiled command, and is skipped entirely when every row names a track. Suppress it by class with suppressWarnings(classes = "tidymedia_dropped_audio").

To switch the check off and skip the whole sweep, use options(tidymedia.check_tracks = FALSE) for the session. Use withr::local_options(tidymedia.check_tracks = FALSE) for the rest of one function.

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

convert_audio(), the single-input form it wraps. ffm_batch(), the batch runner. extract_audio_batch() to stream-copy audio in batch.

Other task functions: anonymize_video(), anonymize_video_batch(), compare_videos(), compare_videos_batch(), concatenate_videos(), concatenate_videos_batch(), convert_audio(), 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(), 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(), crop_video(), crop_video_batch(), 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.mp3", "b.mp3"))
convert_audio_batch(jobs, run = FALSE)

Crop a video to a rectangular region

Description

Crop a video to a rectangular region. The glossary in vignette("tidymedia") explains media terms such as codec, container and stream copy.

Usage

crop_video(
  infile,
  outfile,
  width,
  height,
  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
)

Arguments

Value

The compiled FFmpeg command (invisibly when run = TRUE).

See Also

ffm_crop(), the pipeline function it wraps; has_hardware_encoder() for the hardware toggle; crop_video_batch() for the many-file form.

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_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(), 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_batch(), 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")
crop_video(video, "cropped.mp4", width = 160, height = 120, run = FALSE)

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

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)

Extract the audio stream from a media file

Description

Take one audio track out of infile, and drop the video. When the input has more than one audio track, audio_stream names which one to take. With no audio_stream, the function takes the first audio track. The glossary in vignette("tidymedia") explains media terms such as codec, container and stream copy.

Usage

extract_audio(
  infile,
  outfile,
  audio_codec = "copy",
  audio_stream = NULL,
  run = TRUE
)

Arguments

Details

When no audio_stream is named and the input has tracks that the output will not carry, the function warns. The check costs one FFprobe call per distinct input, which is one call here, because this function takes a single infile. The warning is given when FFprobe is available and the input can be probed. Otherwise the check is skipped silently. It never runs under run = FALSE, and never changes the compiled command. Suppress it by naming a track with audio_stream, or by class with suppressWarnings(classes = "tidymedia_dropped_audio").

To switch the check off and skip its FFprobe call, use options(tidymedia.check_tracks = FALSE) for the session. Use withr::local_options(tidymedia.check_tracks = FALSE) for the rest of one function.

Value

The compiled FFmpeg command (invisibly when run = TRUE).

See Also

ffm_drop() and ffm_codec(), the pipeline functions it wraps. convert_audio() to re-encode the extracted audio. extract_audio_batch() for the many-file form.

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_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(), crop_video_batch(), 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")
extract_audio(video, "audio.aac", run = FALSE)
# Take the second audio track instead of the first
extract_audio(video, "audio.aac", audio_stream = 1, run = FALSE)

Extract Audio From Many Files From a Jobs Table

Description

Take the audio track out of many input files, using one jobs table. This is the batch form of extract_audio(), for when you have more than one file. Each row is one input. The input and output columns are required. The function is a thin wrapper over ffm_batch. It builds one reproducible command for each input, with the same steps as extract_audio(): select the audio track and drop the video. The glossary in vignette("tidymedia") explains media terms such as codec, container and stream copy.

Usage

extract_audio_batch(
  jobs,
  audio_codec = "copy",
  audio_stream = NULL,
  run = TRUE,
  parallel = FALSE,
  ...
)

Arguments

Details

When a row names no audio_stream and its input has tracks that the output will not carry, the function warns once for the whole batch. The warning names every affected row. The check costs one FFprobe call per distinct input it has to probe. A repeated input is probed once, and a row that names a track is not probed at all. The warning is given when FFprobe is available and the input can be probed. Otherwise the check is skipped silently. Those probes run one at a time, before any row starts, so parallel does not reach them. A sweep long enough to look like a hang reports its progress. The check never runs under run = FALSE, never changes any compiled command, and is skipped entirely when every row names a track. Suppress it by class with suppressWarnings(classes = "tidymedia_dropped_audio").

To switch the check off and skip the whole sweep, use options(tidymedia.check_tracks = FALSE) for the session. Use withr::local_options(tidymedia.check_tracks = FALSE) for the rest of one function.

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

extract_audio(), the single-input form it wraps. ffm_batch(), the batch runner. convert_audio_batch() to re-encode audio 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(), crop_video_batch(), extract_audio(), 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(), crop_video_batch(), extract_audio(), 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.aac", "b.aac"))
extract_audio_batch(jobs, run = FALSE)

Extract a single frame from a video

Description

Save one frame of a video to an image file, selected either by timestamp or by frame number. Provide exactly one of timestamp or frame.

Usage

extract_frame(infile, outfile, timestamp = NULL, frame = NULL, run = TRUE)

Arguments

Value

The compiled FFmpeg command (invisibly when run = TRUE).

See Also

ffm_seek(), the pipeline function it uses to get the frame. extract_frame_batch() for the many-file (batch) form.

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_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()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# run = FALSE returns the reproducible command instead of executing it
extract_frame(video, "frame.png", timestamp = 0.5, run = FALSE)

Extract Still Frames From Many Videos From a Jobs Table

Description

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

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)

Run an FFmpeg Pipeline Over Many Files

Description

Apply a pipeline-building function to every row of a jobs table and compile (and optionally run) the resulting FFmpeg command for each. This is the package's main batch function. It gives one reproducible compiled command per job, collected back into a tibble.

Usage

ffm_batch(
  jobs,
  .f,
  ...,
  run = TRUE,
  parallel = FALSE,
  verify = NULL,
  progress = FALSE,
  manifest = FALSE,
  checksums = FALSE
)

Arguments

Details

Each column of jobs is passed by name to .f (as purrr::pmap() does), so a job table with columns input, output and start calls .f(input = ..., output = ..., start = ...). .f must return a pipeline (see ffm_files). Give .f a ... argument if jobs carries columns it does not use.

Two jobs whose pipelines write to the same output path are refused before any job runs, under run = FALSE as well as run = TRUE. Paths are compared exactly as written. An output that writes no file may repeat. Such outputs are - (standard output), a pipe: URL, and an output whose last -f option is -f null, as ffm_output_options("-f null") gives.

with_timeout() explains how to limit how long R waits for each program in a job, and what happens when a program reaches the limit.

Value

jobs as a tibble with an added command column, which holds the compiled FFmpeg command for each job. When run = TRUE, it also has a logical success column. When verify is supplied, it also has a verified column. When manifest = TRUE, a provenance manifest is attached as an attribute; read it with ffm_manifest.

See Also

segment_video(), which is built on ffm_batch(); verify_media() for the verification spec and ffm_manifest() for the provenance manifest.

Other pipeline functions: 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_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
jobs <- tibble::tibble(
  input  = c(video, video),
  output = c("a.mp3", "b.mp3")
)
# run = FALSE compiles one command per job without calling FFmpeg
ffm_batch(jobs, run = FALSE, .f = function(input, output, ...) {
  ffm_files(input, output) |>
    ffm_drop("video") |>
    ffm_codec(audio = "libmp3lame")
})

Set Codecs in an FFmpeg Pipeline

Description

Set the audio codec, the video codec, or both, for the output file. Use ffmpeg_codecs() to see a list of the codecs in your FFmpeg version. The glossary in vignette("tidymedia") explains media terms such as codec and stream copy.

Usage

ffm_codec(object, audio = NULL, video = NULL)

Arguments

Value

object with an added instruction to change the codecs.

References

https://ffmpeg.org/ffmpeg-codecs.html

See Also

ffm_copy(), the shortcut for stream copy, ffmpeg_codecs() to list the codecs you can use, and standardize_video(), a task function built on it.

Other pipeline functions: ffm_batch(), 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_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_codec(video = "libx264", audio = "aac") |>
  ffm_compile()

Compile the tidymedia pipeline into an FFmpeg command

Description

Compile all the instructions into one string, the FFmpeg command that runs them.

Usage

ffm_compile(object)

Arguments

Value

A string with the FFmpeg command that carries out all the instructions in the tidymedia pipeline.

See Also

ffm_run() to compile and run in one step, and ffm_batch() to compile over many files.

Other pipeline functions: ffm_batch(), ffm_codec(), 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_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# ffm_compile() returns the reproducible FFmpeg command as a string
ffm_files(video, "output.mp4") |>
  ffm_trim(start = 1, end = 5) |>
  ffm_crop(width = 160, height = 120) |>
  ffm_codec(video = "libx264") |>
  ffm_compile()

Concatenate Multiple Inputs in an FFmpeg Pipeline

Description

Join the pipeline's input files one after another with FFmpeg's concat demuxer. Like ffm_hstack, this is a pipeline function for several inputs. It uses stream copy, so it is fast and lossless. But every input must share the same parameters, such as codec, resolution and frame rate. The glossary in vignette("tidymedia") explains media terms such as codec, re-encode and stream copy.

Usage

ffm_concat(object)

Arguments

Details

To join inputs with different parameters, you must re-encode with the concat filter. The package does not wrap that filter yet, so use ffmpeg.

The demuxer needs a list file that names the inputs. When you call ffm_concat(), it writes one to a temporary path and stores it in the pipeline, so the compiled command can refer to it. It also copies codecs and maps all streams, as ffm_copy would.

Value

object with an added instruction to concatenate the inputs.

See Also

concatenate_videos(), the task function built on this function.

Other pipeline functions: ffm_batch(), ffm_codec(), ffm_compile(), 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_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Join two inputs end-to-end (they must share codec/resolution/frame rate)
ffm_files(c(video, video), "output.mp4") |>
  ffm_concat() |>
  ffm_compile()

Copy the codecs and map all streams

Description

Copy the audio, the video, or both, with stream copy and no re-encoding. It can also map all streams from the input. This is the fast, lossless path when you only need to put the streams in a new container or cut on keyframes. The glossary in vignette("tidymedia") explains media terms such as codec, container, keyframe and stream copy.

Usage

ffm_copy(object, audio = TRUE, video = TRUE, streams = TRUE)

Arguments

Value

object with an added instruction to copy codecs, map all streams, or both.

See Also

ffm_codec() and ffm_map(), which ffm_copy() calls, and segment_video(), which uses it for fast copy cuts.

Other pipeline functions: ffm_batch(), ffm_codec(), ffm_compile(), ffm_concat(), 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_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_copy() |>
  ffm_compile()

Crop Frames in an FFmpeg Pipeline

Description

Make the video's frames smaller by cropping them.

Usage

ffm_crop(object, width, height, x = "(in_w-out_w)/2", y = "(in_h-out_h)/2")

Arguments

Value

object with an added instruction to crop the frames.

References

https://ffmpeg.org/ffmpeg-filters.html#crop

See Also

ffm_scale() to resize instead of crop. crop_video() and format_for_web() are the task functions built on ffm_crop().

Other pipeline functions: ffm_batch(), ffm_codec(), ffm_compile(), ffm_concat(), ffm_copy(), 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_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Crop to a centered 160x120 region
ffm_files(video, "output.mp4") |>
  ffm_crop(width = 160, height = 120) |>
  ffm_compile()

Draw a Colored Box on the Videos in an FFmpeg Pipeline

Description

Add a video filter that draws a colored rectangle on the input video.

Usage

ffm_drawbox(
  object,
  x = 0,
  y = 0,
  width = "in_w",
  height = "in_h",
  color = "black",
  thickness = "fill"
)

Arguments

Value

object with an added instruction to apply the drawbox filter.

References

https://ffmpeg.org/ffmpeg-filters.html#drawbox

https://ffmpeg.org/ffmpeg-utils.html#color-syntax

See Also

anonymize_video(), the task function that uses ffm_drawbox() to fill regions.

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

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Draw a filled red box covering the top-left quarter of the frame
ffm_files(video, "output.mp4") |>
  ffm_drawbox(width = "in_w/2", height = "in_h/2", color = "red") |>
  ffm_compile()

Drop Streams from an FFmpeg Pipeline

Description

Remove one or more streams from the media file. For example, remove the video, audio, subtitles or data stream from a media file. The glossary in vignette("tidymedia") explains media terms such as stream.

Usage

ffm_drop(object, streams = c("video", "audio", "subtitles", "data"))

Arguments

Value

object with an added instruction to drop these streams from the output file when the pipeline runs.

See Also

extract_audio(), the task function that uses ffm_drop() to drop the video stream.

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

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Drop the audio stream (keep video only)
ffm_files(video, "output.mp4") |>
  ffm_drop(streams = "audio") |>
  ffm_compile()

Specify Files in an FFmpeg Pipeline

Description

Start an FFmpeg pipeline by specifying input and output files.

Usage

ffm_files(input, output, overwrite = TRUE)

Arguments

Value

An FFmpeg pipeline object.

See Also

ffm_compile() to build the command and ffm_run() to run it. The task functions, such as standardize_video() and segment_video(), are built on the pipeline functions.

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

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_compile()

Set the Frame Rate in an FFmpeg Pipeline

Description

Resample the video to a constant frame rate with FFmpeg's fps filter. The filter duplicates or drops frames as needed. It is added to the end of the video filters, like the other filters that take one input. The glossary in vignette("tidymedia") explains media terms such as frame rate.

Usage

ffm_fps(object, fps)

Arguments

Value

object with an added instruction to resample the frame rate.

See Also

standardize_video(), the task function that uses ffm_fps() to set the frame rate.

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

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_fps(fps = 30) |>
  ffm_compile()

Horizontally Stack Multiple Videos in an FFmpeg Pipeline

Description

Add a complex video filter that stacks several videos horizontally (side by side). It can also resize the videos to the same height.

Usage

ffm_hstack(object, shortest = FALSE, resize = FALSE)

Arguments

Value

object with an added instruction to stack the videos horizontally.

See Also

ffm_vstack() for vertical stacking, and compare_videos(), the task function built on both.

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

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Stack two inputs side-by-side (pass more than one input to ffm_files())
ffm_files(c(video, video), "output.mp4") |>
  ffm_hstack() |>
  ffm_compile()

Build a Jobs Table From a Directory

Description

List the media files in a directory and return them as a jobs table for ffm_batch(). The table is a tibble with one row per file and an input column of full paths. Start a batch here, instead of with your own list.files() call.

Usage

ffm_jobs(directory, type, extension = NULL, recursive = FALSE)

Arguments

Details

The table has only the input column. ffm_batch() passes every column of the jobs table to .f by name. So if .f has no argument for a column, and no ... argument, the batch stops with R's "unused argument" error.

Add the columns your pipeline needs with the usual data-frame tools. Some *_batch() task functions need an output column. Others need columns for their task, such as start and end. The examples below make an output column from input.

crop_video_batch() and extract_audio_batch() handle the other columns of the table as follows:

• They read a column named like one of their per-row arguments in place of that argument, row by row. Each help page lists these arguments. Examples are a width column in crop_video_batch() and an audio_codec column in extract_audio_batch().

• They replace a column named like one that ffm_batch() adds. For example, the compiled command replaces a command column. The Value section of ffm_batch() lists the added columns.

• They return every other column unchanged.

Value

A tibble with one row per matching file and one character column, input, with each file's full path. Files whose names start with a dot are left out. Rows are in the order list.files returns them.

Every row is a path that exists and is not a directory. A subdirectory whose own name ends in a listed extension is never a row. On macOS and Linux, a symbolic link whose target is gone is never a row either. Windows reports such a link as existing, so there it can still be a row. The call gives an error, instead of zero rows, when nothing matches. With recursive = TRUE the search follows a symbolic link to a directory, so a row can name a file outside directory.

The scanned extensions include .mka as audio and .ts as video. separate_audio_video() recommends .mka or .m4a for multi-track audio, and this function reads both as audio, so it lists a folder of that output. Not every container that can hold several audio streams is audio here. .ts, like .mp4 and .mkv, is video, so multi-track audio written to one of those is a row under type = "video". The name .ts also belongs to TypeScript source files, and this function reads names rather than file contents. A folder of TypeScript sources therefore comes back as video rows when you ask for type = "video".

See Also

ffm_batch(), which consumes the returned table.

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_loudnorm(), ffm_map(), ffm_output_options(), ffm_overlay(), ffm_pixel_format(), ffm_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

folder <- system.file("extdata", package = "tidymedia")
jobs <- ffm_jobs(folder, type = "video")
jobs

# Derive an output column, then hand the whole table to ffm_batch().
# Two inputs sharing a name (a.mp4 and a.mkv) would derive one output here;
# ffm_batch() refuses jobs that share an output before any of them runs.
jobs$output <- file.path(tempdir(), paste0(
  tools::file_path_sans_ext(basename(jobs$input)), ".mp3"
))
ffm_batch(jobs, run = FALSE, .f = function(input, output, ...) {
  ffm_files(input, output) |> ffm_drop("video")
})

Normalize Loudness in an FFmpeg Pipeline

Description

Add FFmpeg's loudnorm (EBU R128) audio filter. It normalizes the input's perceived loudness toward a target integrated loudness, true-peak ceiling and loudness range. The filter compiles to -af, or joins an existing audio filter chain in the order the filters were added. The glossary in vignette("tidymedia") explains media terms such as LUFS and true peak.

Usage

ffm_loudnorm(
  object,
  target_loudness = -23,
  true_peak = -1,
  loudness_range = 7,
  measured_i = NULL,
  measured_tp = NULL,
  measured_lra = NULL,
  measured_thresh = NULL,
  offset = NULL,
  linear = FALSE,
  print_format = NULL
)

Arguments

Details

This is single-pass (dynamic) loudnorm. The pipeline stays one reproducible command, with no measurement pass. The defaults follow EBU Recommendation R 128 (2014): target_loudness = -23 LUFS and true_peak = -1 dBTP. Loudness is measured per ITU-R BS.1770-4. The default loudness_range = 7 is FFmpeg's own loudnorm default. EBU R128 does not prescribe a single value.

Two filters are added, not one. loudnorm is followed by asetnsamples, which regroups the filtered audio into frames of 4096 samples and does not pad the last one. Dynamic loudnorm resamples to 192 kHz and gives frames of 192000 samples. Some encoders accept whatever frame they are given, FLAC and Vorbis among them. Even those encoders refuse to open at all on frames of 192000 samples.

Value

object with an added instruction to normalize loudness.

References

EBU Recommendation R 128 (2014), Loudness normalisation and permitted maximum level of audio signals; ITU-R BS.1770-4. https://ffmpeg.org/ffmpeg-filters.html#loudnorm

See Also

normalize_audio(), the task function built on this filter.

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_map(), ffm_output_options(), ffm_overlay(), ffm_pixel_format(), ffm_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_loudnorm() |>
  ffm_compile()

Read a Batch Provenance Manifest

Description

Retrieve the reproducibility manifest recorded by ffm_batch() when it was run with manifest = TRUE. The manifest is a tibble with one row per job. Each row has the compiled command and the FFmpeg and FFprobe versions used. It also has the time of the run, the input and output paths, and the output file size. When the batch ran with checksums = TRUE, each row also has md5 checksums of the input and output files. With the manifest, a batch run leaves a record that others can check.

Usage

ffm_manifest(x, path = NULL)

Arguments

Value

The manifest tibble; invisibly when path is written.

See Also

ffm_batch(), which records the manifest.

Other verification functions: verify_media()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
jobs <- tibble::tibble(input = video, output = tempfile(fileext = ".mp3"))
res <- ffm_batch(jobs, manifest = TRUE, .f = function(input, output, ...) {
  ffm_files(input, output) |> ffm_drop("video")
})
ffm_manifest(res)

Set the Stream Mapping in an FFmpeg Pipeline

Description

Choose which input streams go into the output, with FFmpeg's -map option. The default, "0", maps every stream from the first input. The glossary in vignette("tidymedia") explains media terms such as stream.

Usage

ffm_map(object, mapping = "0", replace = FALSE)

Arguments

Details

mapping can be a character vector. Each element adds one -map, in the order given. For example, ffm_map(object, c("0:v", "0:a:1")) keeps the video and the second audio track of the input.

A second ffm_map() call adds to the maps already set. It does not replace them. Pass replace = TRUE to discard them instead. That is how you narrow the all-streams map that ffm_copy sets. Adding to that map puts the stream in the output twice, and does not select it.

ffm_map() is the only pipeline function that adds to earlier calls. Every other ffm_* function that sets a value, ffm_copy included, replaces it. ffm_map() is different because its arguments are partial choices that combine. For example, you keep the video, then name one audio track.

When the pipeline uses a function with several inputs, such as ffm_hstack, your mapping is added beside the automatic -map "[vout]" of the filtered stream. For example, ffm_map(object, "0:a") keeps the audio of the first input next to the stacked video.

Value

object with an added instruction to map streams.

See Also

ffm_copy(), which maps all streams, and separate_audio_video(), a task function built on ffm_map().

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_output_options(), ffm_overlay(), ffm_pixel_format(), ffm_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_map(mapping = "0") |>
  ffm_compile()

# Keep the video and the second audio track only
ffm_files(video, "output.mkv") |>
  ffm_map(mapping = c("0:v", "0:a:1")) |>
  ffm_compile()

Add Raw Output Options to an FFmpeg Pipeline

Description

Add one or more raw FFmpeg output options to the pipeline, after any added before. Output options are the flags after the input and before the output file. Use this function for an option that has no pipeline function of its own. ffm_compile() still decides where the options go and how the rest of the command is quoted. So this is not the same as writing the command string yourself.

Usage

ffm_output_options(object, ...)

Arguments

Value

object with the added output options.

See Also

ffmpeg(), the direct command that takes any FFmpeg arguments, and ffm_compile(), which places these options.

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_overlay(), ffm_pixel_format(), ffm_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Extract a single frame by adding a raw output option
ffm_files(video, "frame.png") |>
  ffm_output_options("-frames:v 1") |>
  ffm_compile()

Overlay One Video on Another in an FFmpeg Pipeline

Description

Draw the second input (the overlay) on top of the first input (the main video) at position x and y. Like ffm_hstack, this is a pipeline function for several inputs. It forces the -filter_complex path and manages its own stream labels internally. It needs exactly two inputs. The first is the background, and the second is drawn over it. The glossary in vignette("tidymedia") explains media terms such as stream.

Usage

ffm_overlay(object, x = 0, y = 0, shortest = FALSE, scale = NULL)

Arguments

Details

x and y accept plain numbers or FFmpeg overlay expressions. A plain number counts pixels from the top-left of the main video. In an expression, main_w and main_h are the main video's dimensions. overlay_w and overlay_h are the overlay's dimensions. For example, x = "main_w-overlay_w-16" puts the overlay 16 pixels from the right edge.

When scale is set, the overlay is first resized to a fraction of the main video's width, and its aspect ratio is kept. The task function picture_in_picture uses this resize. Otherwise, to resize the overlay yourself, filter it in a separate pipeline first.

Value

object with an added instruction to draw the second input on the first.

See Also

picture_in_picture(), the task function built on this function.

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_pixel_format(), ffm_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Draw the second input over the first, 16px in from the top-right corner
ffm_files(c(video, video), "output.mp4") |>
  ffm_overlay(x = "main_w-overlay_w-16", y = 16) |>
  ffm_compile()

Set the Pixel Format in an FFmpeg Pipeline

Description

Set the pixel format of the output with FFmpeg's -pix_fmt option. For example, use "yuv420p" for broad player compatibility. The glossary in vignette("tidymedia") explains media terms such as pixel format.

Usage

ffm_pixel_format(object, format)

Arguments

Value

object with an added instruction to set the pixel format.

See Also

standardize_video() and format_for_web(), the task functions that use ffm_pixel_format() to set the pixel format.

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_run(), ffm_scale(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_pixel_format("yuv420p") |>
  ffm_compile()

Run the FFmpeg Pipeline

Description

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

Usage

ffm_run(object, verify = NULL)

Arguments

Value

FFmpeg's standard output as a character vector, returned invisibly. On a non-zero exit it has a status attribute. You call ffm_run() to write the output file, not for its return value. The pipeline runs as a vector of arguments and never through a shell. So paths with spaces or special characters are safe.

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 field holds the shell's number, 128 plus the signal number, unchanged. That number stands for the signal, not for a status FFmpeg chose to return.

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.

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") |>
  ffm_run(verify = list(width = 160, height = 120))

Scale (Resize) Frames in an FFmpeg Pipeline

Description

Scale (resize) the input video's frames to a width and height in pixels, or with an FFmpeg expression.

Usage

ffm_scale(object, width, height)

Arguments

Value

object with an added instruction to resize the frames.

See Also

ffm_crop() to crop instead of resize. standardize_video() is the task function built on ffm_scale().

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_run(), ffm_seek(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_scale(width = 160, height = 120) |>
  ffm_compile()

Cut a Continuous Section from an FFmpeg Pipeline by Seeking

Description

Keep one continuous section of the input with FFmpeg's fast -ss and -to seek options. It does not use the trim filter of ffm_trim. Unlike the filter, seeking can use stream copy, so it is the tool for fast, lossless cuts. The glossary in vignette("tidymedia") explains media terms such as keyframe, re-encode and stream copy.

Usage

ffm_seek(object, start = NULL, end = NULL, reencode = TRUE)

Arguments

Details

The reencode argument trades accuracy against speed:

• reencode = TRUE (the default) is frame-accurate. The section is re-encoded, so it starts and ends on the exact frames you ask for. This is the safe default.

• reencode = FALSE is a fast, lossless copy. But the cut points move to the nearest keyframes. So the output duration can differ from the request by up to the gap between two keyframes. Use it with ffm_copy for the fastest path.

Value

object with an added instruction to cut the input by seeking.

References

https://ffmpeg.org/ffmpeg.html#Main-options

See Also

ffm_trim() for the filter that cuts, ffm_copy() for the fast copy path, and segment_video(), the task function built on it.

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_run(), ffm_scale(), ffm_trim(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Fast, lossless copy cut (snaps to keyframes)
ffm_files(video, "output.mp4") |>
  ffm_seek(start = 1, end = 5, reencode = FALSE) |>
  ffm_copy() |>
  ffm_compile()

Trim the Duration of the FFmpeg Pipeline

Description

Trim the input so that the output keeps one continuous part of the input. If start is NULL, the kept section starts at the beginning of the input. If both end and duration are NULL, the kept section ends at the end of the input. The glossary in vignette("tidymedia") explains media terms such as stream copy.

Usage

ffm_trim(
  object,
  start = NULL,
  end = NULL,
  duration = NULL,
  units = c("tds", "pts", "frame"),
  setpts = TRUE
)

Arguments

Value

object with added instructions to trim the duration.

References

https://ffmpeg.org/ffmpeg-filters.html#trim

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

See Also

ffm_seek(), the faster cut by seeking, which can use stream copy. ffm_trim() is the filter that cuts on exact frames.

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_run(), ffm_scale(), ffm_seek(), ffm_vstack(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
ffm_files(video, "output.mp4") |>
  ffm_trim(start = 1, end = 5) |>
  ffm_compile()

Vertically Stack Multiple Videos in an FFmpeg Pipeline

Description

Add a complex video filter that stacks several videos vertically (one above the other). It can also resize the videos to the same width.

Usage

ffm_vstack(object, shortest = FALSE, resize = FALSE)

Arguments

Details

This is the vertical form of ffm_hstack. Both are pipeline functions for several inputs. They force the -filter_complex path and manage their own stream labels internally. The glossary in vignette("tidymedia") explains media terms such as stream.

Value

object with an added instruction to stack the videos vertically.

See Also

ffm_hstack() for horizontal stacking, and compare_videos(), the task function built on both.

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_run(), ffm_scale(), ffm_seek(), ffm_trim(), print.tidymedia_ffm()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
# Stack two inputs one above the other (pass more than one input to ffm_files())
ffm_files(c(video, video), "output.mp4") |>
  ffm_vstack() |>
  ffm_compile()

Run a raw FFmpeg command

Description

Send a raw argument string to the FFmpeg command-line program. This is a direct command. The function passes the string to FFmpeg unchanged, after the path of the FFmpeg program. So you are responsible for the quoting and the order of the options.

Usage

ffmpeg(command)

Arguments

Value

A character vector containing the text output by FFmpeg.

See Also

ffmpeg_codecs() and ffmpeg_encoders() ask FFmpeg what it supports. The ⁠ffm_*()⁠ pipeline functions, such as ffm_run(), are a safer way to build a command.

Other direct command functions: ffprobe(), mediainfo()

Examples

# A direct command: the function passes the string to FFmpeg unchanged
ffmpeg("-version")

Get a data frame of all installed codecs

Description

Ask FFmpeg for its list of installed codecs, and return the list as a data frame with information about each codec. The glossary in vignette("tidymedia") explains media terms such as codec and encoder.

Usage

ffmpeg_codecs(sort_by_type = TRUE)

Arguments

Value

A tibble with the following variables:

See Also

ffmpeg_encoders() for the encoder list, ffm_codec() to set a codec in a pipeline, and ffmpeg() for the direct command.

Other capability functions: ffmpeg_encoders(), hardware_encoder(), refresh_ffmpeg_capabilities()

Examples

head(ffmpeg_codecs())
ffmpeg_codecs(sort_by_type = FALSE)

Get a data frame of all installed encoders

Description

Ask FFmpeg for its list of installed encoders, and return the list as a data frame with information about each encoder. The glossary in vignette("tidymedia") explains media terms such as codec and encoder.

Usage

ffmpeg_encoders(sort_by_type = TRUE)

Arguments

Value

A tibble with the following variables:

See Also

ffmpeg_codecs() for the codec list, ffm_codec() to set a codec in a pipeline, and ffmpeg() for the direct command.

Other capability functions: ffmpeg_codecs(), hardware_encoder(), refresh_ffmpeg_capabilities()

Examples

head(ffmpeg_encoders())
ffmpeg_encoders(sort_by_type = FALSE)

Send a command to the FFprobe program

Description

ffprobe() runs the FFprobe program with the arguments in command and returns its output. FFprobe reads information about media files.

Usage

ffprobe(command)

Arguments

Details

ffprobe() is a direct command. The package passes command to FFprobe exactly as you wrote it, so you must add any quotes that it needs. To get tibbles instead, use probe_all() and the other ⁠probe_*()⁠ functions. These functions quote their arguments for you.

Value

A character vector with the text that FFprobe writes to standard output, one element for each line. Messages on standard error, such as FFprobe's banner and errors, are not returned. On macOS and Linux, a shell redirect such as ⁠2>&1⁠ in command returns them too.

See Also

probe_all() and the other ⁠probe_*()⁠ functions, which return tibbles.

Other direct command functions: ffmpeg(), mediainfo()

Examples

ffprobe("-version")

Find the location of a dependency program

Description

Each of these functions returns the location of one program as a string: find_ffmpeg(), find_ffprobe(), find_ffplay() and find_mediainfo().

Usage

find_ffmpeg()

find_mediainfo()

find_ffprobe()

find_ffplay()

Details

The function looks on the PATH first. If the program is not there, the function reads the location that set_program() saved. That location is in a file under tools::R_user_dir("tidymedia", "config"). If neither place has the program, the function gives a warning and returns NULL.

Value

The location of the program as a string, or NULL when it could not be found.

Problems with a saved location

A saved location that no longer works gives a warning, and the function returns NULL. The warning has one of two classes that you can catch:

• tidymedia_location_gone: the function read the location, but no program is there now. The condition holds the program name in tm_program and the location in tm_location.

• tidymedia_location_unreadable: the file does not hold exactly one location. It is empty, has more than one line, or has one empty line. The condition holds the program name in tm_program and the file in tm_file.

A line that holds only spaces counts as a location. So it gives tidymedia_location_gone, not tidymedia_location_unreadable.

To fix either problem, forget the location with unset_program(), or replace it with set_program().

Locations saved by earlier versions

Versions of the package before 0.2.0 saved locations in a different folder, rappdirs::user_config_dir("tidymedia", "R"). The functions still read a file in that folder. They read it only when the current folder has no file for the program. program_status() looks in the same places, in the same order.

A tidymedia_location_unreadable warning names the file that the function read. That file can be the one in the old folder.

set_program() writes to the current folder only. After it writes a file for a program, the old file for that program is not read.

unset_program() removes the file in both folders. So the old location does not come back after the current file is gone.

See Also

set_program() to save the location of a program that is not on the PATH, and install_on_win() to download FFmpeg on Windows.

Other program management functions: install_on_win(), program_status(), set_program(), unset_program()

Examples

# Returns the path to the binary, or NULL with a warning if it is not found
find_ffmpeg()
find_mediainfo()

Re-encode a video for web playback

Description

Re-encode a video into a widely compatible, web-friendly form: H.264 video with yuv420p and +faststart, and AAC audio. Odd dimensions are padded down to even values, as the codec requires. The glossary in vignette("tidymedia") explains media terms such as codec, pixel format and re-encode.

Usage

format_for_web(
  infile,
  outfile,
  hardware = c("none", "nvenc", "videotoolbox"),
  fallback = FALSE,
  quality = NULL,
  audio_stream = NULL,
  run = TRUE
)

Arguments

Value

The compiled FFmpeg command (invisibly when run = TRUE).

See Also

ffm_codec() and ffm_pixel_format(), among the pipeline functions it wraps; has_hardware_encoder() for the hardware toggle; standardize_video() for a configurable re-encode; format_for_web_batch() for the many-file form.

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_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(), crop_video_batch(), extract_audio(), extract_audio_batch(), 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")
format_for_web(video, "web.mp4", run = FALSE)

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

Description

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

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

format_for_web(), the single-input form it wraps; ffm_batch(), the batch runner; standardize_video_batch() for a configurable re-encode.

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(), 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(), crop_video_batch(), extract_audio(), extract_audio_batch(), format_for_web(), 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"))
format_for_web_batch(jobs, run = FALSE)

Get the duration of a media file

Description

get_duration() uses the MediaInfo program to look up the duration of a media file. You choose the section of the file and the unit.

Usage

get_duration(
  file,
  section = c("General", "Video", "Audio"),
  unit = c("ms", "sec", "min", "hour")
)

Arguments

Details

The function returns one number for each file. The ⁠probe_*()⁠ functions, mediainfo_query() and mediainfo_template() return tibbles instead.

Value

A double vector (one per file) giving the duration of the specified section in the specified units.

See Also

mediainfo_parameter() for arbitrary MediaInfo fields, and probe_all() to read information with FFprobe.

Other metadata functions: get_frame_rate(), get_height(), get_sample_rate(), get_width(), mediainfo_parameter(), mediainfo_query(), mediainfo_template(), probe_all(), probe_container()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
get_duration(video, unit = "sec")

Get the video frame rate of a media file

Description

get_frame_rate() uses the MediaInfo program to look up the video frame rate of a media file, in frames per second (fps). The glossary in vignette("tidymedia") explains media terms such as frame rate.

Usage

get_frame_rate(file)

Arguments

Details

The function returns one number for each file. The ⁠probe_*()⁠ functions, mediainfo_query() and mediainfo_template() return tibbles instead.

Value

A double vector (one per file) giving the video frame rate in fps.

See Also

mediainfo_parameter() for arbitrary MediaInfo fields, and probe_all() to read information with FFprobe.

Other metadata functions: get_duration(), get_height(), get_sample_rate(), get_width(), mediainfo_parameter(), mediainfo_query(), mediainfo_template(), probe_all(), probe_container()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
get_frame_rate(video)

Get the video height of a media file

Description

get_height() uses the MediaInfo program to look up the video height of a media file, in pixels (px).

Usage

get_height(file)

Arguments

Details

The function returns one number for each file. The ⁠probe_*()⁠ functions, mediainfo_query() and mediainfo_template() return tibbles instead.

Value

A double vector (one per file) giving the video height in px.

See Also

mediainfo_parameter() for arbitrary MediaInfo fields, and probe_all() to read information with FFprobe.

Other metadata functions: get_duration(), get_frame_rate(), get_sample_rate(), get_width(), mediainfo_parameter(), mediainfo_query(), mediainfo_template(), probe_all(), probe_container()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
get_height(video)

Get the audio sample rate of a media file

Description

get_sample_rate() uses the MediaInfo program to look up the audio sample rate of a media file, in hertz (Hz). The glossary in vignette("tidymedia") explains media terms such as sample rate.

Usage

get_sample_rate(file)

Arguments

Details

The function returns one number for each file. The ⁠probe_*()⁠ functions, mediainfo_query() and mediainfo_template() return tibbles instead.

Value

A double vector (one per file) giving the audio sample rate in Hz.

See Also

mediainfo_parameter() for arbitrary MediaInfo fields, and probe_all() to read information with FFprobe.

Other metadata functions: get_duration(), get_frame_rate(), get_height(), get_width(), mediainfo_parameter(), mediainfo_query(), mediainfo_template(), probe_all(), probe_container()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
get_sample_rate(video)

Get the video width of a media file

Description

get_width() uses the MediaInfo program to look up the video width of a media file, in pixels (px).

Usage

get_width(file)

Arguments

Details

The function returns one number for each file. The ⁠probe_*()⁠ functions, mediainfo_query() and mediainfo_template() return tibbles instead.

Value

A double vector (one per file) giving the video width in px.

See Also

mediainfo_parameter() for arbitrary MediaInfo fields, and probe_all() to read information with FFprobe.

Other metadata functions: get_duration(), get_frame_rate(), get_height(), get_sample_rate(), mediainfo_parameter(), mediainfo_query(), mediainfo_template(), probe_all(), probe_container()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
get_width(video)

Hardware video encoders

Description

These functions help with optional hardware video encoding. hardware_encoder() gives the hardware encoder name for a codec family. has_hardware_encoder() reports whether that encoder is available in the local FFmpeg build. The package supports two backends: NVIDIA nvenc (H.264, HEVC and AV1) and Apple videotoolbox (H.264 and HEVC). So hardware_encoder("h264", "nvenc") is "h264_nvenc", and hardware_encoder("h264", "videotoolbox") is "h264_videotoolbox". The glossary in vignette("tidymedia") explains media terms such as codec, container and hardware encoder.

Usage

hardware_encoder(codec = c("h264", "hevc", "av1", "prores"), hardware)

has_hardware_encoder(codec = c("h264", "hevc", "av1", "prores"), hardware)

Arguments

Details

has_hardware_encoder() is a cheap check. It asks whether FFmpeg lists the encoder (via ffmpeg_encoders). That list reflects how FFmpeg was built. It does not reflect whether working hardware and a driver are present at run time. An encode can still fail at run time on a machine with no capable GPU. To override detection in a known environment (or in tests), set options(tidymedia.hardware_encoders = ) to a character vector of encoder names to treat as available.

The hardware argument of the task functions uses the same encoder names and the same check. These task functions have that argument: standardize_video, format_for_web, anonymize_video, crop_video, segment_video, compare_videos, picture_in_picture, and separate_audio_video (and their _batch forms). Some of these functions have a video_codec that defaults to NULL (no codec named), and they assume the H.264 family. So a container that does not take H.264 (e.g. .webm) needs an explicit HEVC- or AV1-family video_codec. AV1 works only under "nvenc". Hardware decoding (-hwaccel) and GPU filter pipelines are out of scope. Use the ffmpeg direct command for those.

Value

hardware_encoder() returns a single encoder-name string (e.g. "h264_nvenc"). has_hardware_encoder() returns a length-one logical. Neither returns for a codec that the chosen hardware backend has no encoder for. That pair is a wrong argument, not a machine without something. So both give the error that codec describes above. has_hardware_encoder() returns FALSE only for a pair that the chosen backend has an encoder for and this FFmpeg build does not list.

See Also

ffmpeg_encoders for the full encoder list. These task functions have the hardware argument: standardize_video, format_for_web, anonymize_video, crop_video, segment_video, compare_videos, picture_in_picture, and separate_audio_video.

Other capability functions: ffmpeg_codecs(), ffmpeg_encoders(), refresh_ffmpeg_capabilities()

Examples

hardware_encoder("h264", "nvenc")
has_hardware_encoder("h264", "nvenc")

Install FFmpeg on Windows

Description

install_on_win() downloads a Windows build of FFmpeg and unpacks it. Then it saves the locations of ffmpeg, ffprobe and ffplay, as set_program() does. After that, the package can find these programs.

By default, the call downloads the latest "essentials" build from gyan.dev. It unpacks the build into the ffmpeg folder under tools::R_user_dir("tidymedia", "data").

By default, the call asks you to confirm before it does anything. The question names each file it will download and the folder it will unpack into. It also names the saved program locations that the install can replace. If you say no, the call returns FALSE and changes nothing.

This function works on Windows only. On any other system, it gives an error before it asks, writes or downloads anything. The error names the system it found. On macOS, you can install FFmpeg with ⁠brew install ffmpeg⁠. On Linux, you can use ⁠sudo apt-get install ffmpeg⁠. On any system, set_program() tells the package where an installed FFmpeg is.

Usage

install_on_win(
  download_url = NULL,
  install_dir = NULL,
  confirm = TRUE,
  archive_checksum = NULL
)

Arguments

Details

Before the call unpacks the archive, it checks the archive against a SHA-256 checksum. A checksum is a fingerprint of the file's contents. For the default source, the call downloads the checksum that gyan.dev publishes next to each build. That file has the archive's address with .sha256 added. For any other source, give the checksum in archive_checksum.

The published checksum comes from the same site as the archive, over the same connection. So the check finds a damaged or incomplete download. It does not find a source that someone has tampered with.

After the unpack, the call checks each program before it saves any location. The path must be one that R finds as a program. It must be a file, not a folder, and the file must not be empty. The call does not run the program. So a build for the wrong type of processor can pass this check.

The package needs ffmpeg and ffprobe. If either one fails the check, the call saves no location and gives an error. The error names each failed program and its full path. If ffplay is missing or fails the check, the install finishes. A message says that the call did not save ffplay.

Value

TRUE when the install finished. FALSE when you said no to the question, or when the call could not create the install folder. Other failures give an error. The section "Errors" lists the error classes the call gives. A wrong argument gives an error before any of these.

What a failed install leaves behind

When the call gives an error, it tries to leave the install folder as it found it. It removes the files that a failed unpack wrote. It removes a folder that the call created. It does not touch the files that were already in the folder, with one exception.

The exception is a file of yours that the failed unpack wrote over. The call removes that file too, because the file no longer holds what you put there.

On Windows, the removal can fail. After a failed unpack, the unpack library can still hold a file open. Windows does not delete a file that is open.

The error names by full path the entries of the first case below that applies:

• each unpacked file that the call could not remove

• each folder that the call created and could not remove

• each file of yours that the call removed

Two errors come after a successful unpack: tidymedia_program_not_extracted and tidymedia_program_unusable. These errors leave the unpacked files in the folder, and they say so.

The call learns which files the unpack made from the archive's own list and from the folder. A program that the list names but that is not in the folder counts as not unpacked. For example, antivirus software can remove a program right after the unpack. The error then says that the unpack reported writing that file.

If none of the unpacked files are in the folder, tidymedia_program_not_extracted follows the usual rule. The call removes a folder that it created, and the error says so.

Errors

The call gives an error of its own class in these cases:

• tidymedia_wrong_platform: the session is not running on Windows.

• tidymedia_confirmation_unavailable: the call must ask you to confirm, but no one can answer in this session.

• tidymedia_download_unavailable: the archive did not download, or nothing readable arrived.

• tidymedia_checksum_unavailable: the call could not download or read the published checksum.

• tidymedia_checksum_mismatch: the downloaded archive does not match its checksum.

• tidymedia_archive_unreadable: the call could not unpack the archive.

• tidymedia_program_not_extracted: ffmpeg or ffprobe is not at the path where the install would put it.

• tidymedia_program_unusable: the archive made ffmpeg or ffprobe, but the file cannot be used.

See Also

set_program() to save the location of a program you already have, and find_ffmpeg() to check where the package finds a program.

Other program management functions: find_ffmpeg(), program_status(), set_program(), unset_program()

Examples

## Not run: 
# Download and install a static FFmpeg build (Windows)
install_on_win()

## End(Not run)

Set a time limit for the rest of a function

Description

local_timeout() sets a time limit for the rest of the function that calls it. The limit applies to each FFmpeg, FFprobe or MediaInfo program that the function starts after this call. When the function returns, or stops with an error, the caller's own limit is back, except in the cases in Details.

Use with_timeout() to set a limit on one expression. Use local_timeout() to set a limit on the rest of a function, or on several calls that are hard to wrap in one expression.

Usage

local_timeout(seconds, .local_envir = parent.frame())

Arguments

Details

The limit applies to each program, not to the whole function. In a 100-row batch after local_timeout(600), each program that a row starts gets 600 seconds, plus the delay that with_timeout() describes. The workers of a parallel = TRUE run use the same limit.

R can wait up to 40 seconds past the limit, and with_timeout() explains why. It also explains what happens when a limit is reached.

Two calls in one function work like any two ⁠local_*()⁠ calls. The second limit applies until the function ends. Then both are undone, and the caller's limit is back.

In three cases, the caller's limit is not back when the function ends, and there is no error.

• The function calls on.exit() without add = TRUE. That call removes the undo step. Write on.exit(..., add = TRUE) instead.

• The .local_envir belongs to a function that has returned, or it is an environment such as new.env().

• local_timeout() is called directly inside the expression of with_timeout(). There, local_timeout() belongs to the function around it. So when that function ends, the limit that with_timeout() set is in force. Put the inner limit in a function of its own, or use only one of the two.

The first two cases also apply to withr::local_options(), because R's exit handlers work this way. They do not apply to withr::with_options(), which puts the option back itself.

Value

The caller's earlier setting, invisibly. It is a list with one element, the same form that withr::local_options() returns.

See Also

with_timeout() to set a limit for one expression. tidymedia-package describes the session options.

Examples

bounded <- function() {
  local_timeout(30)
  getOption("tidymedia.timeout")
}

# In force for the rest of that function...
bounded()

# ...and gone once it has returned.
getOption("tidymedia.timeout", default = "unset")

# Bound every program a whole function starts, at five minutes. Defining the
# function starts nothing; the limit applies when you call it.
convert_all <- function(files) {
  local_timeout(300)
  for (f in files) extract_audio(f, sub("[.][^.]*$", ".wav", f))
}

Run a MediaInfo command

Description

mediainfo() runs the MediaInfo program with the arguments in command and returns its output. MediaInfo reads information about media files.

Usage

mediainfo(command)

Arguments

Details

mediainfo() is a direct command. The package passes command to MediaInfo exactly as you wrote it, so you must add any quotes that it needs. To get a tibble or a value instead, use mediainfo_template(), mediainfo_query() or mediainfo_parameter(). These functions quote their arguments for you.

Value

A character vector with the text that MediaInfo writes to standard output, one element for each line. Messages on standard error are not returned. On macOS and Linux, a shell redirect such as ⁠2>&1⁠ in command returns them too.

See Also

mediainfo_template(), mediainfo_query() and mediainfo_parameter() for a tibble or a value. get_duration() and the other ⁠get_*()⁠ functions for common single values.

Other direct command functions: ffmpeg(), ffprobe()

Examples

mediainfo("--Version")

Query a single parameter from a single MediaInfo section

Description

mediainfo_parameter() uses the MediaInfo program to read one value, such as the video width, from media files. MediaInfo groups its values in sections, such as "General", "Video" and "Audio". You name the section and the parameter to read.

Usage

mediainfo_parameter(file, section, parameter, typed = TRUE)

Arguments

Details

Give several files in file to get one value for each file. The function returns a vector, not a tibble. The ⁠probe_*()⁠ functions read similar information with FFprobe and return tibbles.

Value

A vector with one value for each element of file. A value is NA when MediaInfo prints more than one line, for example for a section it does not know. A parameter that section does not have gives an empty value. That value is NA when typed = TRUE and "" when typed = FALSE. A value is also NA for a file that does not exist or that reaches the time limit.

The function does not stop at those files. It reads the other files, and then gives one warning that names the files that do not exist or reached the limit. See with_timeout() for the time limit.

See Also

mediainfo_query() to read several parameters at once. mediainfo_template() to apply a whole template. probe_all() to read information with FFprobe. get_duration() and the other ⁠get_*()⁠ functions for common single values.

Other metadata functions: get_duration(), get_frame_rate(), get_height(), get_sample_rate(), get_width(), mediainfo_query(), mediainfo_template(), probe_all(), probe_container()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
mediainfo_parameter(video, section = "Video", parameter = "Width")

Query multiple parameters from a single MediaInfo section

Description

mediainfo_query() uses the MediaInfo program to read several parameters from one section, and returns a tibble. To read parameters from more than one section in one call, use mediainfo_template().

Usage

mediainfo_query(file, section, parameters, names = parameters, typed = TRUE)

Arguments

Details

Give several files in file to get one row for each file. The first column, file, names the input file. The ⁠probe_*()⁠ functions read similar information with FFprobe.

Value

A tibble with one row for each input file. The first column is file, and then there is one column for each parameter.

A file that the function could not read gets a row of NA values. The function reads the other files, and then gives one warning that names the files it could not read. A file that reaches the time limit counts as not read; see with_timeout().

See Also

mediainfo_parameter() to read a single value. mediainfo_template() to apply a whole template. probe_all() to read information with FFprobe. get_duration() and the other ⁠get_*()⁠ functions for common single values.

Other metadata functions: get_duration(), get_frame_rate(), get_height(), get_sample_rate(), get_width(), mediainfo_parameter(), mediainfo_template(), probe_all(), probe_container()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
mediainfo_query(video, section = "Video", parameters = c("Width", "Height"))

Describe media files by applying a MediaInfo template

Description

mediainfo_template() uses the MediaInfo program to describe media files, and returns a tibble. It applies a MediaInfo template, which can read many parameters from many sections.

Usage

mediainfo_template(
  file,
  template = c("brief", "extended", "custom"),
  templatefile = NULL,
  typed = TRUE
)

Arguments

Details

The package comes with two templates, "brief" and "extended". You can also give your own template file. Give several files in file to get one row for each file. The first column, file, names the input file. The ⁠probe_*()⁠ functions read similar information with FFprobe.

Value

A tibble with one row for each input file. The template sets the columns, their names and their order. The function keeps the column names of a custom template, but removes spaces at their start and end.

A file that the function could not read gets a row of NA values. The function reads the other files, and then gives one warning that names the files it could not read. A file that reaches the time limit counts as not read; see with_timeout().

See Also

mediainfo_query() to read one section. mediainfo_parameter() to read a single value. probe_all() to read information with FFprobe. get_duration() and the other ⁠get_*()⁠ functions for common single values.

Other metadata functions: get_duration(), get_frame_rate(), get_height(), get_sample_rate(), get_width(), mediainfo_parameter(), mediainfo_query(), probe_all(), probe_container()

Examples

video <- system.file("extdata", "sample.mp4", package = "tidymedia")
mediainfo_template(video, template = "brief")

Normalize a file's audio loudness (EBU R128)

Description

Normalize the perceived loudness of a file's audio toward an EBU R128 target. The function uses FFmpeg's single-pass loudnorm filter. It can also downmix the channel count and resample. The output holds one audio stream and no video, whatever the input and whatever container outfile names. So the output of this function is audio, as with extract_audio and convert_audio. It does not carry the other streams through. To normalize a recording's soundtrack and keep its picture, first normalize to an audio file. Then put the audio back with the picture using the ffmpeg direct command. The glossary in vignette("tidymedia") explains media terms such as LUFS, true peak and sample rate.

Usage

normalize_audio(
  infile,
  outfile,
  target_loudness = -23,
  true_peak = -1,
  loudness_range = 7,
  channels = NULL,
  sample_rate = NULL,
  audio_codec = NULL,
  two_pass = FALSE,
  audio_stream = NULL,
  run = TRUE
)

Arguments