video-dev · robwalch · Nov 7, 2025 · Nov 6, 2025 · Nov 6, 2025 · Nov 7, 2025
diff --git a/docs/API.md b/docs/API.md
@@ -50,6 +50,7 @@ See [API Reference](https://hlsjs-dev.video-dev.org/api-docs/) for a complete li
   - [`liveSyncDuration`](#livesyncduration)
   - [`liveMaxLatencyDuration`](#livemaxlatencyduration)
   - [`maxLiveSyncPlaybackRate`](#maxlivesyncplaybackrate)
+  - [`timelineOffset`](#timelineoffset)
   - [`liveDurationInfinity`](#livedurationinfinity)
   - [`liveBackBufferLength` (deprecated)](#livebackbufferlength-deprecated)
   - [`preferManagedMediaSource`](#prefermanagedmediasource)
@@ -80,6 +81,7 @@ See [API Reference](https://hlsjs-dev.video-dev.org/api-docs/) for a complete li
   - [`fpsDroppedMonitoringPeriod`](#fpsdroppedmonitoringperiod)
   - [`fpsDroppedMonitoringThreshold`](#fpsdroppedmonitoringthreshold)
   - [`appendErrorMaxRetry`](#appenderrormaxretry)
+  - [`ignorePlaylistParsingErrors`](#ignoreplaylistparsingerrors)
   - [`loader`](#loader)
   - [`fLoader`](#floader)
   - [`pLoader`](#ploader)
@@ -92,6 +94,7 @@ See [API Reference](https://hlsjs-dev.video-dev.org/api-docs/) for a complete li
   - [`bufferController`](#buffercontroller)
   - [`capLevelController`](#caplevelcontroller)
   - [`fpsController`](#fpscontroller)
+  - [`errorController`](#errorcontroller)
   - [`timelineController`](#timelinecontroller)
   - [`enableDateRangeMetadataCues`](#enabledaterangemetadatacues)
   - [`enableEmsgMetadataCues`](#enableemsgmetadatacues)
@@ -122,6 +125,7 @@ See [API Reference](https://hlsjs-dev.video-dev.org/api-docs/) for a complete li
   - [`abrBandWidthUpFactor`](#abrbandwidthupfactor)
   - [`abrMaxWithRealBitrate`](#abrmaxwithrealbitrate)
   - [`minAutoBitrate`](#minautobitrate)
+  - [`preserveManualLevelOnError`](#preservemanuallevelonerror)
   - [`emeEnabled`](#emeenabled)
   - [`widevineLicenseUrl` (deprecated)](#widevinelicenseurl-deprecated)
   - [`licenseXhrSetup`](#licensexhrsetup)
@@ -134,6 +138,9 @@ See [API Reference](https://hlsjs-dev.video-dev.org/api-docs/) for a complete li
   - [`enableInterstitialPlayback`](#enableinterstitialplayback)
   - [`interstitialAppendInPlace`](#interstitialappendinplace)
   - [`interstitialLiveLookAhead`](#interstitiallivelookahead)
+  - [`assetPlayerId`](#assetplayerid)
+  - [`primarySessionId`](#primarysessionid)
+  - [`useMediaCapabilities`](#usemediacapabilities)
 - [Video Binding/Unbinding API](#video-bindingunbinding-api)
   - [`hls.attachMedia(HTMLMediaElement | MediaAttachingData)`](#hlsattachmediahtmlmediaelement--mediaattachingdata)
   - [`hls.detachMedia()`](#hlsdetachmedia)
@@ -798,6 +805,14 @@ When set to a value greater than `1`, the latency-controller will adjust `video.
 
 The default value is `1`, which disables playback rate adjustment. Set `maxLiveSyncPlaybackRate` to a value greater than `1` to enable playback rate adjustment at the live edge.
 
+### `timelineOffset`
+
+(default: `undefined`)
+
+An optional time offset in seconds applied to fragment start times and timeline calculations. This is useful for synchronizing timelines across multiple HLS instances, such as when using Interstitials or when coordinating playback with external systems.
+
+When set, the offset is applied to fragment start positions, seek operations, and timeline calculations. The offset is stored in level details as `appliedTimelineOffset` and can be modified dynamically through the `InterstitialPlayer.timelineOffset` property for interstitial asset players.
+
 ### `liveDurationInfinity`
 
 (default: `false`)
@@ -1099,6 +1114,14 @@ The ratio of frames dropped to frames elapsed within `fpsDroppedMonitoringPeriod
 Max number of `sourceBuffer.appendBuffer()` retry upon error.
 Such error could happen in loop with UHD streams, when internal buffer is full. (Quota Exceeding Error will be triggered). In that case we need to wait for the browser to evict some data before being able to append buffer correctly.
 
+### `ignorePlaylistParsingErrors`
+
+(default: `false`)
+
+When set to `false`, playlist parsing errors will trigger `ERROR` events with `ErrorDetails.LEVEL_PARSING_ERROR`, allowing your application to handle them.
+
+When set to `true`, playlist parsing errors will be ignored and playback will continue. The errors will still be logged but will not trigger error events.
+
 ### `loader`
 
 (default: standard `XMLHttpRequest`-based URL loader)
@@ -1346,6 +1369,14 @@ Customized fps controller.
 A class in charge of monitoring frame rate, that emits `FPS_DROP` events when frames dropped exceeds configured threshold.
 Enable the default fps controller by setting `capLevelOnFPSDrop` to `true`.
 
+### `errorController`
+
+(default: internal error controller)
+
+Customized error controller.
+
+A class in charge of handling errors and error recovery logic. The error controller processes error events and implements recovery strategies such as level switching and fragment retry logic.
+
 ### `timelineController`
 
 (default: internal track timeline controller)
@@ -1602,6 +1633,14 @@ then if config value is set to `true`, ABR will use 2.5 Mb/s for this quality le
 Return the capping/min bandwidth value that could be used by automatic level selection algorithm.
 Useful when browser or tab of the browser is not in the focus and bandwidth drops
 
+### `preserveManualLevelOnError`
+
+(default: `false`)
+
+When set to `false`, if auto-level selection is disabled and a fragment error occurs, HLS.js will reset the manual level selection (`hls.loadLevel` will be set to `-1`), allowing automatic level selection to take over.
+
+When set to `true`, the manual level selection will be preserved even when fragment errors occur, preventing automatic fallback to ABR.
+
 ### `emeEnabled`
 
 (default: `false`)
@@ -1781,6 +1820,28 @@ The time (in seconds) ahead of the end of a live playlist to request scheduled I
 
 The default value is `10`, meaning that HLS.js will begin requesting interstitial ASSET-LIST and ASSET-URIs whose START-DATE is within 10 seconds of the program-date-time at the end of the primary variant playlist while the forward buffer is within a target duration of the same range.
 
+### `assetPlayerId`
+
+(default: `undefined`)
+
+An optional identifier string that is prefixed to debug logs for this HLS instance. This is particularly useful when multiple HLS instances are running simultaneously (such as when using Interstitials with asset players) to distinguish log messages from different players.
+
+When set, the `assetPlayerId` is included in log messages and can be used to identify which HLS instance generated a particular log entry.
+
+### `primarySessionId`
+
+(default: `undefined`)
+
+An optional identifier string used to identify the primary HLS session when working with Interstitials. This value is passed to interstitial asset URLs via the `_HLS_primary_id` query parameter, allowing the server to associate interstitial requests with the primary session.
+
+This is primarily used internally by HLS.js when creating interstitial asset players, but can be set manually if you need to coordinate multiple HLS instances.
+
+### `useMediaCapabilities`
+
+(default value is `true` except in the light build or custom builds with setting the **USE_MEDIA_CAPABILITIES** flag to `false`.)
+
+- get/set: Whether the MediaCapabilities API is used for level, track, and switch filtering. When enabled, HLS.js uses `navigator.mediaCapabilities.decodingInfo()` to determine if a level or track is supported before selection. Some devices may incorrectly report MediaCapabilities, leading to levels/tracks being filtered out that the device actually supports. Whether or not tracks are filtered automatically using this feature, you can manually remove unsupported levels using `hls.removeLevel(levelIndex)` after the manifest is parsed.
+
 ## Video Binding/Unbinding API
 
 ### `hls.attachMedia(HTMLMediaElement | MediaAttachingData)`