Allow primary segment prefetching for interstitial resumption and exp… (#7124)

* Allow primary segment prefetching for interstitial resumption and expand allowance of append-in-line strategy
Resolves #7117

* Handle shortened asset-list result and improve asset-list loaded logging
Fix prefetching asset at live start
Resolves #7117

* Fix prefetching asset segments at target seek position

Author: robwalch

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

@@ -209,7 +209,7 @@ export class AudioStreamController extends BaseStreamController implements Netwo
     // (undocumented)
     protected resetLoadingState(): void;
     // (undocumented)
-    startLoad(startPosition: number): void;
+    startLoad(startPosition: number, skipSeekToStartPosition?: boolean): void;
     // (undocumented)
     protected unregisterListeners(): void;
 }
@@ -402,7 +402,7 @@ export class BaseStreamController extends TaskLoop implements NetworkComponentAP
     // (undocumented)
     protected doTick(): void;
     // (undocumented)
-    filterReplacedPrimary(frag: MediaFragment | null, details: LevelDetails | undefined): MediaFragment | null;
+    protected filterReplacedPrimary(frag: MediaFragment | null, details: LevelDetails | undefined): MediaFragment | null;
     // (undocumented)
     protected flushBufferGap(frag: Fragment): void;
     // (undocumented)
@@ -510,6 +510,8 @@ export class BaseStreamController extends TaskLoop implements NetworkComponentAP
     // (undocumented)
     protected playlistType: PlaylistLevelType;
     // (undocumented)
+    protected get primaryPrefetch(): boolean;
+    // (undocumented)
     protected recoverWorkerError(data: ErrorData): void;
     // (undocumented)
     protected reduceLengthAndFlushBuffer(data: ErrorData): boolean;
@@ -557,6 +559,8 @@ export class BaseStreamController extends TaskLoop implements NetworkComponentAP
     // (undocumented)
     protected _streamEnded(bufferInfo: BufferInfo, levelDetails: LevelDetails): boolean;
     // (undocumented)
+    protected get timelineOffset(): number;
+    // (undocumented)
     protected transmuxer: TransmuxerInterface | null;
     // (undocumented)
     protected unregisterListeners(): void;
@@ -2133,6 +2137,8 @@ export class HlsAssetPlayer {
     // (undocumented)
     get bufferedEnd(): number;
     // (undocumented)
+    bufferedInPlaceToEnd(media?: HTMLMediaElement | null): boolean;
+    // (undocumented)
     get currentTime(): number;
     // (undocumented)
     destroy(): void;
@@ -2689,6 +2695,8 @@ export class InterstitialEvent {
     // (undocumented)
     reset(): void;
     // (undocumented)
+    resetOnResume?: boolean;
+    // (undocumented)
     restrictions: PlaybackRestrictions;
     // (undocumented)
     resumeAnchor?: MediaFragmentRef;
@@ -2705,6 +2713,8 @@ export class InterstitialEvent {
     // (undocumented)
     get startDate(): Date;
     // (undocumented)
+    get startIsAligned(): boolean;
+    // (undocumented)
     get startOffset(): number;
     // (undocumented)
     get startTime(): number;
@@ -4544,7 +4554,7 @@ export class SubtitleStreamController extends BaseStreamController implements Ne
     // (undocumented)
     protected registerListeners(): void;
     // (undocumented)
-    startLoad(startPosition: number): void;
+    startLoad(startPosition: number, skipSeekToStartPosition?: boolean): void;
     // (undocumented)
     protected unregisterListeners(): void;
 }

src/controller/audio-stream-controller.ts

@@ -189,7 +189,7 @@ class AudioStreamController
     );
   }
 
