add loader context types

dzianis-dashkevich · robwalch · commit a50bb7e0fd31 · 2026-03-26T12:16:21.000-07:00
diff --git a/api-extractor/report/hls.js.api.md b/api-extractor/report/hls.js.api.md
@@ -1994,6 +1994,8 @@ export interface FragmentLoaderContext extends LoaderContext {
     part: Part | null;
     // (undocumented)
     resetIV?: boolean;
+    // (undocumented)
+    type: LoaderContextType.MEDIA_FRAGMENT;
 }
 
 // Warning: (ae-missing-release-tag) "FragmentLoadProgressCallback" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -3113,6 +3115,8 @@ export interface KeyLoaderContext extends LoaderContext {
     frag: Fragment;
     // (undocumented)
     keyInfo: KeyLoaderInfo;
+    // (undocumented)
+    type: LoaderContextType.KEY;
 }
 
 // Warning: (ae-missing-release-tag) "KeyLoaderInfo" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -3772,9 +3776,35 @@ export interface LoaderContext {
     // (undocumented)
     responseType: string;
     // (undocumented)
+    type: LoaderContextType;
+    // (undocumented)
     url: string;
 }
 
+// Warning: (ae-missing-release-tag) "LoaderContextType" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+export const enum LoaderContextType {
+    // (undocumented)
+    AUDIO_TRACK = "audioTrack",
+    // (undocumented)
+    INTERSTITIAL_ASSET_LIST = "interstitial-asset-list",
+    // (undocumented)
+    KEY = "key",
+    // (undocumented)
+    LEVEL = "level",
+    // (undocumented)
+    MANIFEST = "manifest",
+    // (undocumented)
+    MEDIA_FRAGMENT = "media-fragment",
+    // (undocumented)
+    SERVER_CERTIFICATE = "server-certificate",
+    // (undocumented)
+    STEERING_MANIFEST = "steering-manifest",
+    // (undocumented)
+    SUBTITLE_TRACK = "subtitleTrack"
+}
+
 // Warning: (ae-missing-release-tag) "LoaderOnAbort" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -4406,16 +4436,7 @@ export type PlayheadTimes = {
 // Warning: (ae-missing-release-tag) "PlaylistContextType" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
-export const enum PlaylistContextType {
-    // (undocumented)
-    AUDIO_TRACK = "audioTrack",
-    // (undocumented)
-    LEVEL = "level",
-    // (undocumented)
-    MANIFEST = "manifest",
-    // (undocumented)
-    SUBTITLE_TRACK = "subtitleTrack"
-}
+export type PlaylistContextType = LoaderContextType.MANIFEST | LoaderContextType.LEVEL | LoaderContextType.AUDIO_TRACK | LoaderContextType.SUBTITLE_TRACK;
 
 // Warning: (ae-missing-release-tag) "PlaylistControllerConfig" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
diff --git a/src/controller/audio-stream-controller.ts b/src/controller/audio-stream-controller.ts
@@ -7,7 +7,7 @@ import { ErrorDetails } from '../errors';
 import { Events } from '../events';
 import { ElementaryStreamTypes, isMediaFragment } from '../loader/fragment';
 import { Level } from '../types/level';
