Clip faster and create sharper with a Windows-first yt-dlp workflow for repeatable source pulls, local verification, transcripts, search, and clip-building, with optional Mullvad VPN guardrails.

Legends YT-DLP exists because raw yt-dlp is powerful, but real creator work needs more than a one-off command. The project wraps the official yt-dlp binary with explicit batch plans, optional source notes, local state, conservative defaults, a short use notice before real runs, default pacing between pulls, and an opt-in Mullvad VPN mode for guarded runs. Ripping a video from time to time is frictionless; bulk pulls slow down and ask for acknowledgement.

What It Does

Supports the official Mullvad CLI as an opt-in guarded-run layer (--with-vpn); nothing requires Mullvad by default.
Stores the Mullvad account number locally in an ignored .env file (only needed for VPN-guarded runs).
Downloads the official Windows yt-dlp.exe release from yt-dlp/yt-dlp.
Verifies the downloaded binary against upstream SHA2-256SUMS.
Detects ffmpeg.
Detects a JavaScript runtime for modern YouTube extraction.
Creates batch manifests with optional rights notes and evidence files.
Inventories channel and playlist URLs into a reviewable item ledger before downloads.
Copies optional rights evidence files into the batch folder.
Provides a one-command setup path for Mullvad safety posture (setup production).
In --with-vpn mode, requires Mullvad connected with Lockdown on, recovers the tunnel on network failures, then disables Lockdown and disconnects after completed real runs.
Supports custom operator-provided smoke URLs for install validation.
Supports bounded smoke jobs with max downloads, height, and filesize limits.
Generates stable anonymous-mode yt-dlp config files with download archives and conservative retry/sleep settings.
Blocks real runs until preflight passes.
Requires an explicit --yes flag for real downloads.
Paces pulls by default and requires --bulk acknowledgement for batches over 50 URLs.
Verifies completed batches with archive, report, info JSON, media count, and ffprobe checks.
Runs the ready-made CrispASR Parakeet backend against verified local media.
Imports timestamped word ledgers for verified local media.
Searches exact words and phrases across local transcripts.
Generates reviewable FFmpeg clip plans and optional montages.
Builds Obsidian-compatible transcript vault pages.

Why It Exists

Creator projects fail in predictable places: messy source lists, duplicate pulls, broken resumes, unclear output folders, missing transcripts, and clips that are hard to find again. Legends YT-DLP turns those weak points into a repeatable plan, pull, verify, search, and cut flow.

The goal is not to evade platform controls. The goal is to make source capture deliberate, resumable, and useful for editing, research, and review.

Current Status

Public beta.

Working now:

doctor
setup production
Mullvad status/login/connect/lockdown wrappers
Mullvad inspect and settings wrappers
Mullvad safe recovery for tunnel/network failures
Mullvad post-run shutdown that turns Lockdown off, disconnects, and verifies the final state
guarded Mullvad disconnect testing that reconnects before returning
VPN posture checks for Mullvad Lockdown, split tunneling, LAN sharing, and auto-connect (--with-vpn)
anonymous yt-dlp auth/cookie policy checks
JavaScript runtime detection/configuration for YouTube extraction
bounded batch limits for smoke tests and controlled archive jobs
official yt-dlp.exe install, update, upstream version check, checksum verification, and 90-day freshness check
custom smoke-pack planning
batch plan
channel/playlist inventory
multi-URL and URL-file batch planning
batch catalog
item ledger
batch preflight
guarded run
batch verify
post-capture intelligence workspace, CrispASR/Parakeet transcription, word import, search, clip planning, rendering, and vault export

Latest release: v0.1.5.

Conversational operation

Tell the agent what you want to download. The agent handles the CLI flags, setup,
and checks; you do not need to know commands such as --with-vpn. An occasional
authorized pull proceeds without a VPN or a separate VPN approval step.

For a large request, such as 100 videos, the agent explains pacing and may offer
VPN assistance as an optional convenience. Your explicit request for that batch
supplies the bulk acknowledgement; it does not require another approval card.
Declining VPN, having no subscription, or having no Mullvad installation is fine
at any batch size. Bulk mode never enables VPN automatically. VPN cannot guarantee
protection from throttling, blocks, or account enforcement and is not a way to
bypass source-side controls. Pause and report those controls when encountered.

Quick Start

From the project root:

