miyuki-dlp 0.3.1

Stealth HLS stream downloader — bypass Cloudflare, intercept M3U8 playlists, and download videos via browser automation and ffmpeg

miyuki-dlp

Stealth HLS stream downloader that bypasses Cloudflare protection using browser automation. Intercepts M3U8 playlists from network traffic and downloads via ffmpeg — no fragile URL scraping required.

Features

• Cloudflare bypass — Uses Patchright (stealth-patched Playwright) with a real Chrome profile
• Smart auto-detection — Starts headless; auto-relaunches headed if Cloudflare blocks
• Automatic M3U8 interception — Captures playlist URLs from browser network traffic
• UUID fallback — Extracts video UUID from page source when interception fails
• Quality selection — Choose best, worst, or specific resolution (e.g. 720p)
• Parallel downloads — 16 concurrent connections for fast segment downloading
• Multi-URL support — Download multiple videos in a single session
• Rich progress UI — Colorful terminal output with download progress
• ffmpeg integration — Reliable stream download with copy-mux to MP4

Requirements

• Python 3.11+
• ffmpeg — for HLS stream downloading
• Google Chrome — real Chrome browser (not Chromium)

Installation

From PyPI (recommended)

pip install miyuki-dlp

# Install the browser driver (required once)
python -m patchright install chromium

From source

git clone https://github.com/muginami/miyuki-dlp.git
cd miyuki-dlp
pip install -e .

# Install the browser driver (required once)
python -m patchright install chromium

Usage

Basic download

miyuki-dlp https://example.com/video-page

List available qualities

miyuki-dlp --list-qualities https://example.com/video-page

Select specific quality

miyuki-dlp -q 720 https://example.com/video-page

Custom output directory

miyuki-dlp -o ~/videos https://example.com/video-page

Verbose mode (debug logging)

miyuki-dlp -v https://example.com/video-page

Download multiple URLs

miyuki-dlp https://example.com/video-1 https://example.com/video-2

Override output filename

miyuki-dlp --title "my-video" https://example.com/video-page

CLI Reference

usage: miyuki-dlp [-h] [-o OUTPUT] [-q QUALITY] [--headful] [--timeout TIMEOUT]
                  [--profile PROFILE] [--list-qualities] [--title TITLE]
                  [-v] [--version]
                  urls [urls ...]

Stealth HLS stream downloader — bypass Cloudflare, intercept M3U8, download via ffmpeg

positional arguments:
  urls                  Video page URLs to download

options:
  -h, --help            show this help message and exit
  -o, --output OUTPUT   Output directory (default: ./downloads)
  -q, --quality QUALITY Quality: best, worst, or height like 720, 1080 (default: best)
  --headful            Force headed browser mode (skip auto-detection)
  --timeout TIMEOUT     M3U8 interception timeout in seconds (default: 30)
  --profile PROFILE     Chrome profile directory path
  --list-qualities      List available qualities and exit
  --title TITLE         Override output filename
  -v, --verbose         Verbose/debug logging
  --version             show program's version number and exit

How It Works

Cloudflare Bypass (Smart Auto-Detection)

1. First run — Browser starts in headless mode. If Cloudflare challenge is detected, it automatically relaunches in headed (visible) mode to solve the challenge.
2. Cookies saved — Once Cloudflare is cleared, session cookies are persisted to the Chrome profile (~/.miyuki-dlp/chrome-profile).
3. Subsequent runs — Headless mode works normally using the cached clearance cookies.
4. Manual override — If auto-detection fails, use --headful to force headed mode from the start.

Pipeline

1. Browser launch — Patchright launches a real Chrome instance with a persistent profile, avoiding bot detection fingerprints
2. Page navigation — The browser navigates to the target page while a network listener captures all .m3u8 requests
3. M3U8 interception — When the video player loads, it requests an HLS master playlist — miyuki-dlp intercepts this URL from network traffic
4. UUID fallback — If no M3U8 is captured via network (e.g. lazy-loaded players), miyuki-dlp extracts the video UUID from the page source and constructs the playlist URL directly
5. Quality selection — The master playlist is fetched and parsed to list available resolutions; the user's preferred quality is selected
6. Parallel download — Segments are downloaded with 16 concurrent HTTP/2 connections, then concatenated and remuxed to MP4 via ffmpeg

Troubleshooting

Cloudflare blocks the request

• The browser auto-relaunches in headed mode if Cloudflare is detected — on first run, a visible browser window is expected
• If auto-detection fails, force headed mode: --headful
• Clear the browser profile: rm -rf ~/.miyuki-dlp/chrome-profile
• Increase timeout: --timeout 60
• Make sure you have Google Chrome (not just Chromium) installed

ffmpeg not found

Install ffmpeg for your platform:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

M3U8 not captured

• Increase the timeout: miyuki-dlp --timeout 60 <url>
• Run in verbose mode: miyuki-dlp -v <url>
• The page may require interaction (e.g. clicking a play button) — currently not supported automatically

Download fails or produces corrupted file

• Check your ffmpeg version: ffmpeg -version (v6+ recommended)
• The stream may have expired — try re-running the command
• Check disk space in the output directory

License

MIT