-import { PlaylistContextType, PlaylistLevelType } from '../types/loader';
+import { LoaderContextType, PlaylistLevelType } from '../types/loader';
 import { ChunkMetadata } from '../types/transmuxer';
 import { alignStream } from '../utils/discontinuities';
 import {
@@ -817,7 +817,7 @@ class AudioStreamController
         if (
           !data.levelRetry &&
           this.state === State.WAITING_TRACK &&
-          data.context?.type === PlaylistContextType.AUDIO_TRACK
+          data.context?.type === LoaderContextType.AUDIO_TRACK
         ) {
           this.state = State.IDLE;
         }
diff --git a/src/controller/audio-track-controller.ts b/src/controller/audio-track-controller.ts
@@ -1,7 +1,7 @@
 import BasePlaylistController from './base-playlist-controller';
 import { ErrorDetails, ErrorTypes } from '../errors';
 import { Events } from '../events';
-import { PlaylistContextType } from '../types/loader';
+import { LoaderContextType } from '../types/loader';
 import { mediaAttributesIdentical } from '../utils/media-option-attributes';
 import {
   audioMatchPredicate,
@@ -221,7 +221,7 @@ class AudioTrackController extends BasePlaylistController {
     }
 
     if (
-      data.context.type === PlaylistContextType.AUDIO_TRACK &&
+      data.context.type === LoaderContextType.AUDIO_TRACK &&
       data.context.id === this.trackId &&
       inGroupOrNone(data.context.groupId, this.groupIds)
     ) {
diff --git a/src/controller/content-steering-controller.ts b/src/controller/content-steering-controller.ts
@@ -7,9 +7,10 @@ import {
   type LoaderCallbacks,
   type LoaderConfiguration,
   type LoaderContext,
+  LoaderContextType,
   type LoaderResponse,
   type LoaderStats,
-  PlaylistContextType,
+  type PlaylistContextType,
 } from '../types/loader';
 import { AttrList } from '../utils/attr-list';
 import { reassignFragmentLevelIndexes } from '../utils/level-helper';
@@ -320,9 +321,9 @@ export default class ContentSteeringController
     );
     for (let i = 0; i < levels.length; i++) {
       if (
-        (type === PlaylistContextType.AUDIO_TRACK &&
+        (type === LoaderContextType.AUDIO_TRACK &&
           levels[i].hasAudioGroup(groupId)) ||
-        (type === PlaylistContextType.SUBTITLE_TRACK &&
+        (type === LoaderContextType.SUBTITLE_TRACK &&
           levels[i].hasSubtitleGroup(groupId))
       ) {
         return levels[i].pathwayId;
@@ -437,6 +438,7 @@ export default class ContentSteeringController
       url.searchParams.set('_HLS_throughput', '' + throughput);
     }
     const context: LoaderContext = {
+      type: LoaderContextType.STEERING_MANIFEST,
       responseType: 'json',
       url: url.href,
     };
diff --git a/src/controller/eme-controller.ts b/src/controller/eme-controller.ts
@@ -7,6 +7,14 @@ import {
   isMediaFragment,
 } from '../loader/fragment';
 import { LevelKey } from '../loader/level-key';
+import {
+  type Loader,
+  type LoaderCallbacks,
+  type LoaderConfiguration,
+  type LoaderContext,
+  LoaderContextType,
+  type PlaylistLevelType,
+} from '../types/loader';
 import { arrayValuesMatch } from '../utils/arrays';
 import {
   addEventListener,
@@ -39,13 +47,6 @@ import type {
   ManifestLoadedData,
   MediaAttachedData,
 } from '../types/events';
-import type {
-  Loader,
-  LoaderCallbacks,
-  LoaderConfiguration,
-  LoaderContext,
-  PlaylistLevelType,
-} from '../types/loader';
 
 type KeySystemAccessPromises = {
   keySystemAccess: Promise<MediaKeySystemAccess>;
@@ -1226,6 +1227,7 @@ class EMEController extends Logger implements ComponentAPI {
     this.log(`Fetching server certificate for "${keySystem}"`);
     return new Promise((resolve, reject) => {
       const loaderContext: LoaderContext = {
+        type: LoaderContextType.SERVER_CERTIFICATE,
         responseType: 'arraybuffer',
         url,
       };
diff --git a/src/controller/error-controller.ts b/src/controller/error-controller.ts
@@ -2,7 +2,7 @@ import { findFragmentByPTS } from './fragment-finders';
 import { ErrorDetails, ErrorTypes } from '../errors';
 import { Events } from '../events';
 import { HdcpLevels } from '../types/level';
-import { PlaylistContextType, PlaylistLevelType } from '../types/loader';
+import { LoaderContextType, PlaylistLevelType } from '../types/loader';
 import { getCodecsForMimeType } from '../utils/codecs';
 import {
   getRetryConfig,
@@ -203,9 +203,9 @@ export default class ErrorController
           const level = hls.loadLevelObj;
           if (
             level &&
-            ((context.type === PlaylistContextType.AUDIO_TRACK &&
+            ((context.type === LoaderContextType.AUDIO_TRACK &&
               level.hasAudioGroup(context.groupId)) ||
-              (context.type === PlaylistContextType.SUBTITLE_TRACK &&
+              (context.type === LoaderContextType.SUBTITLE_TRACK &&
                 level.hasSubtitleGroup(context.groupId)))
           ) {
             // Perform Pathway switch or Redundant failover if possible for fastest recovery
@@ -419,9 +419,9 @@ export default class ErrorController
               }
             }
           } else if (
-            (playlistErrorType === PlaylistContextType.AUDIO_TRACK &&
+            (playlistErrorType === LoaderContextType.AUDIO_TRACK &&
               levelCandidate.hasAudioGroup(playlistErrorGroupId)) ||
-            (playlistErrorType === PlaylistContextType.SUBTITLE_TRACK &&
+            (playlistErrorType === LoaderContextType.SUBTITLE_TRACK &&
               levelCandidate.hasSubtitleGroup(playlistErrorGroupId))
           ) {
             // For audio/subs playlist errors find another group ID or fallthrough to redundant fail-over
diff --git a/src/controller/level-controller.ts b/src/controller/level-controller.ts
@@ -2,7 +2,7 @@ import BasePlaylistController from './base-playlist-controller';
 import { ErrorDetails, ErrorTypes } from '../errors';
 import { Events } from '../events';
 import { isVideoRange, Level, VideoRangeValues } from '../types/level';
-import { PlaylistContextType, PlaylistLevelType } from '../types/loader';
+import { LoaderContextType, PlaylistLevelType } from '../types/loader';
 import {
   areCodecsMediaSourceSupported,
   codecsSetSelectionPreferenceValue,
@@ -578,7 +578,7 @@ export default class LevelController extends BasePlaylistController {
     }
 
     if (
-      data.context.type === PlaylistContextType.LEVEL &&
+      data.context.type === LoaderContextType.LEVEL &&
       data.context.level === this.level
     ) {
       this.checkRetry(data);
diff --git a/src/controller/stream-controller.ts b/src/controller/stream-controller.ts
@@ -7,7 +7,7 @@ import { ErrorDetails } from '../errors';
 import { Events } from '../events';
 import { changeTypeSupported } from '../is-supported';
 import { ElementaryStreamTypes, isMediaFragment } from '../loader/fragment';
-import { PlaylistContextType, PlaylistLevelType } from '../types/loader';
+import { LoaderContextType, PlaylistLevelType } from '../types/loader';
 import { ChunkMetadata } from '../types/transmuxer';
 import { BufferHelper } from '../utils/buffer-helper';
 import { pickMostCompleteCodecName } from '../utils/codecs';
@@ -986,7 +986,7 @@ export default class StreamController
         if (
           !data.levelRetry &&
           this.state === State.WAITING_LEVEL &&
-          data.context?.type === PlaylistContextType.LEVEL
+          data.context?.type === LoaderContextType.LEVEL
         ) {
           this.state = State.IDLE;
         }
diff --git a/src/controller/subtitle-track-controller.ts b/src/controller/subtitle-track-controller.ts
@@ -1,6 +1,6 @@
 import BasePlaylistController from './base-playlist-controller';
 import { Events } from '../events';
-import { PlaylistContextType } from '../types/loader';
+import { LoaderContextType } from '../types/loader';
 import { IMSC1_CODEC } from '../utils/imsc1-ttml-parser';
 import { mediaAttributesIdentical } from '../utils/media-option-attributes';
 import {
@@ -385,7 +385,7 @@ class SubtitleTrackController extends BasePlaylistController {
     }
 
     if (
-      data.context.type === PlaylistContextType.SUBTITLE_TRACK &&
+      data.context.type === LoaderContextType.SUBTITLE_TRACK &&
       data.context.id === this.trackId &&
       inGroupOrNone(data.context.groupId, this.groupIds)
     ) {
diff --git a/src/exports-named.ts b/src/exports-named.ts
@@ -58,7 +58,7 @@ export { LevelKey } from './loader/level-key';
 export { LevelDetails } from './loader/level-details';
 export { MetadataSchema } from './types/demuxer';
 export { HlsSkip, HlsUrlParameters } from './types/level';
-export { PlaylistLevelType } from './types/loader';
+export { LoaderContextType, PlaylistLevelType } from './types/loader';
 export { ChunkMetadata } from './types/transmuxer';
 export { BaseSegment, Fragment, Part } from './loader/fragment';
 export {
diff --git a/src/hls.ts b/src/hls.ts
@@ -1541,6 +1541,7 @@ export type {
 } from './types/level';
 export type {
   PlaylistLevelType,
+  LoaderContextType,
   HlsChunkPerformanceTiming,
   HlsPerformanceTiming,
   HlsProgressivePerformanceTiming,
diff --git a/src/loader/fragment-loader.ts b/src/loader/fragment-loader.ts
@@ -1,4 +1,5 @@
 import { ErrorDetails, ErrorTypes } from '../errors';
+import { LoaderContextType } from '../types/loader';
 import { getLoaderConfigWithoutReties } from '../utils/error-helper';
 import type { BaseSegment, Fragment, Part } from './fragment';
 import type { HlsConfig } from '../config';
@@ -321,6 +322,7 @@ function createLoaderContext(
 ): FragmentLoaderContext {
   const segment: BaseSegment = part || frag;
   const loaderContext: FragmentLoaderContext = {
+    type: LoaderContextType.MEDIA_FRAGMENT,
     frag,
     part,
     responseType: 'arraybuffer',
diff --git a/src/loader/interstitial-asset-list.ts b/src/loader/interstitial-asset-list.ts
@@ -5,6 +5,7 @@ import {
 } from './interstitial-event';
 import { ErrorDetails, ErrorTypes } from '../errors';
 import { Events } from '../events';
+import { LoaderContextType } from '../types/loader';
 import type { InterstitialEvent } from './interstitial-event';
 import type Hls from '../hls';
 import type { ErrorData } from '../types/events';
@@ -59,6 +60,7 @@ export class AssetListLoader {
     const Loader = config.loader;
     const loader = new Loader(config) as Loader<LoaderContext>;
     const context: LoaderContext = {
+      type: LoaderContextType.INTERSTITIAL_ASSET_LIST,
       responseType: 'json',
       url: url.href,
     };
diff --git a/src/loader/key-loader.ts b/src/loader/key-loader.ts
@@ -1,6 +1,7 @@
 import { LoadError } from './fragment-loader';
 import { LevelKey } from './level-key';
 import { ErrorDetails, ErrorTypes } from '../errors';
+import { LoaderContextType } from '../types/loader';
 import { arrayToHex } from '../utils/hex';
 import { Logger } from '../utils/logger';
 import { parseKeyIdsFromTenc } from '../utils/mp4-tools';
@@ -227,6 +228,7 @@ export default class KeyLoader extends Logger implements ComponentAPI {
 
     return (keyInfo.keyLoadPromise = new Promise((resolve, reject) => {
       const loaderContext: KeyLoaderContext = {
+        type: LoaderContextType.KEY,
         keyInfo,
         frag,
         responseType: 'arraybuffer',
diff --git a/src/loader/playlist-loader.ts b/src/loader/playlist-loader.ts
diff --git a/src/types/loader.ts b/src/types/loader.ts
diff --git a/tests/unit/controller/audio-track-controller.ts b/tests/unit/controller/audio-track-controller.ts
diff --git a/tests/unit/utils/fetch-loader.ts b/tests/unit/utils/fetch-loader.ts