legends-yt-dlp onboard
legends-yt-dlp yt-dlp update
legends-yt-dlp yt-dlp version
legends-yt-dlp doctor

Optional: VPN-guarded runs with Mullvad. Nothing above needs it. When you want
guarded runs, set up Mullvad once, then pass --with-vpn to plan,
preflight, and run:

legends-yt-dlp onboard --with-vpn
legends-yt-dlp setup production
legends-yt-dlp mullvad status --verbose
legends-yt-dlp mullvad inspect
legends-yt-dlp mullvad login
legends-yt-dlp mullvad lockdown on
legends-yt-dlp mullvad connect
legends-yt-dlp mullvad recover
legends-yt-dlp mullvad shutdown
legends-yt-dlp mullvad disconnect-test --emergency-unlock
legends-yt-dlp doctor --require-connected
legends-yt-dlp doctor --production

Validate the install with a small authorized smoke URL:

legends-yt-dlp smoke plan --url "https://www.youtube.com/watch?v=..." --name "first-smoke"
legends-yt-dlp preflight "batches\...\manifest.json"
legends-yt-dlp run "batches\...\manifest.json" --dry-run
legends-yt-dlp run "batches\...\manifest.json" --yes
legends-yt-dlp verify "batches\...\manifest.json"

In --with-vpn mode, run --yes shuts Mullvad down after the batch reaches a terminal state: Lockdown is turned off first, Mullvad disconnects with --wait, and the final disconnected state is verified. Use --keep-vpn only when the operator intentionally wants Mullvad and Lockdown left running after the batch.

Create a batch:

legends-yt-dlp plan "https://www.youtube.com/@CHANNEL" --name "channel-name"
legends-yt-dlp plan --from-file ".\urls.txt" --name "catalog-name"
legends-yt-dlp plan --from-file ".\urls.txt" --rights "optional permission/license/fair-use note" --rights-file ".\rights-evidence.md" --name "catalog-name"
legends-yt-dlp plan --from-file ".\urls.txt" --name "catalog-name" --folder-policy batch
legends-yt-dlp catalog

Folder policy controls output layout. auto puts direct multi-link plans into one named batch folder and keeps inventoried channel/playlist work grouped by uploader. Use --folder-policy batch for mixed one-off links, --folder-policy by-uploader for channel/archive work, and --folder-policy flat only when the selected output folder already represents the job.

For channel or playlist work, inventory first:

legends-yt-dlp inventory "https://www.youtube.com/@CHANNEL" --rights-file ".\rights-evidence.md" --name "channel-name"
legends-yt-dlp ledger "batches\...\manifest.json"

Inventory creates the batch manifest, urls.txt, yt-dlp.conf, and items.jsonl without downloading media. Review the ledger with the user before a real run.

Preflight and run:

legends-yt-dlp preflight "batches\...\manifest.json"
legends-yt-dlp run "batches\...\manifest.json" --dry-run
legends-yt-dlp run "batches\...\manifest.json" --yes
legends-yt-dlp verify "batches\...\manifest.json"
legends-yt-dlp ledger "batches\...\manifest.json" --refresh

Analyze verified local media after download when the user asks for transcripts, search, clips, a transcript vault, or when the job clearly calls for post-capture analysis. Plain archive/download jobs do not need transcription by default:

legends-yt-dlp intelligence init "batches\...\manifest.json"
legends-yt-dlp intelligence doctor "batches\...\manifest.json" --require-gpu
legends-yt-dlp intelligence transcribe "batches\...\manifest.json" --media ".\video.mp4" --video-id "VIDEO_ID" --model auto
legends-yt-dlp intelligence transcribe "batches\...\manifest.json" --all --model auto --gpu-backend cuda --require-gpu
legends-yt-dlp intelligence ingest-words "batches\...\manifest.json" --input ".\examples\intelligence-words.jsonl" --video-id "VIDEO_ID"
legends-yt-dlp intelligence align nfa "batches\...\manifest.json" --media ".\video.mp4" --video-id "VIDEO_ID" --prepare-only
legends-yt-dlp intelligence search "batches\...\manifest.json" "agentic workflow"
legends-yt-dlp intelligence clips plan "batches\...\manifest.json" --query "agentic workflow"
legends-yt-dlp intelligence vault build "batches\...\manifest.json"

