Skip to main content

Subtitle Basics

yt-dlp provides extensive support for downloading, processing, and embedding subtitles from various video sources. This guide covers all subtitle-related features and options.

Basic Subtitle Operations​

Download Subtitles​

# Download available subtitles
yt-dlp --write-subs "https://example.com/video"

# Download auto-generated subtitles
yt-dlp --write-auto-subs "https://example.com/video"

# Download both manual and auto-generated
yt-dlp --write-subs --write-auto-subs "https://example.com/video"

List Available Subtitles​

# Show all available subtitle languages
yt-dlp --list-subs "https://example.com/video"

Language Selection​

Specific Languages​

# Download specific language
yt-dlp --write-subs --sub-langs en "https://example.com/video"

# Download multiple languages
yt-dlp --write-subs --sub-langs en,es,fr "https://example.com/video"

# Download all available languages
yt-dlp --write-subs --sub-langs all "https://example.com/video"

Language Patterns​

# Use regex patterns for languages
yt-dlp --write-subs --sub-langs "en.*" "https://example.com/video"

# Exclude specific languages
yt-dlp --write-subs --sub-langs "all,-live_chat" "https://example.com/video"

# Exclude auto-generated
yt-dlp --write-subs --sub-langs "all,-.*auto.*" "https://example.com/video"

Subtitle Formats​

Format Selection​

# Prefer SRT format
yt-dlp --write-subs --sub-format srt "https://example.com/video"

# Multiple format preferences
yt-dlp --write-subs --sub-format "srt/ass/vtt/best" "https://example.com/video"

# Best available format
yt-dlp --write-subs --sub-format best "https://example.com/video"

Supported Formats​

  • SRT: SubRip Text format (most compatible)
  • ASS: Advanced SubStation Alpha (styled subtitles)
  • VTT: WebVTT format (web-optimized)
  • TTML: Timed Text Markup Language
  • JSON: Raw subtitle data

Embedding Subtitles​

Embed in Video File​

# Embed subtitles in video
yt-dlp --embed-subs "https://example.com/video"

# Embed specific languages
yt-dlp --embed-subs --sub-langs en,es "https://example.com/video"

# Write and embed subtitles
yt-dlp --write-subs --embed-subs "https://example.com/video"

Container Compatibility​

# Embed in MP4 (limited format support)
yt-dlp --embed-subs --merge-output-format mp4 "https://example.com/video"

# Embed in MKV (supports all subtitle formats)
yt-dlp --embed-subs --merge-output-format mkv "https://example.com/video"

# Embed in WebM
yt-dlp --embed-subs --merge-output-format webm "https://example.com/video"

Live Chat and Comments​

YouTube Live Chat​

# Download live chat as subtitles
yt-dlp --write-subs --sub-langs live_chat "https://youtube.com/watch?v=VIDEO_ID"

# Exclude live chat from all subtitles
yt-dlp --write-subs --sub-langs "all,-live_chat" "https://youtube.com/watch?v=VIDEO_ID"

Comments as Subtitles​

# Write comments to infojson
yt-dlp --write-comments "https://example.com/video"

# Get comments even for quick extraction
yt-dlp --get-comments "https://example.com/video"

Subtitle Processing​

Format Conversion​

# Convert subtitles to different format
yt-dlp --write-subs --convert-subs srt "https://example.com/video"

# Convert to ASS for styling
yt-dlp --write-subs --convert-subs ass "https://example.com/video"

# Convert to VTT for web use
yt-dlp --write-subs --convert-subs vtt "https://example.com/video"

Subtitle Organization​

# Custom subtitle output template
yt-dlp --write-subs \
  -o "%(title)s.%(ext)s" \
  -o "subtitle:%(title)s.%(lang)s.%(ext)s" \
  "https://example.com/video"

# Organize by language
yt-dlp --write-subs \
  -o "subtitle:subs/%(lang)s/%(title)s.%(ext)s" \
  "https://example.com/video"

Advanced Subtitle Features​

Platform-Specific Features​

# YouTube with auto-translation
yt-dlp --write-auto-subs --sub-langs "en.*" "https://youtube.com/watch?v=VIDEO_ID"

# Twitch chat replay
yt-dlp --write-subs --sub-langs "rechat" "https://twitch.tv/videos/VIDEO_ID"

Subtitle Extraction from Manifests​

# Extract from HLS manifests
yt-dlp --write-subs "https://example.com/video.m3u8"

# Extract from DASH manifests
yt-dlp --write-subs "https://example.com/video.mpd"

Batch Subtitle Operations​

Playlist Subtitles​

# Download subtitles for entire playlist
yt-dlp --write-subs --sub-langs en \
  -o "%(playlist)s/%(title)s.%(ext)s" \
  "https://youtube.com/playlist?list=PLAYLIST_ID"

# Organize subtitles separately
yt-dlp --write-subs \
  -o "videos/%(title)s.%(ext)s" \
  -o "subtitle:subs/%(title)s.%(lang)s.%(ext)s" \
  "https://youtube.com/playlist?list=PLAYLIST_ID"

Subtitle Metadata​

Language Information​

# Include language metadata
yt-dlp --write-info-json --write-subs "https://example.com/video"

Custom Subtitle Processing​

# Post-process subtitles with custom script
yt-dlp --write-subs \
  --exec "after_move:python process_subs.py %(filepath)q" \
  "https://example.com/video"

Troubleshooting Subtitles​

Common Issues​

  • No subtitles available: Check with --list-subs
  • Format not supported: Try different --sub-format
  • Embedding fails: Check container format compatibility
  • Live chat too large: Filter or limit languages

Debug Subtitle Issues​

# Verbose subtitle information
yt-dlp --write-subs --verbose "https://example.com/video"

# Check available formats
yt-dlp --list-subs --list-formats "https://example.com/video"

Subtitle Configuration​

Configuration File Example​

# ~/.config/yt-dlp/config
--write-subs
--sub-langs en,es
--sub-format srt
--convert-subs srt

Conditional Subtitle Download​

# Only download if subtitles exist
yt-dlp --write-subs --ignore-no-formats-error "https://example.com/video"