@videojs/spf 10.0.0-beta.9 → 10.0.0-rc.2

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

@@ -0,0 +1,146 @@
+import { isResolvedTrack } from "../types/index.js";
+//#region src/media/utils/tracks.ts
+/**
+* Get the tracks of the given type from a presentation's first switching set.
+*
+* Returns `[]` when the presentation is unresolved, when no selection set of `type` exists, or when its first switching
+* set is empty. Returned tracks may be partially resolved (URL only) or fully resolved (with segments) — callers narrow
+* as needed.
+*
+* The "first switching set" assumption matches the rest of the codebase (HLS typically has one switching set per type);
+* multi-group / multi-period support would generalize this.
+*/
+function getTracksByType(presentation, type) {
+	return presentation.selectionSets?.find(({ type: t }) => t === type)?.switchingSets[0]?.tracks ?? [];
+}
+/**
+* Find a track of the given type and id within a presentation.
+*
+* Returns the matching track from the first switching set of the matching selection set, or `undefined` if either is
+* missing. The returned track may be partially resolved (URL only) or fully resolved (with segments) — callers narrow
+* as needed.
+*/
+function findTrack(presentation, type, trackId) {
+	return getTracksByType(presentation, type).find(({ id }) => id === trackId);
+}
+/**
+* Find a track by id across all selection sets in a presentation, without knowing its type up front. Used when the
+* caller has a track id obtained from a downstream consumer (e.g. `SourceBufferActor.initTrackId`) and needs to locate
+* the corresponding track in the presentation.
+*
+* Track ids are unique within a presentation per the HLS spec; the first match wins.
+*/
+function findTrackById(presentation, trackId) {
+	for (const selectionSet of presentation.selectionSets ?? []) {
+		const track = selectionSet.switchingSets[0]?.tracks.find(({ id }) => id === trackId);
+		if (track) return track;
+	}
+}
+/**
+* Find a text track of the given id within a presentation and narrow it to the fully-resolved `TextTrack` shape
+* (segments populated). Returns `undefined` if no track matches the id, the matching track isn't a text track, or it
+* hasn't been resolved yet.
+*
+* The segments-non-empty check stays at the call site — a resolved track with zero segments is a valid state, distinct
+* from "ready to load."
+*/
+function findResolvedTextTrack(presentation, trackId) {
+	if (!presentation || !trackId) return void 0;
+	const track = findTrack(presentation, "text", trackId);
+	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?.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?.type !== "audio" || !isResolvedTrack(track)) return void 0;
+	return track;
+}
+/**
+* Whether a track carries a non-empty `codecs` array. Both partially- resolved and fully-resolved tracks may carry
+* codecs — they come from the multivariant playlist's `EXT-X-STREAM-INF` line, not from the per-type media playlist —
+* so this works at either resolution stage.
+*
+* `TextTrack` doesn't declare a `codecs` field; the `'codecs' in track` check narrows it out for the false branch.
+*/
+function hasCodecs(track) {
+	return !!track && "codecs" in track && !!track.codecs?.length;
+}
+/**
+* The family (RFC 6381 4CC) of one codec string: `'avc1.640028'` → `'avc1'`, `'mp4a.40.2'` → `'mp4a'`, dotless strings
+* (`'ec-3'`) pass through whole. Lowercased so families compare regardless of manifest casing.
+*
+* The family is what a `SourceBuffer`'s bytestream is keyed on: renditions in one family swap via a new init segment,
+* while crossing families needs `SourceBuffer.changeType()` (which SPF doesn't implement).
+*/
+function getCodecFamily(codec) {
+	return codec.trim().split(".", 1)[0].toLowerCase();
+}
+/**
+* The distinct codec families a track carries, or `undefined` when it carries no codecs (unknowable, per `hasCodecs` —
+* not "none"). A demuxed rendition has one family; a muxed one (bipbop's `CODECS="hvc1…,mp4a…"`) has one per elementary
+* stream.
+*/
+function getCodecFamilies(track) {
+	if (!track.codecs?.length) return void 0;
+	return [...new Set(track.codecs.map(getCodecFamily))];
+}
+/**
+* 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.
+*
+* **Assumes one container per type, which the HLS specs don't guarantee.** Apple's HLS Authoring Specification not only
+* permits a mixed ladder, it produces one: §1.5 requires HEVC in fMP4, while §9.22 says a 192 kbit/s H.264 variant
+* _packaged in a transport stream_ SHOULD be provided for cellular — so a conformant HEVC ladder with that fallback is
+* necessarily mixed. RFC 8216 is silent too (§6.2.4 constrains variant _content_, not container).
+*
+* Where that happens, resolving the TS variant first relabels the whole type, capability probing prunes all of it, and
+* a source whose fMP4 variants were fine reports as unplayable. Accepted because the current target is CMAF-compliant
+* single-container delivery (plus Apple's official fMP4 example); revisit by narrowing the relabel to the resolved
+* track, or gating propagation on config, if mixed ladders come into scope.
+*/
+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. */
+function updateTrackInPresentation(presentation, resolvedTrack) {
+	const trackId = resolvedTrack.id;
+	return {
+		...presentation,
+		selectionSets: presentation.selectionSets.map((selectionSet) => ({
+			...selectionSet,
+			switchingSets: selectionSet.switchingSets.map((switchingSet) => ({
+				...switchingSet,
+				tracks: switchingSet.tracks.map((track) => track.id === trackId ? resolvedTrack : track)
+			}))
+		}))
+	};
+}
+//#endregion
+export { applyContainerMimeType, findResolvedAudioTrack, findResolvedTextTrack, findResolvedVideoTrack, findTrack, findTrackById, getCodecFamilies, getCodecFamily, getTracksByType, hasCodecs, updateTrackInPresentation };
+
+//# sourceMappingURL=tracks.js.map

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

