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 into ISO BMFF (MP4) fragments. this transmuxing could be performed asynchronously using Web Worker if available in the browser.
hls.js is written in ES6, and transpiled in ES5 using Babel.
http://gdupontavice.dev.dailymotion.com/hls.js/demo/index.html
prepackaged distribution is available in the [dist] (dist) folder:
- [hls.js] (dist/hls.js)
- [hls.min.js] (dist/hls.min.js)
hls.js is compatible with browsers supporting MSE with 'video/MP4' inputs. as of today, it is supported on:
- Chrome for Android 34+
- Chrome for Desktop 34+
- Firefox for Desktop 38+
- IE11+ for Windows 8.1
- Safari for Mac 8+ (still buggy)
- VoD & Live playlists
- Sliding window (aka DVR) support on Live playlists
- Adaptive streaming
- Manual & Auto switching
- 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)
- Manual & Auto switching
- Accurate Seeking on VoD & Live
- ability to seek in buffer and back buffer without redownloading segments
#EXTM3U#EXTINF#EXT-X-STREAM-INF(Multiple bitrate)#EXT-X-ENDLIST(VoD / Live playlist)#EXT-X-MEDIA-SEQUENCE#EXT-X-TARGETDURATION
<script src="dist/hls.js"></script>
<script>
if(Hls.isSupported()) {
var video = document.getElementById('video');
var hls = new Hls();
hls.loadSource('http://devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8');
hls.attachVideo(video);
hls.on(hls.Events.MANIFEST_PARSED,function() {
...
});
hls.on(hls.Events.MSE_ATTACHED,function() {
...
});
}
</script>video is controlled through HTML <video> element.
HTMLVideoElement control and events could be used seamlessly.
configuration parameters could be provided to hls.js upon instantiation of Hls Object.
var config = {
debug : false,
maxBufferLength : 30,
maxBufferSize : 60*1000*1000,
enableWorker : true,
fragLoadingTimeOut : 60000,
fragLoadingMaxRetry : 3,
fragLoadingRetryDelay : 500,
manifestLoadingTimeOut : 10000,
manifestLoadingMaxRetry : 3,
manifestLoadingRetryDelay : 500,
loader : customLoader
};
var hls = new Hls(config);(default false)
turn on debug logs on JS console
(default 30s)
maximum buffer Length in seconds. if buffer length is/become less than this value, a new fragment will be loaded.
(default 60 MB)
maximum buffer size in bytes. if buffer size upfront is bigger than this value, no fragment will be loaded.
(default true)
enable webworker (if available on browser) for TS demuxing/MP4 remuxing, to improve performance and avoid lag/frame drops.
(default 60000ms for fragment/10000ms for manifest)
URL Loader timeout. A timeout callback will be triggered if loading duration exceeds this timeout. no further action will be done : the load operation will not be cancelled/aborted. It is up to the application to catch this event and treat it as needed.
(default 3)
max nb of load retry
(default 500ms)
initial delay between XmlHttpRequest error and first load retry (in ms) any I/O error will trigger retries every 500ms,1s,2s,4s,8s, ... capped to 64s (exponential backoff)
(default : standard XmlHttpRequest based URL loader)
override standard URL loader by a custom one. could be useful for P2P or stubbing (testing).
var customLoader = function() {
/* calling load() will start retrieving content at given URL (HTTP GET)
params :
url : URL to load
responseType : xhr response Type (arraybuffer or default response Type for playlist)
onSuccess : callback triggered upon successful loading of URL.
it should return xhr event and load stats object {trequest,tfirst,tload}
onError : callback triggered if any I/O error is met while loading fragment
onTimeOut : callback triggered if loading is still not finished after a certain duration
timeout : timeout after which onTimeOut callback will be triggered(if loading is still not finished after that delay)
maxRetry : max nb of load retry
retryDelay : delay between an I/O error and following connection retry (ms). this to avoid spamming the server.
*/
this.load = function(url,responseType,onSuccess,onError,timeout,maxRetry,retryDelay) {}
/* abort any loading in progress */
this.abort = function() {}
/* destroy loading context */
this.destroy = function() {}
}hls.js handles quality switch automatically. it is also possible to manually control quality swith using below API:
return array of available quality levels
get : return current playback quality level set : trigger an immediate quality level switch to new quality level. this will pause the video if it was playing, flush the whole buffer, and fetch fragment matching with current position and requested quality level. then resume the video if needed once fetched fragment will have been buffered. set to -1 for automatic level selection
get : return next playback quality level (playback quality level for next buffered fragment). return -1 if next fragment not buffered yet set : trigger a quality level switch for next fragment. this could eventually flush already buffered next fragment set to -1 for automatic level selection
get : return last loaded fragment quality level. set : set quality level for next loaded fragment set to -1 for automatic level selection
get : first level index (index of first level appearing in Manifest. it is usually defined as start level hint for player)
get/set : start level index (level of first fragment that will be played back)
- if not overrided by user : first level appearing in manifest will be used as start level.
- if -1 : automatic start level selection, playback will start from level matching download bandwidth (determined from download of first segment)
default value is firstLevel
tell whether auto level selection is enabled or not
get/set : capping/max level value that could be used by automatic level selection algorithm
default value is -1 (no level capping)
hls.js fires a bunch of events, that could be registered as below:
hls.on(hls.Events.LEVEL_LOADED,function(event,data) {
var level_duration = data.details.totalduration;
});full list of Events available below :
hls.events.MSE_ATTACHED- fired when MediaSource has been succesfully attached to video element.- data: { mediaSource }
hls.events.MANIFEST_LOADED- fired after manifest has been loaded- data: { levels : [available quality levels] , url : manifestURL, stats : { trequest, tfirst, tload, mtime}}
hls.events.MANIFEST_PARSED- fired after manifest has been parsed- data: { levels : [available quality levels] , startLevel : playback start level, audiocodecswitch: true if different audio codecs used}
hls.events.LEVEL_LOADING- fired when a level playlist loading starts- data: { levelId : id of level being loaded}
hls.events.LEVEL_LOADED- fired when a level playlist loading finishes- data: { details : levelDetails object, levelId : id of loaded level, stats : { trequest, tfirst, tload, mtime} }
hls.events.LEVEL_SWITCH- fired when a level switch is requested- data: { levelId : id of new level }
hls.events.FRAG_LOADING- fired when a fragment loading starts- data: { frag : fragment object}
hls.events.FRAG_LOADED- fired when a fragment loading is completed- data: { frag : fragment object, payload : fragment payload, stats : { trequest, tfirst, tload, length}}
hls.events.FRAG_PARSING_INIT_SEGMENT- fired when Init Segment has been extracted from fragment- data: { moov : moov MP4 box, codecs : codecs found while parsing fragment}
hls.events.FRAG_PARSING_DATA- fired when moof/mdat have been extracted from fragment- data: { moof : moof MP4 box, mdat : mdat MP4 box, startPTS : PTS of first sample, endPTS : PTS of last sample, startDTS : DTS of first sample, endDTS : DTS of last sample, type : stream type (audio or video), nb : number of samples}
hls.events.FRAG_PARSED- fired when fragment parsing is completed- data: undefined
hls.events.FRAG_BUFFERED- fired when fragment remuxed MP4 boxes have all been appended into SourceBuffer- data: { frag : fragment object, stats : { trequest, tfirst, tload, tparsed, tbuffered, length} }
hls.events.FRAG_CHANGED- fired when fragment matching with current video position is changing- data: { frag : fragment object }
hls.events.LOAD_ERROR- Identifier for fragment/playlist load error- data: { url : faulty URL, response : XHR response}
hls.events.LOAD_TIMEOUT- Identifier for fragment/playlist load timeout- data: { url : faulty URL,{ trequest, tfirst,loaded } }
hls.events.LEVEL_ERROR- Identifier for a level switch error- data: { level : faulty level Id, event : error description}
hls.events.VIDEO_ERROR- Identifier for a video error- data: undefined
hls.events.PARSING_ERROR- Identifier for a fragment parsing error- data: parsing error description
a level object represents a given quality level. it contains quality level related info, retrieved from manifest, such as
- level bitrate
- used codecs
- video width/height
- level name
- level URL
see sample Level object below:
{
url: 'http://levelURL.com'
bitrate: 246440,
name: "240",
codecs: "mp4a.40.5,avc1.42000d",
width: 320,
height: 136,
}level detailed infos contains level details retrieved after level playlist parsing, they are specified below :
- start sequence number
- end sequence number
- level total duration
- level fragment target duration
- array of fragments info
- is this level a live playlist or not ?
see sample object below, available after corresponding LEVEL_LOADED event has been fired:
{
startSN: 0,
endSN: 50,
totalduration: 510,
targetduration: 10,
fragments: Array[51],
live: false
}the Fragment object contains fragment related info, such as
- fragment URL
- fragment duration
- fragment sequence number
- fragment start offset
- level Id
see sample object below:
{
duration: 10,
level : 3,
sn: 35,
start : 30,
url: 'http://fragURL.com'
}