Manifest versions

HLS Downloader supports both Manifest V2 (MV2) and Manifest V3 (MV3) extension architectures. This guide explains the differences and helps you choose the right version.

Overview

The extension uses different manifest versions to accommodate browser requirements:

Manifest V2 - Default for Firefox and legacy Chromium workflows
Manifest V3 - Required for modern Chromium-based browsers (Chrome, Brave, Arc, Edge)

Firefox does not fully support MV3 background service workers yet, so the MV2 build is recommended for Firefox users.

Key differences

Background execution

Manifest V2
Manifest V3

Uses persistent background pages that remain active throughout the browser session.

src/assets/manifest.json

{
  "manifest_version": 2,
  "background": {
    "scripts": ["background.js"],
    "persistent": true
  }
}

Characteristics:

Background page stays alive continuously
Direct access to DOM and IndexedDB
Works with Firefox and older Chromium versions

Uses service workers that activate on-demand and may be terminated when idle.

src/assets/manifest.chrome.json

{
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js",
    "type": "module"
  }
}

Characteristics:

Service worker lifecycle (can be terminated)
No direct DOM access from background
Required for Chrome Web Store submissions
Uses offscreen documents for DOM operations

Permissions model

MV3 separates host permissions from regular permissions:

{
  "permissions": [
    "webRequest",
    "unlimitedStorage",
    "storage",
    "downloads",
    "tabs",
    "http://*/*",
    "https://*/*"
  ]
}

Content security policy

MV3 requires a different CSP format:

{
  "content_security_policy": "script-src 'self' 'wasm-unsafe-eval' 'unsafe-eval'; object-src 'self'"
}

Both versions require 'wasm-unsafe-eval' to support ffmpeg.wasm for video merging.

Offscreen documents (MV3 only)

Manifest V3 service workers cannot directly access DOM APIs or create object URLs. HLS Downloader uses offscreen documents to work around this limitation.

What are offscreen documents?

Offscreen documents are invisible HTML pages that run alongside the service worker, providing access to DOM APIs like IndexedDB and Blob URLs.

Implementation

The extension creates an offscreen document when needed:

src/background/src/services/indexedb-fs.ts

async function ensureOffscreenDocument() {
  if (!chromeApi?.offscreen?.createDocument) {
    return;
  }

  const hasDocument = await chromeApi.offscreen.hasDocument?.();
  if (hasDocument) {
    return;
  }

  await chromeApi.offscreen.createDocument({
    url: "offscreen.html",
    reasons: [chromeApi.offscreen.Reason.BLOBS],
    justification: "Create object URLs for download blobs",
  });
}

Use cases

The offscreen document handles:

Creating object URLs for download blobs
Managing IndexedDB operations for large file storage
Generating progress updates during merge operations

How offscreen messaging works

The background service worker sends messages to the offscreen document:

// Background sends request
chrome.runtime.sendMessage({
  target: "offscreen",
  type: "create-object-url",
  bucketId: "download-123",
  requestId: "req-456"
});

// Offscreen document responds
chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
  if (message?.target !== "offscreen") {
    return;
  }
  
  if (message.type === "create-object-url") {
    handleCreateObjectUrl(message)
      .then(response => sendResponse(response));
    return true;
  }
});

See src/background/src/offscreen.ts:16-34 for the full implementation.

When to use each version

Use Manifest V2 if:

You’re installing on Firefox
You need a persistent background page
You’re using legacy Chromium versions

Use Manifest V3 if:

You’re installing on Chrome, Brave, Arc, Edge, or Opera
You want the latest Chrome-compatible build
You’re preparing for future Chrome Web Store requirements

Chrome Web Store no longer accepts new MV2 extensions. If you’re distributing publicly, you must use MV3.

Building different versions

The build system generates both versions:

MV2 only
MV3 only
Both versions

MV_TARGET=mv2 pnpm run build

Outputs:

dist/ - Build artifacts
extension-chrome.zip - Chromium package
extension-firefox.xpi - Firefox package

MV_TARGET=mv3 pnpm run build

Outputs:

dist/ - Build artifacts with offscreen.html
extension-chrome.zip - Chromium package only

pnpm run build:all

Outputs:

dist/mv2/ - MV2 build artifacts
dist/mv3/ - MV3 build artifacts
extension-mv2-chrome.zip
extension-mv2-firefox.xpi
extension-mv3-chrome.zip

The build system automatically includes offscreen.html when building for MV3. See scripts/copy-assets.mjs:46-51 for the copy logic.

Browser compatibility

Browser	Recommended Version	Notes
Firefox	MV2	MV3 service workers not fully supported
Chrome	MV3	Required for Web Store
Edge	MV3	Official store uses MV3
Brave	MV3	Chromium-based
Arc	MV3	Chromium-based
Opera	MV3	Chromium-based

Build variants - Learn about store vs experimental builds
Chrome MV3 migration guide
Firefox MV3 status

Getting Started

User Guide

Development

Advanced

Overview

Key differences

Background execution

Permissions model

Content security policy

Offscreen documents (MV3 only)

What are offscreen documents?

Implementation

Use cases

When to use each version

Use Manifest V2 if:

Use Manifest V3 if:

Building different versions

Browser compatibility

Build docs developers (and LLMs) love

Getting Started

User Guide

Development

Advanced

​Overview

​Key differences

​Background execution

​Permissions model

​Content security policy

​Offscreen documents (MV3 only)

​What are offscreen documents?

​Implementation

​Use cases

​When to use each version

​Use Manifest V2 if:

​Use Manifest V3 if:

​Building different versions

​Browser compatibility

​Related resources

Build docs developers (and LLMs) love

Overview

Key differences

Background execution

Permissions model

Content security policy

Offscreen documents (MV3 only)

What are offscreen documents?

Implementation

Use cases

When to use each version

Use Manifest V2 if:

Use Manifest V3 if:

Building different versions

Browser compatibility

Related resources