@@ -0,0 +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 `type` exists, or when its first switching\n * set is empty. Returned tracks may be partially resolved (URL only) or fully resolved (with segments) — callers narrow\n * as needed.\n *\n * The \"first switching set\" assumption matches the rest of the codebase (HLS typically has one switching set per type);\n * multi-group / multi-period 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 selection set, or `undefined` if either is\n * missing. The returned track may be partially resolved (URL only) or fully resolved (with segments) — callers narrow\n * 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 knowing its type up front. Used when the\n * caller has a track id obtained from a downstream consumer (e.g. `SourceBufferActor.initTrackId`) and needs to locate\n * the corresponding track in the presentation.\n *\n * Track ids are unique within a presentation per the HLS spec; the first 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\n  return undefined;\n}\n\n/**\n * Find a text track of the given id within a presentation and narrow it to the fully-resolved `TextTrack` shape\n * (segments populated). Returns `undefined` if no track matches the id, the matching track isn't a text track, or it\n * hasn't been resolved yet.\n *\n * The segments-non-empty check stays at the call site — a resolved track with zero segments is a valid state, distinct\n * 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\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\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\n  const track = findTrack(presentation, 'video', trackId);\n  if (track?.type !== 'video' || !isResolvedTrack(track)) return undefined;\n\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\n  const track = findTrack(presentation, 'audio', trackId);\n  if (track?.type !== 'audio' || !isResolvedTrack(track)) return undefined;\n\n  return track;\n}\n\n/**\n * Whether a track carries a non-empty `codecs` array. Both partially- resolved and fully-resolved tracks may carry\n * codecs — they come from the multivariant playlist's `EXT-X-STREAM-INF` line, not from the per-type media playlist —\n * so this works at either resolution stage.\n *\n * `TextTrack` doesn't declare a `codecs` field; the `'codecs' in track` 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 * The family (RFC 6381 4CC) of one codec string: `'avc1.640028'` → `'avc1'`, `'mp4a.40.2'` → `'mp4a'`, dotless strings\n * (`'ec-3'`) pass through whole. Lowercased so families compare regardless of manifest casing.\n *\n * The family is what a `SourceBuffer`'s bytestream is keyed on: renditions in one family swap via a new init segment,\n * while crossing families needs `SourceBuffer.changeType()` (which SPF doesn't implement).\n */\nexport function getCodecFamily(codec: string): string {\n  return codec.trim().split('.', 1)[0]!.toLowerCase();\n}\n\n/**\n * The distinct codec families a track carries, or `undefined` when it carries no codecs (unknowable, per `hasCodecs` —\n * not \"none\"). A demuxed rendition has one family; a muxed one (bipbop's `CODECS=\"hvc1…,mp4a…\"`) has one per elementary\n * stream.\n */\nexport function getCodecFamilies(track: { codecs?: string[] }): readonly string[] | undefined {\n  if (!track.codecs?.length) return undefined;\n\n  return [...new Set(track.codecs.map(getCodecFamily))];\n}\n\n/**\n * Set `mimeType` on every track of one `type` (immutably). Used to propagate a detected container across a type's\n * renditions: an ABR ladder is the same 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 whole type from a single resolved\n * media playlist, without fetching the rest.\n *\n * Scoped to one type on purpose: propagating _across_ audio/video would be wrong for mixed-container sources (e.g.\n * muxed-TS video + raw-`.aac` audio) and races concurrent per-type resolution. Same-type writes are disjoint and safe.\n * Idempotent — tracks already at `mimeType` are left as-is.\n *\n * **Assumes one container per type, which the HLS specs don't guarantee.** Apple's HLS Authoring Specification not only\n * permits a mixed ladder, it produces one: §1.5 requires HEVC in fMP4, while §9.22 says a 192 kbit/s H.264 variant\n * _packaged in a transport stream_ SHOULD be provided for cellular — so a conformant HEVC ladder with that fallback is\n * necessarily mixed. RFC 8216 is silent too (§6.2.4 constrains variant _content_, not container).\n *\n * Where that happens, resolving the TS variant first relabels the whole type, capability probing prunes all of it, and\n * a source whose fMP4 variants were fine reports as unplayable. Accepted because the current target is CMAF-compliant\n * single-container delivery (plus Apple's official fMP4 example); revisit by narrowing the relabel to the resolved\n * track, or gating propagation on config, if mixed ladders come into scope.\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/** Updates a track within a presentation (immutably). Generic — works for video, audio, or text tracks. */\nexport function updateTrackInPresentation<T extends ResolvedTrack>(\n  presentation: Presentation,\n  resolvedTrack: T\n): Presentation {\n  const trackId = resolvedTrack.id;\n\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":";;;;;;;;;;;;AAsBA,SAAgB,gBACd,cACA,MACqD;CACrD,OAAO,aAAa,eAAe,MAAM,EAAE,MAAM,QAAQ,MAAM,IAAI,CAAC,EAAE,cAAc,EAAE,EAAE,UAAU,CAAC;AACrG;;;;;;;;AASA,SAAgB,UACd,cACA,MACA,SACoD;CACpD,OAAO,gBAAgB,cAAc,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,OAAO,OAAO;AAC5E;;;;;;;;AASA,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;AAGF;;;;;;;;;AAUA,SAAgB,sBACd,cACA,SACuB;CACvB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CAEtC,MAAM,QAAQ,UAAU,cAAc,QAAQ,OAAO;CAGrD,IAAI,OAAO,SAAS,UAAU,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAE9D,OAAO;AACT;AAEA,SAAgB,uBACd,cACA,SACwB;CACxB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CAEtC,MAAM,QAAQ,UAAU,cAAc,SAAS,OAAO;CACtD,IAAI,OAAO,SAAS,WAAW,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAE/D,OAAO;AACT;AAEA,SAAgB,uBACd,cACA,SACwB;CACxB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CAEtC,MAAM,QAAQ,UAAU,cAAc,SAAS,OAAO;CACtD,IAAI,OAAO,SAAS,WAAW,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAE/D,OAAO;AACT;;;;;;;;AASA,SAAgB,UAAU,OAAoE;CAC5F,OAAO,CAAC,CAAC,SAAS,YAAY,SAAS,CAAC,CAAC,MAAM,QAAQ;AACzD;;;;;;;;AASA,SAAgB,eAAe,OAAuB;CACpD,OAAO,MAAM,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,EAAE,CAAE,YAAY;AACpD;;;;;;AAOA,SAAgB,iBAAiB,OAA6D;CAC5F,IAAI,CAAC,MAAM,QAAQ,QAAQ,OAAO,KAAA;CAElC,OAAO,CAAC,GAAG,IAAI,IAAI,MAAM,OAAO,IAAI,cAAc,CAAC,CAAC;AACtD;;;;;;;;;;;;;;;;;;;;;AAsBA,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;;AAGA,SAAgB,0BACd,cACA,eACc;CACd,MAAM,UAAU,cAAc;CAE9B,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/dev/media-tracks.d.ts

