Skip to content

Subscriptions

Jump to bottom
Alex Shnitman edited this page Jul 17, 2026 · 1 revision

Subscriptions make MeTube periodically check a channel or playlist for new items and queue them automatically — set-and-forget downloading for feeds you follow.

Subscribing

  1. Paste a channel or playlist URL into the URL field (single-video URLs can't be subscribed).
  2. Set the download options in the form — type (video/audio), codec, quality, download folder, filename prefix, subtitles, option presets, and everything under Advanced Options — exactly as you would for a one-off download. These options are captured at subscribe time and applied to every video the subscription downloads.
  3. Click Subscribe (the split button next to Download).

Three Advanced Options apply specifically to subscriptions:

  • Subscription Check (min) — how often this subscription is polled for new videos.
  • Subscription Title Filter — a Python-style regex; only new videos whose titles match are queued. Empty means all. Case-sensitive; prefix the pattern with (?i) for case-insensitive matching.
  • Skip members-only subscription videos — skip videos that yt-dlp marks as subscriber/members-only, instead of queueing them and having them fail.

The existing backlog is not downloaded. When you subscribe, the videos already in the feed are marked as seen, and only videos published after that point are queued. To grab the backlog, download the playlist/channel URL as a regular download first, then subscribe.

Upcoming (scheduled) live streams are an exception: they are not marked as seen at subscribe time, and get queued once they go live.

How checking works

  • Each enabled subscription is checked on its own interval (default from SUBSCRIPTION_DEFAULT_CHECK_INTERVAL, 60 minutes). MeTube's scheduler wakes every minute and checks whatever is due; up to 4 subscriptions are checked concurrently.
  • A check fetches the newest SUBSCRIPTION_SCAN_PLAYLIST_END entries of the feed (default 50). Anything not yet seen — and passing the title filter and members-only check — is queued with the subscription's stored download options. If a channel can publish more than that between checks, raise the scan depth or lower the interval.
  • Option presets and per-subscription overrides also apply during the feed scan itself, so things like cookies or impersonation options configured via a preset work for the scan too, not just the downloads.
  • A failing check records the error on the subscription (shown in the table) without affecting other subscriptions, and is retried at the next interval.

Managing subscriptions

The Subscriptions table in the UI shows each subscription with its filter, last-check time, and any error. Per row you can:

  • Check now — trigger an immediate check (also available as Check All / Check Selected).
  • Pause/resume — a paused subscription keeps its state but stops checking.
  • Edit the title filter.
  • Delete the subscription.

The check interval, name, title filter, and members-only flag can be changed after creation. The download options (type, quality, folder, presets, …) are fixed at subscribe time — to change them, delete and re-subscribe (the re-subscribe marks the current feed as seen again, so nothing gets re-downloaded).

State and tuning

Subscription state lives in subscriptions.json under STATE_DIR. The relevant environment variables (see the README for the full reference):

Variable Default Meaning
SUBSCRIPTION_DEFAULT_CHECK_INTERVAL 60 Default minutes between checks for new subscriptions.
SUBSCRIPTION_SCAN_PLAYLIST_END 50 Newest feed entries fetched per check.
SUBSCRIPTION_MAX_SEEN_IDS 50000 Cap on remembered video IDs per subscription, to bound state file growth.

Clone this wiki locally