Convert the Audio of Many Files From a Jobs Table

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

jobs

A data frame with one row per input. It needs at least an input column (source path) and an output column (destination path). The output column is required. The function cannot name an audio destination for you, because its extension picks the output format. An optional audio_codec column overrides the audio_codec argument per row. There, NA means "use the highest-VBR-quality default". Rows without a value use the argument. An optional audio_stream column overrides the audio_stream argument per row in the same way, and NA keeps that row on the first audio track. The function refuses two rows with the same output path, before any row runs. The function ignores any other columns, with one exception. A format column is an error, not a silent no-op. The package retired that column with the argument of the same name.

audio_codec

The output audio codec applied to every row, unless jobs has an audio_codec column. With NULL (default), FFmpeg infers the codec from each output extension, at the highest VBR quality. Name a codec (e.g. "aac", "flac") to set -c:a.

audio_stream

The audio track to take, as a number that counts from 0 among the audio tracks of each row's input. 0 is the first audio track and 1 is the second. Other streams in the file, such as video, do not count. NULL (default) takes the first audio track. Without an audio_stream column, the argument applies to every row. An NA cell in that column means NULL for that row. It does not fall back to the argument. The 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. A track the input does not have gives an FFmpeg error, not an R one. See audio_stream for how this differs from audio_input, the input index on compare_videos and picture_in_picture. (default = NULL)

run

A logical: run each command through FFmpeg (TRUE, default) or only compile them for inspection (FALSE).

parallel

A logical: process the jobs in parallel with furrr (TRUE) or one at a time (FALSE, default). See ffm_batch for the future plan requirement.

...

Additional arguments forwarded to ffm_batch (e.g. verify, manifest, progress).

Value

The jobs tibble with an added command column. When run = TRUE, it also has a success column, plus verified or a provenance manifest, each when requested through .... See ffm_batch.

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.

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)
#> # A tibble: 2 × 3
#>   input                                                        output command   
#>   <chr>                                                        <chr>  <chr>     
#> 1 /home/runner/work/_temp/Library/tidymedia/extdata/sample.mp4 a.mp3  "-y -i \"…
#> 2 /home/runner/work/_temp/Library/tidymedia/extdata/sample.mp4 b.mp3  "-y -i \"…