@@ -0,0 +1,3 @@
+import { AudioTrack, VideoTrack } from "./media/types/index.js";
+import { AudioDedupeKey, VideoDedupeKey, dedupedAudioTracks, dedupedVideoTracks, findAudioTrackById, findVideoTrackById, frameRateToNumber, isSameAudioTrack, isSameVideoTrack, toUserAudioTrackSelection, toUserVideoTrackSelection } from "./media/media-tracks/media-tracks.js";
+export { type AudioDedupeKey, type AudioTrack, type VideoDedupeKey, type VideoTrack, dedupedAudioTracks, dedupedVideoTracks, findAudioTrackById, findVideoTrackById, frameRateToNumber, isSameAudioTrack, isSameVideoTrack, toUserAudioTrackSelection, toUserVideoTrackSelection };

package/dist/dev/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/dev/network/bandwidth-estimator.d.ts

@@ -0,0 +1,48 @@
+//#region src/network/bandwidth-estimator.d.ts
+/**
+ * Dual EWMA Bandwidth Estimator
+ *
+ * Estimates available bandwidth using two EWMA calculations with different half-lives, taking the minimum of both. This
+ * approach (from Shaka Player):
+ *
+ * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops
+ * - **Slow EWMA** (5s half-life): Provides stability during fluctuations
+ * - **min(fast, slow)**: Adapts down quickly, up slowly
+ *
+ * This naturally provides asymmetric behavior needed for good QoE: avoiding stalls (quick downgrade) while preventing
+ * oscillation (slow upgrade).
+ */
+/**
+ * Bandwidth estimator state.
+ *
+ * This state structure will be managed by O1 (State Container). Functions in this module operate on this state
+ * immutably.
+ */
+interface BandwidthState {
+  /** Fast-moving EWMA estimate (raw, uncorrected). */
+  fastEstimate: number;
+  /** Total weight accumulated in fast EWMA. */
+  fastTotalWeight: number;
+  /** Slow-moving EWMA estimate (raw, uncorrected). */
+  slowEstimate: number;
+  /** Total weight accumulated in slow EWMA. */
+  slowTotalWeight: number;
+  /** Total bytes sampled across all valid samples. */
+  bytesSampled: number;
+}
+/** Configuration for bandwidth estimation. */
+interface BandwidthConfig {
+  /** Half-life for fast EWMA in seconds. */
+  fastHalfLife: number;
+  /** Half-life for slow EWMA in seconds. */
+  slowHalfLife: number;
+  /** Minimum total bytes before trusting the estimate. */
+  minTotalBytes: number;
+  /** Minimum bytes per sample to count (filters TTFB-dominated samples). */
+  minBytes: number;
+  /** Minimum sample duration in ms (filters cached responses). */
+  minDuration: number;
+}
+//#endregion
+export { BandwidthConfig, BandwidthState };
+//# sourceMappingURL=bandwidth-estimator.d.ts.map

