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 and code documention: http://video-dev.github.io/hls.js/docs/html
-
Find a more detailed library usage guide, use-cases and example here
https://video-dev.github.io/hls.js/demo
https://video-dev.github.io/hls.js/demo?canary=true
<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 is controlled through HTML <video>
element.
HTMLVideoElement control and events could be used seamlessly.
![]() |
![]() |
||
![]() |
![]() |
![]() |
|
![]() |
![]() |
||
![]() |
|||
![]() |
![]() |
||
![]() |
|||
![]() |
![]() |
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
made by gramk, plays hls from address bar and m3u8 links
- Chrome native-hls
- Firefox native-hls
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.
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
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.
All HLS resources must be delivered with CORS headers permitting GET
requests.
- 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.
- 3 Quality Switching modes are available (controllable through API means)
- Manual & Auto Quality Switching
- 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
- MP3 Elementary Stream in Edge for Windows 10+
#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)
hls.js is released under Apache 2.0 License
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.
Click here for details.