Downloading

Starting a download

Paste any supported URL into the download bar (desktop) or the ⬇ Downloads modal (web). yt-offline classifies the URL by platform, routes it to the right folder, and starts yt-dlp. A channel/playlist URL pulls the whole thing; a single-video URL pulls just that one.

Quality picker: Best / 1080p / 720p / 480p / 360p, or Music mode for audio-only extraction into music/<artist>/.

Fast mode stops at the first already-downloaded video (quick routine re-checks). Turn it off for a full gap-filling scan.

Per-channel options

Right-click a channel (or use the ⚙ on its sidebar row) for overrides that apply to scheduled re-checks and the “Check for new videos” action:

• Quality cap, audio-only, bandwidth cap, min/max file size, date cutoff.
• A free-form --match-filter (e.g. duration > 60 & view_count > 100).
• Subtitle overrides, YouTube player-client override, post-download convert mode — each defaulting to the global setting.
• Skip auth check — silences yt-dlp’s “playlists that require authentication” warning for public channels (see Troubleshooting).

Per-channel options ride along in library backup/restore.

Subtitles

Global defaults (Settings → Subtitles) + per-channel overrides control: download on/off, auto-generated captions, embedding into the container, language filter, and format conversion (srt is the most Plex/player-compatible). Subtitles are written as sidecar files and optionally embedded.

Format conversion

A post-download ffmpeg pass (Settings → Format conversion, or per channel):

• Remux → mp4 — instant container change, no re-encode (device/Plex compatibility).
• Re-encode → H.264 mp4 — shrink large 4K files at a chosen CRF + x264 preset.
• Extract audio — mp3 / m4a / opus / flac.

It runs as a distinct transcode job after the download. Keep original preserves <name>.original.<ext> alongside the converted file; otherwise the source is removed once the convert succeeds.

Resilience

Downloads are hardened against YouTube’s flakiness automatically:

• Retry + backoff on connection resets (--retries 30, linear retry-sleep).
• Jittered throttle between videos so a long channel scan doesn’t look robotic and trip the captcha wall.
• Auto-retry of transient (rate-limit / network / captcha) failures after a cooldown, with adaptive slow-down for the rest of the batch.
• Hang watchdog kills a job that produces no output for 5 minutes (a wedged request) and re-queues it.

Failures are classified and shown with a one-line suggested fix — see Troubleshooting.

Scheduler

Enable it (Settings → Auto-check channels) to re-check every channel for new uploads on an interval. Each channel uses its own stored options. There’s also a per-folder “Check all” action.