Usage

​

Getting started

HLS Downloader makes it easy to capture and download HTTP Live Streams directly from your browser. The extension automatically detects HLS playlists and guides you through selecting quality, audio tracks, and downloading your content.

​

Basic workflow

​

Extension tabs

The extension popup is organized into four main tabs:

​

Sniffer

The Sniffer tab shows all playlists automatically detected from the current page:

• Direct URL input: Paste a playlist URL manually and click Add to create a playlist entry without network sniffing
• Filter playlists: Use the filter input to search through detected playlists by title or URL
• Copy URLs: Copy all detected playlist URLs to your clipboard
• Clear all: Remove all detected playlists from the current session
• Playlist list: Each detected playlist shows the page title, detection time, and source initiator
• Expand details: Click the chevron to see the full playlist URL and action buttons
• Open playlist: Click Open to view available video, audio, and subtitle tracks

​

Downloads

The Downloads tab displays all active and completed download jobs:

• Filter downloads: Search through your download history
• Job cards: Each download shows filename, status badge, progress percentage, and metadata
• Expand details: Click the chevron to see full details, progress bars, and action buttons
• Job actions:
  • Download: Start a queued job
  • Cancel: Stop an active download
  • Save as: Re-save a completed file with a new name
  • Retry download: Restart a failed job
  • Delete: Remove the job from the list

​

Settings

Configure download behavior and performance options:

• Active downloads: Limit how many jobs run simultaneously (1-10 or unlimited)
• Fragment concurrency: Set how many fragments are fetched in parallel (impacts download speed)
• Fetch attempts: Configure retry count per fragment request (useful for unreliable connections)
• Save dialog: Toggle whether the browser prompts for a save location
• Preferred audio language: Auto-select audio tracks matching your preferred language when available

​

About

View extension information and quick links:

• Extension version
• Report bugs on GitHub
• View source code
• Read privacy policy
• Check MIT license
• Contribute to the project

​

Selecting tracks

When you open a playlist, the extension parses the master manifest and shows all available streams:

​

Video quality

Choose from available video renditions sorted from highest to lowest quality:

• Resolution (e.g., 1920×1080, 1280×720)
• Bitrate in mbps
• Frame rate (fps)

Click the clipboard icon to copy the video stream URL.

​

Audio tracks

Select your preferred audio track when multiple options are available:

• Language code (e.g., eng, spa, fra)
• Track name (if different from language)
• Channel count (e.g., 2ch, 6ch)
• Bitrate in mbps
• Default and auto-select indicators

Click the clipboard icon to copy the audio stream URL.

​

Subtitles and closed captions

Choose optional subtitle tracks when provided by the stream:

• Language code
• Track name
• Characteristics (e.g., SDH, forced)

Subtitles are saved as separate .vtt files alongside your video.

​

Download process

Once you click Download, the extension:

1. Fetches level playlists: Retrieves detailed playlist files for your selected video and audio tracks
2. Discovers fragments: Enumerates all video and audio fragments with absolute URLs, including initialization segments
3. Downloads fragments: Fetches fragments in parallel with configurable concurrency and retry attempts
4. Decrypts if needed: Uses Web Crypto API to decrypt AES-128 encrypted fragments when keys are present
5. Stores locally: Writes all fragments to IndexedDB buckets keyed by job ID
6. Muxes with ffmpeg: Runs ffmpeg.wasm in your browser tab to concatenate and merge audio + video into MP4
7. Creates download: Generates an object URL and triggers the browser save dialog

​

Progress tracking

Active downloads show detailed progress information:

• Progress bar: Visual indicator of completion percentage
• Fragment count: Shows completed fragments vs. total (e.g., 245/512)
• Status messages: Indicates current stage (downloading, decrypting, muxing, saving)
• Error details: Displays specific error messages if download fails

​

Manual URL entry

If automatic detection doesn’t capture a stream, you can add playlists manually:

1. Navigate to the Sniffer tab
2. Paste the full .m3u8 playlist URL in the input field
3. Click Add
4. The playlist appears in the list and can be opened like any detected stream

​

Managing playlists

​

Copy playlist URLs

Click Copy URLs in the Sniffer tab to copy all detected playlist URLs to your clipboard, separated by newlines.

​

Clear all playlists

Click Clear all to remove all detected playlists from the current session. This does not affect active downloads.

​

Filter playlists

Use the filter input to search playlists by page title, URL, or initiator. The list updates in real-time as you type.

​

Saving files

By default, the extension prompts you to choose a save location for each download. You can disable this in Settings to use your browser’s default download folder. Filenames are automatically generated from the page title and stream metadata. If a file with the same name exists, the browser adds a unique number suffix.