Portfolio / MediaDL

MEDIA

MediaDL

Media downloader

PowerShellMedia

Open source on GitHub

Delivery

Source-first

Browse code, README, and release notes on GitHub.

Primary lane

PowerShell

Media category

Freshness

Apr 26, 2026

Updated Apr 26, 2026

Latest release

No tag yet

README is the clearest project overview right now.

Preview

Using the generated project card as a clean fallback until a live capture is available.

Source at github.com/SysAdminDoc/MediaDL.

README

Cached at build time, cleaned up for in-site reading, and linked back to the canonical GitHub source.

![Version](https://img.shields.io/badge/v4.0.0-00b894?style=for-the-badge&logo=semanticrelease&logoColor=white&label=Version) ![Sites](https://img.shields.io/badge/1800+-e17055?style=for-the-badge&logo=youtube&logoColor=white&label=Sites) ![PowerShell](https://img.shields.io/badge/5.1+-0078D4?style=for-the-badge&logo=powershell&logoColor=white&label=PowerShell) ![License](https://img.shields.io/badge/MIT-6c5ce7?style=for-the-badge&logo=opensourceinitiative&logoColor=white&label=License)

Download videos and extract audio from YouTube, Facebook, Twitter/X, TikTok, Instagram, and 1800+ more.
Auto-detects media on any page. Floating download pills. Zero configuration.

3-tier failover · hidden background server · real-time progress · 6-layer Facebook extraction

🚀 Quick Install ✨ Features 🌍 Sites 🏗️ Architecture 🔧 Troubleshoot

🚀 Quick Install

One command. Everything configured. No manual setup.

irm https://raw.githubusercontent.com/SysAdminDoc/MediaDL/refs/heads/main/Install-MediaDL.ps1 | iex

_{Run in an elevated PowerShell window. The installer downloads yt-dlp, ffmpeg, registers protocol handlers, deploys the background download server, creates a Scheduled Task for auto-start, and installs the userscript.}

🌍 Supported Sites

MediaDL has optimized detection for these platforms, plus generic <video> detection for any site yt-dlp supports:

	Platform	Video	Audio		Platform	Video	Audio
▶️	YouTube	✅	✅	🔵	Vimeo	✅	✅
📘	Facebook	✅	✅	🔊	SoundCloud	—	✅
🐦	Twitter / X	✅	✅	🎸	Bandcamp	—	✅
🎵	TikTok	✅	✅	📺	Dailymotion	✅	✅
📷	Instagram	✅	✅	🅱️	Bilibili	✅	✅
🟣	Twitch	✅	✅	🏴	Rumble / Odysee	✅	✅
🔴	Reddit	✅	✅	🍿	Crunchyroll / Nebula	✅	✅

_{+ Kick, Floatplane, Streamable, Imgur, Arte, Tagesschau, and 1800+ more via yt-dlp}

✨ Features

🌐 MediaDL Userscript

🔍 Auto-Detect

Scans every page for video and audio elements. Attaches floating download pills automatically — no clicking required.

🛡️ 3-Tier Failover

HTTP server → protocol handler → GM_download. If one method fails, the next activates seamlessly.

⚡ Background Server

Lightweight HTTP server on 127.0.0.1:9751. Concurrent downloads, progress tracking, queue management. Starts on login.

🔑 Zero-Config Auth

Server token negotiated automatically via X-MDL-Client header handshake. No manual setup.

📊 Progress Toasts

In-page progress bars with download speed and ETA. Appear at the bottom-right of the browser window.

🔄 SPA Compatible

MutationObserver + URL change detection handles single-page navigation on YouTube, Facebook, Twitter, and all modern SPAs.

🖥️ Download Handler

🧵 Async UI

Title and thumbnail fetched in background jobs. The progress popup renders instantly and never freezes.

🎯 Duplicate Prevention

SHA256 URL lock prevents accidental double-downloads from rapid clicking.

📈 Smooth Progress

Animated bar with eased interpolation. Reads only last 4KB via FileStream.Seek.

🔪 Cancel Kills All

Cancelling kills both the PowerShell wrapper and child yt-dlp.exe / ffmpeg.exe via CIM process lookup.

🖼️ Universal Thumbnails

YouTube via direct API. All other sites via yt-dlp --get-thumbnail. Both non-blocking.

📂 Open on Complete

Click "Complete!" to open Explorer with the downloaded file pre-selected.

🪟 Win11 Native

DWM rounded corners via DwmSetWindowAttribute. Degrades gracefully on Windows 10.

🔄 yt-dlp Auto-Update

Self-update throttled to once per 24 hours via timestamp file.

🛑 Crash-Proof

4-layer exception handling: closing flag, nuclear try/catch, control guards, and global Application.ThreadException.

📸 Screenshots

Installer Wizard

🏗️ Architecture

 ┌─ Browser ───────────────────────┐    ┌─ Windows ──────────────────────────┐
 │                                 │    │                                    │
 │  MediaDL Userscript             │    │  ┌─ Tier 1: Download Server ────┐  │
 │  ├─ Auto-detect <video>         │HTTP│  │  ytdl-server.ps1              │  │
 │  ├─ Floating download pills     │◀──▶│  │  127.0.0.1:9751              │  │
 │  ├─ Facebook 6-layer extraction │    │  │  ├─ Concurrent downloads (3x) │  │
 │  ├─ In-page progress toasts     │    │  │  ├─ Real-time progress        │  │
 │  └─ SPA navigation handling     │    │  │  └─ Auto-start on login      │  │
 │                                 │    │  └───────────────────────────────  │
 │         ┌──────────────┐   ytdl://   │                                    │
 │         │ Click pill    │────────▶│  ┌─ Tier 2: Protocol Handler ────┐  │
 │         └──────────────┘        │    │  │  ytdl-handler.ps1            │  │
 │                                 │    │  │  ├─ Progress popup           │  │
 │         ┌──────────────┐   GM_dl│    │  │  ├─ Thumbnail + title        │  │
 │         │ CDN direct    │───────▶│  │  └─ Auto-retry (3x)           │  │
 │         └──────────────┘        │    │  └──────────────────────────────  │
 └─────────────────────────────────┘    └────────────────────────────────────┘
                                                      │
                                          Scheduled Task: MediaDL-Server
                                          (auto-start on login, hidden)

Tier	Method	How	Progress	Activates When
1	HTTP Server	`GM_xmlhttpRequest` to `127.0.0.1:9751`	✅ Real-time polling	Server is running (default)
2	Protocol Handler	`ytdl://` URL triggers `ytdl-handler.ps1`	✅ Popup window	Server is offline
3	Browser Direct	`GM_download` for CDN URLs	❌ None	Both 1 & 2 fail, URL is direct CDN

🔬 Facebook 6-Layer Extraction

Facebook aggressively obfuscates video URLs. MediaDL defeats this with six extraction layers tried in priority order:

#	Layer	Technique
1	XHR/Fetch Intercept	Hooks `window.fetch` and `XMLHttpRequest` at `document-start` to capture `playable_url_quality_hd` from GraphQL responses
2	Performance Resource Timing	Scans `performance.getEntriesByType('resource')` for `fbcdn.net` video entries, sorted by transfer size
3	React Fiber Tree Walk	Traverses `__reactFiber` from the `<video>` element upward through `memoizedProps` searching for `browser_native_hd_url`
4	Embedded JSON Scrape	Searches `<script type="application/json">` blocks for HD video URL patterns
5	DOM Permalink Walk	Climbs the DOM tree from the video element to find a `/videos/`, `/watch/`, or `/reel/` link
6	Page URL Fallback	Uses `window.location.href` if it matches a Facebook video/reel/story URL pattern

🔌 Server API Reference

The download server runs on 127.0.0.1:9751 (localhost only, not exposed to network).

Method	Endpoint	Auth	Response
`GET`	`/health`	—	Server status. Returns auth token when `X-MDL-Client: MediaDL` header is present
`POST`	`/download`	🔐	Start download. Body: `{url, title, audioOnly, referer}`. Returns `{id}`
`GET`	`/status/:id`	🔐	`{status, progress, speed, eta, filename}`
`GET`	`/queue`	🔐	Array of all active downloads with status
`DELETE`	`/cancel/:id`	🔐	Cancel and clean up a download
`GET`	`/shutdown`	🔐	Gracefully stop the server

_{🔐 = Requires X-Auth-Token header (auto-negotiated by the userscript)}

📂 Project Files

File	Description
`Install-MediaDL.ps1`	PowerShell WPF installer wizard (dark-themed GUI)
`MediaDL.user.js`	Userscript — auto-detect on all websites
`ytdl-server.ps1`	Hidden HTTP download server (`127.0.0.1:9751`)
`ytdl-handler.ps1`	Protocol handler with async progress popup
`ytdl-server-launcher.vbs`	Windowless server launcher
`ytdl-launcher.vbs`	Silent handler launcher
`config.json`	Paths, server port/token, preferences

💻 Installation

Option 1 — Automatic Installer (recommended)

# Open PowerShell as Administrator, then run:
irm https://raw.githubusercontent.com/SysAdminDoc/MediaDL/refs/heads/main/Install-MediaDL.ps1 | iex

The installer creates a MediaDL-Server Scheduled Task that auto-starts the background server on login. No console windows will appear.

Option 2 — Manual Installation

Install Tampermonkey or Violentmonkey
Install the userscript:
- MediaDL — Universal Media Downloader
Install yt-dlp and ffmpeg
Set up protocol handlers manually (see below)

Protocol Handler Registry Entry

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\ytdl]
@="URL:YTDL Protocol"
"URL Protocol"=""

