@lzwme/m3u8-dl

Language: English | 中文简体

A free, open-source, and powerful m3u8 video batch downloader with multi-threaded downloading, play-while-downloading, WebUI management, video parsing, and more. Supports multiple usage methods including CLI command line, browser, PC client, Docker deployment, and Node.js API calls.

✨ Features

🚀 Core Download Features

• Multi-threaded Downloading: Uses thread pool mode with customizable thread count, significantly improving download speed
• Play-While-Downloading Mode: Supports online playback using downloaded ts cache files without waiting for complete download
• Batch Downloading: Supports batch downloading of multiple m3u8 addresses, supports batch import from text files
• Resume from Cache: Failed downloads retain cache, retries only download failed segments, saving bandwidth and time
• AES Encryption Support: Automatically identifies and decrypts common AES-128 encrypted video streams
• Format Conversion: Automatically merges and converts downloaded ts segments to mp4 format (requires ffmpeg)
• Multi-format Support: Supports downloading video files in mp4, mkv, and other formats
• Segment Filtering: Supports ignoring video segments in specified time ranges (e.g., skip intro and outro)

🌐 WebUI Download Management

• Modern Interface: Modern web interface built with Vue 3 + TypeScript
• Real-time Progress: Real-time display of download progress and status via WebSocket
• Task Management: Supports pausing, resuming, and deleting download tasks, supports batch operations
• Download Center: Centralized management of all download tasks, supports search and filtering
• Configuration Management: Visual configuration of download parameters (thread count, save directory, etc.)
• Access Control: Supports setting access password (token) to protect the service

🎬 Video Parsing Features

• Multi-platform Support: Supports parsing video sharing links from platforms like Douyin, Weibo, Pipixia, etc.
• Watermark-free Download: Automatically extracts watermark-free video addresses and downloads
• Smart Recognition: Automatically recognizes video platforms and selects appropriate parsers

🔍 Smart m3u8 Address Extraction

• Web Page Extraction: Supports automatic extraction of m3u8 addresses from video playback pages
• Deep Search: Supports multi-level page search, automatically discovers video links
• Batch Extraction: Extract multiple video links at once, supports batch downloading

🎯 Browser Userscript Capture Tool

• Auto Capture: Automatically intercepts and captures m3u8 and mp4 video links in web pages
• Real-time Monitoring: Monitors network requests (XMLHttpRequest, fetch, Performance API), automatically discovers video links
• Smart Recognition: Automatically recognizes video types (M3U8/MP4) and extracts video names
• One-click Jump: Supports one-click jump to M3U8-DL WebUI for downloading
• Flexible Configuration: Supports configuring exclusion URL rules to avoid capturing on specific pages
• Draggable Panel: Supports dragging to move panel position, automatically saves position
• Link Management: Supports copying links, clearing list, and other operations

This is a Violentmonkey/Tampermonkey/Greasemonkey userscript that can automatically capture video links in browsers, working with M3U8-DL WebUI to provide a seamless download experience.

📺 Video Search Features

• Collection Site Support: Supports standard collection site APIs, search and download through command-line interaction
• Cache Mechanism: Automatically caches search history, supports continuing unfinished downloads

▶️ Video Playback

• Built-in Player: Both WebUI and desktop client have built-in lightweight video players, can directly play downloaded or downloading videos online without waiting for completion.
• Play-While-Downloading: Supports automatic splicing of ts cache segments, can play while downloading, achieving "download and watch" experience.
• Multi-format Support: Player supports playback of mainstream video formats like mp4, ts, with drag, speed control, fullscreen, picture-in-picture, and other operations.
• History: Automatically records playback progress, supports resume playback, convenient for long video series watching.

No need to rely on third-party players, you can directly watch downloaded content in the browser or client, improving convenience.

💻 Multiple Usage Methods

• Command Line Tool: Provides complete CLI commands with various parameter configurations
• Node.js API: Provides programming interface for easy integration into other projects
• Web Service: Supports starting as a web service, manage downloads through browser
• Docker Deployment: Provides Docker image for one-click deployment to server
• Electron Desktop App: Supports packaging as desktop application with built-in browser functionality

🌍 Internationalization Support

• Supports Chinese and English multi-language
• Both command line and WebUI support language switching

