1. Providers
  2. HLS Video


HLS Video

This provider enables streaming media using the HTTP Live Streaming (HLS) protocol.


You'll need to install hls.js if you're using the HLS provider locally (i.e., not over a CDN):

        npm i hls.js



This provider is used to embed streamable video content into documents using the native <video> element, and supports streaming media using the HTTP Live Streaming (HLS) protocol. HLS streaming is supported natively in some browsers (e.g., iOS Safari), otherwise, we fallback to using hls.js.


Loading hls.js

The HLS provider will default to loading the light version of hls.js from JSDelivr. We load the default bundle in development, and the minified version in production.


You can point library at any URL that re-exports hls.js@^1.0. This means you can use your own server or CDN if desired.

Importing hls.js

You can also load hls.js by statically, or dynamically importing it and setting the library property like so:


Or, you can dynamically import it like so:


Load Events

The provider will fire the following events while loading hls.js:

  • lib-load-start: Fired when we begin downloading the library.
  • lib-loaded: Fired when the library has been loaded.
  • lib-load-error: Fired when the library fails to download.

These events are fired regardless of how you decide to load the library (i.e., import or CDN).

Configuring hls.js

You can configure hls.js using the config property like so:


HLS Context

The hls instance property contains additional data such as the loaded hls.js constructor and instance. It can be accessed like so:


HLS Engine

If you need access to the hls.js instance, you can also listen to the instance event to be notified of when it's created (called before media is attached), and the destroying event for when it will be destroyed.


HLS Events

All hls.js events can be listened to directly off the <vds-hls-video> component. Some examples include:

  • Hls.Events.MEDIA_ATTACHED -> media-attached
  • Hls.Events.MANIFEST_LOADED -> manifest-loaded
  • Hls.Events.LEVEL_SWITCHING -> level-switching

All HLS event types are prefixed with HLS and end with Event like so:

        import {
  type HLSLevelSwitchingEvent,
  type HLSManifestLoadedEvent,
  type HLSMediaAttachedEvent,
} from 'vidstack';


Previous <- Video