format_for_web: Re-encode a video for web playback

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

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

infile	A string containing the path to a video file.
outfile	A string containing the path of the video file to write.
hardware	The encoder backend. "none" (default) uses software libx264. "nvenc" uses NVIDIA GPU H.264 encoding ("h264_nvenc"), and "videotoolbox" uses Apple GPU H.264 encoding ("h264_videotoolbox"). The backend you name is the one used. An unavailable one aborts unless fallback = TRUE. See has_hardware_encoder. Resolving a hardware backend asks this FFmpeg build which encoders it has. So the first such call that re-encodes the video runs FFmpeg while the command is built, even under run = FALSE. The answer is remembered for the rest of the R session. See refresh_ffmpeg_capabilities to discard it.
fallback	A logical. When a hardware other than "none" is requested but its encoder is unavailable, TRUE re-encodes with software libx264 and a message. FALSE (default) aborts instead. A video_codec in a family that the backend has no encoder for is a wrong argument, not an absent encoder. So it aborts whatever fallback says.
quality	A number, or NULL (default) to leave the encoder's own default in place. It is the encoder's own rate-control value, passed through unchanged. libx264 reads it as -crf (0 to 51). h264_nvenc reads it as -cq (0 to 51), and h264_videotoolbox as -q:v (1 to 100). Each scale is its own: the same number means something different on each encoder. A value outside the encoder's range is refused. The encoder is libx264, h264_nvenc or h264_videotoolbox, as hardware chooses. When fallback = TRUE falls back to software, the value is dropped and the message says so, because it belonged to the hardware encoder's scale.
audio_stream	The audio track to carry into the output, as a number that counts from 0 among the audio tracks of the input. 0 is the first audio track and 1 is the second. Other streams in the file, such as video, do not count. NULL (default) carries every audio track. The every-track family reads NULL this way: separate_audio_video, standardize_video, anonymize_video, crop_video, segment_video and format_for_web, and their _batch forms. The first-track family reads it as the first audio track only: extract_audio, convert_audio and normalize_audio, and their _batch forms. The function does not carry subtitle or data streams in either case. A track the input does not have gives an FFmpeg error, not an R one. See audio_stream for how this differs from audio_input, the input index on compare_videos and picture_in_picture. (default = NULL)
run	A logical: run the command through FFmpeg (TRUE, default) or return the compiled command without running it (FALSE).

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)

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