HLS.js - JavaScript HLS Client

Common errors

• Uncaught ReferenceError: Hls is not defined

  cause HLS.js was not properly imported or made globally available (e.g., when using a CDN script without a global `Hls` object, or incorrect module import).
  fix Ensure HLS.js is imported using `import Hls from 'hls.js';` in modern module environments, or that the library's UMD build is loaded via a `<script>` tag before it's referenced, making `Hls` available globally.

• HLS.js error: networkError - fatal: true - manifestLoadError

  cause The HLS manifest (.m3u8 file) could not be retrieved or parsed due to an incorrect URL, network issues, CORS restrictions, or server configuration problems.
  fix Verify the manifest URL is correct and accessible. Check browser developer tools for network errors (404, 403, CORS issues) and server logs. Ensure the server is correctly configured to serve `.m3u8` files with appropriate MIME types and CORS headers. Load the manifest URL directly in a browser to confirm accessibility.

• Hls.js fatal error: keySystemError - keySystemNoKeys

  cause This error indicates a problem with the Encrypted Media Extensions (EME) setup for DRM, specifically that no valid decryption keys were provided or could be obtained from the license server. This often occurs with FairPlay Streaming, PlayReady, or Widevine.
  fix Review your DRM configuration, license server URL, and key acquisition process. Ensure `keyDrmSystem` is correctly specified and that the license server is responding with valid decryption keys for the content. Check browser console for EME-specific errors.

• MediaSource is not supported

  cause The browser or device does not support the Media Source Extensions (MSE) API, which HLS.js relies upon for playback. This is common on older browsers or some mobile Safari versions (which have native HLS support).
  fix Implement a fallback for browsers without MSE support. For iOS Safari, this typically means directly assigning the HLS manifest URL to the `<video src>` attribute, as Safari has native HLS support. For other unsupported browsers, display an error message or provide an alternative player.

• HLS.js error: mediaError - fatal: true - bufferStalledError

  cause The video buffer has stalled, meaning HLS.js could not append new media segments fast enough, leading to playback interruption. This can be caused by network issues, slow servers, incorrect segment parsing, or excessive buffering limits.
  fix Implement error recovery mechanisms using `hls.recoverMediaError()` for `MEDIA_ERROR`. Check network conditions, server performance, and stream health. Adjust HLS.js configuration parameters related to buffering, such as `maxBufferLength` or `maxMaxBufferLength`, or `liveMaxLatencyDuration` for live streams.

Warnings

• breaking HLS.js v1.0.0 and above transitioned to an ESM-first architecture. Projects relying on CommonJS `require()` or older browser compatibility (e.g., Internet Explorer) will encounter breaking changes. This also affects how web workers are configured when using bundlers with ESM.
  Fix: Migrate your project to use ES module `import` syntax. If using bundlers like Webpack with ESM, ensure the `workerPath` configuration option is set to point to `dist/hls.worker.js` if web workers are enabled. For older browser support, consider using the UMD/ES5 build or specific polyfills.
• gotcha Content Protection (DRM) setups, particularly for PlayReady and FairPlay Streaming, are complex and frequently involve specific platform requirements and manifest parsing nuances. Common issues include incorrect key ID handling or endianness problems, leading to 'keyId is null' errors or failed decryption.
  Fix: Refer to the HLS.js documentation on DRM and Encrypted Media Extensions (EME). Ensure correct manifest generation, key server responses, and `EXT-X-KEY` tag attributes. Updates in HLS.js v1.6.15 and v1.6.12 specifically address PlayReady and FairPlay parsing issues.
• deprecated The `hls.currentLevel` property no longer pauses the media element by default when switching quality levels. This change can lead to stall errors if playback doesn't resume quickly enough after a level change, particularly in manual quality switching implementations.
  Fix: Applications implementing manual quality switching should explicitly pause the video (`video.pause()`) or set `video.playbackRate = 0` before changing `hls.currentLevel` and resume playback (`video.play()`) once the level switch is complete to prevent stalls.
• gotcha HLS.js cannot be instantiated or used in Node.js environments. Attempting to `require()` or `import` the library in Node.js will result in a dummy object being exported, and no HLS playback functionality will be available.
  Fix: HLS.js is a browser-specific library relying on Media Source Extensions. It is not designed for server-side processing or Node.js environments. Implement browser-side logic for HLS playback.
• breaking The `v1.7.0-alpha.x` releases introduce a number of significant changes that are likely to be breaking. These are not feature-complete and are intended for early testing and feedback.
  Fix: Avoid using alpha releases in production environments unless specifically testing new features. Consult the v1.7.0 milestone page and planning board on GitHub for detailed changes and migration guidance when a stable v1.7.0 is released.

Install

• npm install hls.js npm
• yarn add hls.js yarn
• pnpm add hls.js pnpm

Imports

• Hls
  wrong:

  const Hls = require('hls.js');

  correct:

  import Hls from 'hls.js';

  Hls.js is primarily an ESM module since v1.0.0, especially when bundled. Using `require` will result in a dummy object in Node.js or import errors in browser environments.
• Hls.Events
  wrong:

  import { Events } from 'hls.js';

  correct:

  import Hls from 'hls.js';
  hls.on(Hls.Events.MANIFEST_PARSED, handler);

  Event constants are exposed as static properties of the default `Hls` export. Direct named import of `Events` is incorrect.
• HlsConfig
  wrong:

  import { HlsConfig } from 'hls.js';

  correct:

  import type { HlsConfig } from 'hls.js';

  When using TypeScript, configuration types like `HlsConfig` should be imported using `import type` to prevent bundling issues and clarify intent.

Quickstart

This quickstart demonstrates how to initialize HLS.js, attach it to an HTML5 video element, load an HLS manifest, and handle common fatal errors for recovery. It includes a check for browser compatibility and a fallback for native HLS playback.

import Hls from 'hls.js';

const video = document.getElementById('video') as HTMLVideoElement;
const manifestUrl = 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8';

if (Hls.isSupported()) {
  const hls = new Hls({
    // Example configuration for a live stream with limited back buffer
    liveSyncDurationCount: 3,
    liveMaxLatencyDuration: 10,
    // workerPath: '/path/to/hls.worker.js' // Required if using ESM build with workers
  });

  hls.on(Hls.Events.MEDIA_ATTACHED, () => {
    console.log('Media attached to video element.');
    hls.loadSource(manifestUrl);
  });

  hls.on(Hls.Events.MANIFEST_PARSED, (event, data) => {
    console.log(`Manifest loaded, found ${data.levels.length} quality level(s).`);
    // Optionally set quality level, e.g., to the highest available
    // hls.currentLevel = data.levels.length - 1;
    video.play();
  });

  hls.on(Hls.Events.ERROR, (event, data) => {
    if (data.fatal) {
      console.error(`Hls.js fatal error: ${data.type} - ${data.details}`, data);
      switch (data.type) {
        case Hls.ErrorTypes.NETWORK_ERROR:
          console.error('Network error detected, trying to recover...');
          hls.startLoad();
          break;
        case Hls.ErrorTypes.MEDIA_ERROR:
          console.error('Media error detected, trying to recover...');
          hls.recoverMediaError();
          break;
        default:
          // Cannot recover
          hls.destroy();
          break;
      }
    }
  });

  hls.attachMedia(video);
} else if (video.canPlayType('application/vnd.apple.mpegurl')) {
  // Native HLS support for Safari, etc.
  video.src = manifestUrl;
  video.addEventListener('loadedmetadata', () => {
    video.play();
  });
} else {
  console.error('This browser does not support HLS playback.');
}