Re-elect penalized level after configurable penalty expiry (#7771)

Authored-by: Harshit Dokania <hadokani@microsoft.com>

Author: Harshit661000143

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

@@ -2355,6 +2355,7 @@ export interface HlsChunkPerformanceTiming extends HlsPerformanceTiming {
     executeStart: number;
 }
 
+// Warning: (ae-forgotten-export) The symbol "ErrorControllerConfig" needs to be exported by the entry point hls.d.ts
 // Warning: (ae-missing-release-tag) "HlsConfig" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -2400,7 +2401,7 @@ export type HlsConfig = {
     progressive: boolean;
     lowLatencyMode: boolean;
     primarySessionId?: string;
-} & ABRControllerConfig & BufferControllerConfig & CapLevelControllerConfig & EMEControllerConfig & FPSControllerConfig & GapControllerConfig & LevelControllerConfig & MP4RemuxerConfig & StreamControllerConfig & SelectionPreferences & LatencyControllerConfig & MetadataControllerConfig & TimelineControllerConfig & TSDemuxerConfig & HlsLoadPolicies & PlaylistControllerConfig & FragmentLoaderConfig & PlaylistLoaderConfig;
+} & ABRControllerConfig & BufferControllerConfig & CapLevelControllerConfig & EMEControllerConfig & ErrorControllerConfig & FPSControllerConfig & GapControllerConfig & LevelControllerConfig & MP4RemuxerConfig & StreamControllerConfig & SelectionPreferences & LatencyControllerConfig & MetadataControllerConfig & TimelineControllerConfig & TSDemuxerConfig & HlsLoadPolicies & PlaylistControllerConfig & FragmentLoaderConfig & PlaylistLoaderConfig;
 
 // Warning: (ae-missing-release-tag) "HlsEventEmitter" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -3251,6 +3252,8 @@ export class Level {
     // (undocumented)
     loadError: number;
     // (undocumented)
+    loadErrorTime: number;
+    // (undocumented)
     get maxBitrate(): number;
     // (undocumented)
     readonly name: string;

src/config.ts

@@ -153,6 +153,14 @@ export type FPSControllerConfig = {
   fpsDroppedMonitoringThreshold: number;
 };
 
+export type ErrorControllerConfig = {
+  /**
+   * Duration in milliseconds after which a penalized level (loadError > 0) becomes
+   * eligible for re-election. Set to 0 (default) to disable penalty expiry.
+   */
+  errorPenaltyExpireMs: number;
+};
+
 export type LevelControllerConfig = {
   startLevel?: number;
 };
