hls.js

Summary

HLS.js v1.6.16 includes bug fixes and improvements over the last release.

Changes Since The Last Release

https://github.com/video-dev/hls.js/compare/v1.6.15...v1.6.16

• Fix Interstitials live start with short sliding window (#7799)
• Limit buffering while paused outside live sliding window (#7788)

Demo Page

https://121bff6b.hls-js-dev.pages.dev/demo/

Feedback

Please provide feedback via Issues in GitHub. For more details on how to contribute to HLS.js, see our CONTRIBUTING guide.

npm

npm

image

Sauce Test Status

jsDeliver

[comment]: <> ([![Sauce Test Status]&#40;https://saucelabs.com/browser-matrix/robwalch.svg&#41;]&#40;https://saucelabs.com/u/robwalch&#41;)

HLS.js

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.

[html5 video]: https://www.html5rocks.com/en/tutorials/video/basics/

[mediasource extensions]: https://w3c.github.io/media-source/

[http live streaming]: https://en.wikipedia.org/wiki/HTTP_Live_Streaming

[web worker]: https://caniuse.com/#search=worker

[ecmascript6]: https://github.com/ericdouglas/ES6-Learning#articles--tutorials

[typescript]: https://www.typescriptlang.org/

[typescript compiler]: https://www.typescriptlang.org/docs/handbook/compiler-options.html

[rollup]: https://rollupjs.org/

Features

• VOD & Live playlists
• DVR support on Live playlists
• Low-Latency HLS (Partial Segments, Blocking Playlist Reload, Playlist Delta Updates, and Rendition Reports)
• Fragmented MP4 container
• HEVC, AV1, VP9, and Dolby Vision video, subject to runtime support
• AC-3, EC-3, FLAC, Opus, and ALAC audio, subject to runtime support
• SUPPLEMENTAL-CODECS attribute for codec selection
• MPEG-2 TS container
• ITU-T Rec. H.264 and ISO/IEC 14496-10 Elementary Stream
• ITU-T Rec. H.265 and ISO/IEC 23008-2 Elementary Stream (full build only)
• ISO/IEC 13818-7 ADTS AAC Elementary Stream
• ISO/IEC 11172-3 / ISO/IEC 13818-3 (MPEG-1/2 Audio Layer III) Elementary Stream
• ATSC A/52 / AC-3 / Dolby Digital Elementary Stream (full build only)
• Packetized metadata (ID3v2.3.0) 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 (ID3 format carried in MPEG-2 TS, Emsg in CMAF/Fragmented MP4, and DATERANGE playlist tags)
• MISB KLV metadata in MPEG-2 TS (opt-in via enableEmsgKLVMetadata)
• AES-128, AES-256, and AES-256-CTR decryption
• "identity" format SAMPLE-AES decryption of MPEG-2 TS segments only
• Encrypted media extensions (EME) support for DRM (digital rights management)
• FairPlay, PlayReady, and Widevine CDMs with fmp4 segments
• Level capping based on HTMLMediaElement resolution, dropped-frames, and HDCP-Level
• CEA-608/708 captions
• WebVTT subtitles
• IMSC1 (TTML) subtitles, limited to the text profile and a subset of TTML styling
• 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.
• Alternate Audio Track Rendition (Multivariant Playlist with Alternative Audio) for VoD and Live playlists
• HLS Interstitials (ad insertion and content replacement scheduled with DATERANGE tags)
• I-frame trick-play, including image I-frame (mjpg) renditions
• 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
• All internal events can be monitored (Network Events, Video Events)
• Playback session metrics are also exposed
• Common Media Client Data (CMCD)
• Content Steering
• Resilience to errors
• Retry mechanism embedded in the library
• Recovery actions can be triggered fix fatal media or network errors
• Redundant/Failover Playlists
• HLS Variable Substitution

Supported HLS tags

For details on the HLS format and these tags' meanings, see https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis

Multivariant Playlist tags

• #EXT-X-STREAM-INF:<attribute-list>

<URI>

• #EXT-X-I-FRAME-STREAM-INF I-frame Media Playlist files
• #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)

Media Playlist tags

• #EXTM3U (required format identifier)
• #EXT-X-VERSION:<n> (value is ignored)
• #EXT-X-INDEPENDENT-SEGMENTS (ignored)
• #EXT-X-I-FRAMES-ONLY
• #EXTINF:<duration>,[<title>]
• #EXT-X-ENDLIST
• #EXT-X-PLAYLIST-TYPE:<type-enum> (see "Not Supported" below)
• #EXT-X-MEDIA-SEQUENCE:<n>
• #EXT-X-TARGETDURATION:<n>
• #EXT-X-DISCONTINUITY
• #EXT-X-DISCONTINUITY-SEQUENCE:<n>
• #EXT-X-BITRATE:<rate>
• #EXT-X-BYTERANGE:<n>[@<o>]
• #EXT-X-MAP:<attribute-list>
• #EXT-X-KEY:<attribute-list> (KEYFORMAT="identity",METHOD=SAMPLE-AES is only supported with MPEG-2 TS segments)
• #EXT-X-PROGRAM-DATE-TIME:<date-time-msec>
• #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
• HLS EXT-X-DATERANGE Schema for Interstitials
• #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)

Parsed but missing feature support:

• #EXT-X-PRELOAD-HINT:<attribute-list> (See #5074)

Not Supported

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-PLAYLIST-TYPE is not used to determine if media playlists should be reloaded based on "Expires" header value (#7082)
• REQ-VIDEO-LAYOUT is not used in variant filtering or selection
• "identity" format SAMPLE-AES method keys with fmp4, aac, mp3, vtt... segments (MPEG-2 TS only)
• MPEG-2 TS segments with FairPlay Streaming, PlayReady, or Widevine encryption
• FairPlay Streaming legacy keys (For com.apple.fps.1_0 use native Safari playback)
• ClearKey (org.w3.clearkey) is incomplete: the key system is recognized, but there is no way to supply key ID/key value pairs to the EME controller, so no license or session path exists (See #2934)
• EC-3 (Dolby Digital Plus) in MPEG-2 TS and in containerless (audio only) elementary streams. EC-3 is supported in Fragmented MP4 segments
• HEVC and AC-3 in MPEG-2 TS are excluded from the light build (see __USE_M2TS_ADVANCED_CODECS__)

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

Open in StackBlitz

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 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 - 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), Variable Substitution, Interstitials, I-frame trick-play, Media Capabilities, or MPEG-2 TS advanced codec (HEVC and AC-3) support. Content Steering is included. In addition, the following types are not available in the light build:

• AudioStreamController
• AudioTrackController
• CuesInterface
• EMEController
• SubtitleStreamController
• SubtitleTrackController
• TimelineController
• CMCDController
• InterstitialsController
• InterstitialsManager
• IFrameController
• HlsIFramesOnly
• HlsImageIFramesOnly

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

Formatting Code

Run prettier to format code

npm run prettier

Type Check

Run type-check to verify TypeScript types

npm run type-check

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

An overview of this project's design, it's modules, events, and error handling can be found here.

API docs and usage guide

• API and usage docs, with code examples
• Auto-Generated API Docs (Latest Release)
• Auto-Generated API Docs (Development Branch)

_Note you can access the docs for a particular version using "https://github.com/video-dev/hls.js/tree/deployments"_

Demo

Latest Release

https://hlsjs.video-dev.org/demo

Master

https://hlsjs-dev.video-dev.org/demo

Specific Version

Find the commit on https://github.com/video-dev/hls.js/tree/deployments.

image

This project is tested with BrowserStack.

This project is tested with SauceLabs.

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 47+ for Desktop
• Firefox 51+ for Desktop
• Edge for Windows 10+
• Safari 10+ for macOS 10.11+
• Safari for iPadOS 13+
• Safari for iOS 17.1+ since HLS version 1.5.0 using Managed Media Source (MMS) WebKit blog
• Chrome for Android 5+
• Firefox for Android 5+

These versions are the targets passed to @babel/preset-env when building the UMD bundles in dist/. They share an ES2016 runtime baseline: ES5-style syntax plus native ES2016 globals (Map, Set, Promise, Array.from, Uint8Array.from, Array.prototype.includes, etc.). To keep bundle size small, no core-js polyfills are bundled.

Optional features such as CMCD pull in ES2017 APIs (e.g. Object.entries), so the full UMD bundle effectively requires an ES2017-capable runtime. The light bundle excludes those features and stays at the ES2016 baseline.

The `dis