@videojs/spf 10.0.0-beta.24 → 10.0.0-beta.26

package/dist/default/media/utils/tracks.js

@@ -53,19 +53,19 @@ function findTrackById(presentation, trackId) {
 function findResolvedTextTrack(presentation, trackId) {
 	if (!presentation || !trackId) return void 0;
 	const track = findTrack(presentation, "text", trackId);
-	if (!track || track.type !== "text" || !isResolvedTrack(track)) return void 0;
+	if (track?.type !== "text" || !isResolvedTrack(track)) return void 0;
 	return track;
 }
 function findResolvedVideoTrack(presentation, trackId) {
 	if (!presentation || !trackId) return void 0;
 	const track = findTrack(presentation, "video", trackId);
-	if (!track || track.type !== "video" || !isResolvedTrack(track)) return void 0;
+	if (track?.type !== "video" || !isResolvedTrack(track)) return void 0;
 	return track;
 }
 function findResolvedAudioTrack(presentation, trackId) {
 	if (!presentation || !trackId) return void 0;
 	const track = findTrack(presentation, "audio", trackId);
-	if (!track || track.type !== "audio" || !isResolvedTrack(track)) return void 0;
+	if (track?.type !== "audio" || !isResolvedTrack(track)) return void 0;
 	return track;
 }
 /**
@@ -81,6 +81,33 @@ function hasCodecs(track) {
 	return !!track && "codecs" in track && !!track.codecs?.length;
 }
 /**
+* Set `mimeType` on every track of one `type` (immutably). Used to propagate a
+* detected container across a type's renditions: an ABR ladder is the same
+* content at different bitrates, so one rendition's container holds for all of
+* them — capability probing + SourceBuffer setup then get the right MIME for the
+* whole type from a single resolved media playlist, without fetching the rest.
+*
+* Scoped to one type on purpose: propagating *across* audio/video would be wrong
+* for mixed-container sources (e.g. muxed-TS video + raw-`.aac` audio) and races
+* concurrent per-type resolution. Same-type writes are disjoint and safe.
+* Idempotent — tracks already at `mimeType` are left as-is.
+*/
+function applyContainerMimeType(presentation, type, mimeType) {
+	return {
+		...presentation,
+		selectionSets: presentation.selectionSets.map((selectionSet) => selectionSet.type === type ? {
+			...selectionSet,
+			switchingSets: selectionSet.switchingSets.map((switchingSet) => ({
+				...switchingSet,
+				tracks: switchingSet.tracks.map((track) => track.mimeType === mimeType ? track : {
+					...track,
+					mimeType
+				})
+			}))
+		} : selectionSet)
+	};
+}
+/**
 * Updates a track within a presentation (immutably). Generic — works for
 * video, audio, or text tracks.
 */
@@ -98,6 +125,6 @@ function updateTrackInPresentation(presentation, resolvedTrack) {
 	};
 }
 //#endregion
-export { findResolvedAudioTrack, findResolvedTextTrack, findResolvedVideoTrack, findTrack, findTrackById, getTracksByType, hasCodecs, updateTrackInPresentation };
+export { applyContainerMimeType, findResolvedAudioTrack, findResolvedTextTrack, findResolvedVideoTrack, findTrack, findTrackById, getTracksByType, hasCodecs, updateTrackInPresentation };
 
 //# sourceMappingURL=tracks.js.map