-  startLoad(startPosition: number) {
+  startLoad(startPosition: number, skipSeekToStartPosition?: boolean) {
     if (!this.levels) {
       this.startPosition = startPosition;
       this.state = State.STOPPED;
@@ -209,11 +209,9 @@ class AudioStreamController
     } else {
       this.state = State.WAITING_TRACK;
     }
-    this.nextLoadPosition =
-      this.startPosition =
-      this.lastCurrentTime =
-        startPosition;
-
+    this.nextLoadPosition = this.lastCurrentTime =
+      startPosition + this.timelineOffset;
+    this.startPosition = skipSeekToStartPosition ? -1 : startPosition;
     this.tick();
   }
 
@@ -325,7 +323,9 @@ class AudioStreamController
     // => if media not attached but start frag prefetch is enabled and start frag not requested yet, we will not exit loop
     if (
       !this.buffering ||
-      (!media && (this.startFragRequested || !config.startFragPrefetch)) ||
+      (!media &&
+        !this.primaryPrefetch &&
+        (this.startFragRequested || !config.startFragPrefetch)) ||
       !levels?.[trackId]
     ) {
       return;

src/controller/base-stream-controller.ts

@@ -255,6 +255,17 @@ export default class BaseStreamController
     }
   }
 
+  protected get timelineOffset(): number {
+    const configuredTimelineOffset = this.config.timelineOffset;
+    if (configuredTimelineOffset) {
+      return (
+        this.getLevelDetails()?.appliedTimelineOffset ||
+        configuredTimelineOffset
+      );
+    }
+    return 0;
+  }
+
   protected onMediaAttached(
     event: Events.MEDIA_ATTACHED,
     data: MediaAttachedData,
@@ -1299,9 +1310,8 @@ export default class BaseStreamController
         : levelDetails.fragmentEnd;
       frag = this.getFragmentAtPosition(pos, end, levelDetails);
     }
-
-    frag = this.filterReplacedPrimary(frag, levelDetails);
-    return this.mapToInitFragWhenRequired(frag);
+    const programFrag = this.filterReplacedPrimary(frag, levelDetails);
+    return this.mapToInitFragWhenRequired(programFrag);
   }
 
   protected isLoopLoading(frag: Fragment, targetBufferTime: number): boolean {
@@ -1351,18 +1361,26 @@ export default class BaseStreamController
     return nextFragment;
   }
 
-  filterReplacedPrimary(
+  protected get primaryPrefetch(): boolean {
+    if (interstitialsEnabled(this.hls.config)) {
+      const playingInterstitial =
+        this.hls.interstitialsManager?.playingItem?.event;
+      if (playingInterstitial) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  protected filterReplacedPrimary(
     frag: MediaFragment | null,
     details: LevelDetails | undefined,
   ): MediaFragment | null {
     if (!frag) {
       return frag;
     }
-    const config = this.hls.config;
     if (
-      __USE_INTERSTITIALS__ &&
-      config.interstitialsController &&
-      config.enableInterstitialPlayback !== false &&
+      interstitialsEnabled(this.hls.config) &&
       frag.type !== PlaylistLevelType.SUBTITLE
     ) {
       // Do not load fragments outside the buffering schedule segment
@@ -1388,7 +1406,13 @@ export default class BaseStreamController
           }
           if (frag.start > bufferingItem.end && bufferingItem.nextEvent) {
             // fragment is past schedule item end
-            return null;
+            // allow some overflow when not appending in place to prevent stalls
+            if (
+              bufferingItem.nextEvent.appendInPlace ||
+              frag.start - bufferingItem.end > 1
+            ) {
+              return null;
+            }
           }
         }
       }
@@ -1659,6 +1683,7 @@ export default class BaseStreamController
     if (startPosition < sliding) {
       startPosition = -1;
     }
+    const timelineOffset = this.timelineOffset;
     if (startPosition === -1) {
       // Use Playlist EXT-X-START:TIME-OFFSET when set
       // Prioritize Multivariant Playlist offset so that main, audio, and subtitle stream-controller start times match
@@ -1693,9 +1718,9 @@ export default class BaseStreamController
         this.log(`setting startPosition to 0 by default`);
         this.startPosition = startPosition = 0;
       }
-      this.lastCurrentTime = startPosition;
+      this.lastCurrentTime = startPosition + timelineOffset;
     }
-    this.nextLoadPosition = startPosition;
+    this.nextLoadPosition = startPosition + timelineOffset;
   }
 
   protected getLoadPosition(): number {
@@ -2066,3 +2091,11 @@ export default class BaseStreamController
     return this._state;
   }
 }
+
+function interstitialsEnabled(config: HlsConfig): boolean {
+  return (
+    __USE_INTERSTITIALS__ &&
+    !!config.interstitialsController &&
+    config.enableInterstitialPlayback !== false
+  );
+}