package/dist/dev/network/bandwidth-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth-estimator.d.ts","names":[],"sources":["../../../src/network/bandwidth-estimator.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;UAsBiB;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIe;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA"}

package/dist/dev/network/bandwidth-estimator.js

@@ -0,0 +1,95 @@
+import { applyZeroFactor, calculateEwma } from "./ewma.js";
+//#region src/network/bandwidth-estimator.ts
+/**
+* Dual EWMA Bandwidth Estimator
+*
+* Estimates available bandwidth using two EWMA calculations with different half-lives, taking the minimum of both. This
+* approach (from Shaka Player):
+*
+* - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops
+* - **Slow EWMA** (5s half-life): Provides stability during fluctuations
+* - **min(fast, slow)**: Adapts down quickly, up slowly
+*
+* This naturally provides asymmetric behavior needed for good QoE: avoiding stalls (quick downgrade) while preventing
+* oscillation (slow upgrade).
+*/
+/**
+* Default bandwidth estimator configuration.
+*
+* Values match Shaka Player defaults based on experimentation.
+*/
+const DEFAULT_BANDWIDTH_CONFIG = {
+	fastHalfLife: 2,
+	slowHalfLife: 5,
+	minTotalBytes: 128e3,
+	minBytes: 16e3,
+	minDuration: 5
+};
+/**
+* Add a bandwidth sample from a segment download.
+*
+* Samples are filtered based on: - Minimum bytes (filters TTFB-dominated small segments) - Minimum duration (filters
+* cached responses)
+*
+* Valid samples update both fast and slow EWMA estimates.
+*
+* @example
+*   let state = { fastEstimate: 0, fastTotalWeight: 0, ... };
+*   // Sample: 1MB in 1 second
+*   state = sampleBandwidth(state, 1000, 1_000_000);
+*
+* @param state - Current estimator state
+* @param durationMs - Download duration in milliseconds
+* @param numBytes - Number of bytes downloaded
+* @param config - Optional estimator configuration (uses defaults if not provided)
+* @returns New estimator state with sample incorporated (or unchanged if filtered)
+*/
+function sampleBandwidth(state, durationMs, numBytes, config = DEFAULT_BANDWIDTH_CONFIG) {
+	const updatedBytesSampled = state.bytesSampled + numBytes;
+	if (numBytes < config.minBytes) return {
+		...state,
+		bytesSampled: updatedBytesSampled
+	};
+	if (durationMs < config.minDuration) return {
+		...state,
+		bytesSampled: updatedBytesSampled
+	};
+	const bandwidth = 8e3 * numBytes / durationMs;
+	const weight = durationMs / 1e3;
+	return {
+		fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),
+		fastTotalWeight: state.fastTotalWeight + weight,
+		slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),
+		slowTotalWeight: state.slowTotalWeight + weight,
+		bytesSampled: updatedBytesSampled
+	};
+}
+/**
+* Get the current bandwidth estimate.
+*
+* Returns the **minimum** of the fast and slow EWMA estimates. This provides the key asymmetric behavior:
+*
+* - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)
+* - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)
+*
+* Uses default estimate until enough data has been sampled — and when no estimator state exists at all (`state ===
+* undefined`).
+*
+* @example
+*   const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default
+*
+* @param state - Current estimator state, or `undefined` before any samples have been collected
+* @param defaultEstimate - Fallback estimate before sufficient samples (bps)
+* @param config - Optional estimator configuration (uses defaults if not provided)
+* @returns Bandwidth estimate in bits per second
+*/
+function getBandwidthEstimate(state, defaultEstimate, config = DEFAULT_BANDWIDTH_CONFIG) {
+	if (!state || state.bytesSampled < config.minTotalBytes) return defaultEstimate;
+	const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);
+	const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);
+	return Math.min(fastEstimate, slowEstimate);
+}
+//#endregion
+export { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate, sampleBandwidth };
+
+//# sourceMappingURL=bandwidth-estimator.js.map

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

