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

1. Install Tampermonkey or Violentmonkey
2. Install the userscript:
   • MediaDL — Universal Media Downloader
3. Install yt-dlp and ffmpeg
4. 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:

1. Task Scheduler → Delete the MediaDL-Server task
2. Delete %LOCALAPPDATA%\MediaDL
3. Registry → Remove HKCU:\Software\Classes\ytdl
4. 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

     

  🐛 Report Issues  
    
  ⭐ Star on GitHub  
    
  👤 SysAdminDoc  

_{Made with ❤️ by SysAdminDoc}