` (See [#5074](https://github.com/video-dev/hls.js/issues/3988)) - #5074
Not Supported
- Advanced variant selection based on runtime media capabilities (See issues labeled [media-capabilities](https://github.com/video-dev/hls.js/labels/media-capabilities))
- HLS Content Steering
- HLS Interstitials
-
#EXT-X-GAP filling
#2940- #EXT-X-I-FRAME-STREAM-INF I-frame Media Playlist files
- SAMPLE-AES with fmp4, aac, mp3, vtt... segments (MPEG-2 TS only)
- FairPlay, PlayReady, Widevine DRM with MPEG-2 TS segments
- FairPlay legacy keys (For com.apple.fps.1_0 use native Safari playback)
- Advanced variant selection based on runtime media capabilities (See issues labeled [media-capabilities](https://github.com/video-dev/hls.js/labels/media-capabilities))
Server-side-rendering (SSR) and require from a Node.js runtime
You 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.
Getting started with development
First, checkout the repository and install the required dependencies
- ```sh
- 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/.
Join the discussion on Slack via
video-dev.org in #hlsjs for updates and questions about development.
Build tasks
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 than webpacks' - 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:
- AudioStreamController
- AudioTrackController
- CuesInterface
- EMEController
- SubtitleStreamController
- SubtitleTrackController
- TimelineController
- CmcdController
Linter (ESlint)
Run linter:
Run linter with auto-fix mode:
Run linter with errors only (no warnings)
Formatting Code
Run prettier to format code
Type Check
Run type-check to verify TypeScript types
Automated tests (Mocha/Karma)
Run all tests at once:
Run unit tests:
Run unit tests in watch mode:
- ```
- npm run test:unit:watch
- ```
Run functional (integration) tests:
Design
An overview of this project's design, it's modules, events, and error handling can be found
here.
API docs and usage guide
Demo
Latest Release
Master
Specific Version
Compatibility
HLS.js is only compatible with browsers supporting MediaSource extensions (MSE) API with 'video/MP4' mime-type inputs.
HLS.js is supported on:
- Chrome 39+ for Android
- Chrome 39+ for Desktop
- Firefox 41+ for Android
- Firefox 42+ for Desktop
- Edge for Windows 10+
- Safari 8+ for MacOS 10.10+
- Safari for ipadOS 13+
Please note: iOS Safari on iPhone does not support the MediaSource API. This includes all browsers on iOS as well as apps using UIWebView and WKWebView.
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
Using HLS.js
Installation
Prepackaged builds are included
with each release. Or install the hls.js as a dependency
of your project:
- ```sh
- 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
- ```
Embedding HLS.js
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:
- ```html
- <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.
- //
- // Note: it would be more normal to wait on the 'canplay' event below however
- // on Safari (where you are most likely to find built-in HLS support) the
- // video.src URL must be on the user-driven white-list before a 'canplay'
- // event will be emitted; the last video event that can be reliably
- // listened-for when the URL is not on the white-list is 'loadedmetadata'.
- else if (video.canPlayType('application/vnd.apple.mpegurl')) {
- video.src = videoSrc;
- }
- </script>
- ```
Alternative setup
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.
- ```html
- <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>
- ```
CORS
All HLS resources must be delivered with
CORS headers permitting
GET requests.
Video Control
Video is controlled through HTML `