Join the discussion on Slack#hlsjs

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, and transpiled in ECMAScript5 using Babel.

API docs and usage guide

• API and code documention: http://video-dev.github.io/hls.js/docs/html

• Find a more detailed library usage guide, use-cases and example here

Demo

Latest Release

https://video-dev.github.io/hls.js/demo

Canary

https://video-dev.github.io/hls.js/demo?canary=true

Getting Started

<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<!-- Or if you want a more recent canary version -->
<!-- <script src="https://cdn.jsdelivr.net/npm/hls.js@canary"></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();
  });
 }
 // 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 throught 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 = '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:

• Akamai Adaptive Media Player (AMP)
• Clappr
• Flowplayer through flowplayer-hlsjs
• MediaElement.js
• Videojs through Videojs-hlsjs
• Videojs through videojs-hls.js. hls.js is integrated as a SourceHandler -- new feature in Video.js 5.
• Videojs through videojs-contrib-hls.js. Production ready plug-in with full fallback compatibility built-in.
• Fluid Player

Chrome/Firefox integration

made by gramk, plays hls from address bar and m3u8 links

• Chrome native-hls
• Firefox native-hls

Dependencies

No external JS libs are needed. Prepackaged build is included in the dist folder:

• hls.js
• hls.min.js
• hls.light.js
• hls.light.min.js

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.

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

• #EXTM3U
• #EXTINF
• #EXT-X-STREAM-INF (adaptive streaming)
• #EXT-X-ENDLIST (Live playlist)
• #EXT-X-MEDIA-SEQUENCE
• #EXT-X-TARGETDURATION
• #EXT-X-DISCONTINUITY
• #EXT-X-DISCONTINUITY-SEQUENCE
• #EXT-X-BYTERANGE
• #EXT-X-MAP
• #EXT-X-KEY (https://tools.ietf.org/html/draft-pantos-http-live-streaming-08#section-3.4.4)
• #EXT-X-PROGRAM-DATE-TIME (https://tools.ietf.org/html/draft-pantos-http-live-streaming-18#section-4.3.2.6)
• EXT-X-START:TIME-OFFSET=x (https://tools.ietf.org/html/draft-pantos-http-live-streaming-18#section-4.3.5.2)

License

hls.js is released under Apache 2.0 License

Contributing

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
# setup dev environement
cd hls.js
npm install
# build dist/hls.js, watch file change for rebuild and launch demo page
npm run dev
# lint
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.

Design

Click here for details.

Tested With