Skip to content

Latest commit

 

History

History
270 lines (201 loc) · 15.4 KB

README.md

File metadata and controls

270 lines (201 loc) · 15.4 KB
Raw

Build Status npm npm Greenkeeper badge

Join the discussion on Slack#hlsjs Slack Status

hls.js

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

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:

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 in the dist folder:

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

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

Browser Stack Logo