Feature: Implement support for LL-HLS #EXT-X-PRELOAD-HINT part loading

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

@@ -288,6 +288,8 @@ export class BaseSegment {
     // (undocumented)
     elementaryStreams: ElementaryStreams;
     // (undocumented)
+    isPreload?: boolean;
+    // (undocumented)
     relurl?: string;
     // (undocumented)
     setByteRange(value: string, previous?: BaseSegment): void;
@@ -315,6 +317,8 @@ export class BaseStreamController extends TaskLoop implements NetworkComponentAP
     // (undocumented)
     protected buffering: boolean;
     // (undocumented)
+    protected cachePreloadHint(details: LevelDetails): void;
+    // (undocumented)
     protected checkLiveUpdate(details: LevelDetails): void;
     // (undocumented)
     protected clearTrackerIfNeeded(frag: Fragment): void;
@@ -344,6 +348,10 @@ export class BaseStreamController extends TaskLoop implements NetworkComponentAP
     //
     // (undocumented)
     protected fragmentLoader: FragmentLoader;
+    // Warning: (ae-forgotten-export) The symbol "FragmentPreloader" needs to be exported by the entry point hls.d.ts
+    //
+    // (undocumented)
+    protected fragmentPreloader: FragmentPreloader;
     // (undocumented)
     protected fragmentTracker: FragmentTracker;
     // (undocumented)
@@ -401,6 +409,8 @@ export class BaseStreamController extends TaskLoop implements NetworkComponentAP
     // (undocumented)
     protected levels: Array<Level> | null;
     // (undocumented)
+    protected loadedEndOfParts(partList: Part[], targetBufferTime: number): boolean;
+    // (undocumented)
     protected loadedmetadata: boolean;
     // (undocumented)
     protected loadFragment(frag: Fragment, level: Level, targetBufferTime: number): void;
@@ -2231,6 +2241,11 @@ export class LevelDetails {
     // (undocumented)
     playlistParsingError: Error | null;
     // (undocumented)
+    preloadData?: {
+        frag: Fragment;
+        part?: Part;
+    };
+    // (undocumented)
     preloadHint?: AttrList;
     // (undocumented)
     PTSKnown: boolean;
@@ -3000,7 +3015,7 @@ export interface NonNativeTextTracksData {
 //
 // @public
 export class Part extends BaseSegment {
-    constructor(partAttrs: AttrList, frag: Fragment, baseurl: string, index: number, previous?: Part);
+    constructor(partAttrs: AttrList, frag: Fragment, baseurl: string, index: number, previous?: Part, isPreload?: boolean);
     // (undocumented)
     readonly duration: number;
     // (undocumented)

src/controller/abr-controller.ts

@@ -378,7 +378,10 @@ class AbrController extends Logger implements AbrComponentAPI {
     { frag, part }: FragLoadedData,
   ) {
     const stats = part ? part.stats : frag.stats;
-    if (frag.type === PlaylistLevelType.MAIN) {
+    if (
+      frag.type === PlaylistLevelType.MAIN &&
+      !(part?.isPreload || frag.isPreload)
+    ) {
       this.bwEstimator.sampleTTFB(stats.loading.first - stats.loading.start);
     }
     if (this.ignoreFragment(frag)) {
@@ -434,9 +437,12 @@ class AbrController extends Logger implements AbrComponentAPI {
     // Use the difference between parsing and request instead of buffering and request to compute fragLoadingProcessing;
     // rationale is that buffer appending only happens once media is attached. This can happen when config.startFragPrefetch
     // is used. If we used buffering in that case, our BW estimate sample will be very large.
+    const loadStart = part?.isPreload
+      ? stats.loading.first
+      : stats.loading.start;
     const processingMs =
       stats.parsing.end -
-      stats.loading.start -
+      loadStart -
       Math.min(
         stats.loading.first - stats.loading.start,
         this.bwEstimator.getEstimateTTFB(),

src/controller/audio-stream-controller.ts

@@ -520,6 +520,8 @@ class AudioStreamController
     let sliding = 0;
     if (newDetails.live || track.details?.live) {
       this.checkLiveUpdate(newDetails);
+      // reset the preloader state to IDLE if we have finished loading, never loaded, or have old data
+      this.fragmentPreloader.revalidate(data);
       const mainDetails = this.mainDetails;
       if (newDetails.deltaUpdateFailed || !mainDetails) {
         return;

src/controller/base-stream-controller.ts

@@ -52,6 +52,7 @@ import type { HlsConfig } from '../config';
 import type { NetworkComponentAPI } from '../types/component-api';
 import type { SourceBufferName } from '../types/buffer';
 import type { RationalTimestamp } from '../utils/timescale-conversion';
+import FragmentPreloader from '../loader/fragment-preloader';
 
 type ResolveFragLoaded = (FragLoadedEndData) => void;
 type RejectFragLoaded = (LoadError) => void;
@@ -95,6 +96,7 @@ export default class BaseStreamController
   protected retryDate: number = 0;
   protected levels: Array<Level> | null = null;
   protected fragmentLoader: FragmentLoader;
+  protected fragmentPreloader: FragmentPreloader;
   protected keyLoader: KeyLoader;
   protected levelLastLoaded: Level | null = null;
   protected startFragRequested: boolean = false;
@@ -114,6 +116,7 @@ export default class BaseStreamController
     this.playlistType = playlistType;
     this.hls = hls;
     this.fragmentLoader = new FragmentLoader(hls.config);
+    this.fragmentPreloader = new FragmentPreloader(hls.config, logPrefix);
     this.keyLoader = keyLoader;
     this.fragmentTracker = fragmentTracker;
     this.config = hls.config;
@@ -149,7 +152,8 @@ export default class BaseStreamController
 
   public stopLoad() {
     this.fragmentLoader.abort();
-    this.keyLoader.abort(this.playlistType);
+    this.fragmentPreloader.abort();
+    this.keyLoader.abort();
     const frag = this.fragCurrent;
     if (frag?.loader) {
       frag.abortRequests();
@@ -349,6 +353,14 @@ export default class BaseStreamController
     this.initPTS = [];
   }
 
+  protected cachePreloadHint(details: LevelDetails): void {
+    const data = details.preloadData;
+    if (!data) {
+      return;
+    }
+    this.fragmentPreloader.cache(data.frag, data.part);
+  }
+
   protected onHandlerDestroying() {
     this.stopLoad();
     super.onHandlerDestroying();
@@ -361,6 +373,9 @@ export default class BaseStreamController
     if (this.fragmentLoader) {
       this.fragmentLoader.destroy();
     }
+    if (this.fragmentPreloader) {
+      this.fragmentPreloader.destroy();
+    }
     if (this.keyLoader) {
       this.keyLoader.destroy();
     }
@@ -374,6 +389,7 @@ export default class BaseStreamController
       this.decrypter =
       this.keyLoader =
       this.fragmentLoader =
+      this.fragmentPreloader =
       this.fragmentTracker =
         null as any;
     super.onHandlerDestroyed();
@@ -739,6 +755,10 @@ export default class BaseStreamController
         if (targetBufferTime > frag.end && details.fragmentHint) {
           frag = details.fragmentHint;
         }
+        const loadedEndOfParts = this.loadedEndOfParts(
+          partList,
+          targetBufferTime,
+        );
         const partIndex = this.getNextPart(partList, frag, targetBufferTime);
         if (partIndex > -1) {
           const part = partList[partIndex];
@@ -794,10 +814,15 @@ export default class BaseStreamController
             );
           }
           return result;
-        } else if (
-          !frag.url ||
-          this.loadedEndOfParts(partList, targetBufferTime)
-        ) {
+        } else if (!frag.url || loadedEndOfParts) {
+          if (
+            loadedEndOfParts &&
+            this.hls.lowLatencyMode &&
+            details?.live &&
+            details.canBlockReload
+          ) {
+            this.cachePreloadHint(details);
+          }
           // Fragment hint has no parts
           return Promise.resolve(null);
         }
@@ -834,23 +859,28 @@ export default class BaseStreamController
     let result: Promise<PartsLoadedData | FragLoadedData | null>;
     if (dataOnProgress && keyLoadingPromise) {
       result = keyLoadingPromise
-        .then((keyLoadedData) => {
+        .then((keyLoadedData: void | KeyLoadedData) => {
           if (!keyLoadedData || this.fragContextChanged(keyLoadedData?.frag)) {
             return null;
           }
-          return this.fragmentLoader.load(frag, progressCallback);
+          return this.getCachedRequestOrLoad(
+            frag,
+            /*part*/ undefined,
+            /*dataOnProgress*/ true,
+            progressCallback,
+          );
         })
         .catch((error) => this.handleFragLoadError(error));
     } else {
       // load unencrypted fragment data with progress event,
       // or handle fragment result after key and fragment are finished loading
-      result = Promise.all([
-        this.fragmentLoader.load(
-          frag,
-          dataOnProgress ? progressCallback : undefined,
-        ),
-        keyLoadingPromise,
-      ])
+      const loadRequest = this.getCachedRequestOrLoad(
+        frag,
+        /*part*/ undefined,
+        dataOnProgress,
+        progressCallback,
+      );
+      result = Promise.all([loadRequest, keyLoadingPromise])
         .then(([fragLoadedData]) => {
           if (!dataOnProgress && fragLoadedData && progressCallback) {
             progressCallback(fragLoadedData);
@@ -879,8 +909,7 @@ export default class BaseStreamController
         const partsLoaded: FragLoadedData[] = [];
         const initialPartList = level.details?.partList;
         const loadPart = (part: Part) => {
-          this.fragmentLoader
-            .loadPart(frag, part, progressCallback)
+          this.getCachedRequestOrLoad(frag, part, true, progressCallback)
             .then((partLoadedData: FragLoadedData) => {
               partsLoaded[part.index] = partLoadedData;
               const loadedPart = partLoadedData.part as Part;
@@ -905,6 +934,36 @@ export default class BaseStreamController
     );
   }
 
+  private getCachedRequestOrLoad(
+    frag: Fragment,
+    part: Part | undefined,
+    dataOnProgress: boolean,
+    progressCallback?: FragmentLoadProgressCallback,
+  ): Promise<FragLoadedData | PartsLoadedData> {
+    const request = this.fragmentPreloader.getCachedRequest(frag, part);
+    if (request !== undefined) {
+      return request.then((data) => {
+        if (progressCallback) {
+          progressCallback(data);
+        }
+        return data;
+      });
+    }
+
+    if (part) {
+      return this.fragmentLoader.loadPart(
+        frag,
+        part,
+        progressCallback ?? (() => {}),
+      );
+    }
+
+    return this.fragmentLoader.load(
+      frag,
+      dataOnProgress ? progressCallback : undefined,
+    );
+  }
+
   private handleFragLoadError(error: LoadError | Error) {
     if ('data' in error) {
       const data = error.data;
@@ -1300,7 +1359,7 @@ export default class BaseStreamController
     return nextPart;
   }
 
-  private loadedEndOfParts(
+  protected loadedEndOfParts(
     partList: Part[],
     targetBufferTime: number,
   ): boolean {
@@ -1612,6 +1671,7 @@ export default class BaseStreamController
     ) {
       this.state = State.IDLE;
     }
+    this.fragmentPreloader.abort();
   }
 
   protected onFragmentOrKeyLoadError(
@@ -1762,6 +1822,7 @@ export default class BaseStreamController
     if (this.state !== State.STOPPED) {
       this.state = State.IDLE;
     }
+    this.fragmentPreloader.abort();
   }
 
   protected resetStartWhenNotLoaded(level: Level | null): void {

src/controller/error-controller.ts

@@ -279,6 +279,12 @@ export default class ErrorController
   }
 
   private getFragRetryOrSwitchAction(data: ErrorData): IErrorAction {
+    if (data.frag?.isPreload) {
+      return {
+        action: NetworkErrorAction.DoNothing,
+        flags: ErrorActionFlags.None,
+      };
+    }
     const hls = this.hls;
     // Share fragment error count accross media options (main, audio, subs)
     // This allows for level based rendition switching when media option assets fail

src/controller/stream-controller.ts

@@ -653,6 +653,15 @@ export default class StreamController
     let sliding = 0;
     if (newDetails.live || curLevel.details?.live) {
       this.checkLiveUpdate(newDetails);
+      if (
+        this.fragmentPreloader.loading &&
+        this.fragmentPreloader.frag?.level !== data.level
+      ) {
+        this.fragmentPreloader.abort();
+      } else {
+        // reset the preloader state if we have finished loading, never loaded, or have old data
+        this.fragmentPreloader.revalidate(data);
+      }
       if (newDetails.deltaUpdateFailed) {
         return;
       }