[HKEY_CLASSES_ROOT\ytdl\shell\open\command]
@="wscript.exe \"C:\\Path\\To\\ytdl-launcher.vbs\" \"%1\""

📋 Requirements

🤖 Automatic (recommended)

The installer handles everything:

	Component	Status
✅	yt-dlp	Auto-downloaded
✅	ffmpeg	Auto-downloaded
✅	Protocol handler	Auto-registered
✅	Download server	Auto-deployed
✅	Scheduled Task	Auto-created

🔧 Manual

If installing without the wizard:

	Component	Link
📌	Userscript manager	Tampermonkey
📌	yt-dlp	GitHub
📌	ffmpeg	ffmpeg.org

🔧 Troubleshooting

Issue	Solution
Download pills don't appear	Refresh the page. Verify userscript is enabled with `@match :///*`
Server not running	Check Task Scheduler for `MediaDL-Server`, or run `ytdl-server-launcher.vbs` manually
Facebook downloads fail	Click the video to trigger playback first (populates CDN URLs for extraction)
Download fails silently	Verify yt-dlp and ffmpeg are installed and paths are correct in `config.json`
JIT debugging dialog	Update to the latest handler (4-layer crash prevention)
Duplicate downloads	Update to the latest handler (SHA256 URL lock)

🗑️ Uninstalling

Run the installer again — it auto-removes the previous installation before reinstalling.

For full manual removal:

Task Scheduler → Delete the MediaDL-Server task
Delete %LOCALAPPDATA%\MediaDL
Registry → Remove HKCU:\Software\Classes\ytdl
Browser → Remove the userscript from Tampermonkey

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Built With

![yt-dlp](https://img.shields.io/badge/yt--dlp-FF0000?style=for-the-badge&logo=youtube&logoColor=white) ![ffmpeg](https://img.shields.io/badge/ffmpeg-007808?style=for-the-badge&logo=ffmpeg&logoColor=white) ![PowerShell](https://img.shields.io/badge/PowerShell-0078D4?style=for-the-badge&logo=powershell&logoColor=white)

🐛 Report Issues ⭐ Star on GitHub 👤 SysAdminDoc

_{Made with ❤️ by SysAdminDoc}

Read on GitHub → github.com/SysAdminDoc/MediaDL