package/dist/default/media/utils/tracks.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracks.js","names":[],"sources":["../../../../src/media/utils/tracks.ts"],"sourcesContent":["import type {\n  AudioTrack,\n  MaybeResolvedPresentation,\n  PartiallyResolvedTrack,\n  Presentation,\n  ResolvedTrack,\n  TextTrack,\n  TrackType,\n  VideoTrack,\n} from '../types';\nimport { isResolvedTrack } from '../types';\n\n/**\n * Get the tracks of the given type from a presentation's first switching set.\n *\n * Returns `[]` when the presentation is unresolved, when no selection set of\n * `type` exists, or when its first switching set is empty. Returned tracks may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n *\n * The \"first switching set\" assumption matches the rest of the codebase\n * (HLS typically has one switching set per type); multi-group / multi-period\n * support would generalize this.\n */\nexport function getTracksByType(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType\n): readonly (PartiallyResolvedTrack | ResolvedTrack)[] {\n  return presentation.selectionSets?.find(({ type: t }) => t === type)?.switchingSets[0]?.tracks ?? [];\n}\n\n/**\n * Find a track of the given type and id within a presentation.\n *\n * Returns the matching track from the first switching set of the matching\n * selection set, or `undefined` if either is missing. The returned track may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n */\nexport function findTrack(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  return getTracksByType(presentation, type).find(({ id }) => id === trackId);\n}\n\n/**\n * Find a track by id across all selection sets in a presentation, without\n * knowing its type up front. Used when the caller has a track id obtained\n * from a downstream consumer (e.g. `SourceBufferActor.initTrackId`) and\n * needs to locate the corresponding track in the presentation.\n *\n * Track ids are unique within a presentation per the HLS spec; the first\n * match wins.\n */\nexport function findTrackById(\n  presentation: MaybeResolvedPresentation,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  for (const selectionSet of presentation.selectionSets ?? []) {\n    const track = selectionSet.switchingSets[0]?.tracks.find(({ id }) => id === trackId);\n    if (track) return track;\n  }\n  return undefined;\n}\n\n/**\n * Find a text track of the given id within a presentation and narrow it to\n * the fully-resolved `TextTrack` shape (segments populated). Returns\n * `undefined` if no track matches the id, the matching track isn't a text\n * track, or it hasn't been resolved yet.\n *\n * The segments-non-empty check stays at the call site — a resolved track\n * with zero segments is a valid state, distinct from \"ready to load.\"\n */\nexport function findResolvedTextTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): TextTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'text', trackId);\n  // `findTrack` returns the wide union; narrow via discriminant before\n  // applying `isResolvedTrack`'s text-specific overload.\n  if (!track || track.type !== 'text' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\nexport function findResolvedVideoTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): VideoTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'video', trackId);\n  if (!track || track.type !== 'video' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\nexport function findResolvedAudioTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): AudioTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'audio', trackId);\n  if (!track || track.type !== 'audio' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\n/**\n * Whether a track carries a non-empty `codecs` array. Both partially-\n * resolved and fully-resolved tracks may carry codecs — they come from\n * the multivariant playlist's `EXT-X-STREAM-INF` line, not from the\n * per-type media playlist — so this works at either resolution stage.\n *\n * `TextTrack` doesn't declare a `codecs` field; the `'codecs' in track`\n * check narrows it out for the false branch.\n */\nexport function hasCodecs(track: PartiallyResolvedTrack | ResolvedTrack | undefined): boolean {\n  return !!track && 'codecs' in track && !!track.codecs?.length;\n}\n\n/**\n * Updates a track within a presentation (immutably). Generic — works for\n * video, audio, or text tracks.\n */\nexport function updateTrackInPresentation<T extends ResolvedTrack>(\n  presentation: Presentation,\n  resolvedTrack: T\n): Presentation {\n  const trackId = resolvedTrack.id;\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) => ({\n      ...selectionSet,\n      switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n        ...switchingSet,\n        tracks: switchingSet.tracks.map((track) => (track.id === trackId ? resolvedTrack : track)),\n      })),\n    })),\n  } as Presentation;\n}\n"],"mappings":";;;;;;;;;;;;;;AAwBA,SAAgB,gBACd,cACA,MACqD;AACrD,QAAO,aAAa,eAAe,MAAM,EAAE,MAAM,QAAQ,MAAM,KAAK,EAAE,cAAc,IAAI,UAAU,EAAE;;;;;;;;;;AAWtG,SAAgB,UACd,cACA,MACA,SACoD;AACpD,QAAO,gBAAgB,cAAc,KAAK,CAAC,MAAM,EAAE,SAAS,OAAO,QAAQ;;;;;;;;;;;AAY7E,SAAgB,cACd,cACA,SACoD;AACpD,MAAK,MAAM,gBAAgB,aAAa,iBAAiB,EAAE,EAAE;EAC3D,MAAM,QAAQ,aAAa,cAAc,IAAI,OAAO,MAAM,EAAE,SAAS,OAAO,QAAQ;AACpF,MAAI,MAAO,QAAO;;;;;;;;;;;;AActB,SAAgB,sBACd,cACA,SACuB;AACvB,KAAI,CAAC,gBAAgB,CAAC,QAAS,QAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,QAAQ,QAAQ;AAGtD,KAAI,CAAC,SAAS,MAAM,SAAS,UAAU,CAAC,gBAAgB,MAAM,CAAE,QAAO,KAAA;AACvE,QAAO;;AAGT,SAAgB,uBACd,cACA,SACwB;AACxB,KAAI,CAAC,gBAAgB,CAAC,QAAS,QAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,SAAS,QAAQ;AACvD,KAAI,CAAC,SAAS,MAAM,SAAS,WAAW,CAAC,gBAAgB,MAAM,CAAE,QAAO,KAAA;AACxE,QAAO;;AAGT,SAAgB,uBACd,cACA,SACwB;AACxB,KAAI,CAAC,gBAAgB,CAAC,QAAS,QAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,SAAS,QAAQ;AACvD,KAAI,CAAC,SAAS,MAAM,SAAS,WAAW,CAAC,gBAAgB,MAAM,CAAE,QAAO,KAAA;AACxE,QAAO;;;;;;;;;;;AAYT,SAAgB,UAAU,OAAoE;AAC5F,QAAO,CAAC,CAAC,SAAS,YAAY,SAAS,CAAC,CAAC,MAAM,QAAQ;;;;;;AAOzD,SAAgB,0BACd,cACA,eACc;CACd,MAAM,UAAU,cAAc;AAC9B,QAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;GAC/D,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAAW,MAAM,OAAO,UAAU,gBAAgB,MAAO;IAC3F,EAAE;GACJ,EAAE;EACJ"}
+{"version":3,"file":"tracks.js","names":[],"sources":["../../../../src/media/utils/tracks.ts"],"sourcesContent":["import type {\n  AudioTrack,\n  MaybeResolvedPresentation,\n  PartiallyResolvedTrack,\n  Presentation,\n  ResolvedTrack,\n  TextTrack,\n  TrackType,\n  VideoTrack,\n} from '../types';\nimport { isResolvedTrack } from '../types';\n\n/**\n * Get the tracks of the given type from a presentation's first switching set.\n *\n * Returns `[]` when the presentation is unresolved, when no selection set of\n * `type` exists, or when its first switching set is empty. Returned tracks may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n *\n * The \"first switching set\" assumption matches the rest of the codebase\n * (HLS typically has one switching set per type); multi-group / multi-period\n * support would generalize this.\n */\nexport function getTracksByType(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType\n): readonly (PartiallyResolvedTrack | ResolvedTrack)[] {\n  return presentation.selectionSets?.find(({ type: t }) => t === type)?.switchingSets[0]?.tracks ?? [];\n}\n\n/**\n * Find a track of the given type and id within a presentation.\n *\n * Returns the matching track from the first switching set of the matching\n * selection set, or `undefined` if either is missing. The returned track may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n */\nexport function findTrack(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  return getTracksByType(presentation, type).find(({ id }) => id === trackId);\n}\n\n/**\n * Find a track by id across all selection sets in a presentation, without\n * knowing its type up front. Used when the caller has a track id obtained\n * from a downstream consumer (e.g. `SourceBufferActor.initTrackId`) and\n * needs to locate the corresponding track in the presentation.\n *\n * Track ids are unique within a presentation per the HLS spec; the first\n * match wins.\n */\nexport function findTrackById(\n  presentation: MaybeResolvedPresentation,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  for (const selectionSet of presentation.selectionSets ?? []) {\n    const track = selectionSet.switchingSets[0]?.tracks.find(({ id }) => id === trackId);\n    if (track) return track;\n  }\n  return undefined;\n}\n\n/**\n * Find a text track of the given id within a presentation and narrow it to\n * the fully-resolved `TextTrack` shape (segments populated). Returns\n * `undefined` if no track matches the id, the matching track isn't a text\n * track, or it hasn't been resolved yet.\n *\n * The segments-non-empty check stays at the call site — a resolved track\n * with zero segments is a valid state, distinct from \"ready to load.\"\n */\nexport function findResolvedTextTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): TextTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'text', trackId);\n  // `findTrack` returns the wide union; narrow via discriminant before\n  // applying `isResolvedTrack`'s text-specific overload.\n  if (track?.type !== 'text' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\nexport function findResolvedVideoTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): VideoTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'video', trackId);\n  if (track?.type !== 'video' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\nexport function findResolvedAudioTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): AudioTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'audio', trackId);\n  if (track?.type !== 'audio' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\n/**\n * Whether a track carries a non-empty `codecs` array. Both partially-\n * resolved and fully-resolved tracks may carry codecs — they come from\n * the multivariant playlist's `EXT-X-STREAM-INF` line, not from the\n * per-type media playlist — so this works at either resolution stage.\n *\n * `TextTrack` doesn't declare a `codecs` field; the `'codecs' in track`\n * check narrows it out for the false branch.\n */\nexport function hasCodecs(track: PartiallyResolvedTrack | ResolvedTrack | undefined): boolean {\n  return !!track && 'codecs' in track && !!track.codecs?.length;\n}\n\n/**\n * Set `mimeType` on every track of one `type` (immutably). Used to propagate a\n * detected container across a type's renditions: an ABR ladder is the same\n * content at different bitrates, so one rendition's container holds for all of\n * them — capability probing + SourceBuffer setup then get the right MIME for the\n * whole type from a single resolved media playlist, without fetching the rest.\n *\n * Scoped to one type on purpose: propagating *across* audio/video would be wrong\n * for mixed-container sources (e.g. muxed-TS video + raw-`.aac` audio) and races\n * concurrent per-type resolution. Same-type writes are disjoint and safe.\n * Idempotent — tracks already at `mimeType` are left as-is.\n */\nexport function applyContainerMimeType(presentation: Presentation, type: TrackType, mimeType: string): Presentation {\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) =>\n      selectionSet.type === type\n        ? {\n            ...selectionSet,\n            switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n              ...switchingSet,\n              tracks: switchingSet.tracks.map((track) =>\n                track.mimeType === mimeType ? track : { ...track, mimeType }\n              ),\n            })),\n          }\n        : selectionSet\n    ),\n  } as Presentation;\n}\n\n/**\n * Updates a track within a presentation (immutably). Generic — works for\n * video, audio, or text tracks.\n */\nexport function updateTrackInPresentation<T extends ResolvedTrack>(\n  presentation: Presentation,\n  resolvedTrack: T\n): Presentation {\n  const trackId = resolvedTrack.id;\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) => ({\n      ...selectionSet,\n      switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n        ...switchingSet,\n        tracks: switchingSet.tracks.map((track) => (track.id === trackId ? resolvedTrack : track)),\n      })),\n    })),\n  } as Presentation;\n}\n"],"mappings":";;;;;;;;;;;;;;AAwBA,SAAgB,gBACd,cACA,MACqD;CACrD,OAAO,aAAa,eAAe,MAAM,EAAE,MAAM,QAAQ,MAAM,IAAI,CAAC,EAAE,cAAc,EAAE,EAAE,UAAU,CAAC;AACrG;;;;;;;;;AAUA,SAAgB,UACd,cACA,MACA,SACoD;CACpD,OAAO,gBAAgB,cAAc,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,OAAO,OAAO;AAC5E;;;;;;;;;;AAWA,SAAgB,cACd,cACA,SACoD;CACpD,KAAK,MAAM,gBAAgB,aAAa,iBAAiB,CAAC,GAAG;EAC3D,MAAM,QAAQ,aAAa,cAAc,EAAE,EAAE,OAAO,MAAM,EAAE,SAAS,OAAO,OAAO;EACnF,IAAI,OAAO,OAAO;CACpB;AAEF;;;;;;;;;;AAWA,SAAgB,sBACd,cACA,SACuB;CACvB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,QAAQ,OAAO;CAGrD,IAAI,OAAO,SAAS,UAAU,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAC9D,OAAO;AACT;AAEA,SAAgB,uBACd,cACA,SACwB;CACxB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,SAAS,OAAO;CACtD,IAAI,OAAO,SAAS,WAAW,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAC/D,OAAO;AACT;AAEA,SAAgB,uBACd,cACA,SACwB;CACxB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,SAAS,OAAO;CACtD,IAAI,OAAO,SAAS,WAAW,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAC/D,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,UAAU,OAAoE;CAC5F,OAAO,CAAC,CAAC,SAAS,YAAY,SAAS,CAAC,CAAC,MAAM,QAAQ;AACzD;;;;;;;;;;;;;AAcA,SAAgB,uBAAuB,cAA4B,MAAiB,UAAgC;CAClH,OAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,iBAC7C,aAAa,SAAS,OAClB;GACE,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAC/B,MAAM,aAAa,WAAW,QAAQ;KAAE,GAAG;KAAO;IAAS,CAC7D;GACF,EAAE;EACJ,IACA,YACN;CACF;AACF;;;;;AAMA,SAAgB,0BACd,cACA,eACc;CACd,MAAM,UAAU,cAAc;CAC9B,OAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;GAC/D,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAAW,MAAM,OAAO,UAAU,gBAAgB,KAAM;GAC3F,EAAE;EACJ,EAAE;CACJ;AACF"}

package/dist/default/media-tracks.js

@@ -0,0 +1,2 @@
+import { dedupedAudioTracks, dedupedVideoTracks, findAudioTrackById, findVideoTrackById, frameRateToNumber, isSameAudioTrack, isSameVideoTrack, toUserAudioTrackSelection, toUserVideoTrackSelection } from "./media/media-tracks/media-tracks.js";
+export { dedupedAudioTracks, dedupedVideoTracks, findAudioTrackById, findVideoTrackById, frameRateToNumber, isSameAudioTrack, isSameVideoTrack, toUserAudioTrackSelection, toUserVideoTrackSelection };

package/dist/default/network/bandwidth-estimator.js.map

