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

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

@@ -1,23 +1,20 @@
 import { isResolvedTrack } from "../types/index.js";
 //#region src/media/utils/track-selection.ts
-/**
-* Map track type to selected track ID property key in state.
-*/
+/** 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.
+* 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
-* }
+*   const videoTrack = getSelectedTrack(state, 'video');
+*   if (videoTrack && isResolvedTrack(videoTrack)) {
+*     // videoTrack is VideoTrack
+*   }
 */
 function getSelectedTrack(state, type) {
 	const { presentation } = state;
@@ -26,10 +23,9 @@ function getSelectedTrack(state, 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.
+* 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) {

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

@@ -1 +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"}
+{"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/** State shape for track selection. Minimal shape containing presentation and selected track IDs. */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string | undefined;\n  selectedAudioTrackId?: string | undefined;\n  selectedTextTrackId?: string | undefined;\n}\n\n/** Map track type to selected track ID property key in state. */\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. Returns properly typed track (partially or fully resolved) or undefined. Type\n * 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  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\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 video over audio. A track is \"resolved\" once\n * its media playlist has been parsed (per {@link isResolvedTrack}). Returns `undefined` if neither selected track is\n * 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\n  if (state.selectedAudioTrackId) {\n    const audio = getSelectedTrack(state, 'audio');\n    if (audio && isResolvedTrack(audio)) return audio.duration;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;AAqBA,MAAa,2BAA2B;CACtC,OAAO;CACP,OAAO;CACP,MAAM;AACR;;;;;;;;;;;AAYA,SAAgB,iBACd,OACA,MAOY;CACZ,MAAM,EAAE,iBAAiB;CACzB,IAAI,CAAC,cAAc,eAAe,OAAO,KAAA;CAIzC,MAAM,UAAU,MADG,yBAAyB;CAG5C,OAAO,aAAa,cACjB,MAAM,EAAE,MAAM,uBAAuB,qBAAqB,IAAI,CAAC,EAC9D,cAAc,EAAE,EAAE,OAAO,MAAM,EAAE,SAAS,OAAO,OAAO;AAC9D;;;;;;AAOA,SAAgB,iCAAiC,OAAgD;CAC/F,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;CAEA,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;AAGF"}

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

@@ -3,14 +3,12 @@ import { isResolvedTrack } from "../types/index.js";
 /**
 * 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.
+* 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.
+* 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 ?? [];
@@ -18,22 +16,19 @@ function getTracksByType(presentation, type) {
 /**
 * 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.
+* 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.
+* 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.
+* 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 ?? []) {
@@ -42,13 +37,12 @@ function findTrackById(presentation, trackId) {
 	}
 }
 /**
-* 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.
+* 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."
+* 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;
@@ -69,42 +63,53 @@ function findResolvedAudioTrack(presentation, trackId) {
 	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.
+* 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.
+* `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.
+* 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.
 *
-* 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.
+* 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).
+* **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.
+* 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 {
@@ -121,10 +126,7 @@ function applyContainerMimeType(presentation, type, mimeType) {
 		} : selectionSet)
 	};
 }
-/**
-* Updates a track within a presentation (immutably). Generic — works for
-* video, audio, or text tracks.
-*/
+/** Updates a track within a presentation (immutably). Generic — works for video, audio, or text tracks. */
 function updateTrackInPresentation(presentation, resolvedTrack) {
 	const trackId = resolvedTrack.id;
 	return {
@@ -139,6 +141,6 @@ function updateTrackInPresentation(presentation, resolvedTrack) {
 	};
 }
 //#endregion
-export { applyContainerMimeType, findResolvedAudioTrack, findResolvedTextTrack, findResolvedVideoTrack, findTrack, findTrackById, getTracksByType, hasCodecs, updateTrackInPresentation };
+export { applyContainerMimeType, findResolvedAudioTrack, findResolvedTextTrack, findResolvedVideoTrack, findTrack, findTrackById, getCodecFamilies, getCodecFamily, getTracksByType, hasCodecs, updateTrackInPresentation };
 
 //# sourceMappingURL=tracks.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"tracks.js","names":[],"sources":["../../../../src/media/utils/tracks.ts"],"sourcesContent":["import type {\n  AudioTrack,\n  MaybeResolvedPresentation,\n  PartiallyResolvedTrack,\n  Presentation,\n  ResolvedTrack,\n  TextTrack,\n  TrackType,\n  VideoTrack,\n} from '../types';\nimport { isResolvedTrack } from '../types';\n\n/**\n * Get the tracks of the given type from a presentation's first switching set.\n *\n * Returns `[]` when the presentation is unresolved, when no selection set of\n * `type` exists, or when its first switching set is empty. Returned tracks may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n *\n * The \"first switching set\" assumption matches the rest of the codebase\n * (HLS typically has one switching set per type); multi-group / multi-period\n * support would generalize this.\n */\nexport function getTracksByType(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType\n): readonly (PartiallyResolvedTrack | ResolvedTrack)[] {\n  return presentation.selectionSets?.find(({ type: t }) => t === type)?.switchingSets[0]?.tracks ?? [];\n}\n\n/**\n * Find a track of the given type and id within a presentation.\n *\n * Returns the matching track from the first switching set of the matching\n * selection set, or `undefined` if either is missing. The returned track may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n */\nexport function findTrack(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  return getTracksByType(presentation, type).find(({ id }) => id === trackId);\n}\n\n/**\n * Find a track by id across all selection sets in a presentation, without\n * knowing its type up front. Used when the caller has a track id obtained\n * from a downstream consumer (e.g. `SourceBufferActor.initTrackId`) and\n * needs to locate the corresponding track in the presentation.\n *\n * Track ids are unique within a presentation per the HLS spec; the first\n * match wins.\n */\nexport function findTrackById(\n  presentation: MaybeResolvedPresentation,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  for (const selectionSet of presentation.selectionSets ?? []) {\n    const track = selectionSet.switchingSets[0]?.tracks.find(({ id }) => id === trackId);\n    if (track) return track;\n  }\n  return undefined;\n}\n\n/**\n * Find a text track of the given id within a presentation and narrow it to\n * the fully-resolved `TextTrack` shape (segments populated). Returns\n * `undefined` if no track matches the id, the matching track isn't a text\n * track, or it hasn't been resolved yet.\n *\n * The segments-non-empty check stays at the call site — a resolved track\n * with zero segments is a valid state, distinct from \"ready to load.\"\n */\nexport function findResolvedTextTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): TextTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'text', trackId);\n  // `findTrack` returns the wide union; narrow via discriminant before\n  // applying `isResolvedTrack`'s text-specific overload.\n  if (track?.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"}
+{"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/default/network/bandwidth-estimator.js

@@ -3,15 +3,15 @@ import { applyZeroFactor, calculateEwma } from "./ewma.js";
 /**
 * 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):
+* 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).
+* This naturally provides asymmetric behavior needed for good QoE: avoiding stalls (quick downgrade) while preventing
+* oscillation (slow upgrade).
 */
 /**
 * Default bandwidth estimator configuration.
@@ -28,22 +28,21 @@ const DEFAULT_BANDWIDTH_CONFIG = {
 /**
 * 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)
+* 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)
-*
-* @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;
@@ -68,21 +67,21 @@ function sampleBandwidth(state, durationMs, numBytes, config = DEFAULT_BANDWIDTH
 /**
 * Get the current bandwidth estimate.
 *
-* Returns the **minimum** of the fast and slow EWMA estimates.
-* This provides the key asymmetric behavior:
+* 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`).
+* 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
-*
-* @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;

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

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

@@ -1,13 +1,11 @@
 //#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.
+* 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`.
+* Errors from the underlying stream propagate naturally — the reader lock is always released via `finally`.
 */
 var ChunkedStreamIterable = class {
 	minChunkSize;

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

@@ -1 +1 @@
-{"version":3,"file":"chunked-stream-iterable.js","names":["#readableStream"],"sources":["../../../src/network/chunked-stream-iterable.ts"],"sourcesContent":["const DEFAULT_MIN_CHUNK_SIZE = 2 ** 17; // 128 KB\n\nexport interface ChunkedStreamIterableOptions {\n  minChunkSize?: number;\n}\n\n/**\n * Adapts a `ReadableStream<Uint8Array>` (e.g. `response.body`) into an\n * `AsyncIterable<Uint8Array>` that yields chunks no smaller than\n * `minChunkSize` bytes. Smaller network chunks are accumulated and yielded\n * together once the threshold is met. Any remainder is flushed on stream end.\n *\n * Errors from the underlying stream propagate naturally — the reader lock is\n * always released via `finally`.\n */\nexport class ChunkedStreamIterable implements AsyncIterable<Uint8Array> {\n  readonly minChunkSize: number;\n  #readableStream: ReadableStream<Uint8Array>;\n\n  constructor(\n    readableStream: ReadableStream<Uint8Array>,\n    { minChunkSize = DEFAULT_MIN_CHUNK_SIZE }: ChunkedStreamIterableOptions = {}\n  ) {\n    this.#readableStream = readableStream;\n    this.minChunkSize = minChunkSize;\n  }\n\n  async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {\n    let pending: Uint8Array | undefined;\n    const reader = this.#readableStream.getReader();\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) {\n          if (pending) yield pending;\n          break;\n        }\n\n        pending = pending ? concat(pending, value) : value;\n\n        if (pending.length >= this.minChunkSize) {\n          yield pending;\n          pending = undefined;\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n\nfunction concat(a: Uint8Array, b: Uint8Array): Uint8Array {\n  const result = new Uint8Array(a.length + b.length);\n  result.set(a);\n  result.set(b, a.length);\n  return result;\n}\n"],"mappings":";AAAA,MAAM,yBAAyB,KAAK;;;;;;;;;;AAepC,IAAa,wBAAb,MAAwE;CACtE;CACA;CAEA,YACE,gBACA,EAAE,eAAe,2BAAyD,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"}
+{"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/default/network/ewma.js

@@ -2,22 +2,19 @@
 /**
 * Exponentially Weighted Moving Average (EWMA)
 *
-* Pure functional implementation of EWMA calculations.
-* Based on Shaka Player's EWMA algorithm.
+* 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
+* 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
+*   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);
@@ -25,19 +22,19 @@ function calculateAlpha(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.
+* 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
-*
-* @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;
@@ -46,20 +43,20 @@ function calculateEwma(prevEstimate, value, weight, halfLife) {
 /**
 * 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.
+* 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.
 *
-* 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
-*
-* @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;

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

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