# Migrating from hls.js 1.x to 1.4+ The 1.4 version of hls.js now ships with an ESM version of the library (`dist/hls.mjs`) which requires that you specify the [`workerPath` config option](https://github.com/video-dev/hls.js/blob/master/docs/API.md#workerpath) in order for web workers to be used. This should point to the `dist/hls.worker.js` file included in the package. If you are using the UMD version (`dist/hls.js`), no changes are required. **Important Notes:** - If you are using a bundler, such as webpack, the ESM version of the package will likely be used by default. If this is the case, make sure to add the `workerPath` config option after upgrading to hls.js 1.4 or above. - Older web engines may experience severe performance degradation when using the ESM version of this package. If targeting older web engines, consider bundling your client application in `loose` mode to avoid additional function overhead. Alternatively, use the UMD/ES5 version of the package. # Migrating from hls.js 0.x to 1.x This guide provides an overview to migrating an application using hls.js from v0.14.x to v1.0.0. ## Dependencies Promise support is now required. If your app requires support for older browsers that do not include support for Promises, include your own Promise polyfill. ## Configuration Changes ### Back Buffer Eviction The new `backBufferLength` setting applies to Live and VOD streams. It defaults to Infinity, leaving back buffer eviction to the browser to perform on SourceBuffer append (https://www.w3.org/TR/media-source-2/#sourcebuffer-coded-frame-eviction). The demo page includes a setting of 90 seconds for demonstration purposes. In v1.0 and up, the back buffer on VOD and Live content will be left up to the browser by default. Set `backBufferLength` to `Infinity` and `liveBackBufferLength` to `90` if you would like v1 to handle back buffer eviction for Live and VOD streams as older versions did. While `liveBackBufferLength` can still be used, it has been marked deprecated and may be removed in an upcoming minor release. ### Front Buffer Eviction The new `frontBufferFlushThreshold` setting defaults to Infinity seconds and governs active eviction of buffered ranges outside of the current contiguous front buffer. For example, given currentTime=0 and bufferedRanges=[[0, 100], [150, 200]] with a configured frontBufferFlushThreshold=60, we will only remove the range from [150, 200] as it lies outside of the target buffer length and is not contiguous with the forward buffer from the currentTime of 0. ### Low Latency Streams The new `lowLatencyMode` setting is enabled by default. Set to `false` to disable Low-latency part loading and target latency playback rate adjustment. ### Chunked Transfer Support (experimental) The new experimental `progressive` setting is disabled by default. Set it to `true` to stream and append audio and video data as it streams for each segment before segment load completion. Not recommended for production or small segments with only a single GoP or less. ## Support for Group-Level Track Switching - `hls.audioTracks` and `hls.subtitleTracks` as well as `AUDIO_TRACKS_UPDATED` and `SUBTITLE_TRACKS_UPDATED` events only list tracks in the active level's audio/sub GROUP-ID after `LEVEL_LOADING` (this will go unnoticed for streams with no or only one group per track type) - The `MANIFEST_PARSED` event still reports all tracks when multiple GROUP-ID values are present. Applications that used that event to get tracks would need to be updated in v1 to switch to the corresponding track update events to select available tracks using the available indexes. - Track ids are no longer indexes of the complete list of audio or subtitle tracks. They are now indexes within each group. So six tracks in two groups that had ids 0,1,2,3,4,5 will now have ids 0,1,2,0,1,2. This allows for tracks to be changed by index/id within the range of available tracks as they were before. - Added `groupId` to audio and subtitle track loading and loaded events ## Playback and Level Changes - Setting `hls.currentLevel` no longer pauses the media element while clearing the buffer and loading the new level. This can result in a stall error if playback doesn't start within a quarter of a second. Applications implementing manual quality switching with `hls.currentLevel` that do not want a stall reported should either pause or set `video.playbackRate` to `0` until the level switch is complete. - The maximum gap that will be jumped is now driven via the GapController `MAX_START_GAP_JUMP`. By default this value is set to two seconds, to match with the value that browsers will automatically skip when the `autoplay` attribute on the `