Add yt-downloader: single-URL YouTube downloads through an isolated Mullvad WireGuard tunnel

2026-08-25 15:09:18 +02:00
commit f6b271a926
9 changed files with 729 additions and 0 deletions
@@ -0,0 +1,100 @@
+# yt-downloader
+
+Download a single YouTube video through an **isolated Mullvad WireGuard tunnel**.
+
+Built as the video equivalent of [music-gatherer](https://github.com/anomalyco/music_gatherer)'s
+download phase: the only thing that talks to YouTube is the `download` command, and when a
+WireGuard config is configured it re-runs itself inside a dedicated network namespace whose
+only egress is the tunnel — so YouTube never sees your home IP. Everything else on your
+machine stays on the normal network.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+Requires `yt-dlp` (pulled in automatically) and `ffmpeg` (used to mux separate
+video + audio streams into a single file).
+
+## Usage
+
+```bash
+yt-downloader init                 # write a starter config
+yt-downloader download <url>       # download one video (auto-wraps into the VPN)
+yt-downloader vpn up               # create the namespace + bring the tunnel up (sudo)
+yt-downloader vpn status           # handshake time, routes, DNS
+yt-downloader vpn down             # tear it all down
+```
+
+Download options:
+
+```bash
+yt-downloader download <url> -q 720                 # quality preset
+yt-downloader download <url> -q best                # best video+audio (default)
+yt-downloader download <url> -q audio               # audio only (no muxing needed)
+yt-downloader download <url> -q 1080 -o ~/Videos    # custom output dir
+yt-downloader download <url> -f 'bestvideo[height<=480]+bestaudio'   # raw yt-dlp format
+```
+
+Quality presets: `best`, `1080`, `720`, `480`, `audio`. The `-f/--format` flag takes any
+yt-dlp format string and overrides the preset.
+
+## Downloads through a Mullvad VPN
+
+By default downloads go through your normal connection. To route **only the yt-dlp
+traffic** through a WireGuard (Mullvad) tunnel, give the tool a WireGuard config:
+
+```toml
+[vpn]
+wireguard = "~/.config/yt-downloader/mullvad.conf"   # Mullvad .conf
+# namespace = "mullvad"   # optional: network namespace name
+# interface = "mv0"       # optional: WireGuard interface name
+```
+
+When set, `yt-downloader download` re-runs itself inside a dedicated **network namespace**
+whose only egress is the WireGuard tunnel. The namespace has no fallback route, so a dead
+tunnel means a failed download, never a leak. Bring-up is automatic (`ensure_up`); use
+`yt-downloader vpn up/down/status` to manage it by hand.
+
+It uses a Mullvad `.conf` (`[Interface]` + `[Peer]`), which you get from mullvad.net; the
+private key is copied into `/etc/wireguard/mv0.conf`.
+
+Requirements: Linux, `wireguard-tools` + `iproute2`, and `sudo`. Interactive runs prompt for
+the sudo password once; for unattended runs add passwordless sudo entries:
+
+```
+# /etc/sudoers.d/yt-downloader   (run: sudo visudo -f /etc/sudoers.d/yt-downloader)
+magerbeton ALL=(root) NOPASSWD: /usr/bin/ip, /usr/bin/wg, /usr/bin/wg-quick, \
+  /usr/sbin/iptables, /usr/sbin/sysctl, /bin/mkdir, /bin/rm, /bin/chmod, /bin/sh
+```
+
+The download process drops back to your user inside the namespace, so downloaded files stay
+owned by you.
+
+## Bot-check mitigation
+
+YouTube sometimes challenges downloads. Like music-gatherer, you can pass your browser
+cookies to yt-dlp:
+
+```toml
+[download]
+# cookies_file = "/path/to/cookies.txt"
+# cookies_from_browser = "firefox"   # e.g. chromium, firefox, safari
+```
+
+## Configuration
+
+See `yt_downloader.toml` after `init` for the full template (`~/.config/yt-downloader/`).
+
+```toml
+[download]
+out = "~/Videos/yt-downloader"   # where videos land
+quality = "best"                 # best | 1080 | 720 | 480 | audio
+# format = ""                    # raw yt-dlp -f string, overrides quality
+
+[vpn]
+# wireguard = "~/.config/yt-downloader/mullvad.conf"
+# namespace = "mullvad"
+# interface = "mv0"
+```