HLS Downloader

Capture and download HTTP Live Streams (HLS) straight from your browser.
Free • Open Source • MIT Licensed

📖 Table of Contents

• Features
• Get It
• Installation
• Usage
• Development
• Contribution
• Code of Conduct
• License

✨ Features

• Automatic stream discovery Detects HLS playlists on the page the moment you open it. No DevTools sniffing required.
• Fine-grained quality control Pick any combination of video resolution (240p → 4K) and audio language/bit-rate before you download, so you never waste bandwidth on the wrong track.
• 100% local, disk-backed merge with ffmpeg.wasm A WebAssembly build of FFmpeg muxes the chosen audio + video into a standard MP4 or MKV while keeping media fragments and final output in browser-managed storage. * Nothing is uploaded, keeping your files private.
• Works everywhere you browse Verified on Firefox, Edge, Chrome, Brave, Arc, and other Chromium-based browsers, on Windows, macOS, and Linux.

📦 Get It

Browser	Download / availability
Google Chrome	Experimental MV3 build available from source (see Development section).
Firefox	Get it on Firefox Add-ons or use manual installation
Microsoft Edge	Get it from Edge Add-ons
Brave	Use manual installation
Arc	Use manual installation
Opera	Use manual installation

^{*For Brave/Arc/etc. download the ZIP from the latest release and follow the manual-install steps below.}

Current releases require Firefox 128 or newer, or Chromium 111 or newer.

🛠️ Installation

Newer versions (≥ 4.1.2) ship only a ZIP archive.
Older versions can still be installed from the CRX (see the collapsible notes).

Chrome

1. Download extension-mv3-chrome.zip from the latest release.
2. Extract the ZIP to a convenient folder.
3. Open chrome://extensions/ and enable Developer mode.
4. Click Load unpacked and select the extracted folder (the one that contains manifest.json).
5. Enjoy 🎉

Brave

1. Download extension-mv3-chrome.zip from the latest release.
2. Extract the ZIP to a convenient folder.
3. Open brave://extensions/ and enable Developer mode.
4. Click Load unpacked and select the extracted folder (the one that contains manifest.json).
5. Enjoy 🎉

Arc

1. Download extension-mv3-chrome.zip from the latest release.
2. Extract the ZIP to a convenient folder.
3. Open Arc Menu → Extensions → Manage Extensions (or press Command+T or Ctrl+T and type Manage Extensions), then enable Developer mode.
4. Click Load unpacked and select the extracted folder (the one that contains manifest.json).
5. Enjoy 🎉

Opera

1. Download extension-mv3-chrome.zip from the latest release.
2. Extract the ZIP to a convenient folder.
3. Open opera://extensions/ and enable Developer mode.
4. Click Load unpacked and select the extracted folder (the one that contains manifest.json).
5. Enjoy 🎉

Firefox

1. Opem about:debugging#/runtime/this-firefox.
2. Click Load Temporary Add-on... and pick the XPI.

For Dear Testers – concise build/install steps for Firefox & Chromium reviewers.

🎬 Usage

1. Browse to a page that plays an HLS video and start playback.
2. Click the HLS Downloader icon – detected playlists appear in the Sniffer tab.
3. Choose Select next to a playlist.
4. Pick your video & audio streams, then press Download.
5. Grab a coffee ☕ – ffmpeg.wasm merges everything and your browser prompts you to save the MP4 when done.

The extension needs enough free disk space for both the downloaded fragments and the finalized media file. Browser storage estimates can be conservative and are treated as informational when unlimited storage permission is active. Downloads started by an older extension version remain readable through the legacy IndexedDB path, but are not migrated; if a legacy finalization runs out of memory, delete it and download it again.

🧑‍💻 Development

Clone & Build

Requires Node.js 22.12+ and the zip command. Firefox release builds use Node.js 22.12.0, npm 10.9.0, and pnpm 10.34.4 exactly.

git clone https://github.com/puemos/hls-downloader.git
cd hls-downloader

# install the pinned pnpm version through npm
npm install --global pnpm@10.34.4

pnpm install --frozen-lockfile
pnpm run build    # outputs → ./dist/, extension-chrome.zip, extension-firefox.xpi

# verify build artifacts then clean up
pnpm run clean

MV2 vs MV3 builds

The default build targets Manifest V2 (Firefox and legacy Chromium workflows). To produce a Manifest V3 bundle for Chromium-based browsers (Firefox does not fully support MV3 background service workers yet):

