yt-dlp Python-Downloader

piknockyou
2026-01-11T13:38:30Z

Unified yt-dlp downloader - generates cross-platform Python scripts for video, audio, subtitles

☕ If you find this tool helpful & would like to support its maintenance, please consider leaving a tip on:

https://ko-fi.com/piknockyou

Thank you! :-)

🖼 For a quick impression of this script, refer to the screenshots at the bottom.

yt-dlp Python-Downloader | Cross-Platform Video/Audio/Subtitle Downloader

Generates ready-to-run Python scripts for downloading media from YouTube, Reddit, Instagram, TikTok, and many more sites using yt-dlp. One-click download button, configurable video/audio/subtitle options, and sophisticated merge/separate output modes—all in a cross-platform script that works on Windows, Mac, and Linux.

⚠️ Recommended Environment

This script is developed and tested primarily on Windows using the following environment:

YouTube and Reddit (primary test platforms)

yt-dlp (latest version; in PATH)

Python 3.13 (in PATH)

MKVToolNix (mkvmerge) for merging (HIGHLY RECOMMENDED; in PATH)

FFmpeg (in PATH)

While the generated Python scripts are designed to be cross-platform and include FFmpeg fallbacks, complex merge scenarios have been thoroughly tested only with mkvmerge on Windows. If you encounter issues on other platforms or without mkvmerge, please feel free to report them, but be aware this is a personal tool shared for others to use "as is."

Why You Need This

Downloading media with yt-dlp requires memorizing complex command-line syntax:

Format selection: -f bestvideo[height<=1080]+bestaudio is not intuitive

Codec preferences: Sorting by AV1, VP9, or H.264 requires -S flags

Subtitle handling: --write-subs --sub-langs en --convert-subs srt is verbose

Merging options: Getting separate files AND a merged file requires multiple commands

Platform differences: Batch files only work on Windows

This script generates a complete, ready-to-run Python script with all your options pre-configured. Just click, download, and run.

Key Features

Cross-Platform

Python scripts work on Windows, Mac, and Linux

Uses only Python standard library (no pip packages required)

Python 3.6+ (pre-installed on Mac/Linux)

Cookie Export

One-click cookie export via the context menu — exports browser cookies in Netscape format for yt-dlp --cookies

Auto Export Cookies option: automatically exports a cookie file alongside every generated .py script

Uses the userscript manager's GM_cookie API — no separate browser extension needed

Full cookie export including HttpOnly authentication cookies (required for YouTube login) — just enable one setting in your userscript manager (see Cookie Authentication section below)

Flexible Output Modes

Mode | Description
Merge | Combine video + audio + subtitles into one MKV file
Separate | Keep each component as its own file
Merge + Sep | Get both: merged file AND separate copies
None | Skip this component entirely

Mix and match modes per component—e.g., merge video+audio but keep subtitles separate.

Video Options

Quality: Best, 4K, 1440p, 1080p, 720p, 480p, 360p, 240p, 144p

Codec (YouTube): Auto, AV1, VP9, H.264

Audio Options

Quality: Best, Medium, Smallest

Format: Auto, MP3, AAC, Opus (available on all sites)

Subtitle Options

Interactive language selection when script runs

Format conversion: Original, SRT, VTT, ASS

Auto-generated subtitles included

Smart Merging

Uses mkvmerge for advanced merging (preserves all tracks)

Falls back to FFmpeg if mkvmerge unavailable

Prefer MP4 option for maximum playback compatibility

Single yt-dlp call for metadata efficiency

Options Menu

Hover over the ⚙️ Options row in the context menu to access power-user toggles:

Include Video ID: Toggle video ID in output filenames (on by default)

Prefer MP4: Use MP4 container instead of MKV (requires FFmpeg, best with H.264+AAC)

Delete .py After Run: Automatically remove the generated .py script after successful execution

Delete Cookie After Run: Automatically remove the exported cookie file after the script finishes

Auto Export Cookies: Automatically export a cookie file every time you generate a download script

Two-Tier File Identification

When downloading video + audio as separate streams, the script uses a robust two-tier system to correctly identify which file is which:

1. Tier 1 — ffprobe (fast, local): Inspects the file's actual streams

2. Tier 2 — yt-dlp format-ID probe (network, authoritative): Matches filenames against yt-dlp's resolved format IDs

This prevents misclassification of audio-only .webm/.mp4 files as video.

Upfront Tool Checks

Generated scripts verify that all required tools (ffmpeg, ffprobe, mkvmerge) are available before starting any downloads, based on what the selected options actually need. Clear error messages tell you exactly what to install.

Additional Features

Thumbnail download: Save the best available thumbnail

Comments download: Export YouTube comments to JSON

List Formats: View all available formats in terminal

Cookie file support: Access age-restricted or private content (see cookie section below)

Force overwrite: Configurable file replacement behavior

Site-specific handling: Optimized for combined-stream sites (HLS), Cloudflare-protected sites, Vimeo embeds

Playlist detection: Automatic simplified flow for playlists and albums

Supported Sites

Works on any site supported by yt-dlp, including:

YouTube (including Music)

Reddit

Instagram

TikTok

Twitter/X

Twitch

Vimeo (including embeds)

Facebook

Dailymotion

SoundCloud

Arte.tv

Tagesschau.de

Livestorm

...and 1000+ more

Usage

Quick Download

Action | Result
Click | Download Python script with current settings
Right-click | Open settings menu
Double-click | Hide button for 5 seconds

Settings Menu

Hover over Video/Audio/Subtitle rows to access quality/codec/format submenus

Click Merge, Sep, or None buttons to toggle output modes

Click "💬 Comments Only" for YouTube comment export

Click "🖼️ Thumbnail" to download the video thumbnail

Click "🍪 Export Cookies" to export browser cookies for yt-dlp

Click "📋 List Formats" to see all available formats

Hover over "⚙️ Options" to access power-user toggles (Prefer MP4, auto-cleanup, etc.)

Click "⬇ Download" button to generate the script

Running the Script

Windows:

python dl_video_name.py

Mac/Linux:

python3 dl_video_name.py

The script changes to its own directory automatically—run it from anywhere.

How It Works

1. Configure: Right-click the floating button to set video quality, codec preference, subtitle format, and output modes.

2. Generate: Click the button to download a .py script pre-configured with your URL and settings.

3. Run: Execute the Python script. It will:

Check for yt-dlp, mkvmerge, ffmpeg, and ffprobe (based on what's actually needed)

List available subtitles and prompt for language

Download all components in a single yt-dlp call

Identify files using two-tier detection (ffprobe → yt-dlp probe)

Merge/copy files according to your mode selections

Clean up temporary files (and optionally the script + cookie file)

Cookie Authentication

For public content, no cookies are needed. For login-required content (age-restricted, private, members-only), you can use the built-in cookie export.

One-Time Setup

The built-in export produces a complete cookie file equivalent to a dedicated extension — but you need to enable HttpOnly cookie access in your userscript manager first. This is a one-time setting.

Tampermonkey

1. Go to Tampermonkey → Settings

2. Under General, set Config mode to Advanced

3. Under Security, set Allow scripts to access cookies to All

Violentmonkey (Beta v2.35.1+)

1. Go to Violentmonkey → Settings → Advanced → Script settings

2. Enable "Allow GM_cookie to access HTTP-only cookies"

3. Then go to the yt-dlp Python-Downloader script → Settings tab

4. Check the box for "Allow GM_cookie to access HTTP-only cookies"

Why is this needed? Critical authentication cookies (YouTube's LOGIN_INFO, HSID, __Secure-*PSID, etc.) are marked as HttpOnly — a security flag that blocks access by default. Both Tampermonkey and Violentmonkey can access these cookies through the browser's extension API, but they require you to explicitly opt in. With the setting enabled, the export is complete.

Exporting Cookies

Once the setting is enabled:

1. Manual: Right-click the script icon → "🍪 Export Cookies"

2. Automatic: Enable "Auto Export Cookies" in ⚙️ Options — exports alongside every .py download

Alternative: Dedicated Extension

If you prefer not to change userscript manager settings, you can use a dedicated cookie extension like "Get cookies.txt LOCALLY". Place the exported file in the same directory as the .py script, named %domain%_cookies.txt (e.g., www.youtube.com_cookies.txt). The generated scripts automatically detect and use it.

Userscript Manager Compatibility

Manager | GM_cookie | HttpOnly Support | Status
Tampermonkey | ✅ | ✅ (enable in settings) | Available in current stable release
Violentmonkey | ✅ | ✅ (enable globally + per-script) | Available in beta v2.35.1+

Installation

Requirements

A userscript manager: Violentmonkey (recommended), Tampermonkey, or Greasemonkey

Python 3.6+ installed on your system

yt-dlp installed and in PATH

(Optional) mkvmerge for advanced merging

(Optional) FFmpeg for fallback merging, audio extraction, and format detection

Steps

1. Install a userscript manager.

2. Install this script.

3. Visit any supported video site.

4. The download button appears in the bottom-right corner.

Technical Details

SPA Support: Monitors URL changes for single-page apps (Reddit, YouTube)

Shadow DOM: Button and menu isolated from page styles

Cookie Files: Export via menu or place hostname_cookies.txt next to the script for authentication

Temp File Handling: Uses random prefixes to avoid collisions; cleans up after completion

File Identification: Two-tier system — ffprobe for local inspection, yt-dlp format-ID probe as fallback

Combined Stream Detection: Automatically splits muxed streams on sites like TikTok and Twitter

Generated Script Structure

PHASE 1: Download all components (single metadata fetch)
PHASE 2: Identify downloaded files (two-tier: ffprobe → yt-dlp probe)
PHASE 3: Merge selected components (mkvmerge or FFmpeg)
PHASE 4: Create separate copies (if requested)
PHASE 5: Cleanup temporary files (+ optional script/cookie removal)

FAQ

Q: Why Python instead of batch files?
A: Batch files only work on Windows. Python scripts run on Windows, Mac, and Linux with identical behavior.

Q: Do I need to install any Python packages?
A: No. The script uses only Python's standard library (subprocess, shutil, pathlib, glob).

Q: What if mkvmerge isn't installed?
A: The script falls back to FFmpeg via yt-dlp's native merging. Some advanced combinations (merge video+subs without audio) require mkvmerge.

Q: Why does the script ask for subtitle language every time?
A: Different videos have different available subtitles. The script shows you what's available and lets you choose interactively.

Q: Can I download private/age-restricted videos?
A: Yes, with cookies. Use the built-in "🍪 Export Cookies" feature — make sure to enable HttpOnly cookie access in your userscript manager's settings first (see Cookie Authentication section).

Q: Will the generated scripts run after I close the browser?
A: Yes. The .py scripts are fully standalone and run independently of the browser.

Q: Can the script and cookie files auto-delete after running?
A: Yes. Enable "Delete .py After Run" and/or "Delete Cookie After Run" in the ⚙️ Options flyout menu. Files are only deleted after successful execution.

Q: The download button isn't appearing on a site.
A: The script only activates on sites listed in the @match directives. You can add additional sites by editing the userscript header.

Q: Where are the advanced options?
A: Hover over the "⚙️ Options" row in the context menu to reveal power-user toggles like Prefer MP4, auto-cleanup, and cookie auto-export.

Q: The cookie export says the API is not available.
A: A banner will appear with setup instructions for your userscript manager. Violentmonkey (beta v2.35.1+) and Tampermonkey both support it — you just need to enable cookie access in their settings. Alternatively, use a dedicated cookie extension as a workaround.

Q: The exported cookies don't work for age-restricted content.
A: Make sure you've enabled HttpOnly cookie access in your userscript manager's settings. Without this, critical authentication cookies are filtered out. See the Cookie Authentication section for step-by-step instructions.

Permissions Explained

Permission | Why It's Needed
GM_setValue / GM_getValue | Save your quality/codec/format preferences
GM_cookie | Export browser cookies for yt-dlp authentication (enable HttpOnly access in manager settings for full functionality)