📦 Installation

Method 1: Global Installation with Node.js

Use as a CLI command-line tool.

npm i -g @lzwme/m3u8-dl
m3u8dl -h
Copy

Or use npx to run directly:

npx @lzwme/m3u8-dl -h
Copy

Method 2: Desktop Application Download

Install as a PC client. Easy to use, suitable for most regular users, with built-in browser functionality to automatically extract video addresses. Download the latest version from one of the following addresses:

• https://m3u8-player.lzw.me/download.html
• https://github.com/lzwme/m3u8-dl/releases

📖 Usage Guide

Tip: If you need to download and convert to mp4 video format, you need to globally install ffmpeg. Or use the --ffmpeg-path parameter to specify the path to ffmpeg.

Using as CLI Command Line Tool

View all available commands and options:

m3u8dl --help
Copy

Basic Download

# Download a single m3u8 file
m3u8dl https://example.com/video.m3u8

# Specify filename and save directory
m3u8dl https://example.com/video.m3u8 --filename "My Video" --save-dir "./downloads"

# Enable play-while-downloading mode
m3u8dl https://example.com/video.m3u8 --play

# Set thread count (default 4)
m3u8dl https://example.com/video.m3u8 --thread-num 8

# Don't convert to mp4 (only download ts segments)
m3u8dl https://example.com/video.m3u8 --no-convert

# Ignore specified time segments (e.g., skip first 30 seconds and last 60 seconds)
m3u8dl https://example.com/video.m3u8 --ignore-segments "0-30,END-60"
Copy

Batch Download

Method 1: Command Line Parameters

# Download multiple files, use | to separate filename and URL
m3u8dl "Episode 1|https://example.com/ep1.m3u8" "Episode 2|https://example.com/ep2.m3u8" --filename "Series Name"
Copy

Method 2: Batch Import from Text File

Create a series-list.txt file with the following format (use $ to separate filename and URL):

Episode 1$https://example.com/ep1.m3u8
Episode 2$https://example.com/ep2.m3u8
Episode 3$https://example.com/ep3.m3u8
Copy

Then execute:

m3u8dl series-list.txt --filename "Series Name"
Copy

Video Parsing Download

Supports sharing links from platforms like Douyin, Weibo, etc.:

# Douyin video sharing link
m3u8dl "https://v.douyin.com/xxxxx/" --type parser

# Weibo video sharing link
m3u8dl "https://weibo.com/xxxxx" --type parser
Copy

Extract m3u8 Address from Web Page

# Automatically extract m3u8 address from video playback page and download
m3u8dl "https://example.com/play/12345" --type web
Copy

Video Search Download

# View search command help
m3u8dl search --help

# Specify collection site API and search download (will cache API address)
m3u8dl search -u https://api.example.com/provide/vod/

# Search keyword directly
m3u8dl search "keyword" -u https://api.example.com/provide/vod/
Copy

Disclaimer: The above are examples only. Please search for available collection site APIs yourself. This tool is only for technical research and learning purposes and does not provide any specific resource information.

Common Command Line Options

Option	Description
-f, --filename <name>	Specify filename
-n, --thread-num <number>	Set download thread count (default 4)
-p, --play	Enable play-while-downloading mode
-C, --cache-dir <dirpath>	Specify cache directory
-S, --save-dir <dirpath>	Specify save directory
--no-convert	Don't convert to mp4
--no-del-cache	Don't delete cache after download completes
--ffmpeg-path <path>	Specify ffmpeg path
-H, --headers <headers>	Set request headers (JSON format)
-I, --ignore-segments <time>	Ignore specified time segments
--debug	Enable debug mode
--lang <lang>	Set language (zh-CN/en)

WebUI Download Management

Start web service to manage download tasks through browser:

# Start service (default port 6600)
m3u8dl server

# Specify port and access password
m3u8dl server -p 8080 -t "your-secret-token"
Copy

After starting, visit http://localhost:6600 in your browser to use WebUI.

WebUI Main Features:

• 📥 Create download tasks (supports m3u8 links, Weibo and Pipixia video sharing links, video playback page extraction)
• 📊 View download progress and speed in real-time
• ⏸️ Pause/Resume download tasks
• 🗑️ Delete tasks and downloaded files
• ⚙️ Configure download parameters (thread count, save directory, etc.)
• 🔍 Search and filter tasks
• 📁 View completed downloads

