my-homelab-configs/infra/youtube-backup/README.md

YouTube Backup

Standalone helper for backing up your own uploaded YouTube videos with yt-dlp. It is intentionally outside jeannie, OpenTofu, Argo CD, and the homelab deployment pipeline.

The backup root defaults to /data/youtube-backup.

Install

pipx install yt-dlp

The Debian host bootstrap installs yt-dlp, ffmpeg, and nodejs for this helper. It installs yt-dlp with its default dependency group so the YouTube EJS challenge scripts are available, and the backup script passes --js-runtimes node by default. On another machine, install those tools before running the backup.

Configure

sudo mkdir -p /data/youtube-backup/{videos,logs}
sudo chown -R "$USER:$USER" /data/youtube-backup
cp infra/youtube-backup/playlists.example.txt /data/youtube-backup/playlists.txt
cp infra/youtube-backup/.env.example infra/youtube-backup/.env

Edit /data/youtube-backup/playlists.txt and add one playlist, channel, or video URL per line.

For private or unlisted uploads, export browser cookies and set:

YOUTUBE_BACKUP_COOKIES_FILE=/data/youtube-backup/cookies.txt

Alternatively, when running on a desktop with a browser profile:

YOUTUBE_BACKUP_COOKIES_FROM_BROWSER=firefox

Run

infra/youtube-backup/backup-youtube.sh

The script uses:

--download-archive /data/youtube-backup/archive.txt

so repeated runs skip videos that were already backed up.

Downloaded videos and sidecar metadata are written under:

/data/youtube-backup/videos

The default backup writes the video, .info.json, description, and embeds one thumbnail into the media file. It does not write separate subtitle files. Set YOUTUBE_BACKUP_WRITE_THUMBNAIL=true if you also want one sidecar .jpg thumbnail.

Each run also writes a timestamped log under:

/data/youtube-backup/logs