Here you can find various useful configurations that can be set via the YTDL_OPTIONS and YTDL_OPTIONS_FILE environment variables.
English subtitles & chapter marks, permissions, modification timestamp
Embeds English subtitles and chapter markers (for videos that have them), changes the permissions on the downloaded video, and sets the file modification timestamp to the date of when it was downloaded.
environment:
- 'YTDL_OPTIONS={"writesubtitles":true,"subtitleslangs":["en","-live_chat"],"updatetime":false,"postprocessors":[{"key":"Exec","exec_cmd":"chmod 0664","when":"after_move"},{"key":"FFmpegEmbedSubtitle","already_have_subtitle":false},{"key":"FFmpegMetadata","add_chapters":true}]}'
Embed metadata
Contributed by @PikuZheng.
NOTE: May cause errors for non-Youtube videos.
environment:
- 'YTDL_OPTIONS={ "ignoreerrors":true, "writethumbnail":true, "postprocessors":[ {"key":"FFmpegMetadata","add_metadata":true,"add_chapters":true,"add_infojson":"if_exists"}, {"key":"EmbedThumbnail"}]}'
Automatically marking MeTube downloads with SponsorBlock chapters
Contributed by @loomweaver.
Mimics the command yt-dlp --sponsorblock-mark sponsor,selfpromo,intro,outro,poi_highlight.
NOTE: due to the complex usage of quotes here (both " and ' are used), it's advisable to put it in a file and point YTDL_OPTIONS_FILE to it, rather than trying to configure it via YTDL_OPTIONS.
{"postprocessors": [{"api":"https://sponsor.ajay.app/","categories": ["intro",
"outro",
"poi_highlight",
"selfpromo",
"sponsor"],
"key": "SponsorBlock",
"when": "after_filter"},
{"force_keyframes":false,
"key": "ModifyChapters",
"remove_chapters_patterns": [],
"remove_ranges": [],
"remove_sponsor_segments": [],
"sponsorblock_chapter_title": "'[SponsorBlock]: ''%(category_names)l'"},
{"add_chapters": true,
"add_infojson": "none",
"add_metadata": false,
"key": "FFmpegMetadata"}]}
Notifications on download completion
The image includes curl, and yt-dlp's Exec postprocessor runs a command
after each successful download — enough for ntfy, Gotify, Pushover, Telegram,
webhooks, etc.:
YTDL_OPTIONS={"postprocessors":[{"key":"Exec","exec_cmd":"curl -s -d 'Downloaded: ' -d %(title)q https://ntfy.sh/YOUR_TOPIC","when":"after_move"}]}
exec_cmd supports the full yt-dlp output-template syntax (%(title)q,
%(filepath)q, ...). To make notifications opt-in per download instead of
global, define it as a named preset via YTDL_OPTIONS_PRESETS.
Note: postprocessors only run on success — there is currently no hook for failed downloads.
Using --parse-metadata (MetadataParser) from JSON
yt-dlp's --parse-metadata normally builds Python tuples that JSON can't
express. Use the MetadataFromField postprocessor instead — it takes plain
"FROM:TO" strings and behaves identically. For example, to clear the
description (the equivalent of --parse-metadata ":(?P<meta_description>)"):
YTDL_OPTIONS={"postprocessors":[{"key":"MetadataFromField","formats":[":(?P<meta_description>)"],"when":"pre_process"}]}
Each entry in formats is one FROM:TO expression, exactly as you would
write it on the yt-dlp command line.
Download video and extract audio in one go
keepvideo plus FFmpegExtractAudio gives you both the video file and an
audio file from a single download:
YTDL_OPTIONS={"keepvideo":true,"postprocessors":[{"key":"FFmpegExtractAudio","preferredcodec":"mp3"}]}
To convert the video container instead (e.g. everything as MKV):
YTDL_OPTIONS={"postprocessors":[{"key":"FFmpegVideoConvertor","preferedformat":"mkv"}]}
(Note: yt-dlp's option is really spelled preferedformat, with one r.)
Define these as named presets via YTDL_OPTIONS_PRESETS to pick them
per-download in the UI instead of applying them globally.