Skip to main content
HLS Downloader offers multiple build variants to accommodate different distribution requirements and user preferences.

​
Overview

Two primary build variants exist:
  1. Store builds - Include a blocklist for official distribution platforms
  2. Experimental builds - No blocklist restrictions for personal use
Each variant is available in both Manifest V2 and V3 formats.

​
Store builds

Official releases distributed through Firefox Add-ons and Edge Add-ons include a blocklist that respects copyright holder opt-out requests.

​
Blocklist behavior

The extension checks visited domains against a maintained blocklist and disables stream detection on matching sites. Current blocklist contents:
blocklist.json
[
  "tiktok.com",
  "douyin.com"
]

​
Why blocklists exist

Store builds comply with distribution platform policies and honor opt-out requests from content owners who do not want the extension to operate on their websites.
Website operators can request to be added to the blocklist by:
  1. Creating an opt-out request issue
  2. Using the title format: [Opt-Out Request] YourDomain.com
  3. Providing verification information (domain and contact email)

​
Distribution channels

Store builds are available through:

​
Experimental builds

Alternative builds for advanced users who prefer complete local control. These variants:
  • Contain no blocklist
  • Allow unrestricted operation on all websites
  • Are named differently to distinguish from store versions
  • Are intended for personal use only
Experimental builds are not submitted to official extension stores. They’re designed for users who prefer to manually install and manage their extensions.

​
Naming convention

Experimental builds use a distinctive name: 
experimental unstable nightly beta alpha hls-downloader
This naming:
  • Clearly identifies non-store variants
  • Prevents confusion with official releases
  • Signals the experimental nature of the build

​
Build process

The name change happens during asset copying:
scripts/copy-assets.mjs
if (process.env.NO_BLOCKLIST === "true") {
  const manifestContent = await import(path.join(assetsDir, manifestFile), {
    assert: { type: "json" },
  });
  const manifest = manifestContent.default;
  manifest.name = "experimental unstable nightly beta alpha hls-downloader";

  await fs.writeFile(
    path.join(distDir, "manifest.json"),
    JSON.stringify(manifest, null, 2)
  );
}
See scripts/copy-assets.mjs:26-38 for the implementation.

​
Building variants

The package.json scripts provide convenient commands for each variant:

​
Store builds (with blocklist)

pnpm run build:mv2
Outputs:
  • dist/mv2/ - Build artifacts
  • extension-mv2-chrome.zip - Chromium package
  • extension-mv2-firefox.xpi - Firefox package
Used for:
  • Firefox Add-ons submission
  • Edge Add-ons submission (legacy)

​
Experimental builds (no blocklist)

pnpm run build:mv2:no-blocklist
Outputs:
  • dist/mv2-no-blocklist/ - Build artifacts
  • extension-mv2-no-blocklist-chrome.zip
  • extension-mv2-no-blocklist-firefox.xpi
Used for:
  • Firefox manual installation
  • Personal testing and development

​
Build all variants

Generate every combination at once: 
pnpm run build:all-variants
Outputs:
  • All four variants (MV2/MV3 × store/experimental)
  • Eight total files (4 dist directories + 4 archives)
The build-variant.mjs script orchestrates variant builds:
scripts/build-variant.mjs
const mvVersion = values.mv; // 'mv2' or 'mv3'
const hasBlocklist = values.blocklist !== undefined
  ? values.blocklist
  : values["no-blocklist"] === true
    ? false
    : true;

const blocklistSuffix = hasBlocklist ? "" : "-no-blocklist";
const distDir = `dist/${mvVersion}${blocklistSuffix}`;
const zipBasename = `extension-${mvVersion}${blocklistSuffix}`;

const env = {
  ...process.env,
  DIST_DIR: distDir,
  MV_TARGET: mvVersion,
  ZIP_BASENAME: zipBasename,
  ...(mvVersion === "mv3" && { MAKE_FIREFOX: "false" }),
  ...(!hasBlocklist && { NO_BLOCKLIST: "true", VITE_NO_BLOCKLIST: "true" }),
};
See scripts/build-variant.mjs:16-37 for the complete logic.

​
Environment variables

Key build environment variables:
VariableValuesEffect
MV_TARGETmv2, mv3Selects manifest version
NO_BLOCKLISTtrue, unsetRemoves blocklist checking
VITE_NO_BLOCKLISTtrue, unsetPasses no-blocklist flag to Vite
DIST_DIRpathCustomizes output directory
ZIP_BASENAMEstringCustomizes archive filename
MAKE_FIREFOXtrue, falseControls .xpi generation

​
Choosing the right variant

​
Use store builds if:

  • You want automatic updates from official stores
  • You prefer vetted, reviewed extensions
  • You’re okay with blocklist restrictions
  • You’re not technical and want simple installation

​
Use experimental builds if:

  • You need unrestricted operation
  • You’re comfortable with manual installation
  • You want to customize or modify the extension
  • You understand the legal implications
Legal responsibility: Users are solely responsible for how they use HLS Downloader. Downloading copyrighted content without permission may violate laws in your jurisdiction.

​
Distribution guidelines

Experimental builds are for personal use only. Do not:
  • Submit them to official extension stores
  • Redistribute them publicly
  • Use them to circumvent copyright protections
The project maintainers:
  • ✅ Honor legitimate opt-out requests
  • ✅ Update the blocklist in store builds
  • ✅ Provide source code for transparency
  • ❌ Do not endorse piracy or copyright violation

Build docs developers (and LLMs) love

Get started for freeTalk to us