Add liveSyncOnStallIncrease config option

api-extractor/report/hls.js.api.md

@@ -2015,6 +2015,7 @@ export type LatencyControllerConfig = {
     liveSyncDuration?: number;
     liveMaxLatencyDuration?: number;
     maxLiveSyncPlaybackRate: number;
+    liveSyncOnStallIncrease: number;
 };
 
 // Warning: (ae-missing-release-tag) "Level" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)

docs/API.md

@@ -40,6 +40,7 @@ See [API Reference](https://hlsjs-dev.video-dev.org/api-docs/) for a complete li
   - [`maxFragLookUpTolerance`](#maxfraglookuptolerance)
   - [`maxMaxBufferLength`](#maxmaxbufferlength)
   - [`liveSyncDurationCount`](#livesyncdurationcount)
+  - [`liveSyncOnStallIncrease`](#livesynconstallincrease)
   - [`liveMaxLatencyDurationCount`](#livemaxlatencydurationcount)
   - [`liveSyncDuration`](#livesyncduration)
   - [`liveMaxLatencyDuration`](#livemaxlatencyduration)
@@ -392,6 +393,7 @@ var config = {
   nudgeMaxRetry: 3,
   maxFragLookUpTolerance: 0.25,
   liveSyncDurationCount: 3,
+  liveSyncOnStallIncrease: 1,
   liveMaxLatencyDurationCount: Infinity,
   liveDurationInfinity: false,
   preferManagedMediaSource: false,
@@ -662,6 +664,17 @@ edge of live delay, expressed in multiple of `EXT-X-TARGETDURATION`.
 if set to 3, playback will start from fragment N-3, N being the last fragment of the live playlist.
 decreasing this value is likely to cause playback stalls.
 
+### `liveSyncOnStallIncrease`
+
+(default: `1`)
+
+increment to the calculated `hls.targetLatency` on each playback stall, expressed in seconds.
+When `liveSyncDuration` is specified in config,
+`hls.targetLatency` is calculated as `liveSyncDuration` plus `liveSyncOnStallIncrease` multiplied by number of stalls.
+Otherwise `hls.targetLatency` is calculated as `liveSyncDurationCount` multiplied by `EXT-X-TARGETDURATION`
+plus `liveSyncOnStallIncrease` multiplied by number of stalls.
+Decreasing this value will mean that each stall will have less affect on `hls.targetLatency`.
+
 ### `liveMaxLatencyDurationCount`
 
 (default: `Infinity`)

src/config.ts

@@ -235,6 +235,7 @@ export type LatencyControllerConfig = {
   liveSyncDuration?: number;
   liveMaxLatencyDuration?: number;
   maxLiveSyncPlaybackRate: number;
+  liveSyncOnStallIncrease: number;
 };
 
 export type MetadataControllerConfig = {
@@ -352,6 +353,7 @@ export const hlsDefaultConfig: HlsConfig = {
   nudgeMaxRetry: 3, // used by stream-controller
   maxFragLookUpTolerance: 0.25, // used by stream-controller
   liveSyncDurationCount: 3, // used by latency-controller
+  liveSyncOnStallIncrease: 1, // used by latency-controller
   liveMaxLatencyDurationCount: Infinity, // used by latency-controller
   liveSyncDuration: undefined, // used by latency-controller
   liveMaxLatencyDuration: undefined, // used by latency-controller

src/controller/latency-controller.ts

@@ -60,11 +60,10 @@ export default class LatencyController implements ComponentAPI {
           : liveSyncDurationCount * targetduration;
     }
     const maxLiveSyncOnStallIncrease = targetduration;
-    const liveSyncOnStallIncrease = 1.0;
     return (
       targetLatency +
       Math.min(
-        this.stallCount * liveSyncOnStallIncrease,
+        this.stallCount * this.config.liveSyncOnStallIncrease,
         maxLiveSyncOnStallIncrease,
       )
     );

tests/unit/controller/latency-controller.ts

@@ -181,6 +181,21 @@ describe('LatencyController', function () {
       latencyController['stallCount'] += 1;
       expect(latencyController.targetLatency).to.equal(6.5);
     });
+
+    it('liveSyncOnStallIncrease can control how fast targetduration increases on stall', function () {
+      latencyController['config'].lowLatencyMode = true;
+      latencyController['config'].liveSyncOnStallIncrease = 1.3;
+      levelDetails.targetduration = 3.5;
+      levelDetails.partHoldBack = 3;
+      levelDetails.age = 0;
+      expect(latencyController.targetLatency).to.equal(3);
+      latencyController['stallCount'] = 1;
+      expect(latencyController.targetLatency).to.equal(4.3);
+      latencyController['stallCount'] += 1;
+      expect(latencyController.targetLatency).to.equal(5.6);
+      latencyController['stallCount'] += 1;
+      expect(latencyController.targetLatency).to.equal(6.5);
+    });
   });
 
   describe('liveSyncPosition', function () {