src/controller/buffer-controller.ts

@@ -1051,17 +1051,10 @@ transfer tracks: ${stringify(transferredTracks, (key, value) => (key === 'initSe
       !this.sourceBuffers.some(([type]) => type && !this.tracks[type]?.ended);
 
     if (allTracksEnding) {
-      this.log(`Queueing EOS`);
-      this.blockUntilOpen(() => {
-        this.sourceBuffers.forEach(([type]) => {
-          if (type !== null) {
-            const track = this.tracks[type];
-            if (track) {
-              track.ending = false;
-            }
-          }
-        });
-        if (allowEndOfStream) {
+      if (allowEndOfStream) {
+        this.log(`Queueing EOS`);
+        this.blockUntilOpen(() => {
+          this.tracksEnded();
           const { mediaSource } = this;
           if (!mediaSource || mediaSource.readyState !== 'open') {
             if (mediaSource) {
@@ -1074,12 +1067,27 @@ transfer tracks: ${stringify(transferredTracks, (key, value) => (key === 'initSe
           this.log(`Calling mediaSource.endOfStream()`);
           // Allow this to throw and be caught by the enqueueing function
           mediaSource.endOfStream();
-        }
+
+          this.hls.trigger(Events.BUFFERED_TO_END, undefined);
+        });
+      } else {
+        this.tracksEnded();
         this.hls.trigger(Events.BUFFERED_TO_END, undefined);
-      });
+      }
     }
   }
 
+  private tracksEnded() {
+    this.sourceBuffers.forEach(([type]) => {
+      if (type !== null) {
+        const track = this.tracks[type];
+        if (track) {
+          track.ending = false;
+        }
+      }
+    });
+  }
+
   private onLevelUpdated(
     event: Events.LEVEL_UPDATED,
     { details }: LevelUpdatedData,

src/controller/interstitial-player.ts

@@ -28,6 +28,7 @@ export class HlsAssetPlayer {
   private hasDetails: boolean = false;
   private mediaAttached: HTMLMediaElement | null = null;
   private _currentTime?: number;
+  private _bufferedEosTime?: number;
 
   constructor(
     HlsPlayerClass: typeof Hls,
@@ -62,6 +63,22 @@ export class HlsAssetPlayer {
     });
   }
 
+  bufferedInPlaceToEnd(media?: HTMLMediaElement | null) {
+    if (!this.interstitial.appendInPlace) {
+      return false;
+    }
+    if (this.hls?.bufferedToEnd) {
+      return true;
+    }
+    if (!media || !this._bufferedEosTime) {
+      return false;
+    }
+    const start = this.timelineOffset;
+    const bufferInfo = BufferHelper.bufferInfo(media, start, 0);
+    const bufferedEnd = this.getAssetTime(bufferInfo.end);
+    return bufferedEnd >= this._bufferedEosTime - 0.02;
+  }
+
   private checkPlayout = () => {
     const interstitial = this.interstitial;
     const playoutLimit = interstitial.playoutLimit;
@@ -90,6 +107,9 @@ export class HlsAssetPlayer {
   get bufferedEnd(): number {
     const media = this.media || this.mediaAttached;
     if (!media) {
+      if (this._bufferedEosTime) {
+        return this._bufferedEosTime;
+      }
       return this.currentTime;
     }
     const bufferInfo = BufferHelper.bufferInfo(media, media.currentTime, 0.001);
@@ -153,10 +173,19 @@ export class HlsAssetPlayer {
     const media = this.mediaAttached;
     if (media) {
       this._currentTime = media.currentTime;
+      this.bufferSnapShot();
       media.removeEventListener('timeupdate', this.checkPlayout);
     }
   }
 
+  private bufferSnapShot() {
+    if (this.mediaAttached) {
+      if (this.hls?.bufferedToEnd) {
+        this._bufferedEosTime = this.bufferedEnd;
+      }
+    }
+  }
+
   destroy() {
     this.removeMediaListeners();
     this.hls.destroy();
@@ -185,6 +214,7 @@ export class HlsAssetPlayer {
   }
 
   transferMedia() {
+    this.bufferSnapShot();
     return this.hls.transferMedia();
   }