Post-processing Options

Audio extraction, video conversion, metadata embedding, and FFmpeg configuration

Audio Extraction

-x, --extract-audio · flag

Convert video files to audio-only files

Requires ffmpeg and ffprobe

--audio-format · string · default: "best"

Format to convert the audio to when -x is used

Supported formats: best, aac, alac, flac, m4a, mp3, opus, vorbis, wav

You can specify multiple rules using similar syntax as --remux-video

Example:

yt-dlp -x --audio-format mp3 URL
yt-dlp -x --audio-format "flac/mp3" URL

--audio-quality · string · default: "5"

Specify ffmpeg audio quality to use when converting the audio with -x

Insert a value between 0 (best) and 10 (worst) for VBR or a specific bitrate like 128K

Example:

yt-dlp -x --audio-quality 0 URL
yt-dlp -x --audio-quality 128K URL

Video Format Conversion

--remux-video · string

Remux the video into another container if necessary

Supported formats: avi, flv, gif, mkv, mov, mp4, webm, aac, aiff, alac, flac, m4a, mka, mp3, ogg, opus, vorbis, wav

If the target container does not support the video/audio codec, remuxing will fail.

You can specify multiple rules; e.g. “aac>m4a/mov>mp4/mkv” will remux aac to m4a, mov to mp4 and anything else to mkv

Example:

yt-dlp --remux-video mkv URL
yt-dlp --remux-video "aac>m4a/mov>mp4/mkv" URL

--recode-video · string

Re-encode the video into another format if necessary

The syntax and supported formats are the same as --remux-video

Example:

yt-dlp --recode-video mp4 URL

Postprocessor Arguments

--postprocessor-args · string

Give these arguments to the postprocessors

Format: NAME:ARGS

Specify the postprocessor/executable name and the arguments separated by a colon ”:”

Supported PP: Merger, ModifyChapters, SplitChapters, ExtractAudio, VideoRemuxer, VideoConvertor, Metadata, EmbedSubtitle, EmbedThumbnail, SubtitlesConvertor, ThumbnailsConvertor, FixupStretched, FixupM4a, FixupM3u8, FixupTimestamp, FixupDuration

Supported executables: AtomicParsley, FFmpeg, FFprobe

You can also specify “PP+EXE:ARGS” to give the arguments to the specified executable only when being used by the specified postprocessor.

For ffmpeg/ffprobe, “_i”/“_o” can be appended to the prefix optionally followed by a number to pass the argument before the specified input/output file.

Alias: --ppa

Example:

yt-dlp --ppa "Merger+ffmpeg_i1:-v quiet" URL
yt-dlp --ppa "FFmpeg:-threads 4" URL

-k, --keep-video · flag

Keep the intermediate video file on disk after post-processing

--no-keep-video · flag · default: "true"

Delete the intermediate video file after post-processing

--post-overwrites · flag · default: "true"

Overwrite post-processed files

--no-post-overwrites · flag

Do not overwrite post-processed files

Embedding

--embed-subs · flag

Embed subtitles in the video (only for mp4, webm and mkv videos)

--no-embed-subs · flag · default: "true"

Do not embed subtitles

--embed-thumbnail · flag

Embed thumbnail in the video as cover art

--no-embed-thumbnail · flag · default: "true"

Do not embed thumbnail

--embed-metadata · flag

Embed metadata to the video file

Also embeds chapters/infojson if present unless --no-embed-chapters/--no-embed-info-json are used

Alias: --add-metadata

--no-embed-metadata · flag · default: "true"

Do not add metadata to file

Alias: --no-add-metadata

--embed-chapters · flag

Add chapter markers to the video file

Alias: --add-chapters

--no-embed-chapters · flag · default: "true"

Do not add chapter markers

Alias: --no-add-chapters

--embed-info-json · flag

Embed the infojson as an attachment to mkv/mka video files

--no-embed-info-json · flag

Do not embed the infojson as an attachment to the video file

Metadata Parsing

--parse-metadata · string

Parse additional metadata like title/artist from other fields

Format: [WHEN:]FROM:TO

See “MODIFYING METADATA” for details. Supported values of “WHEN” are the same as that of --use-postprocessor (default: pre_process)

Example:

