youtube-toolkit

# YouTube Toolkit Download and process YouTube videos: grab best-quality streams, convert/extract, and burn in translated subtitles + a watermark. macOS-first, with Linux notes. Two helper scripts do the deterministic work; the agent does the judgement work (choosing formats, translating subtitles). Read the relevant `references/` file before a non-trivial task instead of guessing flags. ## ⚠️ Pick the right ffmpeg first (the #1 gotcha) Homebrew's **lean `ffmpeg`** formula ships **without libass/libfreetype**, so it has **no `subtitles` and no `drawtext` filter** — subtitle burn-in and watermarks fail with `No option name` / `Error parsing filterchain`. Verify before relying on it: ```bash ffmpeg -hide_banner -filters 2>/dev/null | grep -E ' subtitles | drawtext ' || echo "NO subtitle/drawtext support" ``` If missing, install the full build (keg-only, **does not touch your `ffmpeg`**): ```bash brew install ffmpeg-full # binary at /opt/homebrew/opt/ffmpeg-full/bin/ffmpeg ``` `scripts/burn-subs.sh` auto-detects an ffmpeg with libass, preferring `ffmpeg-full`. Plain download/convert work fine with the lean `ffmpeg`. ## Install tools One shot: `bash scripts/install-tools.sh` (detects OS; installs yt-dlp, an ffmpeg with libass, and optionally the `deno` JS runtime). Or do it manually — details and Linux/conda variants in `references/installation-and-recipes.md`. > yt-dlp prints `No supported JavaScript runtime` and falls back to the Android client. It usually still ...