Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/puemos/hls-downloader/llms.txt

Use this file to discover all available pages before exploring further.

​
Common issues

​
No playlists detected

If the extension doesn’t capture any streams:
Not all videos use HLS. Check if the page uses .m3u8 playlists:
  1. Open browser DevTools (F12)
  2. Go to the Network tab
  3. Play the video
  4. Filter requests by “m3u8”
  5. If you see .m3u8 files, the stream uses HLS
If no .m3u8 files appear, the video uses a different streaming protocol (DASH, progressive download, etc.) and this extension cannot capture it.
The extension must be running when the page loads:
  1. Ensure the extension is installed and enabled
  2. Refresh the page completely (Ctrl+R or Cmd+R)
  3. Start video playback
  4. Check the extension popup for detected playlists
If you installed the extension after loading the page, it won’t capture streams that loaded before activation.
Verify the extension has necessary permissions:
  1. Open browser extension settings (e.g., chrome://extensions)
  2. Find HLS Downloader
  3. Ensure it has permissions for:
    • Web requests
    • Downloads
    • Storage
    • Tabs
  4. Re-enable if any permissions were disabled
If automatic detection fails, add the playlist manually:
  1. Copy the .m3u8 URL from DevTools Network tab
  2. Open the extension popup
  3. Go to the Sniffer tab
  4. Paste the URL in the input field
  5. Click Add
This bypasses automatic network sniffing.

​
Download fails or stops

Fragment downloads require stable connectivity:
  • Ensure you have a stable internet connection
  • Avoid switching networks mid-download
  • Increase Fetch attempts in Settings for unreliable connections
  • Try downloading during off-peak hours if server is slow
Too many parallel requests can overwhelm servers:
  1. Open the extension popup
  2. Go to Settings
  3. Decrease Fragment concurrency to 2 or 3
  4. Click Retry download on the failed job
Lower concurrency reduces server load and can improve success rates.
Expand the job card in the Downloads tab to see detailed error messages:
  • Decryption errors: The stream uses unsupported encryption (e.g., DRM)
  • 403 Forbidden: Server blocks requests (try manual download or check access)
  • 404 Not Found: Fragments expired or URL invalid
  • Network error: Connection lost during download
Error messages provide clues for diagnosis.
Some quality levels may have issues:
  1. Go back to the playlist selection
  2. Choose a different video quality or audio track
  3. Start a new download
Lower quality streams may be more reliable if high-quality variants fail.

​
Extension icon doesn’t update

Icon updates only after successful playlist parsing:
  • Parsing can take a few seconds for large manifests
  • Check the Sniffer tab manually to see if playlists are listed
  • The icon updates per-tab, so ensure you’re looking at the correct tab
Sometimes the background script needs a refresh:
  1. Go to browser extension settings
  2. Find HLS Downloader
  3. Click the reload/refresh button
  4. Reload the page with the video
  5. Check again

​
Muxing takes forever

FFmpeg processing is CPU-intensive:
  • Muxing a 2-hour 1080p video can take 5-10 minutes
  • Progress is shown in the Downloads tab
  • Do not close the browser tab or popup during muxing
  • Consider downloading lower quality for faster processing
FFmpeg runs in your browser and uses CPU/memory:
  • Close unnecessary browser tabs
  • Free up system RAM
  • Ensure your computer isn’t thermal throttling
  • Desktop browsers generally perform better than mobile

​
Encrypted content fails

The extension supports AES-128 only:
  1. View the playlist in the Sniffer tab
  2. Click Open to see encryption details
  3. If the message says “unsupported encryption,” the stream uses DRM or another method
  4. AES-128 streams with keys in the manifest are supported
DRM-protected content (Widevine, FairPlay, PlayReady) cannot be decrypted by this extension.
Some AES-128 keys are access-restricted:
  • The extension must be able to fetch decryption keys from the URLs in the manifest
  • If keys are behind authentication or expire quickly, decryption may fail
  • Check the Downloads tab for specific decryption error messages

​
Save dialog doesn’t appear

You may have disabled the save prompt:
  1. Open the extension popup
  2. Go to Settings
  3. Check the Save dialog toggle
  4. If disabled, files save directly to your default download folder
  5. Enable it if you want to choose a location each time
Your browser may be set to always download to a specific folder:
  1. Open browser settings
  2. Search for “Downloads”
  3. Ensure “Ask where to save each file before downloading” is enabled
  4. Restart the browser if you change this setting

​
Jobs disappear after reload

This is expected behavior. Playlists and download jobs are not persisted across extension reloads or browser restarts.
To avoid losing jobs:
  • Wait for active downloads to finish before closing the browser
  • Use the Save as button to re-save completed jobs before reloading
  • Keep the browser open until muxing completes
Persistence of jobs is a known limitation. If you’d like to see this improved:
  1. Visit the GitHub issues page
  2. Search for existing persistence requests
  3. Add a comment or upvote to express interest

​
Browser-specific issues

​
Firefox

If you installed via about:debugging:
  • The extension is removed when Firefox restarts
  • Reinstall as a temporary add-on each session
  • Or install from Firefox Add-ons for persistence
Extensions may not work in private windows:
  1. Go to about:addons
  2. Click HLS Downloader
  3. Enable “Run in Private Windows” if needed

​
Chrome / Chromium

Manual installations require Developer mode:
  1. Go to chrome://extensions/
  2. Enable Developer mode toggle (top right)
  3. Restart Chrome if the extension doesn’t appear
Unpacked extensions may be disabled:
  1. Chrome warns about developer mode extensions on startup
  2. Click “Enable” or dismiss the warning
  3. Alternatively, package the extension as a .crx (not recommended for security)

​
Edge

For the best experience on Edge:

​
Brave

Brave’s shields may interfere:
  1. Click the Brave icon in the address bar
  2. Disable shields for the specific site if downloads fail
  3. Re-enable after capturing the playlist

​
Performance optimization

​
Speed up downloads

For faster downloads on stable connections:
  1. Go to Settings
  2. Increase Fragment concurrency to 6-10
  3. Monitor for failed fragments
  4. Reduce if you see frequent failures
Process multiple jobs simultaneously:
  1. Go to Settings
  2. Increase Active downloads or set to Unlimited
  3. Be aware that multiple jobs use more CPU and memory

​
Reduce memory usage

Fewer parallel requests reduce memory footprint:
  1. Go to Settings
  2. Decrease Fragment concurrency to 2-3
  3. Downloads will be slower but use less RAM
Delete finished jobs to free up memory:
  1. Go to the Downloads tab
  2. Click the chevron on completed jobs
  3. Click Delete
  4. IndexedDB buckets are cleaned up automatically

​
Reporting issues

If you encounter a bug or unexpected behavior:
1

Check existing issues

Visit the GitHub issues page and search for similar reports.
2

Gather information

Collect details to help diagnose:
  • Browser name and version
  • Extension version (visible in the About tab)
  • Page URL (if not sensitive)
  • Steps to reproduce
  • Error messages from the Downloads tab or browser console
3

Open a new issue

If no existing issue matches:
  1. Click New Issue on GitHub
  2. Choose the “Bug Report” template
  3. Fill in all requested information
  4. Attach screenshots if helpful
The more details you provide, the easier it is to diagnose and fix issues.

​
Getting help

For questions or assistance:
The project is open source and maintained by the community. Response times may vary.

Build docs developers (and LLMs) love

Get started for freeTalk to us