@@ -0,0 +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 half-lives, taking the minimum of both. This\n * 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: avoiding stalls (quick downgrade) while preventing\n * 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). Functions in this module operate on this state\n * 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/** Configuration for bandwidth estimation. */\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: - Minimum bytes (filters TTFB-dominated small segments) - Minimum duration (filters\n * cached responses)\n *\n * Valid samples update both fast and slow EWMA estimates.\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 *\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 */\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. This provides the key asymmetric behavior:\n *\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 estimator state exists at all (`state ===\n * undefined`).\n *\n * @example\n *   const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default\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 */\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: - Enough total bytes sampled (minTotalBytes threshold) - At least one valid EWMA sample (totalWeight >\n * 0)\n *\n * @example\n *   if (hasGoodEstimate(state)) {\n *     const estimate = getBandwidthEstimate(state, 5_000_000);\n *   }\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 */\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":";;;;;;;;;;;;;;;;;;;;AAsDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;AACf;;;;;;;;;;;;;;;;;;;;AAqBA,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/dev/network/chunked-stream-iterable.js

@@ -0,0 +1,47 @@
+//#region src/network/chunked-stream-iterable.ts
+const DEFAULT_MIN_CHUNK_SIZE = 2 ** 17;
+/**
+* Adapts a `ReadableStream<Uint8Array>` (e.g. `response.body`) into an `AsyncIterable<Uint8Array>` that yields chunks
+* no smaller than `minChunkSize` bytes. Smaller network chunks are accumulated and yielded together once the threshold
+* is met. Any remainder is flushed on stream end.
+*
+* Errors from the underlying stream propagate naturally — the reader lock is always released via `finally`.
+*/
+var ChunkedStreamIterable = class {
+	minChunkSize;
+	#readableStream;
+	constructor(readableStream, { minChunkSize = DEFAULT_MIN_CHUNK_SIZE } = {}) {
+		this.#readableStream = readableStream;
+		this.minChunkSize = minChunkSize;
+	}
+	async *[Symbol.asyncIterator]() {
+		let pending;
+		const reader = this.#readableStream.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) {
+					if (pending) yield pending;
+					break;
+				}
+				pending = pending ? concat(pending, value) : value;
+				if (pending.length >= this.minChunkSize) {
+					yield pending;
+					pending = void 0;
+				}
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	}
+};
+function concat(a, b) {
+	const result = new Uint8Array(a.length + b.length);
+	result.set(a);
+	result.set(b, a.length);
+	return result;
+}
+//#endregion
+export { ChunkedStreamIterable };
+
+//# sourceMappingURL=chunked-stream-iterable.js.map

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

@@ -0,0 +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 `AsyncIterable<Uint8Array>` that yields chunks\n * no smaller than `minChunkSize` bytes. Smaller network chunks are accumulated and yielded together once the threshold\n * is met. Any remainder is flushed on stream end.\n *\n * Errors from the underlying stream propagate naturally — the reader lock is 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\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n\n        if (done) {\n          if (pending) yield pending;\n\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\n  result.set(a);\n  result.set(b, a.length);\n  return result;\n}\n"],"mappings":";AAAA,MAAM,yBAAyB,KAAK;;;;;;;;AAapC,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;EAE9C,IAAI;GACF,OAAO,MAAM;IACX,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;IAE1C,IAAI,MAAM;KACR,IAAI,SAAS,MAAM;KAEnB;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;CAEjD,OAAO,IAAI,CAAC;CACZ,OAAO,IAAI,GAAG,EAAE,MAAM;CACtB,OAAO;AACT"}

