Add Subscriptions guide

Subscriptions.md

@@ -0,0 +1,45 @@
+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](https://github.com/alexta69/metube#%EF%B8%8F-configuration-via-environment-variables) 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. |