@videojs/spf 10.0.0-beta.3 → 10.0.0-beta.30

package/dist/default/media/utils/track-selection.js

@@ -0,0 +1,47 @@
+import { isResolvedTrack } from "../types/index.js";
+//#region src/media/utils/track-selection.ts
+/**
+* Map track type to selected track ID property key in state.
+*/
+const SelectedTrackIdKeyByType = {
+	video: "selectedVideoTrackId",
+	audio: "selectedAudioTrackId",
+	text: "selectedTextTrackId"
+};
+/**
+* Get selected track from state by type.
+* Returns properly typed track (partially or fully resolved) or undefined.
+* Type parameter T is inferred from the type argument.
+*
+* @example
+* const videoTrack = getSelectedTrack(state, 'video');
+* if (videoTrack && isResolvedTrack(videoTrack)) {
+*   // videoTrack is VideoTrack
+* }
+*/
+function getSelectedTrack(state, type) {
+	const { presentation } = state;
+	if (!presentation?.selectionSets) return void 0;
+	const trackId = state[SelectedTrackIdKeyByType[type]];
+	return presentation.selectionSets.find(({ type: selectionSetType }) => selectionSetType === type)?.switchingSets[0]?.tracks.find(({ id }) => id === trackId);
+}
+/**
+* Returns the duration of the first resolved selected track, preferring
+* video over audio. A track is "resolved" once its media playlist has been
+* parsed (per {@link isResolvedTrack}). Returns `undefined` if neither
+* selected track is resolved.
+*/
+function getResolvedSelectedTrackDuration(state) {
+	if (state.selectedVideoTrackId) {
+		const video = getSelectedTrack(state, "video");
+		if (video && isResolvedTrack(video)) return video.duration;
+	}
+	if (state.selectedAudioTrackId) {
+		const audio = getSelectedTrack(state, "audio");
+		if (audio && isResolvedTrack(audio)) return audio.duration;
+	}
+}
+//#endregion
+export { SelectedTrackIdKeyByType, getResolvedSelectedTrackDuration, getSelectedTrack };
+
+//# sourceMappingURL=track-selection.js.map