Environment Variable Configuration:

# Set port
export DS_PORT=6600

# Set access password
export DS_SECRET=your-secret-token

# Set save directory
export DS_SAVE_DIR=./downloads

# Set cache directory
export DS_CACHE_DIR=./cache

# Set ffmpeg path
export DS_FFMPEG_PATH=/usr/local/bin/ffmpeg

# Enable debug mode
export DS_DEBUG=1

# Limit file access (only allow access to download and cache directories)
export DS_LIMTE_FILE_ACCESS=1
Copy

Integration as Node.js API

Call related APIs in your project. Code examples:

import { m3u8Download, m3u8BatchDownload, VideoParser, getM3u8Urls } from '@lzwme/m3u8-dl';

// Example 1: Single file download
const result = await m3u8Download('https://example.com/video.m3u8', {
  filename: 'My Video',
  saveDir: './downloads',
  threadNum: 8,
  debug: true,
});

if (result.errmsg) {
  console.error('Download failed:', result.errmsg);
} else {
  console.log('Download successful:', result.filepath);
}

// Example 2: Batch download
const fileList = [
  'Episode 1$https://example.com/ep1.m3u8',
  'Episode 2$https://example.com/ep2.m3u8',
];
await m3u8BatchDownload(fileList, {
  filename: 'Series Name',
  threadNum: 4,
});

// Example 3: Video parsing download (Douyin, Weibo, etc.)
const parser = new VideoParser();
const parseResult = await parser.parse('https://v.douyin.com/xxxxx/');
if (parseResult.data) {
  console.log('Video title:', parseResult.data.title);
  console.log('Video URL:', parseResult.data.url);

  // Download video
  await parser.download('https://v.douyin.com/xxxxx/', {
    filename: parseResult.data.title,
  });
}

// Example 4: Extract m3u8 addresses from web page
const urls = await getM3u8Urls({
  url: 'https://example.com/play/12345',
  headers: {
    'User-Agent': 'Mozilla/5.0...',
  },
  deep: 2, // Search depth
});
console.log('Extracted addresses:', Array.from(urls.keys()));

// Example 5: Specify ffmpeg path
import ffmpegStatic from 'ffmpeg-static';
m3u8Download('https://example.com/video.m3u8', {
  filename: 'Test Video',
  ffmpegPath: ffmpegStatic, // Use ffmpeg-static package. Suitable for scenarios where ffmpeg is not globally installed
  // Or specify the absolute path of installed ffmpeg (if already in PATH environment variable, no need to specify)
  // ffmpegPath: '/usr/local/bin/ffmpeg',
});
Copy

Docker Deployment

Using Docker Command

# Pull image
docker pull renxia/m3u8dl-dl:latest

# Run container
docker run --rm -it \
  -v ./cache:/app/cache \
  -v ./downloads:/app/downloads \
  -p 6600:6600 \
  -e DS_PORT=6600 \
  -e DS_SECRET=your-secret-token \
  renxia/m3u8dl-dl:latest
Copy

Using Docker Compose

Create docker-compose.yml file:

services:
  m3u8-dl:
    image: renxia/m3u8dl-dl:latest
    container_name: m3u8-dl
    volumes:
      - ./downloads:/app/downloads
      - ./cache:/app/cache
    ports:
      - '6600:6600'
    environment:
      DS_PORT: '6600'
      DS_SAVE_DIR: '/app/downloads'
      DS_CACHE_DIR: '/app/cache'
      DS_SECRET: '' # Set access password
      DS_DEBUG: ''
      DS_FFMPEG_PATH: ''  # Leave empty to use ffmpeg from system PATH
      DS_LIMTE_FILE_ACCESS: '1' # Limit file access
    restart: unless-stopped
Copy

Start service:

docker-compose up -d
Copy

After successful deployment, visit http://your-server-ip:6600 in your browser to use.

Tip: The Docker image already includes ffmpeg, no need for additional installation. The image also includes AriaNg static resources.

Electron Desktop Application

The project supports packaging as an Electron desktop application with richer features:

