Library / SDK
video-dev/hls.js avatar
video-dev/hls.js

hls.js ships an ES5 bundle and a size budget, from modern source

HLS.js is a JavaScript library that plays HLS in browsers with support for MSE.

17,053 stars2,780 forksTypeScriptNOASSERTION

At a glance

What is it?
hls.js is a browser HLS client that transmuxes MPEG-2 transport streams and AAC or MP3 audio into fragmented MP4 for the Media Source Extensions API, in a Web Worker where one exists. Its source is TypeScript, its UMD bundles are transpiled to ES5 while its ESM bundles use native module syntax, and it publishes two builds selected by import path, with a bundle size budget file and a size check script.
Who is it for?
hls.js fits a web player that has to play HLS in browsers with no plugin, and it gives you a feature set covering subtitles, timed metadata, interstitials and trick play. It does not fit a build with a tight JavaScript budget that nobody is thinking about, because the full build carries all of that.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • video-dev/hls.js17,053 ★ · +105
Star history
Repository2026-09-212026-11-15
video-dev/hls.js16.9k17.1k

105 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

It transmuxes into fragments and hands them to a plain video element

The mechanism is four sentences in the opening and they are worth reading closely. The library is an HTTP Live Streaming client, it relies on the HTML5 video element and Media Source Extensions for playback, and it works by transmuxing MPEG-2 transport streams and AAC or MP3 audio into ISO base media file format fragments. Transmuxing happens asynchronously in a Web Worker where the browser provides one. So the video element you already have is the player, and the library's job is parsing, buffering and feeding it. The conditional is the part with consequences: the UMD bundles inline the transmuxer worker, but the ESM bundles do not, so with those you set workerPath to the published hls.worker.js to transmux off the main thread.

The source is modern and the bundle you ship is ES5

The build story is stated in one sentence and it is unusual. The library is written in TypeScript and transpiled using Babel to ECMAScript 5 for the UMD bundles and to native ES module syntax for the ESM bundles, with the TypeScript compiler and API Extractor used for type checking and type declarations, and Rollup building the bundles and, in watch mode, the local development environment. The consequence for the UMD bundles is a hard compatibility floor chosen on purpose, and it is enforced rather than assumed: the repository carries a configuration file for checking the target language version, and the continuous integration build ends by running that check. The cost is bundle size, since downlevelling syntax adds code, and the project fights that cost with automation of its own, a script that measures the distribution and a check mode of it, and a budget file the check compares against.

There are two builds, and the import path is the only switch

The package manifest publishes two entry points and the difference is the whole of the choice you make:

json
  "exports": {
    ".": {
      "import": "./dist/hls.mjs",
      "require": "./dist/hls.js"
    },
    "./light": {
      "import": "./dist/hls.light.mjs",
      "require": "./dist/hls.light.js"
    },
    "./dist/*": "./dist/*",
    "./package.json": "./package.json"
  },

Each entry point resolves to both a module build and a CommonJS build, and there is a passthrough for the distribution directory and the manifest. The published files include the source as well as the build, so you are not forced to take the bundle. The trap is that the specifier itself carries no information: the README says the light build leaves out optional features such as alternate audio, subtitles, EME (DRM), CMCD and Interstitials, so that is what you read before choosing.

Two qualifiers run through the feature list: runtime support and full build

Read the feature list with its parentheses in hand, because the same caveat appears twice in different forms. Video codecs including HEVC, AV1, VP9 and Dolby Vision, and audio codecs including AC-3, EC-3, FLAC, Opus and ALAC, are each marked as subject to runtime support, and there is a documented attribute for selecting codecs in the playlist when the stream offers a choice. Separately, two entries are marked as available in the full build only: the H.265 elementary stream and the ATSC A/52 AC-3 stream. So a codec appearing in a feature list can be missing for two unrelated reasons, and they fail the same way on screen. That is why the codec selection attribute exists at all, and it is the reason you should verify the codecs you need against both the build you ship and the browsers you support rather than against the list.

The tag list is the most useful page, because it says what gets ignored

