Join the discussion via video-dev.org in #hlsjs (our Slack channel)

!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```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].

[HTML5 video]: http://www.html5rocks.com/en/tutorials/video/basics/
[MediaSource Extensions]: http://w3c.github.io/media-source/
[HTTP Live Streaming]: http://en.wikipedia.org/wiki/HTTP_Live_Streaming
[Web Worker]: http://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
[Webpack]: https://webpack.js.org/

API docs and usage guide

* API and usage docs, with code examples

* Auto-Generated Docs (Latest Release)
* Auto-Generated Docs (Master)

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

Demo

$3

https://hls-js.netlify.com/demo

$3

https://hls-js-latest.netlify.com/demo

$3

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

Getting Started

`html





`

Video Control

Video is controlled through HTML `` 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
- OpenPlayerJS, as part of the OpenPlayer project

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 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

`sh
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

`sh
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.

$3

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+

$3

- #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

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
`sh
git clone https://github.com/video-dev/hls.js.git


setup dev environment

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.

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.

$3