• 🖥️ Native desktop experience
• 🌐 Built-in browser, supports extracting video links from web pages
• 📱 System tray support
• 🔄 Auto-update functionality

Download the built application:

• https://m3u8-player.lzw.me/download.html
• https://github.com/lzwme/m3u8-dl/releases

Browser Script Installation and Usage

Installation Steps:

1. Install browser extension (choose one):

   • Violentmonkey (【Recommended】Open-source alternative)
   • Tampermonkey (Supports Chrome, Firefox, Edge, Safari, etc.)
   • Greasemonkey (Firefox only)

2. Install script:

   • Open userscript manager (Violentmonkey/Tampermonkey) management panel
   • Click "Add new script"
   • Copy content from client/m3u8-capture.user.js file
   • Paste into editor and save
   • Or directly visit the link in browser: https://raw.githubusercontent.com/lzwme/m3u8-dl/refs/heads/main/client/m3u8-capture.user.js

3. Configure WebUI address:

   • Visit any web page, click the 🎬 icon in the top right corner to open the capture panel
   • Click the settings button ⚙️
   • Enter your M3U8-DL WebUI address (e.g., http://localhost:6600)
   • Save settings

Feature Description:

• Auto Capture: The script automatically monitors network requests in web pages, when m3u8 or mp4 video links are detected, automatically adds them to the list
• Video Name Extraction: Prioritizes extracting video names from page h1, h2, or document.title
• Jump to Download: Click the "Jump to Download" button to automatically jump to M3U8-DL WebUI and fill in video link and name (format: url|name)
• Exclusion Rules: In settings, you can configure exclusion URL rule list, matching URLs will not show panel and will not capture video links
  • Supports plain string matching (contains match)
  • Supports regular expressions (starts and ends with /, e.g., /example\.com/)

Usage Example:

1. Visit video playback page
2. Script automatically captures video links, displayed in the panel in the bottom right corner
3. Click "Jump to Download" button
4. Automatically jumps to M3U8-DL WebUI, video link and name are automatically filled
5. Click "Start Download" in WebUI

Exclusion Rule Configuration Example:

localhost:6600
127.0.0.1
/example\.com/
admin
Copy

Tip: The script automatically excludes WebUI address pages to avoid capturing in WebUI pages. You can also manually add more exclusion rules.

🛠️ Tech Stack

• Backend: Node.js + TypeScript + Express + WebSocket
• Frontend: Vue 3 + TypeScript + Vite + Pinia + TailwindCSS
• Desktop App: Electron
• Code Quality: Biome (Linter & Formatter)
• Build Tool: TypeScript Compiler

💻 Development Guide

Local Development

# Clone project
git clone https://github.com/lzwme/m3u8-dl.git
cd m3u8-dl

# Install dependencies
pnpm install

# Development mode (watch file changes and auto-compile)
pnpm dev

# Build project
pnpm build

# Code check
pnpm lint

# Code format
pnpm format

# Fix code issues
pnpm fix
Copy

Build desktop application:

# Enter application directory
cd packages/m3u8dl-app

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build application
pnpm build
Copy

Project Structure

m3u8-dl/
├── src/              # Source code (TypeScript)
│   ├── cli.ts        # Command line entry
│   ├── lib/          # Core library
│   ├── server/       # Web service
│   ├── video-parser/ # Video parser
│   └── types/        # Type definitions
├── packages/
│   ├── frontend/     # Vue 3 frontend project
│   ├── m3u8dl-app/   # Electron desktop application
│   └── m3u8-capture/ # Browser userscript (TypeScript + Vite)
├── cjs/              # Compiled CommonJS code
└── client/           # Frontend build output
    └── m3u8-capture.user.js  # Browser video address capture userscript (built from packages/m3u8-capture)
Copy

Contributing

Welcome to submit Issues and Pull Requests!

1. Fork this project
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request

Welcome to contribute ideas and code! 🎉

📚 Related Resources

• ffmpeg Download - Video processing tool
• m3u8 Format Specification - M3U8 playlist format
• Project Changelog - View version update history

🙏 Acknowledgments

Thanks to the following projects for inspiration and reference:

• m3u8-multi-thread-downloader
• m3u8Utils

License

@lzwme/m3u8-dl is released under the MIT license.

This plugin is developed and maintained by Zhiwen Studio.