package/dist/dev/network/ewma.js

@@ -0,0 +1,68 @@
+//#region src/network/ewma.ts
+/**
+* Exponentially Weighted Moving Average (EWMA)
+*
+* Pure functional implementation of EWMA calculations. Based on Shaka Player's EWMA algorithm.
+*/
+/**
+* Calculate alpha (decay factor) from half-life.
+*
+* Alpha determines how quickly old data "expires": - alpha close to 1 = slow decay (long memory) - alpha close to 0 =
+* fast decay (short memory)
+*
+* @example
+*   const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life
+*
+* @param halfLife - The quantity of prior samples (by weight) that make up half of the new estimate. Must be positive.
+* @returns Alpha value between 0 and 1
+*/
+function calculateAlpha(halfLife) {
+	return Math.exp(Math.log(.5) / halfLife);
+}
+/**
+* Calculate exponentially weighted moving average.
+*
+* Updates an estimate by blending a new value with the previous estimate, weighted by the sample duration. Longer
+* samples have more influence.
+*
+* @example
+*   let estimate = 0;
+*   estimate = calculateEwma(estimate, 1_000_000, 1, 2); // First sample
+*   estimate = calculateEwma(estimate, 2_000_000, 1, 2); // Second sample
+*
+* @param prevEstimate - Previous EWMA estimate
+* @param value - New sample value to incorporate
+* @param weight - Sample weight (typically duration in seconds)
+* @param halfLife - Half-life for decay (typically 2-5 seconds)
+* @returns Updated EWMA estimate
+*/
+function calculateEwma(prevEstimate, value, weight, halfLife) {
+	const adjAlpha = calculateAlpha(halfLife) ** weight;
+	return value * (1 - adjAlpha) + adjAlpha * prevEstimate;
+}
+/**
+* Apply zero-factor correction to EWMA estimate.
+*
+* The zero-factor correction compensates for bias when starting from zero. Without this correction, early estimates
+* would be artificially low.
+*
+* As totalWeight increases, the correction factor approaches 1, meaning the estimate becomes more reliable and needs
+* less correction.
+*
+* @example
+*   const raw = calculateEwma(0, 1_000_000, 1, 2);
+*   const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000
+*
+* @param estimate - Raw EWMA estimate (uncorrected)
+* @param totalWeight - Accumulated weight from all samples
+* @param halfLife - Half-life used in EWMA calculation
+* @returns Corrected estimate, or 0 if totalWeight is 0
+*/
+function applyZeroFactor(estimate, totalWeight, halfLife) {
+	if (totalWeight === 0) return 0;
+	return estimate / (1 - calculateAlpha(halfLife) ** totalWeight);
+}
+//#endregion
+export { applyZeroFactor, calculateAlpha, calculateEwma };
+
+//# sourceMappingURL=ewma.js.map

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

@@ -0,0 +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. 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\": - alpha close to 1 = slow decay (long memory) - alpha close to 0 =\n * fast decay (short memory)\n *\n * @example\n *   const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life\n *\n * @param halfLife - The quantity of prior samples (by weight) that make up half of the new estimate. Must be positive.\n * @returns Alpha value between 0 and 1\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, weighted by the sample duration. Longer\n * samples have more influence.\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 *\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 */\nexport function calculateEwma(prevEstimate: number, value: number, weight: number, halfLife: number): number {\n  const alpha = calculateAlpha(halfLife);\n  const adjAlpha = alpha ** weight;\n\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. Without this correction, early estimates\n * would be artificially low.\n *\n * As totalWeight increases, the correction factor approaches 1, meaning the estimate becomes more reliable and needs\n * less correction.\n *\n * @example\n *   const raw = calculateEwma(0, 1_000_000, 1, 2);\n *   const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000\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 */\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\n  return estimate / zeroFactor;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,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;CAE1B,OAAO,SAAS,IAAI,YAAY,WAAW;AAC7C;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,gBAAgB,UAAkB,aAAqB,UAA0B;CAC/F,IAAI,gBAAgB,GAClB,OAAO;CAMT,OAAO,YAFY,IADL,eAAe,QACF,KAAK;AAGlC"}

package/dist/dev/network/fetch.js

