Home Reference Source

Build Status npm npm

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

API docs and usage guide

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

Demo

Latest Release

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

Master

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

Specific Version

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

Getting Started

Alternative setup

Note that the example code above will check for hls.js support first and then fallback to check if the browser natively supports HLS. If you want to check for native browser support first, and then fallback to Hls.js you will want to swap those conditionals.

The order of these checks depends on if you want to use hls.js whenever possible see this comment to understand some of the tradeoffs.

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 with the releases.

If you want to bundle the application yourself, use node

npm install hls.js

or for the version from master (alpha)

npm install hls.js@alpha

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:

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.

Server-side-rendering (SSR) and require from a Node.js runtime

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

Not Supported (Yet)

Supported M3U8 tags

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.

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.

Tested With

Browser Stack Logo