80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# ytdy — the YouTube provider
|
||
|
||
Mounts YouTube at **`/youtube`** in the crabidy library.
|
||
|
||
## How it works
|
||
|
||
Metadata comes from the pure-Rust [rustypipe] Innertube client:
|
||
|
||
- **`/youtube/search`** works without any login. Press `%` to create a
|
||
search term; the term becomes a persistent child node listing the top
|
||
video results as tracks. Terms are renamable (`e`, re-runs the
|
||
search) and deletable (`d`). Terms live in memory — a server restart
|
||
forgets them, but navigating to an old term path recreates it.
|
||
- **`/youtube/playlists`** appears when a cookie login is configured
|
||
and accepted: it lists the account's saved playlists.
|
||
|
||
**Stream URLs** are resolved through a minimal `yt-dlp` sidecar when
|
||
the binary is available (one bounded subprocess call per played or
|
||
captured track — no other functionality uses it). This is a deliberate
|
||
concession: YouTube currently caps tokenless stream URLs at their
|
||
leading ~1 MiB, and `yt-dlp` is the only maintained solver for the
|
||
cipher challenges that lift the cap; its URLs stream whole files at a
|
||
throttled ~32 KB/s (still ~2× audio bitrate). Without the binary the
|
||
provider still works, but playback of a track stops after roughly a
|
||
minute. Streams prefer `audio/mp4` (AAC), the format the built-in
|
||
player decodes; captures therefore store `.m4a` files. See
|
||
`architecture/youtube-rustypipe.md` for the full analysis.
|
||
|
||
Search results and playlists are downloadable: `W` captures them with
|
||
audio into `/captures/<name>` (slow under the throttle, but captures
|
||
are resumable — re-capture the same name to continue).
|
||
|
||
## Configuration — `~/.config/crabidy/ytdy.toml`
|
||
|
||
All options with their defaults:
|
||
|
||
```toml
|
||
# Netscape cookies.txt export for the logged-in features (saved
|
||
# playlists). Export with a browser extension like "Get cookies.txt
|
||
# LOCALLY", ideally from an Incognito session you close afterwards.
|
||
# The provider caches the rotated session cookie under
|
||
# ~/.config/crabidy/rustypipe/, so the export only needs to be valid
|
||
# once. Default: unset (logged out; search still works).
|
||
# cookies = "/home/me/youtube-cookies.txt"
|
||
|
||
# Results per search term. Default: 20.
|
||
# search_results = 20
|
||
|
||
# Per-request timeout in seconds (Innertube calls; the yt-dlp sidecar
|
||
# gets at least 60 s). Default: 30.
|
||
# call_timeout_secs = 30
|
||
|
||
# The yt-dlp binary used ONLY for stream URLs. A bare name resolves
|
||
# via PATH. Default: "yt-dlp". Keep it fresh — a stale yt-dlp is the
|
||
# first suspect when YouTube playback breaks.
|
||
# binary = "yt-dlp"
|
||
|
||
# Optional rustypipe-botguard binary for PO-token attestation (also
|
||
# auto-detected on PATH). Currently ineffective upstream, but once
|
||
# rustypipe's web-client deciphering is fixed this makes streams work
|
||
# without yt-dlp. Default: unset.
|
||
# botguard_bin = "/home/me/.cargo/bin/rustypipe-botguard"
|
||
```
|
||
|
||
Secrets: the cookies file and the rustypipe cache grant access to your
|
||
YouTube session — keep both private. The provider never logs their
|
||
contents (paths only), and stream URLs are redacted from logs.
|
||
|
||
## Failure behavior
|
||
|
||
- No network / broken client at startup: only `/youtube` is disabled,
|
||
the server runs on.
|
||
- Rejected or missing cookies: degrades to logged-out with a warning.
|
||
- Missing `yt-dlp`: warning at startup; streams stop after ~1 MiB.
|
||
- `403 Forbidden` on streams in the log: YouTube's per-IP/per-video
|
||
enforcement fluctuates; usually transient. If it persists, update
|
||
`yt-dlp`.
|
||
|
||
[rustypipe]: https://crates.io/crates/rustypipe
|