Skip to content

YTDL_OPTIONS Cookbook

Jump to bottom
Alex edited this page May 23, 2025 · 3 revisions

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":"set()",
                     "sponsorblock_chapter_title": "'[SponsorBlock]: ''%(category_names)l'"},
                    {"add_chapters": true,
                     "add_infojson": "none",
                     "add_metadata": false,
                     "key": "FFmpegMetadata"}]}
Clone this wiki locally