100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# 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"
|
|
``` |