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