Skip to main content

​
Overview

Post-processing in yt-dlp allows you to automatically manipulate downloaded files through various operations like format conversion, metadata embedding, subtitle processing, and custom commands.

​
Post-Processing Pipeline

Post-processors run in this order:
  1. Pre-process: After video extraction, before format selection
  2. After filter: After video passes filters
  3. Video: After format selection, before download
  4. Before download: Before each video download
  5. Post-process: After each video download (default)
  6. After move: After moving to final location
  7. After video: After processing all formats of a video
  8. Playlist: At end of playlist

​
Audio Extraction

Convert videos to audio-only files: 
# Extract audio in best format
yt-dlp -x URL

# Extract as MP3
yt-dlp -x --audio-format mp3 URL
See the Audio Extraction guide for detailed examples.

​
Format Conversion

​
Remuxing

Change container without re-encoding: 
# Remux to MP4 if necessary
yt-dlp --remux-video mp4 URL

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

​
Re-encoding

Re-encoding reduces quality and takes longer. Use only when necessary.
# Re-encode to MP4
yt-dlp --recode-video mp4 URL

# Conditional re-encoding
yt-dlp --recode-video "avi>mp4/flv>mp4/mp4" URL

​
Metadata Operations

​
Embedding metadata

1

Basic metadata

yt-dlp --embed-metadata URL
Embeds video metadata and chapters (in MKV, also embeds infojson).
2

Additional metadata

# Embed thumbnail as cover art
yt-dlp --embed-thumbnail URL

# Embed subtitles
yt-dlp --embed-subs URL

# Embed chapters
yt-dlp --embed-chapters URL
3

Complete embedding

# Embed everything
yt-dlp --embed-metadata \
  --embed-thumbnail \
  --embed-subs \
  --embed-chapters \
  URL

​
Modifying metadata

# Parse metadata from fields
yt-dlp --parse-metadata "title:%(artist)s - %(title)s" \
  --embed-metadata URL

# Replace text in metadata
yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-" URL
See the Metadata Modification guide for detailed examples.

​
Subtitle Processing

​
Download and convert

# Download available subtitles
yt-dlp --write-subs URL

# Download auto-generated subtitles
yt-dlp --write-auto-subs URL

# All subtitles
yt-dlp --write-subs --write-auto-subs URL

​
Thumbnail Processing

# Download thumbnail
yt-dlp --write-thumbnail URL

# Convert to JPG
yt-dlp --write-thumbnail --convert-thumbnails jpg URL

# Embed in media file
yt-dlp --embed-thumbnail URL

# All thumbnail formats
yt-dlp --write-all-thumbnails URL

​
Chapter Operations

​
Splitting by chapters

# Split video into chapter files
yt-dlp --split-chapters URL

# With custom output template for chapters
yt-dlp --split-chapters \
  -o "chapter:%(title)s - %(section_number)s %(section_title)s.%(ext)s" \
  URL

​
Removing chapters

# Remove chapters matching regex
yt-dlp --remove-chapters "Intro" URL

# Remove multiple patterns
yt-dlp --remove-chapters "Intro" \
  --remove-chapters "Outro" \
  URL

# Remove sponsor segments (with SponsorBlock)
yt-dlp --sponsorblock-remove sponsor URL

​
Modifying chapters

# Force keyframes at chapter boundaries
yt-dlp --split-chapters \
  --force-keyframes-at-cuts \
  URL

​
SponsorBlock Integration

Remove or mark sponsor segments in YouTube videos: 
# Create chapters for sponsor segments
yt-dlp --sponsorblock-mark all URL

# Mark specific categories
yt-dlp --sponsorblock-mark sponsor,selfpromo URL

# Exclude categories
yt-dlp --sponsorblock-mark all,-filler URL
See the SponsorBlock guide for detailed usage.

​
File Fixup

Automatically fix common file issues: 
# Auto-detect and fix (default)
yt-dlp --fixup detect_or_warn URL

# Force fixing even if file exists
yt-dlp --fixup force URL