@@ -350,6 +358,7 @@ export type HlsConfig = {
   BufferControllerConfig &
   CapLevelControllerConfig &
   EMEControllerConfig &
+  ErrorControllerConfig &
   FPSControllerConfig &
   GapControllerConfig &
   LevelControllerConfig &
@@ -478,6 +487,7 @@ export const hlsDefaultConfig: HlsConfig = {
   interstitialLiveLookAhead: 10,
   useMediaCapabilities: __USE_MEDIA_CAPABILITIES__,
   preserveManualLevelOnError: false,
+  errorPenaltyExpireMs: 0, // used by error-controller and abr-controller
 
   certLoadPolicy: {
     default: defaultLoadPolicy,

src/controller/abr-controller.ts

@@ -2,6 +2,7 @@ import { ErrorDetails } from '../errors';
 import { Events } from '../events';
 import { type Fragment, fragmentsAreEqual } from '../loader/fragment';
 import { PlaylistLevelType } from '../types/loader';
+import { isPenaltyExpired } from '../utils/error-helper';
 import EwmaBandWidthEstimator from '../utils/ewma-bandwidth-estimator';
 import { Logger } from '../utils/logger';
 import {
@@ -959,9 +960,10 @@ class AbrController extends Logger implements AbrComponentAPI {
       const canSwitchWithinTolerance =
         // if adjusted bw is greater than level bitrate AND
         adjustedbw >= bitrate &&
-        // no level change, or new level has no error history
+        // no level change, new level has no error history or penalty expired because error happened a while ago
         (i === lastLoadedFragLevel ||
-          (levelInfo.loadError === 0 && levelInfo.fragmentError === 0)) &&
+          (levelInfo.loadError === 0 && levelInfo.fragmentError === 0) ||
+          isPenaltyExpired(levelInfo, this.hls.config.errorPenaltyExpireMs)) &&
         // fragment fetchDuration unknown OR live stream OR fragment fetchDuration less than max allowed fetch duration, then this level matches
         // we don't account for max Fetch Duration for live streams, this is to avoid switching down when near the edge of live sliding window ...
         // special case to support startLevel = -1 (bitrateTest) on live streams : in that case we should not exit loop so that findBestLevel will return -1

src/controller/error-controller.ts

@@ -7,6 +7,7 @@ import { getCodecsForMimeType } from '../utils/codecs';
 import {
   getRetryConfig,
   isKeyError,
+  isPenaltyExpired,
   isTimeoutError,
   isUnusableKeyError,
   shouldRetry,
@@ -362,6 +363,7 @@ export default class ErrorController
     if (level) {
       const errorDetails = data.details;
       level.loadError++;
+      level.loadErrorTime = self.performance.now();
       if (errorDetails === ErrorDetails.BUFFER_APPEND_ERROR) {
         level.fragmentError++;
       }
@@ -397,7 +399,11 @@ export default class ErrorController
           candidate !== loadLevel &&
           candidate >= minAutoLevel &&
           candidate <= maxAutoLevel &&
-          levels[candidate].loadError === 0
+          (levels[candidate].loadError === 0 ||
+            isPenaltyExpired(
+              levels[candidate],
+              hls.config.errorPenaltyExpireMs,
+            ))
         ) {
           const levelCandidate = levels[candidate];
 

src/types/level.ts

@@ -120,6 +120,7 @@ export class Level {
   public details?: LevelDetails;
   public fragmentError: number = 0;
   public loadError: number = 0;
+  public loadErrorTime: number = 0;
   public loaded?: { bytes: number; duration: number };
   public realBitrate: number = 0;
   public supportedPromise?: Promise<MediaDecodingInfo>;

src/utils/error-helper.ts

@@ -1,6 +1,7 @@
 import { ErrorDetails } from '../errors';
 import type { LoaderConfig, LoadPolicy, RetryConfig } from '../config';
 import type { ErrorData } from '../types/events';
+import type { Level } from '../types/level';
 import type { LoaderResponse } from '../types/loader';
 
 export function isTimeoutError(error: ErrorData): boolean {
@@ -93,3 +94,17 @@ export function retryForHttpStatus(httpStatus: number | undefined): boolean {
 export function offlineHttpStatus(httpStatus: number | undefined): boolean {
   return httpStatus === 0 && navigator.onLine === false;
 }
+
+export function isPenaltyExpired(level: Level, expireMs: number): boolean {
+  // A penalized level (loadError > 0) is excluded from ABR upswitch and error
+  // recovery candidate selection. Its errors only clear when it successfully
+  // buffers — but it can't buffer because it won't be selected — leaving the
+  // player stuck at a lower quality until stopLoad. This allows a penalized
+  // level to be re-elected once its penalty has expired.
+  return (
+    expireMs > 0 &&
+    level.loadError > 0 &&
+    level.loadErrorTime !== 0 &&
+    self.performance.now() - level.loadErrorTime > expireMs
+  );
+}

tests/unit/utils/error-helper.js

@@ -1,7 +1,22 @@
 import { expect } from 'chai';
-import { shouldRetry } from '../../../src/utils/error-helper';
+import { isPenaltyExpired, shouldRetry } from '../../../src/utils/error-helper';
 
 describe('ErrorHelper', function () {
+  describe('isPenaltyExpired', function () {
+    it('level with loadError but no loadErrorTime is not elected', function () {
+      const level = { loadError: 1, loadErrorTime: 0 };
+      expect(isPenaltyExpired(level, 60_000)).to.be.false;
+    });
+
+    it('level with loadError and elapsed loadErrorTime is elected', function () {
+      const level = {
+        loadError: 1,
+        loadErrorTime: self.performance.now() - 60_001,
+      };
+      expect(isPenaltyExpired(level, 60_000)).to.be.true;
+    });
+  });
+
   it('shouldRetry', function () {
     const retryConfig = {
       maxNumRetry: 3,