@@ -0,0 +1,108 @@
+import { sampleBandwidth } from "./bandwidth-estimator.js";
+import { ChunkedStreamIterable } from "./chunked-stream-iterable.js";
+//#region src/network/fetch.ts
+/**
+* HTTP Fetch Wrapper
+*
+* Composable building blocks: - fetchResolvable() — fetch a Resource (handles byte ranges); returns Response -
+* getResponseText() — extract text from Response - fetchResolvableStream() — single-stage async generator over body
+* chunks - fetchStream() — two-stage: await connection establishment, then lazily iterate body chunks. Use when timing
+* the connection start independently of body consumption matters (e.g., observable fetch timing for ABR). -
+* createTrackedFetch() — factory for a fetchStream-shape function that samples bandwidth (via EWMA) per chunk and
+* notifies via callback.
+*/
+/**
+* Fetch resolvable from a Resource.
+*
+* Handles byte range requests if byteRange is present. Returns native fetch Response for composability (can extract
+* text, stream, etc.).
+*
+* @example
+*   const response = await fetchResolvable({ url: 'https://example.com/segment.m4s' });
+*   const text = await getResponseText(response);
+*
+* @example
+*   // With byte range
+*   const response = await fetchResolvable({
+*     url: 'https://example.com/file.mp4',
+*     byteRange: { start: 1000, end: 1999 },
+*   });
+*
+* @param addressable - Resource to fetch (url + optional byteRange)
+* @returns Promise resolving to Response
+*/
+async function fetchResolvable(addressable, options) {
+	const headers = new Headers(options?.headers);
+	if (addressable.byteRange) {
+		const { start, end } = addressable.byteRange;
+		headers.set("Range", `bytes=${start}-${end}`);
+	}
+	const request = new Request(addressable.url, {
+		method: "GET",
+		headers,
+		...options
+	});
+	return fetch(request);
+}
+/**
+* Extract text from Response.
+*
+* Accepts minimal Response-like object (just needs text() method). Returns promise from response.text().
+*
+* @example
+*   const response = await fetchResolvable(addressable);
+*   const text = await getResponseText(response);
+*
+* @param response - Response-like object with text() method
+* @returns Promise resolving to text content
+*/
+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);
+	if (!response.body) throw new Error("Response has no body");
+	return new ChunkedStreamIterable(response.body, ...minChunkSize !== void 0 ? [{ minChunkSize }] : []);
+}
+/**
+* Returns a {@link FetchBytes} function that samples bandwidth via EWMA per body chunk. The factory captures the
+* running bandwidth state internally; per chunk it computes the next state and notifies the supplied `onSample`
+* callback.
+*
+* The factory's internal accumulator is seeded from `initial` and updated on every chunk; callers don't need to thread
+* it back in. `onSample` receives the _new_ state after each chunk — typical use is to bridge samples back into engine
+* state for ABR consumers.
+*
+* @param initial - Starting `BandwidthState` (commonly zeros or the engine's current accumulator).
+* @param onSample - Called with the new `BandwidthState` after each chunk.
+*/
+function createTrackedFetch(initial, onSample) {
+	let state = initial;
+	return async (addressable, options) => {
+		const { minChunkSize, ...fetchOptions } = options ?? {};
+		const response = await fetchResolvable(addressable, fetchOptions);
+		if (!response.body) throw new Error("Response has no body");
+		const body = response.body;
+		return { [Symbol.asyncIterator]: async function* () {
+			let chunkStart = performance.now();
+			for await (const chunk of new ChunkedStreamIterable(body, ...minChunkSize !== void 0 ? [{ minChunkSize }] : [])) {
+				const elapsed = performance.now() - chunkStart;
+				state = sampleBandwidth(state, elapsed, chunk.byteLength);
+				onSample(state);
+				yield chunk;
+				chunkStart = performance.now();
+			}
+		} };
+	};
+}
+//#endregion
+export { createTrackedFetch, fetchResolvable, fetchResolvableText, fetchStream, getResponseText };
+
+//# sourceMappingURL=fetch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","names":[],"sources":["../../../src/network/fetch.ts"],"sourcesContent":["/**\n * HTTP Fetch Wrapper\n *\n * Composable building blocks: - fetchResolvable() — fetch a Resource (handles byte ranges); returns Response -\n * getResponseText() — extract text from Response - fetchResolvableStream() — single-stage async generator over body\n * chunks - fetchStream() — two-stage: await connection establishment, then lazily iterate body chunks. Use when timing\n * the connection start independently of body consumption matters (e.g., observable fetch timing for ABR). -\n * createTrackedFetch() — factory for a fetchStream-shape function that samples bandwidth (via EWMA) per chunk and\n * notifies via callback.\n */\n\nimport { type BandwidthState, sampleBandwidth } from './bandwidth-estimator';\nimport { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from './chunked-stream-iterable';\n\n/** Minimal Response-like interface for text extraction. Allows testing without full Response object. */\nexport interface ResponseLike {\n  text(): Promise<string>;\n}\n\n/**\n * An HTTP-addressable resource — URL plus optional byte range. Media's `AddressableObject` (and anything else with the\n * same shape) is structurally compatible; kept local so this module stays 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. Returns native fetch Response for composability (can extract\n * text, stream, etc.).\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 *\n * @param addressable - Resource to fetch (url + optional byteRange)\n * @returns Promise resolving to Response\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\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 ArrayBuffer. Use this when you need the raw\n * bytes (e.g. segment appends). 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\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 via ChunkedStreamIterable. Headers are\n * awaited before the first chunk is yielded (TTFB is accounted for before iteration begins).\n *\n * Throws if the response body is null (e.g. non-body HTTP status). Errors from the underlying stream propagate\n * 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\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). Returns promise from response.text().\n *\n * @example\n *   const response = await fetchResolvable(addressable);\n *   const text = await getResponseText(response);\n *\n * @param response - Response-like object with text() method\n * @returns Promise resolving to text content\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 {@link FetchBytes}. A non-OK status rejects, so HTTP\n * failures surface as rejections that callers (and decorators like the failover tracker) handle uniformly with network\n * 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\n  if (!response.ok) {\n    throw new Error(`fetchResolvableText: ${response.status} ${response.statusText} for ${addressable.url}`);\n  }\n\n  return getResponseText(response);\n};\n\n/**\n * Two-stage fetch helper: eagerly starts the HTTP request (TTFB is awaited), then returns a lazy iterable over the\n * response body. Separating connection 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 `fetch` only when iteration starts). Pick\n * `fetchStream` when \"when did the fetch start\" needs to be observable separately from \"when did the body begin\n * 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\n  return new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Returns a {@link FetchBytes} function that samples bandwidth via EWMA per body chunk. The factory captures the\n * running bandwidth state internally; per chunk it computes the next state and notifies the supplied `onSample`\n * callback.\n *\n * The factory's internal accumulator is seeded from `initial` and updated on every chunk; callers don't need to thread\n * it back in. `onSample` receives the _new_ state after each chunk — typical use is to bridge samples back into engine\n * state for ABR consumers.\n *\n * @param initial - Starting `BandwidthState` (commonly zeros or the 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\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\n    const body = response.body;\n\n    return {\n      [Symbol.asyncIterator]: async function* () {\n        let chunkStart = performance.now();\n\n        for await (const chunk of new ChunkedStreamIterable(\n          body,\n          ...(minChunkSize !== undefined ? [{ minChunkSize }] : [])\n        )) {\n          const elapsed = performance.now() - chunkStart;\n\n          state = sampleBandwidth(state, elapsed, chunk.byteLength);\n          onSample(state);\n          yield chunk;\n          chunkStart = performance.now();\n        }\n      },\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,eAAsB,gBAAgB,aAAuB,SAA0C;CACrG,MAAM,UAAU,IAAI,QAAQ,SAAS,OAAO;CAG5C,IAAI,YAAY,WAAW;EACzB,MAAM,EAAE,OAAO,QAAQ,YAAY;EAEnC,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;;;;;;;;;;;;;AA8CA,SAAgB,gBAAgB,UAAyC;CACvE,OAAO,SAAS,KAAK;AACvB;;AAUA,MAAa,sBAAiC,OAAO,aAAa,YAAY;CAC5E,MAAM,WAAW,MAAM,gBAAgB,aAAa,OAAO;CAE3D,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,MAAM,wBAAwB,SAAS,OAAO,GAAG,SAAS,WAAW,OAAO,YAAY,KAAK;CAGzG,OAAO,gBAAgB,QAAQ;AACjC;AAeA,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;CAE1D,OAAO,IAAI,sBAAsB,SAAS,MAAM,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAE;AAC3G;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,SAAyB,UAAsD;CAChH,IAAI,QAAQ;CAEZ,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;EAE1D,MAAM,OAAO,SAAS;EAEtB,OAAO,EACL,CAAC,OAAO,gBAAgB,mBAAmB;GACzC,IAAI,aAAa,YAAY,IAAI;GAEjC,WAAW,MAAM,SAAS,IAAI,sBAC5B,MACA,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CACzD,GAAG;IACD,MAAM,UAAU,YAAY,IAAI,IAAI;IAEpC,QAAQ,gBAAgB,OAAO,SAAS,MAAM,UAAU;IACxD,SAAS,KAAK;IACd,MAAM;IACN,aAAa,YAAY,IAAI;GAC/B;EACF,EACF;CACF;AACF"}