e06c2ef826
An mdBook under docs/ rendering eight pages: introduction, installation, first-run/config, downloading, an anti-bot guide that captures the hard-won cookies/curl_cffi/POT/player-client knowledge, troubleshooting (the nine error classes + non-download issues), architecture (the two-front-ends/one-engine design, settings flow, layout invariant, persistence), and packaging. - .forgejo/workflows/docs.yml builds the book and publishes docs/book/ to the `pages` branch for Codeberg Pages on docs/ changes. - docs/book/ is gitignored (rendered output). - README: fix the stale backup.directory comment — every platform nests under the one library root, not a channels/ sibling split. - Add CLAUDE.md (repo guidance for Claude Code). Builds clean with mdbook 0.5; intra-doc anchor links verified. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2.9 KiB
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.