What is hls.js?
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.
What are hls.js's main functionalities?
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
});
Other packages similar to hls.js
video.js
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
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
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.
Join the discussion via video-dev.org in #hlsjs (our Slack channel)
hls.js is a JavaScript library which 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.
This transmuxing could be performed asynchronously using Web Worker if available in the browser.
hls.js also supports HLS + fmp4, as announced during WWDC2016
hls.js does not need any player, it 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 the TypeScript compiler.
Modules written in TS and plain JS/ES6 can be interdependent and imported/required by each other.
To build our distro bundle and serve our development environment we use Webpack.
API docs and usage guide
Note you can access the docs for a particular version using "https://github.com/video-dev/hls.js/blob/deployments/README.md"
Demo
Latest Release
https://hls-js.netlify.com/demo
Master
https://hls-js-latest.netlify.com/demo
Specific Version
Find the commit on https://github.com/video-dev/hls.js/blob/deployments/README.md.
Getting Started
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="video"></video>
<script>
var video = document.getElementById('video');
if(Hls.isSupported()) {
var hls = new Hls();
hls.loadSource('https://video-dev.github.io/streams/x36xhzz/x36xhzz.m3u8');
hls.attachMedia(video);
hls.on(Hls.Events.MANIFEST_PARSED,function() {
video.play();
});
}
else if (video.canPlayType('application/vnd.apple.mpegurl')) {
video.src = 'https://video-dev.github.io/streams/x36xhzz/x36xhzz.m3u8';
video.addEventListener('loadedmetadata',function() {
video.play();
});
}
</script>
Video Control
Video is controlled through HTML <video>
element.
HTMLVideoElement control and events could be used seamlessly.
they use hls.js in production !
Player Integration
hls.js is (being) integrated in the following players:
Chrome/Firefox integration
made by gramk, plays hls from address bar and m3u8 links
Dependencies
No external JS libs are needed.
Prepackaged build is included with the releases.
If you want to bundle the application yourself, use node
npm install hls.js
or for the version from master (canary)
npm install hls.js@canary
NOTE: hls.light.*.js
dist files do not include subtitling and alternate-audio features.
Installation
Either directly include dist/hls.js or dist/hls.min.js
Or type
npm install --save hls.js
Optionally there is a declaration file available to help with code completion and hinting within your IDE for the hls.js api
npm install --save-dev @types/hls.js
Compatibility
hls.js is compatible with browsers supporting MediaSource extensions (MSE) API with 'video/MP4' mimetypes inputs.
Find a support matrix of the MediaSource API here: https://developer.mozilla.org/en-US/docs/Web/API/MediaSource
As of today, it is supported on:
- Chrome for Android 34+
- Chrome for Desktop 34+
- Firefox for Android 41+
- Firefox for Desktop 42+
- IE11+ for Windows 8.1+
- Edge for Windows 10+
- Opera for Desktop
- Vivaldi for Desktop
- Safari for Mac 8+ (beta)
Please note: iOS Safari "Mobile" does not support the MediaSource API. Safari browsers have however built-in HLS support through the plain video "tag" source URL. See the example above (Getting Started) 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, you will not be able to play HLS.
Server-side-rendering (SSR) and require
from a Node.js runtime
We support this now. You can safely require this library in Node and absolutely nothing will happen :) See https://github.com/video-dev/hls.js/pull/1841
(This is also known as "Universal builds" and "isomorphic apps")
CORS
All HLS resources must be delivered with CORS headers permitting GET
requests.
Features
- VoD & Live playlists
- DVR support on Live playlists
- fragmented MP4 container (beta)
- MPEG-2 TS container
- ITU-T Rec. H.264 and ISO/IEC 14496-10 Elementary Stream
- ISO/IEC 13818-7 ADTS AAC Elementary Stream
- ISO/IEC 11172-3 / ISO/IEC 13818-3 (MPEG-1/2 Audio Layer III) Elementary Stream
- Packetized metadata (ID3) Elementary Stream
- AAC container (audio only streams)
- MPEG Audio container (MPEG-1/2 Audio Layer III audio only streams)
- Timed Metadata for HTTP Live Streaming (in ID3 format, carried in MPEG-2 TS)
- AES-128 decryption
- SAMPLE-AES decryption (only supported if using MPEG-2 TS container)
- Encrypted media extensions (EME) support for DRM (digital rights management)
- Widevine CDM (beta/experimental) (see Shaka-package test-stream in demo)
- CEA-608/708 captions
- WebVTT subtitles
- Alternate Audio Track Rendition (Master Playlist with alternative Audio) for VoD and Live playlists
- Adaptive streaming
- Manual & Auto Quality Switching
- 3 Quality Switching modes are available (controllable through API means)
- Instant switching (immediate quality switch at current video position)
- Smooth switching (quality switch for next loaded fragment)
- Bandwidth conservative switching (quality switch change for next loaded fragment, without flushing the buffer)
- In Auto-Quality mode, emergency switch down in case bandwidth is suddenly dropping to minimize buffering.
- Accurate Seeking on VoD & Live (not limited to fragment or keyframe boundary)
- Ability to seek in buffer and back buffer without redownloading segments
- Built-in Analytics
- Every internal events could be monitored (Network Events,Video Events)
- Playback session metrics are also exposed
- Resilience to errors
- Retry mechanism embedded in the library
- Recovery actions could be triggered fix fatal media or network errors
- Redundant/Failover Playlists
Not Supported (Yet)
- MP3 Elementary Stream in Edge for Windows 10+
Supported M3U8 tags
License
hls.js is released under Apache 2.0 License
Development and contributing - first steps
Pull requests are welcome. Here is a quick guide on how to start.
- First, checkout the repository and install required dependencies
git clone https://github.com/video-dev/hls.js.git
cd hls.js
npm install
npm run dev
npm run lint
- Use EditorConfig or at least stay consistent to the file formats defined in the
.editorconfig
file. - Develop in a topic branch, not master
- Don't commit the updated
dist/hls.js
file in your PR. We'll take care of generating an updated build right before releasing a new tagged version.
Setup
After cloning or pulling from the repository, first of all, make sure your local node-modules are up-to-date with the package deps:
npm install
Build system (Webpack)
Build all flavors:
npm install
npm run build
Only debug:
npm run build:debug
Build and watch
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.
Build with bundle analyzer (to help optimize build size)
npm run build:analyze
Linter (ESlint)
Run 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
Automated tests (Mocha/Karma)
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
Design
Click here for details.
Tested With