package/dist/default/media/utils/track-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-selection.js","names":[],"sources":["../../../../src/media/utils/track-selection.ts"],"sourcesContent":["import type {\n  AudioTrack,\n  MaybeResolvedPresentation,\n  PartiallyResolvedAudioTrack,\n  PartiallyResolvedTextTrack,\n  PartiallyResolvedVideoTrack,\n  TextTrack,\n  TrackType,\n  VideoTrack,\n} from '../types';\nimport { isResolvedTrack } from '../types';\n\n/**\n * State shape for track selection.\n * Minimal shape containing presentation and selected track IDs.\n */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string | undefined;\n  selectedAudioTrackId?: string | undefined;\n  selectedTextTrackId?: string | undefined;\n}\n\n/**\n * Map track type to selected track ID property key in state.\n */\nexport const SelectedTrackIdKeyByType = {\n  video: 'selectedVideoTrackId',\n  audio: 'selectedAudioTrackId',\n  text: 'selectedTextTrackId',\n} as const;\n\n/**\n * Get selected track from state by type.\n * Returns properly typed track (partially or fully resolved) or undefined.\n * Type parameter T is inferred from the type argument.\n *\n * @example\n * const videoTrack = getSelectedTrack(state, 'video');\n * if (videoTrack && isResolvedTrack(videoTrack)) {\n *   // videoTrack is VideoTrack\n * }\n */\nexport function getSelectedTrack<T extends TrackType>(\n  state: TrackSelectionState,\n  type: T\n): T extends 'video'\n  ? PartiallyResolvedVideoTrack | VideoTrack | undefined\n  : T extends 'audio'\n    ? PartiallyResolvedAudioTrack | AudioTrack | undefined\n    : T extends 'text'\n      ? PartiallyResolvedTextTrack | TextTrack | undefined\n      : never {\n  const { presentation } = state;\n\n  if (!presentation?.selectionSets) return undefined as any;\n\n  // Get track ID based on type\n  const trackIdKey = SelectedTrackIdKeyByType[type];\n  const trackId = state[trackIdKey];\n  return presentation.selectionSets\n    .find(({ type: selectionSetType }) => selectionSetType === type)\n    ?.switchingSets[0]?.tracks.find(({ id }) => id === trackId) as any;\n}\n\n/**\n * Returns the duration of the first resolved selected track, preferring\n * video over audio. A track is \"resolved\" once its media playlist has been\n * parsed (per {@link isResolvedTrack}). Returns `undefined` if neither\n * selected track is resolved.\n */\nexport function getResolvedSelectedTrackDuration(state: TrackSelectionState): number | undefined {\n  if (state.selectedVideoTrackId) {\n    const video = getSelectedTrack(state, 'video');\n    if (video && isResolvedTrack(video)) return video.duration;\n  }\n  if (state.selectedAudioTrackId) {\n    const audio = getSelectedTrack(state, 'audio');\n    if (audio && isResolvedTrack(audio)) return audio.duration;\n  }\n  return undefined;\n}\n"],"mappings":";;;;;AA0BA,MAAa,2BAA2B;CACtC,OAAO;CACP,OAAO;CACP,MAAM;AACR;;;;;;;;;;;;AAaA,SAAgB,iBACd,OACA,MAOY;CACZ,MAAM,EAAE,iBAAiB;CAEzB,IAAI,CAAC,cAAc,eAAe,OAAO,KAAA;CAIzC,MAAM,UAAU,MADG,yBAAyB;CAE5C,OAAO,aAAa,cACjB,MAAM,EAAE,MAAM,uBAAuB,qBAAqB,IAAI,CAAC,EAC9D,cAAc,EAAE,EAAE,OAAO,MAAM,EAAE,SAAS,OAAO,OAAO;AAC9D;;;;;;;AAQA,SAAgB,iCAAiC,OAAgD;CAC/F,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;CACA,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;AAEF"}

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

@@ -0,0 +1,144 @@
+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;
+}
+/**
+* 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, getTracksByType, hasCodecs, updateTrackInPresentation };
+
+//# sourceMappingURL=tracks.js.map

package/dist/default/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\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 *\n * **Assumes one container per type, which the HLS specs don't guarantee.** Apple's\n * HLS Authoring Specification not only permits a mixed ladder, it produces one:\n * §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\n * conformant HEVC ladder with that fallback is necessarily mixed. RFC 8216 is\n * silent too (§6.2.4 constrains variant *content*, not container).\n *\n * Where that happens, resolving the TS variant first relabels the whole type,\n * capability probing prunes all of it, and a source whose fMP4 variants were fine\n * reports as unplayable. Accepted because the current target is CMAF-compliant\n * single-container delivery (plus Apple's official fMP4 example); revisit by\n * narrowing the relabel to the resolved track, or gating propagation on config,\n * 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/**\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;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,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/mux-audio.js

@@ -0,0 +1,3 @@
+import { muxMediaDefaultProps } from "./playback/adapters/mux-video/adapter.js";
+import { MuxAudioMedia } from "./playback/adapters/mux-audio/media.js";
+export { MuxAudioMedia, muxMediaDefaultProps };

package/dist/default/mux-background-video.js

@@ -0,0 +1,3 @@
+import { HlsBackgroundVideoMediaElement, HlsBackgroundVideoMediaMixin, hlsBackgroundVideoMediaDefaultProps } from "./playback/adapters/hls-background-video/adapter.js";
+import { HlsBackgroundVideoMedia } from "./playback/adapters/hls-background-video/media.js";
+export { HlsBackgroundVideoMedia as MuxBackgroundVideoMedia, HlsBackgroundVideoMediaElement as MuxBackgroundVideoMediaElement, HlsBackgroundVideoMediaMixin as MuxBackgroundVideoMediaMixin, hlsBackgroundVideoMediaDefaultProps as muxBackgroundVideoMediaDefaultProps };

package/dist/default/mux-video.js

@@ -0,0 +1,3 @@
+import { MuxMediaMixin, muxMediaDefaultProps } from "./playback/adapters/mux-video/adapter.js";
+import { MuxVideoMedia } from "./playback/adapters/mux-video/media.js";
+export { MuxMediaMixin, MuxVideoMedia, muxMediaDefaultProps };

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

@@ -0,0 +1,96 @@
+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.
+*
+* @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)
+*
+* @example
+* let state = { fastEstimate: 0, fastTotalWeight: 0, ... };
+* // Sample: 1MB in 1 second
+* state = sampleBandwidth(state, 1000, 1_000_000);
+*/
+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`).
+*
+* @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
+*
+* @example
+* const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default
+*/
+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/default/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\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

@@ -0,0 +1,49 @@
+//#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/default/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\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

@@ -0,0 +1,71 @@
+//#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)
+*
+* @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
+*
+* @example
+* const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life
+*/
+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.
+*
+* @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
+*
+* @example
+* let estimate = 0;
+* estimate = calculateEwma(estimate, 1_000_000, 1, 2); // First sample
+* estimate = calculateEwma(estimate, 2_000_000, 1, 2); // Second sample
+*/
+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.
+*
+* @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
+*
+* @example
+* const raw = calculateEwma(0, 1_000_000, 1, 2);
+* const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000
+*/
+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/default/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.\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

@@ -0,0 +1,115 @@
+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.).
+*
+* @param addressable - Resource to fetch (url + optional byteRange)
+* @returns Promise resolving to Response
+*
+* @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 }
+* });
+*/
+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().
+*
+* @param response - Response-like object with text() method
+* @returns Promise resolving to text content
+*
+* @example
+* const response = await fetchResolvable(addressable);
+* const text = await getResponseText(response);
+*/
+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/default/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:\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"}