Download System

Download System

🌐 English · Deutsch

Flow

1. Episodes are added to the download queue via the UI (or by AutoSync / Seerr).
2. A single global worker processes the queue sequentially — one job (with any number of episodes) at a time.
3. For each episode the matching host extractor is invoked, the direct link resolved, and the stream saved as .mkv via yt-dlp/FFmpeg (audio/subtitle tracks are tagged correctly).
4. On completion: Notifications, optional Jellyfin/Plex library refresh, optional Anime4K upscaling.

Queue entry statuses

Status	Meaning
queued	Waiting for the worker
running	Currently downloading
completed	All episodes succeeded
partial	Partially successful — at least one episode ok, at least one failed
failed	All episodes failed
cancelled	Cancelled by the user

After a crash, running entries are automatically reset to queued on restart (crash recovery).

Error handling & watchdog

• 3 attempts per episode (2 s pause in between). If the requested language simply isn't available for an episode, a readable message is stored without further retries ("Not available in: …").
• Watchdog: Every episode download runs in a monitored thread. Hard timeout after 30 min (watchdog_hang_timeout), abort after 60 min without progress (watchdog_stall_timeout) — a hung yt-dlp can never block the queue permanently.
• Failed episodes are stored on the entry with URL + error text and shown in the UI.

Queue actions

Action	Description
Pause / Resume	Global pause; persisted in the DB and survives restarts. The current episode still finishes
Cancel	Aborts the running job (kills the active subprocess immediately)
Skip episode	Skips only the currently running episode without counting it as an error
Retry single episode	For partial/failed: retry just one failed episode
Restart	Re-queue the whole entry
Move	Reorder waiting entries
Clear completed	Remove all finished entries

Captcha solving in the WebUI

When an extractor hits a captcha page (e.g. Cloudflare Turnstile), the app launches an invisible Patchright Chromium with stealth measures and a built-in ad blocker. The captcha view is streamed into the WebUI as a live screenshot; clicks in the UI are forwarded to the browser. Admins can solve any captcha, regular users only those of their own downloads.

Storage location & file names

• Base: download path from the settings (default ~/Downloads) or a custom path per job.
• Language separation (optional): one subfolder per language — german-dub, english-sub, german-sub, english-dub, english-dub-german-sub.
• Naming template: by default {title} ({year}) [imdbid-{imdbid}]/Season {season}/{title} S{season}E{episode}.mkv (Configuration).

Disk space check

Before each job the worker checks free space at the target path. If it falls below the configured minimum (notif_disk_space_min_gb, default 5 GB, 0 = disabled), a warning is sent (max. once per hour) — the download still starts.

Statistics

Average speed (MB/s) and total size are recorded per job; aggregates are shown on the statistics page (/stats).