luna/catacomb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rename yt-offline → Catacomb across README, ROADMAP, guides, packaging

Browse source 
Prose + commands updated to the new name: brand reads "Catacomb", while
binary/path/package references are the lowercase `catacomb` (commands, deb/rpm
names, ~/.local/share/catacomb, catacomb.db, catacomb.desktop). Codeberg repo
URLs left pointing at the existing repo. Also folds in the pending doc edits
from earlier in the session.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Luna 2026-06-19 03:34:18 -07:00
parent 404362bfb0
commit 3f611849af
72 changed files with 1513 additions and 293 deletions
Download patch file Download diff file Expand all files Collapse all files

18
docs/src/anti-bot.md
View file

@ -1,7 +1,7 @@
# Staying ahead of YouTube's bot detection
YouTube increasingly fingerprints and rate-limits automated clients.
yt-offline ships a layered defense; understanding the layers makes the
catacomb ships a layered defense; understanding the layers makes the
difference between "everything downloads" and "constant captchas."
In rough order of impact:
@ -10,13 +10,13 @@ In rough order of impact:
This is the single biggest factor. **Anonymous requests get captcha-
walled the hardest.** Provide a `cookies.txt` exported from a browser
where you are **signed in to YouTube**, or point yt-offline at the
where you are **signed in to YouTube**, or point catacomb at the
browser profile directly.
A *valid* logged-in jar contains the auth cookies `SID`, `SAPISID`,
`__Secure-1PSID`, `__Secure-3PSID`, `LOGIN_INFO`, etc. A jar with only
`VISITOR_INFO1_LIVE`, `PREF`, `YSC` is **anonymous** — it's not signed in
and actually makes detection *worse* than no cookies. yt-offline's
and actually makes detection *worse* than no cookies. catacomb's
Settings → Cookies panel warns you when your jar is anonymous or expired.
Two ways to supply cookies:
@ -37,7 +37,7 @@ Two ways to supply cookies:
subdirectory itself). The advantage: cookies are read fresh from the
live session each download, so they never go stale.
> Cookies are session credentials — yt-offline never commits or transmits
> Cookies are session credentials — catacomb never commits or transmits
> `cookies.txt` unprompted, and redacts the cookie path out of any log
> line shown in the UI.
@ -45,7 +45,7 @@ Two ways to supply cookies:
yt-dlp's `--impersonate` makes requests carry a real browser's TLS
fingerprint (via `curl_cffi`), so the connection doesn't *look* like a
script. The bundled install sets this up automatically and yt-offline
script. The bundled install sets this up automatically and catacomb
picks an impersonation target per platform.
If impersonation silently does nothing, it's almost always a
@ -58,7 +58,7 @@ is present). See
## 3. POT tokens (Proof-of-Origin)
YouTube increasingly binds a per-video **Proof-of-Origin token** to
playback; without one, format URLs come back empty. yt-offline can run
playback; without one, format URLs come back empty. catacomb can run
[bgutil-pot](https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs), a
loopback HTTP server that mints these tokens, and point yt-dlp at it.
@ -68,14 +68,14 @@ yt-dlp; the matching plugin installs into its venv) and click **Install**.
> **Version-skew footgun:** the yt-dlp plugin must come from the *same
> release* as the bgutil-pot server binary — **not** the PyPI package,
> which versions independently and silently produces no tokens on a
> mismatch. yt-offline's installer handles this by unpacking the
> mismatch. catacomb's installer handles this by unpacking the
> version-matched plugin zip from the server's release.
## 4. Player-client selection
YouTube cracks down on different internal "player clients" over time —
the `web` client is currently the most captcha-prone, while `tv` and
`mweb` are the least. yt-offline no longer forces `web`; it lets yt-dlp
`mweb` are the least. catacomb no longer forces `web`; it lets yt-dlp
pick good defaults. If a specific channel keeps hitting captchas, set a
client override (global or per-channel):
@ -85,7 +85,7 @@ tv,mweb
## 5. Throttling
A burst of ~30 rapid requests is a classic trip-wire. yt-offline inserts
A burst of ~30 rapid requests is a classic trip-wire. catacomb inserts
a small jittered pause between videos (a fixed cadence looks robotic; a
random one looks human) and, after any rate-limit hit, triples the
sleeps for the rest of the batch before recovering.