yt dlp options

MeTube lets you customize how yt-dlp behaves at three levels, from broadest to most specific:

1. Global options — apply to every download by default.
2. Presets — named bundles of options that users can pick per download from the UI.
3. Per-download overrides — free-form options entered in the UI for a single download.

When a download starts, these layers are combined in order. If the same option appears in more than one layer, the more specific one wins: per-download overrides beat presets, and presets beat global options.

In JSON presets and overrides, setting an option to null clears that option for that download (for example, "download_archive": null overrides a global archive path so the archive is not used). This follows yt-dlp's usual meaning of None for that option.

For ready-made configurations, see the YTDL_OPTIONS Cookbook.

Option format

yt-dlp options in MeTube are expressed as JSON objects. The keys are yt-dlp API option names, which roughly correspond to command-line flags with dashes replaced by underscores. For example, the command-line flag --write-subs becomes "writesubtitles": true in JSON.

Some command-line flags don't have a direct single-key equivalent — for instance, --embed-thumbnail and --recode-video must be expressed via "postprocessors". A full list of available API options can be found in the yt-dlp source, and this conversion script can help translate command-line flags to their API equivalents — but read Converting a yt-dlp command line into JSON before pasting its output in, and What MeTube already sets for you for the options MeTube manages itself.

Global options

Global options form the baseline for every download. There are two ways to define them, and you can use either or both:

Inline via environment variable (YTDL_OPTIONS) — pass a JSON object directly:

environment:
  - 'YTDL_OPTIONS={"writesubtitles": true, "subtitleslangs": ["en", "de"], "updatetime": false, "writethumbnail": true}'

Via a JSON file (YTDL_OPTIONS_FILE) — mount a file into the container and point to it:

volumes:
  - /path/to/ytdl-options.json:/config/ytdl-options.json
environment:
  - YTDL_OPTIONS_FILE=/config/ytdl-options.json

where ytdl-options.json contains:

{
  "writesubtitles": true,
  "subtitleslangs": ["en", "de"],
  "updatetime": false,
  "writethumbnail": true
}

The file is monitored for changes and reloaded automatically — no container restart needed. If you use both methods and they define the same key, the file takes precedence.

Presets

Presets are named bundles of options that appear in the web UI under Advanced Options as "Option Presets". Users can select one or more per download, without editing global settings.

Like global options, presets can be set inline or via a file:

• YTDL_OPTIONS_PRESETS — a JSON object where each key is a preset name and its value is a set of yt-dlp options.
• YTDL_OPTIONS_PRESETS_FILE — path to a JSON file containing presets, monitored and reloaded on changes.

If both are used and they define a preset with the same name, the file's version takes precedence.

Example — a presets file defining three presets:

{
  "embed-subs": {
    "writesubtitles": true,
    "writeautomaticsub": true,
    "subtitleslangs": ["en", "de"],
    "postprocessors": [{ "key": "FFmpegEmbedSubtitle" }]
  },
  "limit-rate": {
    "ratelimit": 5000000
  },
  "via-proxy": {
    "proxy": "socks5://192.168.1.10:1080"
  }
}

This makes three presets available in the UI:

• embed-subs — downloads English and German subtitles and embeds them into the video file.
• limit-rate — caps download speed to ~5 MB/s.
• via-proxy — routes that download through a SOCKS proxy, e.g. for a video that's blocked in your country.

When multiple presets are selected for a download, they are applied in order. If two presets set the same option, the later one wins.

Presets also apply when a subscription scans its feed, not just to the downloads it queues.

Per-download overrides

For one-off tweaks, MeTube can expose a free-text JSON field in the UI ("Custom yt-dlp Options") where users type yt-dlp options that apply only to that single download. This is disabled by default:

environment:
  - ALLOW_YTDL_OPTIONS_OVERRIDES=true

Once enabled, the field appears under Advanced Options. Any options entered there take the highest priority, overriding both global options and selected presets.

⚠️ Security note: Enabling this allows arbitrary yt-dlp API options to be supplied by anyone with access to the UI. Depending on the options used, this may enable arbitrary command execution inside the container. Enable only in trusted environments.

How the layers combine

When a download starts, the final set of yt-dlp options is built in this order:

1. Start with global options (YTDL_OPTIONS / YTDL_OPTIONS_FILE).
2. Apply each selected preset in order (later presets overwrite earlier ones for conflicting keys).
3. Apply any per-download overrides on top (overwrite everything else for conflicting keys).

MeTube always forces its own flat-extract behaviour during the initial metadata fetch (extract_flat, noplaylist, etc.); presets cannot override those keys for that phase.

Example: Suppose your global options set "writesubtitles": false, but you select a preset that sets "writesubtitles": true. Subtitles will be written for that download because the preset overrides the global setting. If you additionally enter {"writesubtitles": false} in the per-download overrides field, that value wins and subtitles will not be written.