hls.js is a JavaScript library that allows you to play HLS (HTTP Live Streaming) streams in browsers that do not support it natively. It works by using Media Source Extensions (MSE) to play HLS streams in browsers like Chrome, Firefox, and Edge.
Basic HLS Playback
This code demonstrates how to set up basic HLS playback using hls.js. It checks if HLS is supported, creates an instance of Hls, loads the HLS stream, attaches it to a video element, and starts playback once the manifest is parsed.
const video = document.getElementById('video');
if (Hls.isSupported()) {
const hls = new Hls();
hls.loadSource('https://path/to/your/hls/playlist.m3u8');
hls.attachMedia(video);
hls.on(Hls.Events.MANIFEST_PARSED, function () {
video.play();
});
}Error Handling
This code demonstrates how to handle errors in hls.js. It listens for the ERROR event and logs the error type and details. If the error is fatal, it attempts to recover based on the type of error.
hls.on(Hls.Events.ERROR, function (event, data) {
const errorType = data.type;
const errorDetails = data.details;
const errorFatal = data.fatal;
console.error('Error type:', errorType);
console.error('Error details:', errorDetails);
if (errorFatal) {
switch (errorType) {
case Hls.ErrorTypes.NETWORK_ERROR:
console.error('Fatal network error encountered, try to recover');
hls.startLoad();
break;
case Hls.ErrorTypes.MEDIA_ERROR:
console.error('Fatal media error encountered, try to recover');
hls.recoverMediaError();
break;
default:
hls.destroy();
break;
}
}
});Quality Level Selection
This code demonstrates how to select a specific quality level for playback. It listens for the MANIFEST_PARSED event, logs the available quality levels, and sets the current level to 720p.
hls.on(Hls.Events.MANIFEST_PARSED, function (event, data) {
const availableQualities = hls.levels.map(level => level.height);
console.log('Available qualities:', availableQualities);
hls.currentLevel = availableQualities.indexOf(720); // Set to 720p
});Video.js is a web video player built from the ground up for an HTML5 world. It supports HLS through plugins like videojs-http-streaming (VHS). Compared to hls.js, Video.js offers a more comprehensive solution for video playback with a wide range of plugins and customization options.
Shaka Player is an open-source JavaScript library for adaptive media. It supports DASH and HLS and is known for its robustness and extensive feature set. Compared to hls.js, Shaka Player offers more advanced features like offline playback and wide support for DRM.
Clappr is an extensible media player for the web. It supports HLS out of the box and is designed to be highly customizable. Compared to hls.js, Clappr provides a more flexible and modular approach to building media players.
HLS.js is a JavaScript library that implements an HTTP Live Streaming client. It relies on HTML5 video and MediaSource Extensions for playback.
It works by transmuxing MPEG-2 Transport Stream and AAC/MP3 streams into ISO BMFF (MP4) fragments. Transmuxing is performed asynchronously using a Web Worker when available in the browser. HLS.js also supports HLS + fmp4, as announced during WWDC2016.
HLS.js works directly on top of a standard HTML<video> element.
HLS.js is written in ECMAScript6 (*.js) and TypeScript (*.ts) (strongly typed superset of ES6), and transpiled in ECMAScript5 using Babel and the TypeScript compiler.
Rollup is used to build the distro bundle and serve the local development environment.
For details on the HLS format and these tags' meanings, see https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis
#EXT-X-STREAM-INF:<attribute-list>
<URI>#EXT-X-MEDIA:<attribute-list>#EXT-X-SESSION-DATA:<attribute-list>#EXT-X-SESSION-KEY:<attribute-list> EME Key-System selection and preloading#EXT-X-START:TIME-OFFSET=<n>#EXT-X-CONTENT-STEERING:<attribute-list> Content Steering#EXT-X-DEFINE:<attribute-list> Variable Substitution (NAME,VALUE,QUERYPARAM attributes)The following properties are added to their respective variants' attribute list but are not implemented in their selection and playback.
VIDEO-RANGE (See #2489)#EXTM3U#EXT-X-VERSION=<n>#EXTINF:<duration>,[<title>]#EXT-X-ENDLIST#EXT-X-MEDIA-SEQUENCE=<n>#EXT-X-TARGETDURATION=<n>#EXT-X-DISCONTINUITY#EXT-X-DISCONTINUITY-SEQUENCE=<n>#EXT-X-BYTERANGE=<n>[@<o>]#EXT-X-MAP:<attribute-list>#EXT-X-KEY:<attribute-list> (KEYFORMAT="identity",METHOD=SAMPLE-AES is only supports with MPEG-2 TS segments)#EXT-X-PROGRAM-DATE-TIME:<attribute-list>#EXT-X-START:TIME-OFFSET=<n>#EXT-X-SERVER-CONTROL:<attribute-list>#EXT-X-PART-INF:PART-TARGET=<n>#EXT-X-PART:<attribute-list>#EXT-X-SKIP:<attribute-list> Delta Playlists#EXT-X-RENDITION-REPORT:<attribute-list>#EXT-X-DATERANGE:<attribute-list> Metadata
#EXT-X-DEFINE:<attribute-list> Variable Import and Substitution (NAME,VALUE,IMPORT,QUERYPARAM attributes)#EXT-X-GAP (Skips loading GAP segments and parts. Skips playback of unbuffered program containing only GAP content and no suitable alternates. See #2940)The following tags are added to their respective fragment's attribute list but are not implemented in streaming and playback.
#EXT-X-BITRATE (Not used in ABR controller)Parsed but missing feature support
#EXT-X-PRELOAD-HINT:<attribute-list> (See #5074)
For a complete list of issues, see "Top priorities" in the Release Planning and Backlog project tab. Codec support is dependent on the runtime environment (for example, not all browsers on the same OS support HEVC).
#EXT-X-I-FRAME-STREAM-INF I-frame Media Playlist filesSAMPLE-AES method keys with fmp4, aac, mp3, vtt... segments (MPEG-2 TS only)require from a Node.js runtimeYou can safely require this library in Node and absolutely nothing will happen. A dummy object is exported so that requiring the library does not throw an error. HLS.js is not instantiable in Node.js. See #1841 for more details.
First, checkout the repository and install the required dependencies
git clone https://github.com/video-dev/hls.js.git
cd hls.js
# After cloning or pulling from the repository, make sure all dependencies are up-to-date
npm install ci
# Run dev-server for demo page (recompiles on file-watch, but doesn't write to actual dist fs artifacts)
npm run dev
# After making changes run the sanity-check task to verify all checks before committing changes
npm run sanity-check
The dev server will host files on port 8000. Once started, the demo can be found running at http://localhost:8000/demo/.
Before submitting a PR, please see our contribution guidelines. Join the discussion on Slack via video-dev.org in #hlsjs for updates and questions about development.
Build all flavors (suitable for prod-mode/CI):
npm install ci
npm run build
Only debug-mode artifacts:
npm run build:debug
Build and watch (customized dev setups where you'll want to host through another server - for example in a sub-module/project)
npm run build:watch
Only specific flavor (known configs are: debug, dist, light, light-dist, demo):
npm run build -- --env dist # replace "dist" by other configuration name, see above ^
Note: The "demo" config is always built.
NOTE: hls.light.*.js dist files do not include alternate-audio, subtitles, CMCD, EME (DRM), or Variable Substitution support. In addition, the following types are not available in the light build:
AudioStreamControllerAudioTrackControllerCuesInterfaceEMEControllerSubtitleStreamControllerSubtitleTrackControllerTimelineControllerCmcdControllerRun linter:
npm run lint
Run linter with auto-fix mode:
npm run lint:fix
Run linter with errors only (no warnings)
npm run lint:quiet
Run prettier to format code
npm run prettier
Run type-check to verify TypeScript types
npm run type-check
Run all tests at once:
npm test
Run unit tests:
npm run test:unit
Run unit tests in watch mode:
npm run test:unit:watch
Run functional (integration) tests:
npm run test:func
An overview of this project's design, it's modules, events, and error handling can be found here.
Note you can access the docs for a particular version using "https://github.com/video-dev/hls.js/tree/deployments"
https://hlsjs.video-dev.org/demo
https://hlsjs-dev.video-dev.org/demo
Find the commit on https://github.com/video-dev/hls.js/tree/deployments.
HLS.js is only compatible with browsers supporting MediaSource extensions (MSE) API with 'video/MP4' mime-type inputs.
HLS.js is supported on:
A Promise polyfill is required in browsers missing native promise support.
Please note:
Safari browsers (iOS, iPadOS, and macOS) have built-in HLS support through the plain video "tag" source URL. See the example below (Using HLS.js) to run appropriate feature detection and choose between using HLS.js or natively built-in HLS support.
When a platform has neither MediaSource nor native HLS support, the browser cannot play HLS.
Keep in mind that if the intention is to support HLS on multiple platforms, beyond those compatible with HLS.js, the HLS streams need to strictly follow the specifications of RFC8216, especially if apps, smart TVs, and set-top boxes are to be supported.
Find a support matrix of the MediaSource API here: https://developer.mozilla.org/en-US/docs/Web/API/MediaSource
Prepackaged builds are included with each release. Or install the hls.js as a dependency of your project:
npm install --save hls.js
A canary channel is also available if you prefer to work off the development branch (master):
npm install hls.js@canary
Directly include dist/hls.js or dist/hls.min.js in a script tag on the page. This setup prioritizes HLS.js MSE playback over native browser support for HLS playback in HTMLMediaElements:
<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<!-- Or if you want the latest version from the main branch -->
<!-- <script src="https://cdn.jsdelivr.net/npm/hls.js@canary"></script> -->
<video id="video"></video>
<script>
var video = document.getElementById('video');
var videoSrc = 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8';
if (Hls.isSupported()) {
var hls = new Hls();
hls.loadSource(videoSrc);
hls.attachMedia(video);
}
// HLS.js is not supported on platforms that do not have Media Source
// Extensions (MSE) enabled.
//
// When the browser has built-in HLS support (check using `canPlayType`),
// we can provide an HLS manifest (i.e. .m3u8 URL) directly to the video
// element through the `src` property. This is using the built-in support
// of the plain video element, without using HLS.js.
else if (video.canPlayType('application/vnd.apple.mpegurl')) {
video.src = videoSrc;
}
</script>
To check for native browser support first and then fallback to HLS.js, swap these conditionals. See this comment to understand some of the tradeoffs.
<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<!-- Or if you want the latest version from the main branch -->
<!-- <script src="https://cdn.jsdelivr.net/npm/hls.js@canary"></script> -->
<video id="video"></video>
<script>
var video = document.getElementById('video');
var videoSrc = 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8';
//
// First check for native browser HLS support
//
if (video.canPlayType('application/vnd.apple.mpegurl')) {
video.src = videoSrc;
//
// If no native HLS support, check if HLS.js is supported
//
} else if (Hls.isSupported()) {
var hls = new Hls();
hls.loadSource(videoSrc);
hls.attachMedia(video);
}
</script>
HLS transcoding of an original video file often pushes the time of the first frame a bit. If you depend on having an exact match of frame times between original video and HLS stream, you need to account for this:
let tOffset = 0;
const getAppendedOffset = (eventName, { frag }) => {
if (frag.type === 'main' && frag.sn !== 'initSegment' && frag.elementaryStreams.video) {
const { start, startDTS, startPTS, maxStartPTS, elementaryStreams } = frag;
tOffset = elementaryStreams.video.startPTS - start;
hls.off(Hls.Events.BUFFER_APPENDED, getAppendedOffset);
console.log('video timestamp offset:', tOffset, { start, startDTS, startPTS, maxStartPTS, elementaryStreams });
}
}
hls.on(Hls.Events.BUFFER_APPENDED, getAppendedOffset);
// and account for this offset, for example like this:
const video = document.querySelector('video');
video.addEventListener('timeupdate', () => setTime(Math.max(0, video.currentTime - tOffset))
const seek = (t) => video.currentTime = t + tOffset;
const getDuration = () => video.duration - tOffset;
For more embed and API examples see docs/API.md.
All HLS resources must be delivered with CORS headers permitting GET requests.
Video is controlled through HTML <video> element HTMLVideoElement methods, events and optional UI controls (<video controls>).
The following players integrate HLS.js for HLS playback:
 |  |  |  |
 |  |  |  |
 |  |  |  |
 |  |  |  |
 |  |  | |
 |  |  |  |
 |  |  |  |
 |  |  |  |
| cdn77 |  |  |  |
 |  |  |
made by gramk, plays hls from address bar and m3u8 links
HLS.js is released under Apache 2.0 License
FAQs
JavaScript HLS client using MediaSourceExtension
The npm package hls.js receives a total of 552,825 weekly downloads. As such, hls.js popularity was classified as popular.
We found that hls.js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.