There is a section enumerating the supported playlist tags, and it is annotated in a way most players are not. Some tags are marked as parsed and ignored: the version tag, whose value is ignored, and the independent segments tag, which is ignored outright. Others carry a behavioural note, such as the gap tag, which skips loading those segments and skips playback of an unbuffered stretch containing only gap content with no suitable alternate, with a link to the issue tracking it. The sample-aes form of the key tag is supported only with MPEG-2 transport stream segments, which is a real limitation stated in place. And there is a separate category for tags that are parsed but whose feature is missing, currently one entry, the preload hint tag, again with an issue link. A silently ignored tag is how a stream plays and then drifts from the specification, so this page is the one to read.

Three quality-switching modes, and a buffer you can seek inside

Adaptive streaming is described with more precision than usual, and the three modes are worth knowing by name because they are the knob you will actually turn. Instant switching changes quality immediately at the current video position. Smooth switching applies the change at the next loaded fragment. Bandwidth conservative switching applies it at the next fragment too, without flushing the buffer, which is the one that trades a little adaptation speed for a stall-free picture. All three are controllable through the API, and in automatic mode the library also switches down urgently when bandwidth drops suddenly, in order to reduce buffering. Seeking is described with the same care: accurate seeking on both on-demand and live streams that is not limited to a fragment or keyframe boundary, and the ability to seek within the buffer and the back buffer without downloading segments again.

Errors get a retry mechanism, recovery actions and an events API

Resilience is a feature section rather than a troubleshooting page, which tells you something about the project's shape. There is a retry mechanism inside the library, and recovery actions that can be triggered to fix fatal media or network errors, alongside failover and redundant playlists when the origin provides them. Then there is built-in analytics, described as the ability to monitor all internal events, with network events and video events, playback session metrics exposed, and support for Common Media Client Data. Content steering is there too, for a player that has to follow a decision made elsewhere. The practical instruction is to wire the events up before you need them, because a library that retries silently and reports on request gives you a player that looks fine until the day it does not.

Editorial conclusion

hls.js fits a web player that has to play HLS in browsers with no plugin, and it gives you a feature set covering subtitles, timed metadata, interstitials and trick play. It does not fit a build with a tight JavaScript budget that nobody is thinking about, because the full build carries all of that. Before you adopt it, read the supported tag list rather than the feature list, because several tags are parsed and deliberately ignored, and that is the failure you will not see in a demo. Then choose the build deliberately: the exports map offers a full and a light entry point, and the specifier tells you nothing about what the light one drops. And wire the analytics events up early, because the library treats network and video events as a first-class part of its API rather than something you add later.

Frequently asked questions

What does HLS js do?

It implements an HTTP Live Streaming client for browsers, relying on the HTML5 video element and Media Source Extensions. It transmuxes MPEG-2 transport streams and AAC or MP3 audio into fragmented MP4, asynchronously in a Web Worker where one is available, and it also supports streams already packaged as fragmented MP4.

what is hls js

It is a library that plays HLS in a browser with no plugin, sitting directly on top of a standard video element. Beyond playback it handles adaptive bitrate switching, subtitles in two formats, captions, timed metadata, digital rights management, ad interstitials, trick play, content steering and built-in analytics.

how to install hls js

It is published to a package registry as hls.js under the Apache 2.0 licence, and the published files include both the distribution bundle and the source. The manifest offers a full entry point and a light one, each with a module and a CommonJS build, so the choice of import path is what selects your build.

how to use hls js

Attach it to a video element, give it a source manifest, and let it drive playback and buffering. The knobs worth knowing are the three quality-switching modes, which are instant, smooth and bandwidth conservative and are all controllable through the API, plus the automatic mode's emergency switch down when bandwidth falls.

what is hls js error

Error handling is a documented feature rather than an accident. The library embeds a retry mechanism and exposes recovery actions that can be triggered to fix fatal media or network errors, supports redundant and failover playlists, and emits network and video events along with playback session metrics, so failures can be observed rather than guessed at.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. video-dev/hls.js on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/video-dev-hls-js.svg)](https://hysenlabs.com/projects/video-dev-hls-js)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/video-dev-hls-js.svg)](https://hysenlabs.com/projects/video-dev-hls-js)

Was this useful?