Gap controller fixes

- Improve stall detection and reporting using "waiting" event timing
- Add `config.detectStallWithCurrentTimeMs` with a default of 1250 to configure stall detection when currentTime does not advance while playing without a "waiting" event
- Implement STALL_RESOLVED event - fires after "playing", "seeked", or "ended" event following BUFFER_STALLED_ERROR (Resolves #4273)
- Add BufferInfo to stall-related errors (BUFFER_STALLED_ERROR, BUFFER_NUDGE_ON_STALL, BUFFER_SEEK_OVER_HOLE)
- Add `stalled.start` performance timing to BUFFER_STALLED_ERROR
- Add `buffered` time range array to BufferInfo
- Only perform BUFFER_NUDGE_ON_STALL when needed (multiple buffered time ranges)
- Fix seek on start without play() request (regression in dev)

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

@@ -763,6 +763,15 @@ export type BufferInfo = {
     start: number;
     end: number;
     nextStart?: number;
+    buffered?: BufferTimeRange[];
+};
+
+// Warning: (ae-missing-release-tag) "BufferTimeRange" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public
+export type BufferTimeRange = {
+    start: number;
+    end: number;
 };
 
 // Warning: (ae-missing-release-tag) "CapLevelController" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -1209,6 +1218,8 @@ export interface ErrorData {
     // (undocumented)
     buffer?: number;
     // (undocumented)
+    bufferInfo?: BufferInfo;
+    // (undocumented)
     bytes?: number;
     // (undocumented)
     chunkMeta?: ChunkMetadata;
@@ -1253,6 +1264,10 @@ export interface ErrorData {
     // (undocumented)
     sourceBufferName?: SourceBufferName;
     // (undocumented)
+    stalled?: {
+        start: number;
+    };
+    // (undocumented)
     stats?: LoaderStats;
     // (undocumented)
     type: ErrorTypes;
@@ -1517,6 +1532,8 @@ export enum Events {
     // (undocumented)
     PLAYOUT_LIMIT_REACHED = "hlsPlayoutLimitReached",
     // (undocumented)
+    STALL_RESOLVED = "hlsStallResolved",
+    // (undocumented)
     STEERING_MANIFEST_LOADED = "hlsSteeringManifestLoaded",
     // (undocumented)
     SUBTITLE_FRAG_PROCESSED = "hlsSubtitleFragProcessed",
@@ -2202,6 +2219,7 @@ export type HlsConfig = {
     progressive: boolean;
     lowLatencyMode: boolean;
     primarySessionId?: string;
+    detectStallWithCurrentTimeMs: number;
 } & ABRControllerConfig & BufferControllerConfig & CapLevelControllerConfig & EMEControllerConfig & FPSControllerConfig & LevelControllerConfig & MP4RemuxerConfig & StreamControllerConfig & SelectionPreferences & LatencyControllerConfig & MetadataControllerConfig & TimelineControllerConfig & TSDemuxerConfig & HlsLoadPolicies & 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)
@@ -2359,6 +2377,8 @@ export interface HlsListeners {
     // (undocumented)
     [Events.PLAYOUT_LIMIT_REACHED]: (event: Events.PLAYOUT_LIMIT_REACHED, data: {}) => void;
     // (undocumented)
+    [Events.STALL_RESOLVED]: (event: Events.STALL_RESOLVED, data: {}) => void;
+    // (undocumented)
     [Events.STEERING_MANIFEST_LOADED]: (event: Events.STEERING_MANIFEST_LOADED, data: SteeringManifestLoadedData) => void;
     // (undocumented)
     [Events.SUBTITLE_FRAG_PROCESSED]: (event: Events.SUBTITLE_FRAG_PROCESSED, data: SubtitleFragProcessedData) => void;

src/config.ts

@@ -319,6 +319,7 @@ export type HlsConfig = {
   progressive: boolean;
   lowLatencyMode: boolean;
   primarySessionId?: string;
+  detectStallWithCurrentTimeMs: number;
 } & ABRControllerConfig &
   BufferControllerConfig &
   CapLevelControllerConfig &
@@ -427,6 +428,7 @@ export const hlsDefaultConfig: HlsConfig = {
   progressive: false,
   lowLatencyMode: true,
   cmcd: undefined,
+  detectStallWithCurrentTimeMs: 1250,
   enableDateRangeMetadataCues: true,
   enableEmsgMetadataCues: true,
   enableEmsgKLVMetadata: false,