convert_audio: Extract or convert a media file's audio track

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

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

infile	A string containing the path to a media file.
outfile	A string containing the path of the audio file to write.
audio_codec	An optional string naming the output audio codec (e.g. "libmp3lame", "aac", "flac"), passed to FFmpeg's -c:a. When NULL (default), FFmpeg infers the codec from the outfile extension and encodes at the highest VBR quality. On the other task functions, NULL means "leave the codec unset". Here NULL does not leave the codec unset. NULL selects -q:a 0.
audio_stream	The audio track to take, 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) takes the first audio track. The first-track family reads NULL this way: 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 the command through FFmpeg (TRUE, default) or return the compiled command without running it (FALSE).

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)

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