Skip to main content

​
Overview

yt-dlp can extract, parse, modify, and embed metadata in your downloaded files. This is useful for organizing media libraries, fixing incorrect information, or adding custom metadata fields.

​
Understanding Metadata Flow

Metadata modification happens in this order:
  1. Extraction: Metadata obtained from the website
  2. Parsing: Custom parsing with --parse-metadata
  3. Replacement: Text replacement with --replace-in-metadata
  4. Format selection: Uses modified metadata
  5. Post-processing: Embedding metadata in files
  6. Final output: File with embedded metadata
Metadata modification happens before format selection and post-processing. Some fields may be added or changed during these steps, potentially overriding your changes.

​
Parsing Metadata

​
Basic syntax

The --parse-metadata FROM:TO option extracts data from one field and creates or modifies another: 
# Basic syntax
yt-dlp --parse-metadata "FROM:TO" URL

​
Extract from title

# Parse "Artist - Title" from title field
yt-dlp --parse-metadata "title:%(artist)s - %(title)s" URL

​
Extract from description

1

Simple pattern matching

# Extract artist from description
yt-dlp --parse-metadata "description:Artist - (?P<artist>.+)" URL
2

Multi-line matching

# Match across multiple lines with (?s) flag
yt-dlp --parse-metadata "description:(?s)(?P<meta_comment>.+)" URL
3

Extract URLs

# Extract additional URLs from description
yt-dlp --parse-metadata "description:(?P<additional_urls>https?://www\.vimeo\.com/\d+)" URL

​
Modifying File Metadata

Use the meta_ prefix to set metadata that will be embedded in the file:

​
Common metadata fields

# Prioritize uploader as artist field
yt-dlp --parse-metadata "%(uploader|)s:%(meta_artist)s" \
  --embed-metadata URL

​
Default Metadata Mappings

yt-dlp automatically maps these fields to file metadata:
Metadata FieldSource Fields
titletrack or title
dateupload_date
description, synopsisdescription
purl, commentwebpage_url
tracktrack_number
artistartist, artists, creator, creators, uploader, uploader_id
composercomposer or composers
genregenre, genres, categories, tags
albumalbum or series
album_artistalbum_artist or album_artists
discdisc_number
showseries
season_numberseason_number
episode_idepisode or episode_id
episode_sortepisode_number
languageformat’s language
You can override any of these defaults using --parse-metadata with the meta_ prefix.

​
Replacing Text in Metadata

Use --replace-in-metadata to find and replace text: 
# Replace spaces and underscores with dashes
yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-" URL

​
Removing Metadata Fields

Set fields to empty to remove them: 
# Don't set synopsis in metadata
yt-dlp --parse-metadata ":(?P<meta_synopsis>)" URL

​
Advanced Metadata Examples

​
Music downloads

# Complete music metadata from playlist
yt-dlp -x --audio-format mp3 \
  --parse-metadata "%(playlist_title|)s:%(meta_album)s" \
  --parse-metadata "%(uploader|)s:%(meta_artist)s" \
  --parse-metadata "%(playlist_index|)s:%(meta_track)s" \
  --parse-metadata "title:%(artist)s - %(title)s" \
  --embed-metadata \
  --embed-thumbnail \
  -o "%(artist)s/%(album)s/%(track)s - %(title)s.%(ext)s" \
  PLAYLIST_URL

​
TV series episodes

# Parse and format TV series metadata
yt-dlp \
  --parse-metadata "title:%(series)s - (?P<season_number>\d+)x(?P<episode_number>\d+)" \
  --parse-metadata "%(series)s S%(season_number)02dE%(episode_number)02d:%(title)s" \
  -o "%(series)s/Season %(season_number)s/%(title)s.%(ext)s" \
  URL

​
Podcast episodes

# Set podcast metadata
yt-dlp -x --audio-format mp3 \
  --parse-metadata "%(uploader|)s:%(meta_album)s" \
  --parse-metadata "%(upload_date>%Y-%m-%d)s:%(meta_date)s" \
  --parse-metadata "%(description|)s:%(meta_comment)s" \
  --embed-metadata \
  --embed-thumbnail \
  -o "Podcasts/%(uploader)s/%(upload_date)s - %(title)s.%(ext)s" \
  URL

​
Clean YouTube titles

# Remove common YouTube title decorations
yt-dlp \
  --replace-in-metadata "title" " ?\[?Official Music Video\]?" "" \
  --replace-in-metadata "title" " ?\(?Official Audio\)?" "" \
  --replace-in-metadata "title" " ?\[?HD\]?" "" \
  --replace-in-metadata "title" " ?\[?4K\]?" "" \
  --parse-metadata "title:%(artist)s - %(title)s" \
  URL

​
Metadata for Different Streams

Set metadata for individual streams using meta<n>_ prefix: 
# Set language for stream 1
yt-dlp --parse-metadata ":%(meta1_language)s" URL

# Set different metadata for audio stream
yt-dlp --parse-metadata "en:%(meta1_language)s" URL

​
Copy Metadata Between Fields

# Copy episode to title
yt-dlp --parse-metadata "episode:title" URL

​
Timing and Execution

Control when metadata parsing happens: 
# Pre-process (default): before format selection
yt-dlp --parse-metadata "pre_process:title:%(meta_title)s" URL

# Video: after format selection
yt-dlp --parse-metadata "video:title:%(meta_title)s" URL

# Post-process: after download
yt-dlp --parse-metadata "post_process:title:%(meta_title)s" URL

​
Embedding Metadata

After parsing and modifying metadata, embed it in the file:
1

Enable metadata embedding

yt-dlp --embed-metadata URL
This also embeds chapters and infojson (in MKV) unless disabled.
2

Control what gets embedded

# Embed metadata and thumbnail
yt-dlp --embed-metadata --embed-thumbnail URL

# Include subtitles
yt-dlp --embed-metadata --embed-subs URL

# Don't embed chapters
yt-dlp --embed-metadata --no-embed-chapters URL
3

Verify embedded metadata

# Check metadata with ffprobe
ffprobe -hide_banner video.mp4

​
Regular Expression Tips

​
Common patterns

# Named capture groups
(?P<name>pattern)

# Non-greedy match (minimal)
.+?

# Multi-line mode
(?s)pattern

# Case-insensitive
(?i)pattern

# Word boundary
\b

# Digits
\d+

# Optional whitespace
\s*

​
Example patterns

"title:(?P<artist>[^-]+) - (?P<title>.+)"

​
Troubleshooting

​
Metadata not embedding

# Ensure embed-metadata is enabled
yt-dlp --embed-metadata --verbose URL

# Check if format supports metadata
# MP4, M4A, MKV support most metadata
yt-dlp --merge-output-format mp4 --embed-metadata URL

# Install mutagen for better support
pip install mutagen

​
Regex not matching

# Test with --print to see field contents
yt-dlp --print "title:%(title)s" URL
yt-dlp --print "description:%(description)s" URL

# Use verbose to see parsed metadata
yt-dlp --parse-metadata "title:pattern" --verbose URL

​
Wrong metadata in file

Metadata might be overwritten during post-processing. Use meta_ prefix to ensure your values are used.
# Force specific values with meta_ prefix
yt-dlp --parse-metadata "MY VALUE:%(meta_artist)s" \
  --embed-metadata URL

​
Next Steps

Output Templates

Use metadata in filename templates

Post-Processing

Learn about post-processing options

Audio Extraction

Embed metadata in audio files

Format Selection

Use metadata in format selection

Build docs developers (and LLMs) love

Get started for freeTalk to us