intelligence doctor --require-gpu is the truth gate for GPU-backed Parakeet. CPU-only CrispASR still runs locally without Codex or Claude token spend, but the project does not label that install GPU-ready unless CrispASR diagnostics report a compiled GPU backend.

intelligence align nfa prepares and imports NVIDIA NeMo Forced Aligner word CTM output for delicate clip boundaries. It expects NeMo/PyTorch/model weights in an external operator-managed environment; the core package only writes manifests and refines the word ledger.

Treat legends-yt-dlp intelligence as an optional post-capture layer. The normal archive contract ends after run, verify, and ledger review unless the user requested analysis or the operator has a clear reason to propose it.

Safety Boundary

Allowed:

archiving videos you own
archiving videos you have permission to download
archiving public-domain or appropriately licensed content
using Mullvad as a privacy and leak-prevention layer while source capture is actively running
stopping on throttling, captcha, login, or block signals
keeping pulls modest; batches over 50 URLs require explicit --bulk acknowledgement

Not allowed:

bypassing DRM, paywalls, captchas, login challenges, account controls, or access controls
rotating VPN relays to continue through throttles, captchas, login prompts, account controls, or platform blocks
using Legends YT-DLP for unlawful downloads
hiding abusive or copyright-infringing use

See docs/SAFETY.md.

Architecture

Operator command
  -> CLI control plane
  -> Policy checks
  -> Optional Mullvad guard
  -> yt-dlp runner
  -> Batch state and reports

The project uses yt-dlp as an external child-process dependency rather than reimplementing download logic.

See docs/ARCHITECTURE.md.

Agent setup (via `cto-legends`)

Part of the CTO Legends ecosystem. cto-legends is the only registered skill; this repo vendors a pinned copy at skills/cto-legends/SKILL.md.

Install with cto-legends install legends-yt-dlp, then follow the module recipe the router loads. Do not register this module as its own skill.

Agent Routing

Legends YT-DLP is markdown-first: an agent reads this README plus
docs/OPERATOR-ROUTING.md and the docs below to operate the CLI. No skill
installation is required to start; cto-legends routes capture goals here and
hands over this README plus the recipe. Human operators use the same commands
through legends-yt-dlp or python -m legends_ytdlp.

Transcription Routes

Capture and transcription are separate concerns. This module transcribes its own
verified media through an external CrispASR executable (Parakeet-capable, never
bundled). For heavier transcription work, route outward instead of bulking up:
continuous background audio and voice sketchpads belong to
legends-ambient-intelligence, and live typing belongs to legends-hyperyap.
See docs/TRANSCRIPTION.md.

Empire Vault

intelligence vault build exports Obsidian-compatible transcript pages that
slot into a Legends Empire vault as cited evidence. See
docs/VAULT-MAP.md for the page layout and the Empire-side
mapping.

Documentation

Local Secrets

.env is ignored by git. Use .env.example for the expected shape.

Never commit Mullvad account numbers, cookies, account tokens, or batch outputs.

All batches are anonymous by default: no browser cookies, no cookie files, no username/password auth, no .netrc, and no inherited user-level yt-dlp config.

Packaging

Verify release readiness and test coverage:

python -m unittest discover -s tests -p "test_*.py" -v
python scripts/check_release.py

The package excludes .env, .local, batches, reports, downloads, caches, cookies, secrets, and git metadata.

FAQ

Is Mullvad VPN required to use legends-yt-dlp?
No. Occasional authorized pulls run without Mullvad or any VPN setup. Mullvad (--with-vpn) is strictly an opt-in guardrail for operators who want leak protection during larger batches.

Does legends-yt-dlp bundle yt-dlp.exe in the repository?
No. It downloads the official release binary from yt-dlp/yt-dlp locally and verifies its SHA-256 checksum against upstream SHA2-256SUMS.

License

Legends YT-DLP is released under the MIT License.

Important distribution note: the project does not commit or package the yt-dlp.exe binary. It downloads the official upstream executable locally and verifies its checksum. See NOTICE and docs/LEGAL.md.

Specification & benchmarks on cto-legends.com:

Module specification & architecture matrix: cto-legends.com/modules/legends-yt-dlp
Related engineering dispatches: How to Build AI Agents: Production CLI & MCP Routing · Obsidian Second Brain: Markdown Knowledge Base Guide · Claude Code Skills: MCP vs CLI Workflow Architecture
Ecosystem hub: cto-legends.com/home