MV_TARGET=mv3 pnpm run build   # writes manifest v3 + offscreen page to dist/
pnpm run clean                 # optional: remove artifacts after testing

You can generate both flavors at once with pre-named artifacts:

pnpm run build:all          # outputs dist/mv2 + dist/mv3
# zips: extension-mv2-chrome.zip / extension-mv2-firefox.xpi  (MV2 contents at archive root)
#       extension-mv3-chrome.zip                            (MV3 contents at archive root; Chromium only)

For Firefox Add-ons source review, use the exact reproduction steps in AMO_SOURCE_REVIEW.md. Do not upload a stale local source-code.zip; pnpm run publish:firefox creates a fresh source archive from the committed release revision.

Tip: If pnpm is missing, run npm install --global pnpm@10.34.4 to match the locked toolchain. Do not use the Corepack bundled with Node.js 22.12.0; its pnpm signing keys are obsolete.

Run tests & generate coverage badge:

pnpm test          # unit tests
pnpm test:coverage # combined coverage + badge

Run the local browser e2e smoke test:

pnpm test:e2e:local

This builds the MV3 extension, launches Brave on macOS with the unpacked extension, opens a real online HLS stream with audio/video/WebVTT subtitles, verifies Sniffer, preview, playlist selection, download, and saved .mkv or equivalent media-container output, then removes generated extension artifacts. The downloaded media file stays in a temp directory and the script prints its path so you can review it manually. It is intentionally not part of CI and skips when CI=true. Set E2E_BROWSER=/path/to/Brave Browser for a custom Brave binary path, E2E_HLS_URL=https://.../playlist.m3u8 to override the stream, or E2E_CLEAN_DOWNLOAD=1 to delete the downloaded file after the run.

Live Development

pnpm dev        # watches & rebuilds into dist/
pnpm storybook  # preview popup & design-system components

Project Structure

src/
├─ assets/          # extension manifest & icons
├─ background/      # background scripts
├─ core/            # shared logic & Redux store
├─ design-system/   # UI component library
└─ popup/           # React popup UI

🤝 Contributing

We ♥ PRs! See the contributing guide and automation guide.

git checkout -b feature/my-awesome-idea
# ...code...
git commit -am "feat: add awesome idea"
git push origin feature/my-awesome-idea
# open PR 🎉

📜 Code of Conduct

TLDR: Be kind This project follows the Contributor Covenant.

🚧 Build Variants

HLS Downloader is available in multiple build variants to accommodate different distribution requirements:

Store Builds (Firefox Add-ons / Edge Add-ons)

Official store releases include a blocklist that respects copyright holder opt-out requests. This version complies with distribution platform policies and content owner preferences.

Independent Builds

Alternative builds are available for advanced users who prefer complete local control. These "experimental" variants contain no blocklist and allow unrestricted operation:

# MV2 without blocklist (Firefox/Edge manual install)
pnpm run build:mv2:no-blocklist

# MV3 without blocklist (Chrome/Brave/Arc manual install)
pnpm run build:mv3:no-blocklist

# Build all variants at once
pnpm run build:all-variants

Non-blocklist builds are named "HLS Downloader (Experimental No Blocklist)" and are intended for personal use only—not for redistribution on official stores.

🤚 Disclaimer

This extension is designed for downloading video content that you own or have authorization to access. It is prohibited to use this tool for downloading copyrighted content without permission. Users are solely responsible for their actions, and the developer assumes no liability for user behavior. This tool is provided "as-is" without warranty of any kind.

🚫 Copyright Protection and Opt-Out Policy

We respect the intellectual property rights and legitimate interests of all websites and content operators.

If you do not wish this tool to operate on your website, you may submit an opt-out request. We will add verified domains to the project's blocklist in subsequent releases.

How to Submit an Opt-Out Request

1. Create a new Issue using the "Opt-Out Request" template
2. Use the title format: [Opt-Out Request] YourDomain.com
3. Provide the following information for verification:
   • Website Domain (e.g., example.com)
   • Contact Email (for identity verification if necessary)

We commit to honoring legitimate requests and will include verified domains in the blocklist for store-distributed versions. Please note that as an open-source project, update cycles may vary. Thank you for your understanding and cooperation.

📝 License

The MIT License (MIT)

Copyright (c) 2025 Shy Alter

More: https://github.com/puemos/hls-downloader/blob/master/LICENSE

Made with ♥ by puemos