@@ -1 +1 @@
-{"version":3,"file":"bandwidth-estimator.js","names":[],"sources":["../../../src/network/bandwidth-estimator.ts"],"sourcesContent":["/**\n * Dual EWMA Bandwidth Estimator\n *\n * Estimates available bandwidth using two EWMA calculations with different\n * half-lives, taking the minimum of both. This approach (from Shaka Player):\n *\n * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops\n * - **Slow EWMA** (5s half-life): Provides stability during fluctuations\n * - **min(fast, slow)**: Adapts down quickly, up slowly\n *\n * This naturally provides asymmetric behavior needed for good QoE:\n * avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).\n */\n\nimport { applyZeroFactor, calculateEwma } from './ewma';\n\n/**\n * Bandwidth estimator state.\n *\n * This state structure will be managed by O1 (State Container).\n * Functions in this module operate on this state immutably.\n */\nexport interface BandwidthState {\n  /** Fast-moving EWMA estimate (raw, uncorrected). */\n  fastEstimate: number;\n  /** Total weight accumulated in fast EWMA. */\n  fastTotalWeight: number;\n  /** Slow-moving EWMA estimate (raw, uncorrected). */\n  slowEstimate: number;\n  /** Total weight accumulated in slow EWMA. */\n  slowTotalWeight: number;\n  /** Total bytes sampled across all valid samples. */\n  bytesSampled: number;\n}\n\n/**\n * Configuration for bandwidth estimation.\n */\nexport interface BandwidthConfig {\n  /** Half-life for fast EWMA in seconds. */\n  fastHalfLife: number;\n  /** Half-life for slow EWMA in seconds. */\n  slowHalfLife: number;\n  /** Minimum total bytes before trusting the estimate. */\n  minTotalBytes: number;\n  /** Minimum bytes per sample to count (filters TTFB-dominated samples). */\n  minBytes: number;\n  /** Minimum sample duration in ms (filters cached responses). */\n  minDuration: number;\n}\n\n/**\n * Default bandwidth estimator configuration.\n *\n * Values match Shaka Player defaults based on experimentation.\n */\nexport const DEFAULT_BANDWIDTH_CONFIG: BandwidthConfig = {\n  fastHalfLife: 2, // 2 seconds\n  slowHalfLife: 5, // 5 seconds\n  minTotalBytes: 128_000, // 128 KB\n  minBytes: 16_000, // 16 KB\n  minDuration: 5, // 5 ms\n};\n\n/**\n * Add a bandwidth sample from a segment download.\n *\n * Samples are filtered based on:\n * - Minimum bytes (filters TTFB-dominated small segments)\n * - Minimum duration (filters cached responses)\n *\n * Valid samples update both fast and slow EWMA estimates.\n *\n * @param state - Current estimator state\n * @param durationMs - Download duration in milliseconds\n * @param numBytes - Number of bytes downloaded\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns New estimator state with sample incorporated (or unchanged if filtered)\n *\n * @example\n * let state = { fastEstimate: 0, fastTotalWeight: 0, ... };\n * // Sample: 1MB in 1 second\n * state = sampleBandwidth(state, 1000, 1_000_000);\n */\nexport function sampleBandwidth(\n  state: BandwidthState,\n  durationMs: number,\n  numBytes: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): BandwidthState {\n  // Always track bytes for startup phase calculation\n  const updatedBytesSampled = state.bytesSampled + numBytes;\n\n  // Filter: Ignore samples below minimum bytes (TTFB-dominated)\n  // Small segments' download time is mostly connection setup latency,\n  // which would artificially lower our bandwidth estimate\n  if (numBytes < config.minBytes) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Filter: Ignore samples faster than minimum duration (cached responses)\n  // Cached responses load nearly instantly and would artificially inflate\n  // our bandwidth estimate\n  if (durationMs < config.minDuration) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Calculate bandwidth in bits per second\n  // Formula: (bytes * 8 bits/byte * 1000 ms/s) / ms = bits/s\n  const bandwidth = (8000 * numBytes) / durationMs;\n\n  // Weight by duration in seconds\n  // Longer downloads are more reliable indicators of true bandwidth\n  const weight = durationMs / 1000;\n\n  return {\n    fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),\n    fastTotalWeight: state.fastTotalWeight + weight,\n    slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),\n    slowTotalWeight: state.slowTotalWeight + weight,\n    bytesSampled: updatedBytesSampled,\n  };\n}\n\n/**\n * Get the current bandwidth estimate.\n *\n * Returns the **minimum** of the fast and slow EWMA estimates.\n * This provides the key asymmetric behavior:\n * - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)\n * - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)\n *\n * Uses default estimate until enough data has been sampled — and when no\n * estimator state exists at all (`state === undefined`).\n *\n * @param state - Current estimator state, or `undefined` before any samples have been collected\n * @param defaultEstimate - Fallback estimate before sufficient samples (bps)\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns Bandwidth estimate in bits per second\n *\n * @example\n * const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default\n */\nexport function getBandwidthEstimate(\n  state: BandwidthState | undefined,\n  defaultEstimate: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): number {\n  // Use default until we have enough samples to trust our estimate\n  if (!state || state.bytesSampled < config.minTotalBytes) {\n    return defaultEstimate;\n  }\n\n  // Apply zero-factor correction to both estimates\n  const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);\n\n  const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);\n\n  // Take the minimum - this is the key insight from Shaka Player\n  // It naturally provides \"down quickly, up slowly\" behavior\n  return Math.min(fastEstimate, slowEstimate);\n}\n\n/**\n * Check if the estimator has enough data to provide a reliable estimate.\n *\n * Requires both:\n * - Enough total bytes sampled (minTotalBytes threshold)\n * - At least one valid EWMA sample (totalWeight > 0)\n *\n * @param state - Current estimator state\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns True if we've sampled enough bytes to trust the estimate\n *\n * @example\n * if (hasGoodEstimate(state)) {\n *   const estimate = getBandwidthEstimate(state, 5_000_000);\n * }\n */\nexport function hasGoodEstimate(state: BandwidthState, config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG): boolean {\n  // Need enough total bytes AND at least one valid EWMA sample\n  return state.bytesSampled >= config.minTotalBytes && state.fastTotalWeight > 0 && state.slowTotalWeight > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;CACd;;;;;;;;;;;;;;;;;;;;;AAsBD,SAAgB,gBACd,OACA,YACA,UACA,SAA0B,0BACV;CAEhB,MAAM,sBAAsB,MAAM,eAAe;AAKjD,KAAI,WAAW,OAAO,SACpB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;AAMxD,KAAI,aAAa,OAAO,YACtB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;CAKxD,MAAM,YAAa,MAAO,WAAY;CAItC,MAAM,SAAS,aAAa;AAE5B,QAAO;EACL,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc;EACf;;;;;;;;;;;;;;;;;;;;;AAsBH,SAAgB,qBACd,OACA,iBACA,SAA0B,0BAClB;AAER,KAAI,CAAC,SAAS,MAAM,eAAe,OAAO,cACxC,QAAO;CAIT,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;CAEpG,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;AAIpG,QAAO,KAAK,IAAI,cAAc,aAAa"}
+{"version":3,"file":"bandwidth-estimator.js","names":[],"sources":["../../../src/network/bandwidth-estimator.ts"],"sourcesContent":["/**\n * Dual EWMA Bandwidth Estimator\n *\n * Estimates available bandwidth using two EWMA calculations with different\n * half-lives, taking the minimum of both. This approach (from Shaka Player):\n *\n * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops\n * - **Slow EWMA** (5s half-life): Provides stability during fluctuations\n * - **min(fast, slow)**: Adapts down quickly, up slowly\n *\n * This naturally provides asymmetric behavior needed for good QoE:\n * avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).\n */\n\nimport { applyZeroFactor, calculateEwma } from './ewma';\n\n/**\n * Bandwidth estimator state.\n *\n * This state structure will be managed by O1 (State Container).\n * Functions in this module operate on this state immutably.\n */\nexport interface BandwidthState {\n  /** Fast-moving EWMA estimate (raw, uncorrected). */\n  fastEstimate: number;\n  /** Total weight accumulated in fast EWMA. */\n  fastTotalWeight: number;\n  /** Slow-moving EWMA estimate (raw, uncorrected). */\n  slowEstimate: number;\n  /** Total weight accumulated in slow EWMA. */\n  slowTotalWeight: number;\n  /** Total bytes sampled across all valid samples. */\n  bytesSampled: number;\n}\n\n/**\n * Configuration for bandwidth estimation.\n */\nexport interface BandwidthConfig {\n  /** Half-life for fast EWMA in seconds. */\n  fastHalfLife: number;\n  /** Half-life for slow EWMA in seconds. */\n  slowHalfLife: number;\n  /** Minimum total bytes before trusting the estimate. */\n  minTotalBytes: number;\n  /** Minimum bytes per sample to count (filters TTFB-dominated samples). */\n  minBytes: number;\n  /** Minimum sample duration in ms (filters cached responses). */\n  minDuration: number;\n}\n\n/**\n * Default bandwidth estimator configuration.\n *\n * Values match Shaka Player defaults based on experimentation.\n */\nexport const DEFAULT_BANDWIDTH_CONFIG: BandwidthConfig = {\n  fastHalfLife: 2, // 2 seconds\n  slowHalfLife: 5, // 5 seconds\n  minTotalBytes: 128_000, // 128 KB\n  minBytes: 16_000, // 16 KB\n  minDuration: 5, // 5 ms\n};\n\n/**\n * Add a bandwidth sample from a segment download.\n *\n * Samples are filtered based on:\n * - Minimum bytes (filters TTFB-dominated small segments)\n * - Minimum duration (filters cached responses)\n *\n * Valid samples update both fast and slow EWMA estimates.\n *\n * @param state - Current estimator state\n * @param durationMs - Download duration in milliseconds\n * @param numBytes - Number of bytes downloaded\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns New estimator state with sample incorporated (or unchanged if filtered)\n *\n * @example\n * let state = { fastEstimate: 0, fastTotalWeight: 0, ... };\n * // Sample: 1MB in 1 second\n * state = sampleBandwidth(state, 1000, 1_000_000);\n */\nexport function sampleBandwidth(\n  state: BandwidthState,\n  durationMs: number,\n  numBytes: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): BandwidthState {\n  // Always track bytes for startup phase calculation\n  const updatedBytesSampled = state.bytesSampled + numBytes;\n\n  // Filter: Ignore samples below minimum bytes (TTFB-dominated)\n  // Small segments' download time is mostly connection setup latency,\n  // which would artificially lower our bandwidth estimate\n  if (numBytes < config.minBytes) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Filter: Ignore samples faster than minimum duration (cached responses)\n  // Cached responses load nearly instantly and would artificially inflate\n  // our bandwidth estimate\n  if (durationMs < config.minDuration) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Calculate bandwidth in bits per second\n  // Formula: (bytes * 8 bits/byte * 1000 ms/s) / ms = bits/s\n  const bandwidth = (8000 * numBytes) / durationMs;\n\n  // Weight by duration in seconds\n  // Longer downloads are more reliable indicators of true bandwidth\n  const weight = durationMs / 1000;\n\n  return {\n    fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),\n    fastTotalWeight: state.fastTotalWeight + weight,\n    slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),\n    slowTotalWeight: state.slowTotalWeight + weight,\n    bytesSampled: updatedBytesSampled,\n  };\n}\n\n/**\n * Get the current bandwidth estimate.\n *\n * Returns the **minimum** of the fast and slow EWMA estimates.\n * This provides the key asymmetric behavior:\n * - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)\n * - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)\n *\n * Uses default estimate until enough data has been sampled — and when no\n * estimator state exists at all (`state === undefined`).\n *\n * @param state - Current estimator state, or `undefined` before any samples have been collected\n * @param defaultEstimate - Fallback estimate before sufficient samples (bps)\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns Bandwidth estimate in bits per second\n *\n * @example\n * const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default\n */\nexport function getBandwidthEstimate(\n  state: BandwidthState | undefined,\n  defaultEstimate: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): number {\n  // Use default until we have enough samples to trust our estimate\n  if (!state || state.bytesSampled < config.minTotalBytes) {\n    return defaultEstimate;\n  }\n\n  // Apply zero-factor correction to both estimates\n  const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);\n\n  const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);\n\n  // Take the minimum - this is the key insight from Shaka Player\n  // It naturally provides \"down quickly, up slowly\" behavior\n  return Math.min(fastEstimate, slowEstimate);\n}\n\n/**\n * Check if the estimator has enough data to provide a reliable estimate.\n *\n * Requires both:\n * - Enough total bytes sampled (minTotalBytes threshold)\n * - At least one valid EWMA sample (totalWeight > 0)\n *\n * @param state - Current estimator state\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns True if we've sampled enough bytes to trust the estimate\n *\n * @example\n * if (hasGoodEstimate(state)) {\n *   const estimate = getBandwidthEstimate(state, 5_000_000);\n * }\n */\nexport function hasGoodEstimate(state: BandwidthState, config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG): boolean {\n  // Need enough total bytes AND at least one valid EWMA sample\n  return state.bytesSampled >= config.minTotalBytes && state.fastTotalWeight > 0 && state.slowTotalWeight > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;AACf;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,gBACd,OACA,YACA,UACA,SAA0B,0BACV;CAEhB,MAAM,sBAAsB,MAAM,eAAe;CAKjD,IAAI,WAAW,OAAO,UACpB,OAAO;EAAE,GAAG;EAAO,cAAc;CAAoB;CAMvD,IAAI,aAAa,OAAO,aACtB,OAAO;EAAE,GAAG;EAAO,cAAc;CAAoB;CAKvD,MAAM,YAAa,MAAO,WAAY;CAItC,MAAM,SAAS,aAAa;CAE5B,OAAO;EACL,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,YAAY;EACtF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,YAAY;EACtF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc;CAChB;AACF;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,qBACd,OACA,iBACA,SAA0B,0BAClB;CAER,IAAI,CAAC,SAAS,MAAM,eAAe,OAAO,eACxC,OAAO;CAIT,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,YAAY;CAEnG,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,YAAY;CAInG,OAAO,KAAK,IAAI,cAAc,YAAY;AAC5C"}

package/dist/default/network/chunked-stream-iterable.js.map

@@ -1 +1 @@
-{"version":3,"file":"chunked-stream-iterable.js","names":["#readableStream"],"sources":["../../../src/network/chunked-stream-iterable.ts"],"sourcesContent":["const DEFAULT_MIN_CHUNK_SIZE = 2 ** 17; // 128 KB\n\nexport interface ChunkedStreamIterableOptions {\n  minChunkSize?: number;\n}\n\n/**\n * Adapts a `ReadableStream<Uint8Array>` (e.g. `response.body`) into an\n * `AsyncIterable<Uint8Array>` that yields chunks no smaller than\n * `minChunkSize` bytes. Smaller network chunks are accumulated and yielded\n * together once the threshold is met. Any remainder is flushed on stream end.\n *\n * Errors from the underlying stream propagate naturally — the reader lock is\n * always released via `finally`.\n */\nexport class ChunkedStreamIterable implements AsyncIterable<Uint8Array> {\n  readonly minChunkSize: number;\n  #readableStream: ReadableStream<Uint8Array>;\n\n  constructor(\n    readableStream: ReadableStream<Uint8Array>,\n    { minChunkSize = DEFAULT_MIN_CHUNK_SIZE }: ChunkedStreamIterableOptions = {}\n  ) {\n    this.#readableStream = readableStream;\n    this.minChunkSize = minChunkSize;\n  }\n\n  async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {\n    let pending: Uint8Array | undefined;\n    const reader = this.#readableStream.getReader();\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) {\n          if (pending) yield pending;\n          break;\n        }\n\n        pending = pending ? concat(pending, value) : value;\n\n        if (pending.length >= this.minChunkSize) {\n          yield pending;\n          pending = undefined;\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n\nfunction concat(a: Uint8Array, b: Uint8Array): Uint8Array {\n  const result = new Uint8Array(a.length + b.length);\n  result.set(a);\n  result.set(b, a.length);\n  return result;\n}\n"],"mappings":";AAAA,MAAM,yBAAyB,KAAK;;;;;;;;;;AAepC,IAAa,wBAAb,MAAwE;CACtE;CACA;CAEA,YACE,gBACA,EAAE,eAAe,2BAAyD,EAAE,EAC5E;AACA,QAAA,iBAAuB;AACvB,OAAK,eAAe;;CAGtB,QAAQ,OAAO,iBAA6C;EAC1D,IAAI;EACJ,MAAM,SAAS,MAAA,eAAqB,WAAW;AAC/C,MAAI;AACF,UAAO,MAAM;IACX,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM;AAC3C,QAAI,MAAM;AACR,SAAI,QAAS,OAAM;AACnB;;AAGF,cAAU,UAAU,OAAO,SAAS,MAAM,GAAG;AAE7C,QAAI,QAAQ,UAAU,KAAK,cAAc;AACvC,WAAM;AACN,eAAU,KAAA;;;YAGN;AACR,UAAO,aAAa;;;;AAK1B,SAAS,OAAO,GAAe,GAA2B;CACxD,MAAM,SAAS,IAAI,WAAW,EAAE,SAAS,EAAE,OAAO;AAClD,QAAO,IAAI,EAAE;AACb,QAAO,IAAI,GAAG,EAAE,OAAO;AACvB,QAAO"}
+{"version":3,"file":"chunked-stream-iterable.js","names":["#readableStream"],"sources":["../../../src/network/chunked-stream-iterable.ts"],"sourcesContent":["const DEFAULT_MIN_CHUNK_SIZE = 2 ** 17; // 128 KB\n\nexport interface ChunkedStreamIterableOptions {\n  minChunkSize?: number;\n}\n\n/**\n * Adapts a `ReadableStream<Uint8Array>` (e.g. `response.body`) into an\n * `AsyncIterable<Uint8Array>` that yields chunks no smaller than\n * `minChunkSize` bytes. Smaller network chunks are accumulated and yielded\n * together once the threshold is met. Any remainder is flushed on stream end.\n *\n * Errors from the underlying stream propagate naturally — the reader lock is\n * always released via `finally`.\n */\nexport class ChunkedStreamIterable implements AsyncIterable<Uint8Array> {\n  readonly minChunkSize: number;\n  #readableStream: ReadableStream<Uint8Array>;\n\n  constructor(\n    readableStream: ReadableStream<Uint8Array>,\n    { minChunkSize = DEFAULT_MIN_CHUNK_SIZE }: ChunkedStreamIterableOptions = {}\n  ) {\n    this.#readableStream = readableStream;\n    this.minChunkSize = minChunkSize;\n  }\n\n  async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {\n    let pending: Uint8Array | undefined;\n    const reader = this.#readableStream.getReader();\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) {\n          if (pending) yield pending;\n          break;\n        }\n\n        pending = pending ? concat(pending, value) : value;\n\n        if (pending.length >= this.minChunkSize) {\n          yield pending;\n          pending = undefined;\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n\nfunction concat(a: Uint8Array, b: Uint8Array): Uint8Array {\n  const result = new Uint8Array(a.length + b.length);\n  result.set(a);\n  result.set(b, a.length);\n  return result;\n}\n"],"mappings":";AAAA,MAAM,yBAAyB,KAAK;;;;;;;;;;AAepC,IAAa,wBAAb,MAAwE;CACtE;CACA;CAEA,YACE,gBACA,EAAE,eAAe,2BAAyD,CAAC,GAC3E;EACA,KAAKA,kBAAkB;EACvB,KAAK,eAAe;CACtB;CAEA,QAAQ,OAAO,iBAA6C;EAC1D,IAAI;EACJ,MAAM,SAAS,KAAKA,gBAAgB,UAAU;EAC9C,IAAI;GACF,OAAO,MAAM;IACX,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;IAC1C,IAAI,MAAM;KACR,IAAI,SAAS,MAAM;KACnB;IACF;IAEA,UAAU,UAAU,OAAO,SAAS,KAAK,IAAI;IAE7C,IAAI,QAAQ,UAAU,KAAK,cAAc;KACvC,MAAM;KACN,UAAU,KAAA;IACZ;GACF;EACF,UAAU;GACR,OAAO,YAAY;EACrB;CACF;AACF;AAEA,SAAS,OAAO,GAAe,GAA2B;CACxD,MAAM,SAAS,IAAI,WAAW,EAAE,SAAS,EAAE,MAAM;CACjD,OAAO,IAAI,CAAC;CACZ,OAAO,IAAI,GAAG,EAAE,MAAM;CACtB,OAAO;AACT"}

package/dist/default/network/ewma.js

@@ -66,6 +66,6 @@ function applyZeroFactor(estimate, totalWeight, halfLife) {
 	return estimate / (1 - calculateAlpha(halfLife) ** totalWeight);
 }
 //#endregion
-export { applyZeroFactor, calculateEwma };
+export { applyZeroFactor, calculateAlpha, calculateEwma };
 
 //# sourceMappingURL=ewma.js.map

package/dist/default/network/ewma.js.map

@@ -1 +1 @@
-{"version":3,"file":"ewma.js","names":[],"sources":["../../../src/network/ewma.ts"],"sourcesContent":["/**\n * Exponentially Weighted Moving Average (EWMA)\n *\n * Pure functional implementation of EWMA calculations.\n * Based on Shaka Player's EWMA algorithm.\n */\n\n/**\n * Calculate alpha (decay factor) from half-life.\n *\n * Alpha determines how quickly old data \"expires\":\n * - alpha close to 1 = slow decay (long memory)\n * - alpha close to 0 = fast decay (short memory)\n *\n * @param halfLife - The quantity of prior samples (by weight) that make up\n *   half of the new estimate. Must be positive.\n * @returns Alpha value between 0 and 1\n *\n * @example\n * const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life\n */\nexport function calculateAlpha(halfLife: number): number {\n  return Math.exp(Math.log(0.5) / halfLife);\n}\n\n/**\n * Calculate exponentially weighted moving average.\n *\n * Updates an estimate by blending a new value with the previous estimate,\n * weighted by the sample duration. Longer samples have more influence.\n *\n * @param prevEstimate - Previous EWMA estimate\n * @param value - New sample value to incorporate\n * @param weight - Sample weight (typically duration in seconds)\n * @param halfLife - Half-life for decay (typically 2-5 seconds)\n * @returns Updated EWMA estimate\n *\n * @example\n * let estimate = 0;\n * estimate = calculateEwma(estimate, 1_000_000, 1, 2); // First sample\n * estimate = calculateEwma(estimate, 2_000_000, 1, 2); // Second sample\n */\nexport function calculateEwma(prevEstimate: number, value: number, weight: number, halfLife: number): number {\n  const alpha = calculateAlpha(halfLife);\n  const adjAlpha = alpha ** weight;\n  return value * (1 - adjAlpha) + adjAlpha * prevEstimate;\n}\n\n/**\n * Apply zero-factor correction to EWMA estimate.\n *\n * The zero-factor correction compensates for bias when starting from zero.\n * Without this correction, early estimates would be artificially low.\n *\n * As totalWeight increases, the correction factor approaches 1, meaning\n * the estimate becomes more reliable and needs less correction.\n *\n * @param estimate - Raw EWMA estimate (uncorrected)\n * @param totalWeight - Accumulated weight from all samples\n * @param halfLife - Half-life used in EWMA calculation\n * @returns Corrected estimate, or 0 if totalWeight is 0\n *\n * @example\n * const raw = calculateEwma(0, 1_000_000, 1, 2);\n * const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000\n */\nexport function applyZeroFactor(estimate: number, totalWeight: number, halfLife: number): number {\n  if (totalWeight === 0) {\n    return 0;\n  }\n\n  const alpha = calculateAlpha(halfLife);\n  const zeroFactor = 1 - alpha ** totalWeight;\n  return estimate / zeroFactor;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,UAA0B;AACvD,QAAO,KAAK,IAAI,KAAK,IAAI,GAAI,GAAG,SAAS;;;;;;;;;;;;;;;;;;;AAoB3C,SAAgB,cAAc,cAAsB,OAAe,QAAgB,UAA0B;CAE3G,MAAM,WADQ,eAAe,SAAS,IACZ;AAC1B,QAAO,SAAS,IAAI,YAAY,WAAW;;;;;;;;;;;;;;;;;;;;AAqB7C,SAAgB,gBAAgB,UAAkB,aAAqB,UAA0B;AAC/F,KAAI,gBAAgB,EAClB,QAAO;AAKT,QAAO,YADY,IADL,eAAe,SAAS,IACN"}
+{"version":3,"file":"ewma.js","names":[],"sources":["../../../src/network/ewma.ts"],"sourcesContent":["/**\n * Exponentially Weighted Moving Average (EWMA)\n *\n * Pure functional implementation of EWMA calculations.\n * Based on Shaka Player's EWMA algorithm.\n */\n\n/**\n * Calculate alpha (decay factor) from half-life.\n *\n * Alpha determines how quickly old data \"expires\":\n * - alpha close to 1 = slow decay (long memory)\n * - alpha close to 0 = fast decay (short memory)\n *\n * @param halfLife - The quantity of prior samples (by weight) that make up\n *   half of the new estimate. Must be positive.\n * @returns Alpha value between 0 and 1\n *\n * @example\n * const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life\n */\nexport function calculateAlpha(halfLife: number): number {\n  return Math.exp(Math.log(0.5) / halfLife);\n}\n\n/**\n * Calculate exponentially weighted moving average.\n *\n * Updates an estimate by blending a new value with the previous estimate,\n * weighted by the sample duration. Longer samples have more influence.\n *\n * @param prevEstimate - Previous EWMA estimate\n * @param value - New sample value to incorporate\n * @param weight - Sample weight (typically duration in seconds)\n * @param halfLife - Half-life for decay (typically 2-5 seconds)\n * @returns Updated EWMA estimate\n *\n * @example\n * let estimate = 0;\n * estimate = calculateEwma(estimate, 1_000_000, 1, 2); // First sample\n * estimate = calculateEwma(estimate, 2_000_000, 1, 2); // Second sample\n */\nexport function calculateEwma(prevEstimate: number, value: number, weight: number, halfLife: number): number {\n  const alpha = calculateAlpha(halfLife);\n  const adjAlpha = alpha ** weight;\n  return value * (1 - adjAlpha) + adjAlpha * prevEstimate;\n}\n\n/**\n * Apply zero-factor correction to EWMA estimate.\n *\n * The zero-factor correction compensates for bias when starting from zero.\n * Without this correction, early estimates would be artificially low.\n *\n * As totalWeight increases, the correction factor approaches 1, meaning\n * the estimate becomes more reliable and needs less correction.\n *\n * @param estimate - Raw EWMA estimate (uncorrected)\n * @param totalWeight - Accumulated weight from all samples\n * @param halfLife - Half-life used in EWMA calculation\n * @returns Corrected estimate, or 0 if totalWeight is 0\n *\n * @example\n * const raw = calculateEwma(0, 1_000_000, 1, 2);\n * const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000\n */\nexport function applyZeroFactor(estimate: number, totalWeight: number, halfLife: number): number {\n  if (totalWeight === 0) {\n    return 0;\n  }\n\n  const alpha = calculateAlpha(halfLife);\n  const zeroFactor = 1 - alpha ** totalWeight;\n  return estimate / zeroFactor;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,UAA0B;CACvD,OAAO,KAAK,IAAI,KAAK,IAAI,EAAG,IAAI,QAAQ;AAC1C;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,cAAc,cAAsB,OAAe,QAAgB,UAA0B;CAE3G,MAAM,WADQ,eAAe,QACR,KAAK;CAC1B,OAAO,SAAS,IAAI,YAAY,WAAW;AAC7C;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,gBAAgB,UAAkB,aAAqB,UAA0B;CAC/F,IAAI,gBAAgB,GAClB,OAAO;CAKT,OAAO,YADY,IADL,eAAe,QACF,KAAK;AAElC"}

package/dist/default/network/fetch.js

@@ -63,6 +63,12 @@ async function fetchResolvable(addressable, options) {
 function getResponseText(response) {
 	return response.text();
 }
+/** Default {@link FetchText}: fetch the resource, reject on non-OK, return text. */
+const fetchResolvableText = async (addressable, options) => {
+	const response = await fetchResolvable(addressable, options);
+	if (!response.ok) throw new Error(`fetchResolvableText: ${response.status} ${response.statusText} for ${addressable.url}`);
+	return getResponseText(response);
+};
 async function fetchStream(addressable, options) {
 	const { minChunkSize, ...fetchOptions } = options ?? {};
 	const response = await fetchResolvable(addressable, fetchOptions);
@@ -104,6 +110,6 @@ function createTrackedFetch(initial, onSample) {
 	};
 }
 //#endregion
-export { createTrackedFetch, fetchResolvable, fetchStream, getResponseText };
+export { createTrackedFetch, fetchResolvable, fetchResolvableText, fetchStream, getResponseText };
 
 //# sourceMappingURL=fetch.js.map

package/dist/default/network/fetch.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.js","names":[],"sources":["../../../src/network/fetch.ts"],"sourcesContent":["/**\n * HTTP Fetch Wrapper\n *\n * Composable building blocks:\n * - fetchResolvable() — fetch a Resource (handles byte ranges); returns Response\n * - getResponseText() — extract text from Response\n * - fetchResolvableStream() — single-stage async generator over body chunks\n * - fetchStream() — two-stage: await connection establishment, then lazily\n *   iterate body chunks. Use when timing the connection start independently\n *   of body consumption matters (e.g., observable fetch timing for ABR).\n * - createTrackedFetch() — factory for a fetchStream-shape function that\n *   samples bandwidth (via EWMA) per chunk and notifies via callback.\n */\n\nimport { type BandwidthState, sampleBandwidth } from './bandwidth-estimator';\nimport { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from './chunked-stream-iterable';\n\n/**\n * Minimal Response-like interface for text extraction.\n * Allows testing without full Response object.\n */\nexport interface ResponseLike {\n  text(): Promise<string>;\n}\n\n/**\n * An HTTP-addressable resource — URL plus optional byte range.\n * Media's `AddressableObject` (and anything else with the same shape)\n * is structurally compatible; kept local so this module stays\n * domain-agnostic.\n */\nexport interface Resource {\n  url: string;\n  byteRange?: {\n    start: number;\n    end: number;\n  };\n}\n\n/**\n * Fetch resolvable from a Resource.\n *\n * Handles byte range requests if byteRange is present.\n * Returns native fetch Response for composability (can extract text, stream, etc.).\n *\n * @param addressable - Resource to fetch (url + optional byteRange)\n * @returns Promise resolving to Response\n *\n * @example\n * const response = await fetchResolvable({ url: 'https://example.com/segment.m4s' });\n * const text = await getResponseText(response);\n *\n * @example\n * // With byte range\n * const response = await fetchResolvable({\n *   url: 'https://example.com/file.mp4',\n *   byteRange: { start: 1000, end: 1999 }\n * });\n */\nexport async function fetchResolvable(addressable: Resource, options?: RequestInit): Promise<Response> {\n  const headers = new Headers(options?.headers);\n\n  // Add Range header for byte range requests\n  if (addressable.byteRange) {\n    const { start, end } = addressable.byteRange;\n    headers.set('Range', `bytes=${start}-${end}`);\n  }\n\n  const request = new Request(addressable.url, {\n    method: 'GET',\n    headers,\n    ...options,\n  });\n\n  return fetch(request);\n}\n\n/**\n * Fetch resolvable as bytes.\n *\n * Convenience wrapper around fetchResolvable that resolves the body as an\n * ArrayBuffer. Use this when you need the raw bytes (e.g. segment appends).\n * For text or streaming consumption, use fetchResolvable directly.\n */\nexport async function fetchResolvableBytes(addressable: Resource, options?: RequestInit): Promise<ArrayBuffer> {\n  const response = await fetchResolvable(addressable, options);\n  return response.arrayBuffer();\n}\n\n/**\n * Fetch resolvable as a stream of Uint8Array chunks.\n *\n * Convenience wrapper around fetchResolvable that yields the body as chunks\n * via ChunkedStreamIterable. Headers are awaited before the first chunk is\n * yielded (TTFB is accounted for before iteration begins).\n *\n * Throws if the response body is null (e.g. non-body HTTP status).\n * Errors from the underlying stream propagate naturally as thrown errors.\n */\nexport async function* fetchResolvableStream(\n  addressable: Resource,\n  options?: RequestInit & ChunkedStreamIterableOptions\n): AsyncGenerator<Uint8Array> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  yield* new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Extract text from Response.\n *\n * Accepts minimal Response-like object (just needs text() method).\n * Returns promise from response.text().\n *\n * @param response - Response-like object with text() method\n * @returns Promise resolving to text content\n *\n * @example\n * const response = await fetchResolvable(addressable);\n * const text = await getResponseText(response);\n */\nexport function getResponseText(response: ResponseLike): Promise<string> {\n  return response.text();\n}\n\n/**\n * Two-stage fetch helper: eagerly starts the HTTP request (TTFB is awaited),\n * then returns a lazy iterable over the response body. Separating connection\n * start from body iteration makes fetch timing predictable and observable\n * regardless of when downstream consumers begin pulling chunks.\n *\n * Sibling to {@link fetchResolvableStream}, which is single-stage (calls\n * `fetch` only when iteration starts). Pick `fetchStream` when \"when did the\n * fetch start\" needs to be observable separately from \"when did the body\n * begin arriving.\"\n */\nexport type FetchOptions = RequestInit & ChunkedStreamIterableOptions;\n\nexport type FetchBytes = (addressable: Resource, options?: FetchOptions) => Promise<AsyncIterable<Uint8Array>>;\n\nexport async function fetchStream(addressable: Resource, options?: FetchOptions): Promise<AsyncIterable<Uint8Array>> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  return new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Returns a {@link FetchBytes} function that samples bandwidth via EWMA\n * per body chunk. The factory captures the running bandwidth state\n * internally; per chunk it computes the next state and notifies the\n * supplied `onSample` callback.\n *\n * The factory's internal accumulator is seeded from `initial` and updated\n * on every chunk; callers don't need to thread it back in. `onSample`\n * receives the *new* state after each chunk — typical use is to bridge\n * samples back into engine state for ABR consumers.\n *\n * @param initial - Starting `BandwidthState` (commonly zeros or the\n *   engine's current accumulator).\n * @param onSample - Called with the new `BandwidthState` after each chunk.\n */\nexport function createTrackedFetch(initial: BandwidthState, onSample: (next: BandwidthState) => void): FetchBytes {\n  let state = initial;\n  return async (addressable, options) => {\n    const { minChunkSize, ...fetchOptions } = options ?? {};\n    const response = await fetchResolvable(addressable, fetchOptions);\n    if (!response.body) throw new Error('Response has no body');\n    const body = response.body;\n    return {\n      [Symbol.asyncIterator]: async function* () {\n        let chunkStart = performance.now();\n        for await (const chunk of new ChunkedStreamIterable(\n          body,\n          ...(minChunkSize !== undefined ? [{ minChunkSize }] : [])\n        )) {\n          const elapsed = performance.now() - chunkStart;\n          state = sampleBandwidth(state, elapsed, chunk.byteLength);\n          onSample(state);\n          yield chunk;\n          chunkStart = performance.now();\n        }\n      },\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,eAAsB,gBAAgB,aAAuB,SAA0C;CACrG,MAAM,UAAU,IAAI,QAAQ,SAAS,QAAQ;AAG7C,KAAI,YAAY,WAAW;EACzB,MAAM,EAAE,OAAO,QAAQ,YAAY;AACnC,UAAQ,IAAI,SAAS,SAAS,MAAM,GAAG,MAAM;;CAG/C,MAAM,UAAU,IAAI,QAAQ,YAAY,KAAK;EAC3C,QAAQ;EACR;EACA,GAAG;EACJ,CAAC;AAEF,QAAO,MAAM,QAAQ;;;;;;;;;;;;;;;AAgDvB,SAAgB,gBAAgB,UAAyC;AACvE,QAAO,SAAS,MAAM;;AAkBxB,eAAsB,YAAY,aAAuB,SAA4D;CACnH,MAAM,EAAE,cAAc,GAAG,iBAAiB,WAAW,EAAE;CACvD,MAAM,WAAW,MAAM,gBAAgB,aAAa,aAAa;AACjE,KAAI,CAAC,SAAS,KAAM,OAAM,IAAI,MAAM,uBAAuB;AAC3D,QAAO,IAAI,sBAAsB,SAAS,MAAM,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,cAAc,CAAC,GAAG,EAAE,CAAE;;;;;;;;;;;;;;;;;AAkB5G,SAAgB,mBAAmB,SAAyB,UAAsD;CAChH,IAAI,QAAQ;AACZ,QAAO,OAAO,aAAa,YAAY;EACrC,MAAM,EAAE,cAAc,GAAG,iBAAiB,WAAW,EAAE;EACvD,MAAM,WAAW,MAAM,gBAAgB,aAAa,aAAa;AACjE,MAAI,CAAC,SAAS,KAAM,OAAM,IAAI,MAAM,uBAAuB;EAC3D,MAAM,OAAO,SAAS;AACtB,SAAO,EACL,CAAC,OAAO,gBAAgB,mBAAmB;GACzC,IAAI,aAAa,YAAY,KAAK;AAClC,cAAW,MAAM,SAAS,IAAI,sBAC5B,MACA,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,cAAc,CAAC,GAAG,EAAE,CACzD,EAAE;IACD,MAAM,UAAU,YAAY,KAAK,GAAG;AACpC,YAAQ,gBAAgB,OAAO,SAAS,MAAM,WAAW;AACzD,aAAS,MAAM;AACf,UAAM;AACN,iBAAa,YAAY,KAAK;;KAGnC"}
+{"version":3,"file":"fetch.js","names":[],"sources":["../../../src/network/fetch.ts"],"sourcesContent":["/**\n * HTTP Fetch Wrapper\n *\n * Composable building blocks:\n * - fetchResolvable() — fetch a Resource (handles byte ranges); returns Response\n * - getResponseText() — extract text from Response\n * - fetchResolvableStream() — single-stage async generator over body chunks\n * - fetchStream() — two-stage: await connection establishment, then lazily\n *   iterate body chunks. Use when timing the connection start independently\n *   of body consumption matters (e.g., observable fetch timing for ABR).\n * - createTrackedFetch() — factory for a fetchStream-shape function that\n *   samples bandwidth (via EWMA) per chunk and notifies via callback.\n */\n\nimport { type BandwidthState, sampleBandwidth } from './bandwidth-estimator';\nimport { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from './chunked-stream-iterable';\n\n/**\n * Minimal Response-like interface for text extraction.\n * Allows testing without full Response object.\n */\nexport interface ResponseLike {\n  text(): Promise<string>;\n}\n\n/**\n * An HTTP-addressable resource — URL plus optional byte range.\n * Media's `AddressableObject` (and anything else with the same shape)\n * is structurally compatible; kept local so this module stays\n * domain-agnostic.\n */\nexport interface Resource {\n  url: string;\n  byteRange?: {\n    start: number;\n    end: number;\n  };\n}\n\n/**\n * Fetch resolvable from a Resource.\n *\n * Handles byte range requests if byteRange is present.\n * Returns native fetch Response for composability (can extract text, stream, etc.).\n *\n * @param addressable - Resource to fetch (url + optional byteRange)\n * @returns Promise resolving to Response\n *\n * @example\n * const response = await fetchResolvable({ url: 'https://example.com/segment.m4s' });\n * const text = await getResponseText(response);\n *\n * @example\n * // With byte range\n * const response = await fetchResolvable({\n *   url: 'https://example.com/file.mp4',\n *   byteRange: { start: 1000, end: 1999 }\n * });\n */\nexport async function fetchResolvable(addressable: Resource, options?: RequestInit): Promise<Response> {\n  const headers = new Headers(options?.headers);\n\n  // Add Range header for byte range requests\n  if (addressable.byteRange) {\n    const { start, end } = addressable.byteRange;\n    headers.set('Range', `bytes=${start}-${end}`);\n  }\n\n  const request = new Request(addressable.url, {\n    method: 'GET',\n    headers,\n    ...options,\n  });\n\n  return fetch(request);\n}\n\n/**\n * Fetch resolvable as bytes.\n *\n * Convenience wrapper around fetchResolvable that resolves the body as an\n * ArrayBuffer. Use this when you need the raw bytes (e.g. segment appends).\n * For text or streaming consumption, use fetchResolvable directly.\n */\nexport async function fetchResolvableBytes(addressable: Resource, options?: RequestInit): Promise<ArrayBuffer> {\n  const response = await fetchResolvable(addressable, options);\n  return response.arrayBuffer();\n}\n\n/**\n * Fetch resolvable as a stream of Uint8Array chunks.\n *\n * Convenience wrapper around fetchResolvable that yields the body as chunks\n * via ChunkedStreamIterable. Headers are awaited before the first chunk is\n * yielded (TTFB is accounted for before iteration begins).\n *\n * Throws if the response body is null (e.g. non-body HTTP status).\n * Errors from the underlying stream propagate naturally as thrown errors.\n */\nexport async function* fetchResolvableStream(\n  addressable: Resource,\n  options?: RequestInit & ChunkedStreamIterableOptions\n): AsyncGenerator<Uint8Array> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  yield* new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Extract text from Response.\n *\n * Accepts minimal Response-like object (just needs text() method).\n * Returns promise from response.text().\n *\n * @param response - Response-like object with text() method\n * @returns Promise resolving to text content\n *\n * @example\n * const response = await fetchResolvable(addressable);\n * const text = await getResponseText(response);\n */\nexport function getResponseText(response: ResponseLike): Promise<string> {\n  return response.text();\n}\n\n/**\n * Fetch a resource and resolve its text body — the text analog of\n * {@link FetchBytes}. A non-OK status rejects, so HTTP failures surface as\n * rejections that callers (and decorators like the failover tracker) handle\n * uniformly with network errors.\n */\nexport type FetchText = (addressable: Resource, options?: RequestInit) => Promise<string>;\n\n/** Default {@link FetchText}: fetch the resource, reject on non-OK, return text. */\nexport const fetchResolvableText: FetchText = async (addressable, options) => {\n  const response = await fetchResolvable(addressable, options);\n  if (!response.ok) {\n    throw new Error(`fetchResolvableText: ${response.status} ${response.statusText} for ${addressable.url}`);\n  }\n  return getResponseText(response);\n};\n\n/**\n * Two-stage fetch helper: eagerly starts the HTTP request (TTFB is awaited),\n * then returns a lazy iterable over the response body. Separating connection\n * start from body iteration makes fetch timing predictable and observable\n * regardless of when downstream consumers begin pulling chunks.\n *\n * Sibling to {@link fetchResolvableStream}, which is single-stage (calls\n * `fetch` only when iteration starts). Pick `fetchStream` when \"when did the\n * fetch start\" needs to be observable separately from \"when did the body\n * begin arriving.\"\n */\nexport type FetchOptions = RequestInit & ChunkedStreamIterableOptions;\n\nexport type FetchBytes = (addressable: Resource, options?: FetchOptions) => Promise<AsyncIterable<Uint8Array>>;\n\nexport async function fetchStream(addressable: Resource, options?: FetchOptions): Promise<AsyncIterable<Uint8Array>> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  return new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Returns a {@link FetchBytes} function that samples bandwidth via EWMA\n * per body chunk. The factory captures the running bandwidth state\n * internally; per chunk it computes the next state and notifies the\n * supplied `onSample` callback.\n *\n * The factory's internal accumulator is seeded from `initial` and updated\n * on every chunk; callers don't need to thread it back in. `onSample`\n * receives the *new* state after each chunk — typical use is to bridge\n * samples back into engine state for ABR consumers.\n *\n * @param initial - Starting `BandwidthState` (commonly zeros or the\n *   engine's current accumulator).\n * @param onSample - Called with the new `BandwidthState` after each chunk.\n */\nexport function createTrackedFetch(initial: BandwidthState, onSample: (next: BandwidthState) => void): FetchBytes {\n  let state = initial;\n  return async (addressable, options) => {\n    const { minChunkSize, ...fetchOptions } = options ?? {};\n    const response = await fetchResolvable(addressable, fetchOptions);\n    if (!response.body) throw new Error('Response has no body');\n    const body = response.body;\n    return {\n      [Symbol.asyncIterator]: async function* () {\n        let chunkStart = performance.now();\n        for await (const chunk of new ChunkedStreamIterable(\n          body,\n          ...(minChunkSize !== undefined ? [{ minChunkSize }] : [])\n        )) {\n          const elapsed = performance.now() - chunkStart;\n          state = sampleBandwidth(state, elapsed, chunk.byteLength);\n          onSample(state);\n          yield chunk;\n          chunkStart = performance.now();\n        }\n      },\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,eAAsB,gBAAgB,aAAuB,SAA0C;CACrG,MAAM,UAAU,IAAI,QAAQ,SAAS,OAAO;CAG5C,IAAI,YAAY,WAAW;EACzB,MAAM,EAAE,OAAO,QAAQ,YAAY;EACnC,QAAQ,IAAI,SAAS,SAAS,MAAM,GAAG,KAAK;CAC9C;CAEA,MAAM,UAAU,IAAI,QAAQ,YAAY,KAAK;EAC3C,QAAQ;EACR;EACA,GAAG;CACL,CAAC;CAED,OAAO,MAAM,OAAO;AACtB;;;;;;;;;;;;;;AA+CA,SAAgB,gBAAgB,UAAyC;CACvE,OAAO,SAAS,KAAK;AACvB;;AAWA,MAAa,sBAAiC,OAAO,aAAa,YAAY;CAC5E,MAAM,WAAW,MAAM,gBAAgB,aAAa,OAAO;CAC3D,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,MAAM,wBAAwB,SAAS,OAAO,GAAG,SAAS,WAAW,OAAO,YAAY,KAAK;CAEzG,OAAO,gBAAgB,QAAQ;AACjC;AAiBA,eAAsB,YAAY,aAAuB,SAA4D;CACnH,MAAM,EAAE,cAAc,GAAG,iBAAiB,WAAW,CAAC;CACtD,MAAM,WAAW,MAAM,gBAAgB,aAAa,YAAY;CAChE,IAAI,CAAC,SAAS,MAAM,MAAM,IAAI,MAAM,sBAAsB;CAC1D,OAAO,IAAI,sBAAsB,SAAS,MAAM,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAE;AAC3G;;;;;;;;;;;;;;;;AAiBA,SAAgB,mBAAmB,SAAyB,UAAsD;CAChH,IAAI,QAAQ;CACZ,OAAO,OAAO,aAAa,YAAY;EACrC,MAAM,EAAE,cAAc,GAAG,iBAAiB,WAAW,CAAC;EACtD,MAAM,WAAW,MAAM,gBAAgB,aAAa,YAAY;EAChE,IAAI,CAAC,SAAS,MAAM,MAAM,IAAI,MAAM,sBAAsB;EAC1D,MAAM,OAAO,SAAS;EACtB,OAAO,EACL,CAAC,OAAO,gBAAgB,mBAAmB;GACzC,IAAI,aAAa,YAAY,IAAI;GACjC,WAAW,MAAM,SAAS,IAAI,sBAC5B,MACA,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CACzD,GAAG;IACD,MAAM,UAAU,YAAY,IAAI,IAAI;IACpC,QAAQ,gBAAgB,OAAO,SAAS,MAAM,UAAU;IACxD,SAAS,KAAK;IACd,MAAM;IACN,aAAa,YAAY,IAAI;GAC/B;EACF,EACF;CACF;AACF"}

package/dist/default/playback/actors/dom/segment-loader.js

@@ -1,106 +1,49 @@
 import { peek } from "../../../core/signals/primitives.js";
-import { effect } from "../../../core/signals/effect.js";
 import { SerialRunner, Task } from "../../../core/tasks/task.js";
 import { createMachineActor } from "../../../core/actors/create-machine-actor.js";
-import { DEFAULT_FORWARD_BUFFER_CONFIG, calculateForwardFlushPoint, getSegmentsToLoad } from "../../../media/buffer/forward-buffer.js";
-import { SEGMENT_TIME_EPSILON } from "../../../media/types/index.js";
+import "../../../media/types/index.js";
+import { DEFAULT_FORWARD_BUFFER_CONFIG, calculateForwardFlushPoint, getSegmentsToLoad, isTimeRangeCovered, mergeTimeRanges } from "../../../media/buffer/forward-buffer.js";
 import { DEFAULT_BACK_BUFFER_CONFIG, calculateBackBufferFlushPoint } from "../../../media/buffer/back-buffer.js";
+import { DEFAULT_MESSAGE_PIPELINES } from "../../primitives/segment-load-pipeline.js";
 //#region src/playback/actors/dom/segment-loader.ts
 /**
-* Resolves when the SourceBufferActor snapshot reaches 'idle'.
-* Rejects if the signal is aborted or the actor is destroyed.
-*
-* Used to sequence SourceBufferActor operations without awaiting send()
-* directly — send() is fire-and-forget; callers observe completion via
-* state transition.
+* Wraps a LoadTask descriptor into a Task that runs the op's message pipeline
+* (fetch/discover/stamp/dispatch, per the composition's `messagePipelines`).
+* Updates in-flight context around the async region so the loading handler can
+* make accurate continue/preempt decisions at any point, and checks the abort
+* signal before each step.
 */
-function waitForIdle(snapshot, signal) {
-	return new Promise((resolve, reject) => {
-		if (snapshot.get().value === "idle") {
-			resolve();
-			return;
-		}
-		if (snapshot.get().value === "destroyed") {
-			reject(new DOMException("Aborted", "AbortError"));
-			return;
-		}
-		if (signal.aborted) {
-			reject(signal.reason);
-			return;
-		}
-		let stop;
-		const cleanup = (fn) => {
-			stop?.();
-			signal.removeEventListener("abort", onAbort);
-			fn();
-		};
-		const onAbort = () => cleanup(() => reject(signal.reason));
-		stop = effect(() => {
-			const value = snapshot.get().value;
-			if (value === "idle") cleanup(resolve);
-			else if (value === "destroyed") cleanup(() => reject(new DOMException("Aborted", "AbortError")));
-		});
-		signal.addEventListener("abort", onAbort, { once: true });
-	});
-}
-/**
-* Wraps a LoadTask descriptor into a Task that fetches (if needed) and
-* forwards to SourceBufferActor. Updates in-flight context around async
-* operations so the loading handler can make accurate continue/preempt
-* decisions at any point.
-*/
-function makeLoadTask(op, { getContext, setContext, fetchBytes, sourceBufferActor }) {
+function makeLoadTask(op, { getContext, setContext, pipelines, deps }) {
 	return new Task(async (taskSignal) => {
 		if (taskSignal.aborted) return;
-		if (op.type === "remove") {
-			sourceBufferActor.send(op);
-			await waitForIdle(sourceBufferActor.snapshot, taskSignal);
-			return;
-		}
-		if (op.type === "append-init") {
-			setContext({
+		const frame = op.type === "append-segment" ? {
+			op,
+			meta: op.meta
+		} : { op };
+		try {
+			if (op.type === "append-init") setContext({
 				...getContext(),
 				inFlightInitTrackId: op.meta.trackId
 			});
-			try {
-				const data = await fetchBytes(op, {
-					signal: taskSignal,
-					minChunkSize: Infinity
-				});
-				if (!taskSignal.aborted) {
-					sourceBufferActor.send({
-						type: "append-init",
-						data,
-						meta: op.meta
-					});
-					await waitForIdle(sourceBufferActor.snapshot, taskSignal);
+			else if (op.type === "append-segment") setContext({
+				...getContext(),
+				inFlightSegment: {
+					id: op.meta.id,
+					trackId: op.meta.trackId
 				}
-			} finally {
-				setContext({
-					...getContext(),
-					inFlightInitTrackId: null
-				});
-			}
-			return;
-		}
-		setContext({
-			...getContext(),
-			inFlightSegmentId: op.meta.id
-		});
-		try {
-			const stream = await fetchBytes(op, { signal: taskSignal });
-			if (!taskSignal.aborted) {
-				sourceBufferActor.send({
-					type: "append-segment",
-					data: stream,
-					meta: op.meta
-				});
-				await waitForIdle(sourceBufferActor.snapshot, taskSignal);
+			});
+			for (const step of pipelines[op.type]) {
+				if (taskSignal.aborted) return;
+				await step(frame, taskSignal, deps);
 			}
 		} finally {
-			setContext({
+			if (op.type === "append-init") setContext({
 				...getContext(),
-				inFlightSegmentId: null
+				inFlightInitTrackId: null
+			});
+			else if (op.type === "append-segment") setContext({
+				...getContext(),
+				inFlightSegment: null
 			});
 		}
 	});
@@ -123,8 +66,16 @@ function makeLoadTask(op, { getContext, setContext, fetchBytes, sourceBufferActo
 * @param fetchBytes - Tracked fetch closure (owns throughput sampling for segments).
 *   Accepts an optional `minChunkSize` in options; init segments pass `Infinity`
 *   so the entire body accumulates as one chunk before appending.
+* @param compositionDeps - The composition's `state`/`context`/`config`, threaded
+*   opaquely into each step's {@link StepDeps} (the loader never reads them). Lets
+*   injected steps (relocation) read composition signals at call time. Defaults to
+*   empty for standalone / base-pipeline use.
 */
-function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
+function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}, compositionDeps = {
+	state: {},
+	context: {},
+	config: {}
+}) {
 	const forwardBufferConfig = {
 		...DEFAULT_FORWARD_BUFFER_CONFIG,
 		...config.forwardBuffer
@@ -133,9 +84,22 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 		...DEFAULT_BACK_BUFFER_CONFIG,
 		...config.backBuffer
 	};
+	const deps = {
+		state: compositionDeps.state,
+		context: compositionDeps.context,
+		config: {
+			...compositionDeps.config,
+			sourceBufferActor,
+			fetch: fetchBytes
+		}
+	};
+	const pipelines = (config.messagePipelines ?? DEFAULT_MESSAGE_PIPELINES)();
 	const getBufferedSegments = (allSegments) => {
-		const bufferedIds = new Set(peek(sourceBufferActor.snapshot).context.segments.filter((s) => !s.partial).map((s) => s.id));
-		return allSegments.filter((s) => bufferedIds.has(s.id));
+		const merged = mergeTimeRanges(peek(sourceBufferActor.snapshot).context.segments.filter((s) => !s.partial).map((s) => ({
+			start: s.startTime,
+			end: s.startTime + s.duration
+		})));
+		return allSegments.filter((s) => isTimeRangeCovered(s.startTime, s.startTime + s.duration, merged));
 	};
 	/**
 	* Translate a load message into an ordered LoadTask list based on committed
@@ -144,9 +108,19 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 	* @todo Rename alongside LoadTask (e.g. planOps).
 	*
 	* Case 1 — Removes: forward and back buffer flush points, segment-aligned.
-	*   No flush on track switch: appending new content overwrites existing buffer
-	*   ranges, and the actor's time-aligned deduplication keeps the segment model
-	*   accurate as new segments arrive.
+	*   ABR-style track switches (same content, different bitrate) do not flush:
+	*   appending new content overwrites existing buffer ranges, and the actor's
+	*   time-aligned deduplication keeps the segment model accurate as new
+	*   segments arrive.
+	*
+	*   Cross-rendition track switches (audio language change, text language
+	*   change) do flush: the buffered content is semantically incompatible with
+	*   the newly-selected track, so overwrite-on-append would leave stale
+	*   content playing until each replacement segment lands. Today's predicate:
+	*   `actorCtx.initTrackLanguage !== track.language` — fires for language
+	*   changes, no-ops for video / same-language audio bitrate switches.
+	*   Future stage: pluggable predicate / strategy at actor construction time
+	*   for codec-change (5.1 surround) and other cross-rendition shapes.
 	*
 	* Case 2 — Init: schedule if not yet committed for this track.
 	*
@@ -158,29 +132,50 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 		const bufferedSegments = getBufferedSegments(track.segments);
 		const currentTime = range?.start ?? 0;
 		const tasks = [];
+		const isCrossRenditionSwitch = actorCtx.initTrackId !== void 0 && actorCtx.initTrackId !== track.id && actorCtx.initTrackLanguage !== track.language;
+		const removes = [];
+		const staleRanges = [];
 		if (range) {
+			if (isCrossRenditionSwitch) {
+				const staleStart = actorCtx.segments.find((s) => s.startTime <= currentTime && s.startTime + s.duration > currentTime)?.startTime ?? actorCtx.segments.find((s) => s.startTime > currentTime)?.startTime;
+				if (staleStart !== void 0) staleRanges.push({
+					start: staleStart,
+					end: Infinity
+				});
+			}
 			const forwardFlushStart = calculateForwardFlushPoint(bufferedSegments, currentTime, forwardBufferConfig);
-			if (forwardFlushStart < Infinity) tasks.push({
-				type: "remove",
+			if (forwardFlushStart < Infinity) removes.push({
 				start: forwardFlushStart,
 				end: Infinity
 			});
 			const backFlushEnd = calculateBackBufferFlushPoint(bufferedSegments, currentTime, backBufferConfig);
-			if (backFlushEnd > 0) tasks.push({
-				type: "remove",
+			if (backFlushEnd > 0) removes.push({
 				start: 0,
 				end: backFlushEnd
 			});
+			for (const r of removes) tasks.push({
+				type: "remove",
+				start: r.start,
+				end: r.end
+			});
 		}
+		const overlapsStale = (seg) => {
+			const segEnd = seg.startTime + seg.duration;
+			return removes.some((r) => seg.startTime < r.end && segEnd > r.start) || staleRanges.some((r) => seg.startTime < r.end && segEnd > r.start);
+		};
+		const effectiveBuffered = removes.length + staleRanges.length > 0 ? bufferedSegments.filter((s) => !overlapsStale(s)) : bufferedSegments;
 		if (actorCtx.initTrackId !== track.id) tasks.push({
 			type: "append-init",
-			meta: { trackId: track.id },
+			meta: {
+				trackId: track.id,
+				language: track.language
+			},
 			url: track.initialization.url,
 			...track.initialization.byteRange !== void 0 && { byteRange: track.initialization.byteRange }
 		});
 		if (range) {
-			const segmentsToLoad = getSegmentsToLoad(track.segments, bufferedSegments, currentTime, forwardBufferConfig).filter((seg) => {
-				const existing = actorCtx.segments.find((s) => Math.abs(s.startTime - seg.startTime) < SEGMENT_TIME_EPSILON);
+			const segmentsToLoad = getSegmentsToLoad(track.segments, effectiveBuffered, currentTime, forwardBufferConfig).filter((seg) => {
+				const existing = actorCtx.segments.find((s) => !overlapsStale(s) && Math.abs(s.startTime - seg.startTime) < 1e-4);
 				if (existing?.partial) return true;
 				if (!existing?.trackBandwidth || !track.bandwidth) return true;
 				return track.bandwidth > existing.trackBandwidth;
@@ -205,8 +200,8 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 			runner.schedule(makeLoadTask(op, {
 				getContext,
 				setContext,
-				fetchBytes,
-				sourceBufferActor
+				pipelines,
+				deps
 			})).then(void 0, (e) => {
 				if (e instanceof Error && e.name === "AbortError") return;
 				console.error("Unexpected error in segment loader:", e);
@@ -219,7 +214,7 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 		initial: "idle",
 		context: {
 			inFlightInitTrackId: null,
-			inFlightSegmentId: null
+			inFlightSegment: null
 		},
 		states: {
 			idle: { on: { load: (msg, ctx) => {
@@ -233,12 +228,14 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 				on: { load: (msg, ctx) => {
 					const { context, runner } = ctx;
 					const allTasks = planTasks(msg);
-					if (context.inFlightSegmentId !== null && allTasks.some((t) => t.type === "append-segment" && t.meta.id === context.inFlightSegmentId) || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)) {
+					const inFlight = context.inFlightSegment;
+					const segmentInFlightStillNeeded = (t) => t.type === "append-segment" && inFlight !== null && t.meta.id === inFlight.id && t.meta.trackId === inFlight.trackId;
+					if (inFlight !== null && allTasks.some(segmentInFlightStillNeeded) || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)) {
 						runner.abortPending();
-						scheduleAll(allTasks.filter((t) => !(t.type === "append-segment" && t.meta.id === context.inFlightSegmentId) && !(t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)), ctx);
+						scheduleAll(allTasks.filter((t) => !segmentInFlightStillNeeded(t) && !(t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)), ctx);
 					} else {
 						runner.abortAll();
-						if (context.inFlightSegmentId !== null || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId !== context.inFlightInitTrackId)) sourceBufferActor.send({ type: "cancel" });
+						if (context.inFlightSegment !== null || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId !== context.inFlightInitTrackId)) sourceBufferActor.send({ type: "cancel" });
 						scheduleAll(allTasks, ctx);
 					}
 				} }