MIGRATING.md
No public exports were removed, and no code changes are required to upgrade. There is one observable playback change, described in Media timeline offsets are based on decode time. The remaining changes affect TypeScript consumers, who may see new compile errors where previously loose types have been narrowed; see TypeScript type changes.
hls.js now derives the timestampOffset it applies to each SourceBuffer from the lowest decode timestamp (DTS) across the audio and video tracks, rather than from the first presentation timestamp (PTS) of the track it synchronizes to. This keeps appended timestamps from going negative at the start of a stream, which produced stalls, unexpected buffered ranges, and repeated segment loads when playback started midstream and then seeked back toward zero. See #7700, #7880, and #7932.
This change was backported to v1.6.18, so it is not unique to 1.7. Apps staying on 1.6 see it as soon as they take the latest patch release.
The change applies to MPEG-TS content that hls.js transmuxes. Fragmented MP4 content is unaffected, because its timestamp offsets already come from base media decode times. Where the first frame of a transmuxed segment has a non-zero composition offset (PTS − DTS), presentation times now land that later on the media timeline than they did in v1.6.17 and earlier. The size of the shift depends on the starting segment's initial composition time and how the browser maps media timestamps to currentTime on append.
Reported in #7977.
| Type | 1.6 | 1.7 |
|---|---|---|
networkDetails on ManifestLoadedData, TrackLoadedData, LevelLoadedData, FragLoadedData, AssetListLoadedData, ErrorData | any | NullableNetworkDetails (XMLHttpRequest | Response | null) |
NonNativeTextTrack | interface, label: any | type, label: string |
BufferEOSData.type | SourceBufferName | undefined | SourceBufferName | null |
FragBufferedData.id | string | PlaylistLevelType |
FragChangedData.frag | Fragment | MediaFragment |
CMCDControllerConfig.includeKeys | string[] | CmcdKey[] (from @svta/cml-cmcd) |
If you declared a variable as any to hold networkDetails, narrow it before use, or import NullableNetworkDetails from hls.js. If you extended NonNativeTextTrack with interface X extends NonNativeTextTrack, use an intersection type instead.
The keyContext argument passed to EME hooks now carries the fragment's key:
drmSystems[KEY-SYSTEM].generateRequest receives keyContext & { decryptdata: LevelKey, reason: LicenseRequestReason } and returns GenerateRequestFilterResult.licenseXhrSetup and licenseResponseCallback receive keyContext & { decryptdata: LevelKey }. licenseXhrSetup may now also return or resolve a string in addition to a Uint8Array.Existing implementations continue to work — the argument types were widened, not replaced.
cmcd.version still defaults to 1, so existing CMCD configurations report the same fields as in 1.6. CMCD v2 fields and event reporting require version: 2, and event reports additionally require eventTargets.
New public API and configuration in 1.7, all optional (a few of these were soft launched in v1.6.x patch releases):
hls.iframeVariants, hls.createIFramePlayer(), hls.createImageIFramePlayer(), and iframeCacheLimit.appendTimeout with BUFFER_APPEND_NO_PROGRESS, MEDIA_SOURCE_REQUIRES_RESET, and skipBufferHolePadding.liveMaxUnchangedPlaylistRefresh with PLAYLIST_UNCHANGED_ERROR.abrSwitchInterval and errorPenaltyExpireMs.loopBackBufferFlush and startOnSegmentBoundary.handleMpegTsVideoIntegrityErrors and emsgKLVSchemaUri.requireKeySystemAccessOnStart.hls.mainForwardBufferInfo and hls.audioForwardBufferInfo.hls.nextAudioTrack, the optional flushImmediate argument to hls.setAudioOption(), and nextAudioTrackBufferFlushForwardOffset.streamController, gapController, latencyController, id3TrackController, and iframeController.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 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:
workerPath config option after upgrading to hls.js 1.4 or above.loose mode to avoid additional function overhead. Alternatively, use the UMD/ES5 version of the package.This guide provides an overview to migrating an application using hls.js from v0.14.x to v1.0.0.
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.
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.
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.
The new lowLatencyMode setting is enabled by default. Set to false to disable Low-latency part loading and target
latency playback rate adjustment.
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.
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)
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.groupId to audio and subtitle track loading and loaded eventsSetting 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 <video> element is set to true.
Event order and content have changed in some places. See Breaking Changes below, and please report any issues with breaking changes that impact your integrations
FRAG_LOADED fires after events handled on progress which can include everything up to appending a fragment if workers are disabled (more details below under Known Issues)BUFFER_CODECS data has changed from { tracks: { video?, audio? } } to simply { video?, audio? }BUFFER_APPENDING data has changed from { type, data, parent, content } to { type, data, frag, chunkMeta }BUFFER_APPENDED data has changedFRAG_DECRYPT_ERROR events are now surfaced as a FRAG_PARSING_ERROR along with other fragment transmuxing errorsSUBTITLE_LOAD_ERRORSUBTITLE_TRACK_LOAD_TIMEOUTUNKNOWNBUFFER_INCOMPATIBLE_CODECS_ERROR will fire instead of BUFFER_CREATED with an empty tracks list. This media error
is fatal and not recoverable. If you encounter this error make sure you include the correct CODECS string in
your manifest, as this is most likely to occur when attempting to play a fragmented mp4 playlist with unknown codecs.FRAG_LOAD_PROGRESS has been deprecatedFRAG_PARSING_DATA has been deprecatedSTREAM_STATE_TRANSITION has been deprecatedstats object has changed
trequest, tfirst, tload have been replaced by loading: HlsProgressivePerformanceTimingtparsed has been replaced by parsing: HlsProgressivePerformanceTimingFragment object:
hasElementaryStream function has been removedsetElementaryStream and _elementaryStreams have been renamed (these are only for internal use)part property that include the part details.v0.x types are not compatible with v1.x. Type definitions are now exported with the build and npm package in
dist/hls.d.ts and dist/hls.d.mts. Please use these type definitions if you are having trouble with
DefinitelyTyped @types/hls.js and v1.x.