yt-dlp --parse-metadata "title:%(artist)s - %(title)s" URL

--replace-in-metadata · string

Replace text in a metadata field using the given regex

Format: [WHEN:]FIELDS REGEX REPLACE

This option can be used multiple times. Supported values of “WHEN” are the same as that of --use-postprocessor (default: pre_process)

Example:

yt-dlp --replace-in-metadata "title" "\\[.*?\\]" "" URL

--xattrs · flag

Write metadata to the video file’s xattrs (using Dublin Core and XDG standards)

Playlist Concatenation

--concat-playlist · string

Concatenate videos in a playlist

Values:

• never
• always
• multi_video (default) - Only when the videos form a single show

All the video files must have the same codecs and number of streams to be concatenable. The “pl_video:” prefix can be used with --paths and --output to set the output filename for the concatenated files.

See “OUTPUT TEMPLATE” for details

Fixup Policy

--fixup · string

Automatically correct known faults of the file

Values:

• never - Do nothing
• warn - Only emit a warning
• detect_or_warn (default) - Fix the file if we can, warn otherwise
• force - Try fixing even if the file already exists

FFmpeg Location

--ffmpeg-location · string

Location of the ffmpeg binary; either the path to the binary or its containing directory

Example:

yt-dlp --ffmpeg-location /usr/local/bin/ffmpeg URL
yt-dlp --ffmpeg-location /usr/local/bin URL

Execute Command

--exec · string

Execute a command, optionally prefixed with when to execute it

Format: [WHEN:]CMD

Supported values of “WHEN” are the same as that of --use-postprocessor (default: after_move)

The same syntax as the output template can be used to pass any field as arguments to the command. If no fields are passed, %(filepath,_filename|)q is appended to the end of the command.

This option can be used multiple times.

Example:

yt-dlp --exec "echo Downloaded: {}" URL
yt-dlp --exec after_video:"notify-send 'Download complete'" URL

--no-exec · flag

Remove any previously defined --exec

Format Conversion

--convert-subs · string

Convert the subtitles to another format

Currently supported: ass, lrc, srt, vtt

Use --convert-subs none to disable conversion (default)

Alias: --convert-subtitles

Example:

yt-dlp --convert-subs srt URL

--convert-thumbnails · string

Convert the thumbnails to another format

Currently supported: jpg, png, webp

You can specify multiple rules using similar syntax as --remux-video.

Use --convert-thumbnails none to disable conversion (default)

Example:

yt-dlp --convert-thumbnails jpg URL
yt-dlp --convert-thumbnails "webp>jpg/png" URL

Chapter Handling

--split-chapters · flag

Split video into multiple files based on internal chapters

The “chapter:” prefix can be used with --paths and --output to set the output filename for the split files.

See “OUTPUT TEMPLATE” for details

--no-split-chapters · flag · default: "true"

Do not split video based on chapters

--remove-chapters · string

Remove chapters whose title matches the given regular expression

The syntax is the same as --download-sections. This option can be used multiple times.

Example:

yt-dlp --remove-chapters "sponsor" URL

--no-remove-chapters · flag · default: "true"

Do not remove any chapters from the file

--force-keyframes-at-cuts · flag

Force keyframes at cuts when downloading/splitting/removing sections

This is slow due to needing a re-encode, but the resulting video may have fewer artifacts around the cuts

--no-force-keyframes-at-cuts · flag · default: "true"

Do not force keyframes around the chapters when cutting/splitting

Custom Postprocessors

--use-postprocessor · string

The (case-sensitive) name of plugin postprocessors to be enabled, and (optionally) arguments to be passed to it

Format: NAME[:ARGS]

ARGS are a semicolon ”;” delimited list of NAME=VALUE.

The “when” argument determines when the postprocessor is invoked. It can be one of:

• pre_process - After video extraction
• after_filter - After video passes filter
• video - After —format; before —print/—output
• before_dl - Before each video download
• post_process (default) - After each video download
• after_move - After moving the video file to its final location
• after_video - After downloading and processing all formats of a video
• playlist - At end of playlist

This option can be used multiple times to add different postprocessors.

Example:

yt-dlp --use-postprocessor "FFmpegMetadata:when=pre_process" URL