# HLS Downloader: a browser extension that sniffs and muxes HLS streams to MP4 or MKV > HLS Downloader is an MIT-licensed web extension for Firefox, Edge and Chromium browsers that detects HTTP Live Streaming playlists on a page and merges the selected video and audio tracks locally with ffmpeg.wasm. This article covers how it works, how to install it, and where it falls short. **puemos/hls-downloader** — Web Extension for sniffing and downloading HTTP Live streams (HLS) - Repository: https://github.com/puemos/hls-downloader - Website: https://puemos.gitbook.io/hls-downloader/ - Stars: 2,713 · Forks: 303 - Language: TypeScript - License: MIT - Published: 2026-09-28 · Updated: 2026-09-28 · Language: en - Canonical page: https://hysenlabs.com/projects/puemos-hls-downloader ## The problem HLS Downloader addresses An HTTP Live Streaming stream is not a file. It is a manifest playlist that points at short media segments, usually split into separate video and audio renditions. Saving one with a browser's normal download command gets you a text playlist, not a video. The usual workaround is opening developer tools, filtering network requests for .m3u8, copying the URL into a separate command-line tool, and manually pairing the right audio rendition with the right video rendition. HLS Downloader removes the sniffing step and the manual pairing step. It is aimed at someone watching a lecture, a conference recording, or any other HLS-backed page in a desktop browser who wants a single playable file afterwards. The README describes the audience implicitly through the feature list: resolution choices from 240p to 4K and audio language or bit-rate selection, made before the download starts. That is a viewer's decision, not a pipeline engineer's. If you are building an automated capture system, this is the wrong shape of tool, because it lives inside a browser profile and expects a human to pick tracks. ## How the extension discovers playlists and muxes tracks The extension watches network traffic rather than the rendered page. When a page requests an HLS playlist, the extension records it, and the popup lists what it found. The README says detection happens "the moment you open it. No DevTools sniffing required." Once a playlist is selected, the user picks a combination of video resolution and audio language or bit-rate. The extension then fetches the media fragments and hands them to ffmpeg.wasm, a WebAssembly build of FFmpeg that runs inside the browser. That build muxes the chosen audio and video into a standard MP4 or MKV. The README states that media fragments and the final output stay in browser-managed storage and that "Nothing is uploaded, keeping your files private." The practical consequence is that the merge runs on the machine you are sitting at, so a long stream costs local CPU time and local disk space rather than server bandwidth. The repository layout backs up the architecture claim. The build is a pnpm workspace with separate packages under src: core, design-system, background and popup. Build scripts target each package individually (build:core, build:design-system, build:background, build:popup) before zipping the result. That split is consistent with a background script doing the network observation and a popup doing the track selection UI, with shared logic in core. The topics list also names redux-observable and clean-architecture, which fits the pattern of a stream of detected playlists feeding a state store. ## Installing HLS Downloader on Firefox, Edge, Chrome and Brave Firefox and Edge users get the simplest path. The README links to the Firefox Add-ons listing and to the Edge Add-ons listing, so installation is the normal store flow for those two browsers. Current releases require Firefox 128 or newer, or Chromium 111 or newer. Chrome, Brave, Arc and Opera are manual. The README says the Chrome build is an "Experimental MV3 build available from source" and directs you to the Development section. For the other Chromium browsers, download extension-mv3-chrome.zip from the latest release, extract it, enable Developer mode on the extensions page, and use Load unpacked against the folder that contains manifest.json. The README repeats those steps for each browser with the browser-specific extensions URL. ```bash # Nothing to run for the store installs. # For Chromium browsers, the manual steps are: # 1. Download extension-mv3-chrome.zip from the latest release # 2. Extract it to a folder # 3. Open chrome://extensions/ (or brave://extensions/, opera://extensions/) # 4. Enable Developer mode # 5. Load unpacked -> select the folder containing manifest.json ``` The README also notes that versions 4.1.2 and newer ship only a ZIP archive, while older versions were distributed as a CRX that you could drag onto the extensions page. If you are following an old tutorial that says to drag a .crx file, you are looking at the pre-4.1.2 instructions. Building from source is a separate path. The repository uses pnpm and states a Node engine requirement of >=22.12.0, with packageManager pinned to pnpm@10.34.4. ```bash pnpm run build:all ``` That script cleans previous output and produces both an MV2 and an MV3 variant. There are also no-blocklist variants (build:mv2:no-blocklist, build:mv3:no-blocklist), which suggests the default build embeds a blocklist file; the repository does contain a blocklist.json at the top level. The README does not explain what the blocklist does, so treat that as undocumented rather than assume a purpose. ## A first real download and what to check afterwards Open a page that plays an HLS stream, then open the extension popup. According to the README, the playlist should already be listed because discovery happens on page load. Select it, choose a video resolution and an audio track, and start the download. The extension fetches fragments, runs the WebAssembly FFmpeg merge, and produces an MP4 or MKV. The README does not document a progress indicator, a cancel path, or what happens if you close the tab mid-merge. That silence matters for long streams. Before committing to a two-hour capture, test the workflow on a short clip and confirm the output file plays end to end. Also confirm the file lands where you expect: the README says fragments and output live in browser-managed storage, which is not the same as your Downloads folder, and it does not describe an export step. If the popup shows nothing, the likely cause is that the page has not requested a playlist yet. Detection is tied to network activity, so a page that only loads the player on interaction, or one that uses a non-HLS delivery method, will produce no entries. ## Where HLS Downloader is the wrong tool The clearest limitation is platform coverage. There is no Safari build and no Android build described. The README's table lists Firefox, Edge, Chrome, Brave, Arc and Opera, all desktop browsers. Someone who watches HLS on a phone or in Safari has no path here, and the manual-install instructions are desktop-only. The second limitation is the Chrome install itself. Calling the MV3 build "experimental" and shipping it only from source means Chrome users do not get store updates. Every new release is a manual download, extract, and reload. That is a real maintenance cost, and it is the opposite of what most people expect from a Chrome extension. The third is automation. Everything runs through a popup and a browser profile. There is no documented CLI, no headless mode, and no API for scripting a batch of downloads. If you need to capture hundreds of streams on a schedule, a command-line downloader is the correct instrument and this is not. Finally, the README does not document failure handling. It does not say what happens when a playlist references a segment that 404s, when the stream is DRM-protected, or when the WebAssembly merge runs out of memory on a very long stream. Those are the cases worth testing yourself before depending on the tool for anything you cannot re-download. ## How it differs from a command-line HLS downloader The obvious alternative is a command-line tool built on FFmpeg, such as yt-dlp or a direct ffmpeg invocation against the playlist URL. The difference in approach is where the work happens and who does the sniffing. A command-line downloader needs the manifest URL as input. You find that URL yourself, usually through browser developer tools. It then runs as a native process, writes directly to a path you specify, and is trivially scriptable and repeatable. HLS Downloader inverts both properties: it finds the URL for you, and it runs the merge inside the browser through WebAssembly instead of a native binary. The trade is convenience for control. You get automatic discovery and a track picker without leaving the page, and you give up scripting, direct file paths, and native performance. For a one-off download of something you are already watching, the extension is less work. For anything repeated, scheduled, or run on a machine without a desktop session, the command-line route wins on every axis. Note also that ffmpeg.wasm is a reimplementation compiled to WebAssembly, not the same binary you would install from your package manager, so throughput and memory behaviour should not be assumed to match. ## Licence, maintenance and upgrade cost The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are included. That is permissive and carries no copyleft obligation. Nothing here is legal advice; read the LICENSE file in the repository for the actual terms. The repository is not archived, and the last push was on 2026-09-22. Recent releases are v5.5.0 on 2026-07-27, v5.4.4 on 2026-05-12 and v5.4.3 on 2026-05-12. That is a recent push and a recent release, so the codebase is being touched, though the README does not describe a support commitment or a release cadence. Upgrade cost splits by browser. Firefox and Edge users upgrade through the add-on stores. Chrome, Brave, Arc and Opera users re-download the ZIP and reload the unpacked extension for each release, unless they build from source. Anyone building from source needs Node >=22.12.0 and pnpm@10.34.4, and should expect the build to produce both MV2 and MV3 variants plus ZIP and XPI archives. The repository also carries a security:audit script that runs pnpm audit at moderate level and a patch verification step, which implies dependency patches are tracked deliberately; a fork that ignores that script may drift from upstream fixes. ## Conclusion Adopt HLS Downloader if you watch HLS content in a desktop Firefox, Edge or Chromium browser and want the muxing to happen on your own machine with no upload step. Skip it if you need a mobile or Safari workflow, a headless command-line downloader, or a Chrome Web Store install with automatic updates, since the Chrome build is an experimental MV3 package loaded unpacked from source. Before relying on it, confirm the release ZIP you downloaded contains manifest.json at its root and that your browser meets the stated floor of Firefox 128 or Chromium 111. ## FAQ ### What is HLS Downloader and what does it do? It is an MIT-licensed web extension that captures HTTP Live Streaming playlists from the pages you browse and downloads the media. It lets you choose a video resolution and an audio track, then muxes the two into an MP4 or MKV using ffmpeg.wasm inside the browser. ### How do I use the HLS Downloader extension? Open a page that plays an HLS stream and open the extension popup. The README states the playlist is detected on page load, so you select it, pick a resolution and audio track, and start the download. ### How do I install HLS Downloader in Chrome? The README describes the Chrome build as an experimental MV3 build available from source. Download extension-mv3-chrome.zip from the latest release, extract it, enable Developer mode at chrome://extensions/, and use Load unpacked on the folder containing manifest.json. Chrome requires version 111 or newer. ### Is HLS Downloader safe to use? The README states that the ffmpeg.wasm merge is 100% local and that nothing is uploaded, with media fragments and final output kept in browser-managed storage. The project is MIT licensed and the repository contains a PRIVACY.md file. No independent security audit is referenced. ### How do I download an HLS video? With HLS Downloader installed, open the page that plays the stream and use the extension popup. The README says the playlist is detected automatically, after which you choose the video resolution and audio track and start the download, which produces an MP4 or MKV. ## Sources - [License: MIT](https://github.com/puemos/hls-downloader/blob/master/LICENSE) - [Project website](https://puemos.gitbook.io/hls-downloader/) - [puemos/hls-downloader on GitHub](https://github.com/puemos/hls-downloader) - [README](https://github.com/puemos/hls-downloader/blob/master/README.md) - [Releases](https://github.com/puemos/hls-downloader/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/puemos-hls-downloader