# 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.

Search results and playlists are downloadable: `W` captures them with
audio into `/crabidy/<name>` (slow under the throttle, but captures
are resumable — re-capture the same name to continue).

## Logging in (optional)

Search and playback need no login. A cookie export only adds
`/youtube/playlists`, the saved playlists of an account:

1. Export your YouTube cookies in Netscape `cookies.txt` format — a browser
   extension like "Get cookies.txt LOCALLY" does it. Doing this from an
   Incognito window you close afterwards keeps the session from being
   rotated out from under the file.
2. Point `cookies` at the file (see below) and restart the server.
3. The provider caches the rotated session cookie under
   `~/.config/crabidy/rustypipe/`, so the export only has to be valid once.

Rejected or missing cookies degrade to logged-out with a warning; nothing
else is affected.

## 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`.

Build the server without the `youtube` cargo feature to leave this provider
(and the `rustypipe` dependency) out of the binary entirely.

[rustypipe]: https://crates.io/crates/rustypipe