# Never fix
yt-dlp --fixup never URL

# Only warn about issues
yt-dlp --fixup warn URL

​
Custom Post-Processors

​
Execute commands

# Run command after each download
yt-dlp --exec "echo Downloaded: {}" URL

# Move to folder
yt-dlp --exec "mv {} /path/to/folder/" URL

​
Post-Processor Arguments

Pass custom arguments to ffmpeg and other post-processors: 
# Arguments to ffmpeg
yt-dlp --ppa "ffmpeg:-c:v libx264 -preset slow" URL

# Audio normalization
yt-dlp --ppa "ffmpeg:-af loudnorm" URL

​
Concatenating Playlists

Merge playlist videos into single file: 
# Concatenate multi-part videos (default)
yt-dlp --concat-playlist multi_video URL

# Always concatenate
yt-dlp --concat-playlist always URL

# Never concatenate
yt-dlp --concat-playlist never URL

# Custom output for concatenated file
yt-dlp --concat-playlist always \
  -o "pl_video:%(playlist)s.%(ext)s" \
  URL
All videos must have the same codecs and number of streams to be concatenable.

​
Plugin Post-Processors

Use custom post-processor plugins: 
# Enable plugin post-processor
yt-dlp --use-postprocessor NAME URL

# With arguments
yt-dlp --use-postprocessor NAME:arg1=value;arg2=value URL

# Execute at specific time
yt-dlp --use-postprocessor NAME:when=after_move URL

​
Advanced Workflows

​
Music downloads

yt-dlp -x --audio-format mp3 --audio-quality 0 \
  --embed-metadata \
  --embed-thumbnail \
  --parse-metadata "%(uploader|)s:%(meta_artist)s" \
  --parse-metadata "%(playlist_title|)s:%(meta_album)s" \
  -o "%(artist)s/%(album)s/%(title)s.%(ext)s" \
  PLAYLIST_URL

​
Archival with metadata

yt-dlp -f "bv*+ba" \
  --embed-metadata \
  --embed-thumbnail \
  --embed-subs \
  --write-description \
  --write-info-json \
  --write-comments \
  --sponsorblock-remove all \
  URL

​
Format for devices

# Apple devices
yt-dlp --merge-output-format mp4 \
  --remux-video mp4 \
  --embed-metadata \
  --embed-subs \
  -S "vcodec:h264,acodec:aac" \
  URL

​
Stream processing

# Download, process, and stream
yt-dlp -o - URL | ffmpeg -i pipe:0 -f matroska - | mpv -

​
Overwrite Behavior

# Don't overwrite files (default for video)
yt-dlp --no-overwrites URL

# Overwrite all files
yt-dlp --force-overwrites URL

# Overwrite post-processed files (default)
yt-dlp --post-overwrites URL

# Don't overwrite post-processed files
yt-dlp --no-post-overwrites URL

​
Keeping Intermediate Files

# Keep video file after audio extraction
yt-dlp -x --keep-video URL

# Keep downloaded fragments
yt-dlp --keep-fragments URL

​
Troubleshooting

​
Post-processing fails

# Check ffmpeg installation
ffmpeg -version

# Specify ffmpeg location
yt-dlp --ffmpeg-location /path/to/ffmpeg URL

# View detailed error messages
yt-dlp --verbose URL

​
Metadata not embedding

# Install required libraries
pip install mutagen  # For better metadata support

# Use compatible format
yt-dlp --merge-output-format mp4 --embed-metadata URL

​
Thumbnail not embedding

# Convert thumbnail format
yt-dlp --embed-thumbnail --convert-thumbnails jpg URL

# Use AtomicParsley for MP4 (if mutagen fails)
yt-dlp --embed-thumbnail \
  --compat-options embed-thumbnail-atomicparsley \
  URL

​
Next Steps

Audio Extraction

Detailed audio extraction guide

Format Conversion

Converting between formats

Metadata Modification

Parse and modify metadata

SponsorBlock

Remove sponsor segments