@videojs/spf 10.0.0-beta.1 → 10.0.0-beta.11

package/dist/default/dom/playback-engine/engine.js

@@ -0,0 +1,176 @@
+import { createState } from "../../core/state/create-state.js";
+import { createEventStream } from "../../core/events/create-event-stream.js";
+import { resolvePresentation, syncPreloadAttribute } from "../../core/features/resolve-presentation.js";
+import { switchQuality } from "../../core/features/quality-switching.js";
+import { loadSegments } from "../features/load-segments.js";
+import { destroyVttParser } from "../text/parse-vtt-segment.js";
+import { loadTextTrackCues } from "../features/load-text-track-cues.js";
+import { trackCurrentTime } from "../features/track-current-time.js";
+import { trackPlaybackInitiated } from "../features/track-playback-initiated.js";
+import { calculatePresentationDuration } from "../../core/features/calculate-presentation-duration.js";
+import { resolveTrack } from "../../core/features/resolve-track.js";
+import { selectAudioTrack, selectTextTrack, selectVideoTrack } from "../../core/features/select-tracks.js";
+import { endOfStream } from "../features/end-of-stream.js";
+import { setupMediaSource } from "../features/setup-mediasource.js";
+import { setupSourceBuffers } from "../features/setup-sourcebuffer.js";
+import { setupTextTracks } from "../features/setup-text-tracks.js";
+import { syncSelectedTextTrackFromDom } from "../features/sync-selected-text-track-from-dom.js";
+import { syncTextTrackModes } from "../features/sync-text-track-modes.js";
+import { updateDuration } from "../features/update-duration.js";
+
+//#region src/dom/playback-engine/engine.ts
+/**
+* Create a POC playback engine.
+*
+* Wires together all orchestrations to create a reactive playback pipeline:
+* 1. Resolve presentation (multivariant playlist)
+* 2. Select initial video and audio tracks
+* 3. Resolve selected tracks (media playlists)
+* 4. Setup MediaSource
+* 5. Setup SourceBuffers for video and audio
+*
+* Note: This is a POC - does not yet load/append segments.
+*
+* @param config - Playback engine configuration
+* @returns Playback engine instance with state, owners, and destroy function
+*
+* @example
+* const engine = createPlaybackEngine({
+*   initialBandwidth: 2_000_000,
+*   preferredAudioLanguage: 'en',
+* });
+*
+* // Initialize by patching state and owners
+* engine.owners.patch({ mediaElement: document.querySelector('video') });
+* engine.state.patch({
+*   presentation: { url: 'https://example.com/playlist.m3u8' },
+*   preload: 'auto',
+* });
+*
+* // Inspect state
+* console.log(engine.state.current);
+*
+* // Cleanup
+* engine.destroy();
+*/
+function createPlaybackEngine(config = {}) {
+	const state = createState({ bandwidthState: {
+		fastEstimate: 0,
+		fastTotalWeight: 0,
+		slowEstimate: 0,
+		slowTotalWeight: 0,
+		bytesSampled: 0
+	} });
+	const owners = createState({});
+	const events = createEventStream();
+	const cleanups = [
+		syncPreloadAttribute(state, owners),
+		trackPlaybackInitiated({
+			state,
+			owners,
+			events
+		}),
+		resolvePresentation({
+			state,
+			events
+		}),
+		selectVideoTrack({
+			state,
+			owners,
+			events
+		}, {
+			type: "video",
+			...config.initialBandwidth !== void 0 && { initialBandwidth: config.initialBandwidth }
+		}),
+		selectAudioTrack({
+			state,
+			owners,
+			events
+		}, {
+			type: "audio",
+			...config.preferredAudioLanguage !== void 0 && { preferredAudioLanguage: config.preferredAudioLanguage }
+		}),
+		selectTextTrack({
+			state,
+			owners,
+			events
+		}, {
+			type: "text",
+			...config.preferredSubtitleLanguage !== void 0 && { preferredSubtitleLanguage: config.preferredSubtitleLanguage },
+			...config.includeForcedTracks !== void 0 && { includeForcedTracks: config.includeForcedTracks },
+			...config.enableDefaultTrack !== void 0 && { enableDefaultTrack: config.enableDefaultTrack }
+		}),
+		resolveTrack({
+			state,
+			events
+		}, { type: "video" }),
+		resolveTrack({
+			state,
+			events
+		}, { type: "audio" }),
+		resolveTrack({
+			state,
+			events
+		}, { type: "text" }),
+		calculatePresentationDuration({ state }),
+		setupMediaSource({
+			state,
+			owners
+		}),
+		updateDuration({
+			state,
+			owners
+		}),
+		setupSourceBuffers({
+			state,
+			owners
+		}),
+		trackCurrentTime({
+			state,
+			owners
+		}),
+		switchQuality({ state }),
+		loadSegments({
+			state,
+			owners
+		}, { type: "video" }),
+		loadSegments({
+			state,
+			owners
+		}, { type: "audio" }),
+		endOfStream({
+			state,
+			owners
+		}),
+		setupTextTracks({
+			state,
+			owners
+		}),
+		syncTextTrackModes({
+			state,
+			owners
+		}),
+		syncSelectedTextTrackFromDom({
+			state,
+			owners
+		}),
+		loadTextTrackCues({
+			state,
+			owners
+		})
+	];
+	events.dispatch({ type: "@@INITIALIZE@@" });
+	return {
+		state,
+		owners,
+		events,
+		destroy: () => {
+			cleanups.forEach((cleanup) => cleanup());
+			destroyVttParser();
+		}
+	};
+}
+
+//#endregion
+export { createPlaybackEngine };
+//# sourceMappingURL=engine.js.map

package/dist/default/dom/playback-engine/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","names":[],"sources":["../../../../src/dom/playback-engine/engine.ts"],"sourcesContent":["import type { BandwidthState } from '../../core/abr/bandwidth-estimator';\nimport { createEventStream } from '../../core/events/create-event-stream';\nimport { calculatePresentationDuration } from '../../core/features/calculate-presentation-duration';\nimport { switchQuality } from '../../core/features/quality-switching';\nimport {\n  type PresentationAction,\n  resolvePresentation,\n  syncPreloadAttribute,\n} from '../../core/features/resolve-presentation';\nimport { resolveTrack, type TrackResolutionAction } from '../../core/features/resolve-track';\nimport {\n  selectAudioTrack,\n  selectTextTrack,\n  selectVideoTrack,\n  type TrackSelectionAction,\n} from '../../core/features/select-tracks';\nimport { createState } from '../../core/state/create-state';\nimport { endOfStream } from '../features/end-of-stream';\nimport { loadSegments } from '../features/load-segments';\nimport type { TextTrackBufferState } from '../features/load-text-track-cues';\nimport { loadTextTrackCues } from '../features/load-text-track-cues';\nimport { setupMediaSource } from '../features/setup-mediasource';\nimport { setupSourceBuffers } from '../features/setup-sourcebuffer';\nimport { setupTextTracks } from '../features/setup-text-tracks';\nimport { syncSelectedTextTrackFromDom } from '../features/sync-selected-text-track-from-dom';\nimport { syncTextTrackModes } from '../features/sync-text-track-modes';\nimport { trackCurrentTime } from '../features/track-current-time';\nimport { trackPlaybackInitiated } from '../features/track-playback-initiated';\nimport { updateDuration } from '../features/update-duration';\nimport type { SourceBufferActor } from '../media/source-buffer-actor';\nimport { destroyVttParser } from '../text/parse-vtt-segment';\n\n/**\n * Union of all action types used by playback engine orchestrations.\n * Includes synthetic @@INITIALIZE@@ event for combineLatest bootstrapping.\n */\nexport type PlaybackEngineAction =\n  | PresentationAction\n  | TrackResolutionAction\n  | TrackSelectionAction\n  | { type: '@@INITIALIZE@@' };\n\n/**\n * Configuration for the playback engine.\n */\nexport interface PlaybackEngineConfig {\n  /**\n   * Initial bandwidth estimate for cold start (bits per second).\n   * Default: 1 Mbps (conservative).\n   */\n  initialBandwidth?: number;\n\n  /**\n   * Preferred audio language (ISO 639 code, e.g., \"en\", \"es\").\n   * If not specified, selects first audio track.\n   */\n  preferredAudioLanguage?: string;\n\n  /**\n   * Preferred subtitle language (ISO 639 code, e.g., \"en\", \"es\").\n   * If specified, selects matching text track if available.\n   */\n  preferredSubtitleLanguage?: string;\n\n  /**\n   * Include FORCED subtitle tracks in selection.\n   * Default: false (follows hls.js/http-streaming pattern)\n   */\n  includeForcedTracks?: boolean;\n\n  /**\n   * Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS).\n   * Default: false (user opt-in, matches hls.js/http-streaming)\n   */\n  enableDefaultTrack?: boolean;\n}\n\n/**\n * Combined state shape for the playback engine.\n * Includes all state needed by orchestrations.\n */\nexport interface PlaybackEngineState {\n  // Presentation state\n  presentation?: any;\n  preload?: string;\n\n  // Track selection state\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  // NOTE: Text Tracks (subtitles/ccs) can be unselected\n  selectedTextTrackId?: string;\n\n  // Bandwidth estimation state\n  bandwidthState?: BandwidthState;\n\n  // ABR control — set to true to suppress automatic quality switching (manual selection mode).\n  // TODO: replace with separate manualVideoTrackId / abrVideoTrackId fields so the two\n  // concerns don't share a field; see quality-switching.ts for the full design note.\n  abrDisabled?: boolean;\n\n  // Text track buffer state (tracks loaded VTT segments per text track ID)\n  textBufferState?: TextTrackBufferState;\n\n  // Current playback position (mirrored from mediaElement via trackCurrentTime)\n  currentTime?: number;\n\n  // True once the user has initiated playback (enables segment loading regardless of preload)\n  playbackInitiated?: boolean;\n}\n\n/**\n * Combined owners shape for the playback engine.\n * Includes all mutable platform objects.\n */\nexport interface PlaybackEngineOwners {\n  // Media element\n  mediaElement?: HTMLMediaElement | undefined;\n\n  // MediaSource\n  mediaSource?: MediaSource;\n\n  // SourceBuffers and their actors (created together by setupSourceBuffer)\n  videoBuffer?: SourceBuffer;\n  audioBuffer?: SourceBuffer;\n  videoBufferActor?: SourceBufferActor;\n  audioBufferActor?: SourceBufferActor;\n\n  // Text tracks (track elements by ID)\n  textTracks?: Map<string, HTMLTrackElement>;\n}\n\n/**\n * Playback engine instance.\n */\nexport interface PlaybackEngine {\n  /**\n   * Reactive state (for inspection/testing).\n   */\n  state: ReturnType<typeof createState<PlaybackEngineState>>;\n\n  /**\n   * Mutable owners (for inspection/testing).\n   */\n  owners: ReturnType<typeof createState<PlaybackEngineOwners>>;\n\n  /**\n   * Shared event stream (for inspection/testing/triggering events).\n   */\n  events: ReturnType<typeof createEventStream<PlaybackEngineAction>>;\n\n  /**\n   * Cleanup function to destroy all orchestrations.\n   */\n  destroy: () => void;\n}\n\n/**\n * Create a POC playback engine.\n *\n * Wires together all orchestrations to create a reactive playback pipeline:\n * 1. Resolve presentation (multivariant playlist)\n * 2. Select initial video and audio tracks\n * 3. Resolve selected tracks (media playlists)\n * 4. Setup MediaSource\n * 5. Setup SourceBuffers for video and audio\n *\n * Note: This is a POC - does not yet load/append segments.\n *\n * @param config - Playback engine configuration\n * @returns Playback engine instance with state, owners, and destroy function\n *\n * @example\n * const engine = createPlaybackEngine({\n *   initialBandwidth: 2_000_000,\n *   preferredAudioLanguage: 'en',\n * });\n *\n * // Initialize by patching state and owners\n * engine.owners.patch({ mediaElement: document.querySelector('video') });\n * engine.state.patch({\n *   presentation: { url: 'https://example.com/playlist.m3u8' },\n *   preload: 'auto',\n * });\n *\n * // Inspect state\n * console.log(engine.state.current);\n *\n * // Cleanup\n * engine.destroy();\n */\nexport function createPlaybackEngine(config: PlaybackEngineConfig = {}): PlaybackEngine {\n  // Create reactive state and owners (initially empty)\n  const state = createState<PlaybackEngineState>({\n    bandwidthState: {\n      fastEstimate: 0,\n      fastTotalWeight: 0,\n      slowEstimate: 0,\n      slowTotalWeight: 0,\n      bytesSampled: 0,\n    },\n  });\n  const owners = createState<PlaybackEngineOwners>({});\n\n  // Create single shared event stream for all orchestrations\n  const events = createEventStream<PlaybackEngineAction>();\n\n  // Wire up orchestrations (all share single event stream)\n  // Note: @ts-expect-error needed due to EventStream invariance - each orchestration expects\n  // specific event types, but shared stream has union of all types. Proper fix would\n  // require making EventStream covariant or refactoring event system.\n  const cleanups = [\n    // 0a. Sync preload attribute from mediaElement → state.preload\n    //     Only re-reads when the mediaElement reference changes (lastMediaElement guard).\n    //     Normalises '' (absent attribute) to 'auto' (browser default).\n    // @ts-expect-error - WritableState type variance\n    syncPreloadAttribute(state, owners),\n\n    // 0b. Bridge media element play event → state.playbackInitiated + event stream\n    //     Enables preload=\"none\"/\"metadata\" resolution via native controls / element.play()\n    // @ts-expect-error - EventStream type variance\n    trackPlaybackInitiated({ state, owners, events }),\n\n    // 1. Resolve presentation (URL already in state)\n    // @ts-expect-error - EventStream type variance\n    resolvePresentation({ state, events }),\n\n    // 2. Select initial tracks (when presentation loads)\n    selectVideoTrack(\n      // @ts-expect-error - Owners and EventStream type compatibility\n      { state, owners, events },\n      {\n        type: 'video',\n        ...(config.initialBandwidth !== undefined && { initialBandwidth: config.initialBandwidth }),\n      }\n    ),\n    selectAudioTrack(\n      // @ts-expect-error - Owners and EventStream type compatibility\n      { state, owners, events },\n      {\n        type: 'audio',\n        ...(config.preferredAudioLanguage !== undefined && { preferredAudioLanguage: config.preferredAudioLanguage }),\n      }\n    ),\n    selectTextTrack(\n      // @ts-expect-error - Owners and EventStream type compatibility\n      { state, owners, events },\n      {\n        type: 'text',\n        ...(config.preferredSubtitleLanguage !== undefined && {\n          preferredSubtitleLanguage: config.preferredSubtitleLanguage,\n        }),\n        ...(config.includeForcedTracks !== undefined && { includeForcedTracks: config.includeForcedTracks }),\n        ...(config.enableDefaultTrack !== undefined && { enableDefaultTrack: config.enableDefaultTrack }),\n      }\n    ),\n\n    // 3. Resolve selected tracks (fetch media playlists)\n    // @ts-expect-error - EventStream type variance\n    resolveTrack({ state, events }, { type: 'video' as const }),\n    // @ts-expect-error - EventStream type variance\n    resolveTrack({ state, events }, { type: 'audio' as const }),\n    // @ts-expect-error - EventStream type variance\n    resolveTrack({ state, events }, { type: 'text' as const }),\n\n    // 3.5. Calculate presentation duration from resolved tracks\n    calculatePresentationDuration({ state }),\n\n    // 4. Setup MediaSource (when presentation loaded)\n    setupMediaSource({ state, owners }),\n\n    // 4.5. Update MediaSource duration (when presentation duration available)\n    updateDuration({ state, owners }),\n\n    // 5. Setup SourceBuffers (when MediaSource ready and all selected tracks resolved)\n    // Both SourceBuffers are created in a single synchronous operation to guarantee\n    // neither is visible to loadSegments before the other exists — preventing the\n    // Firefox bug where appending video data before audio SB is created causes\n    // mozHasAudio to be permanently false.\n    setupSourceBuffers({ state, owners }),\n\n    // 5.5. Track currentTime from mediaElement (feeds forward buffer management)\n    //\n    // NOTE: SourceBufferActor wiring is intentionally absent here in Phase 1.\n    //\n    // Attempting to wire actors into the engine at this layer revealed a\n    // brittleness in the current architecture: every patch to `owners` —\n    // regardless of which field changed — wakes up ALL combineLatest subscribers\n    // (loadSegments, endOfStream, etc.). Storing actor references in owners\n    // caused loadSegments to re-evaluate mid-task, store a spurious pending\n    // state, and run a second loading cycle on completion.\n    //\n    // This means any future feature that needs to introduce new reactive state\n    // alongside SourceBuffers faces the same hazard. The right fix is for\n    // loadSegments (and other orchestrations) to route their MSE operations\n    // through the actor directly, at which point the actor lifecycle is\n    // co-located with its consumer rather than managed centrally here.\n    //\n    // Actor wiring will be introduced in Phase 2 as part of the loadSegments\n    // refactor. See .claude/plans/spf/buffer-state-shadow-actual-model.md.\n    trackCurrentTime({ state, owners }),\n\n    // 5.75. ABR quality switching (reacts to bandwidth samples from loadSegments)\n    switchQuality({ state }),\n\n    // 6. Load segments (when SourceBuffer ready and track resolved)\n    loadSegments({ state, owners }, { type: 'video' }),\n    loadSegments({ state, owners }, { type: 'audio' }),\n\n    // 6.5. Signal end of stream when all segments loaded\n    endOfStream({ state, owners }),\n\n    // 7. Setup text tracks (when mediaElement and presentation ready)\n    setupTextTracks({ state, owners }),\n\n    // 8. Sync text track modes (when track selected and track elements created)\n    syncTextTrackModes({ state, owners }),\n\n    // 8.5. Bridge DOM text track mode changes → selectedTextTrackId\n    //      Detects when external code (e.g. captions button via toggleSubtitles())\n    //      sets a subtitle/caption track to 'showing' and reflects that into SPF\n    //      state, which in turn drives loadTextTrackCues.\n    syncSelectedTextTrackFromDom({ state, owners }),\n\n    // 9. Load text track cues (when track resolved and mode set)\n    loadTextTrackCues({ state, owners }),\n  ];\n\n  // Dispatch synthetic initialize event to satisfy combineLatest\n  // (combineLatest waits for all sources to emit before triggering listeners)\n  events.dispatch({ type: '@@INITIALIZE@@' });\n\n  // Return engine instance\n  return {\n    state,\n    owners,\n    events,\n    destroy: () => {\n      cleanups.forEach((cleanup) => cleanup());\n      destroyVttParser();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8LA,SAAgB,qBAAqB,SAA+B,EAAE,EAAkB;CAEtF,MAAM,QAAQ,YAAiC,EAC7C,gBAAgB;EACd,cAAc;EACd,iBAAiB;EACjB,cAAc;EACd,iBAAiB;EACjB,cAAc;EACf,EACF,CAAC;CACF,MAAM,SAAS,YAAkC,EAAE,CAAC;CAGpD,MAAM,SAAS,mBAAyC;CAMxD,MAAM,WAAW;EAKf,qBAAqB,OAAO,OAAO;EAKnC,uBAAuB;GAAE;GAAO;GAAQ;GAAQ,CAAC;EAIjD,oBAAoB;GAAE;GAAO;GAAQ,CAAC;EAGtC,iBAEE;GAAE;GAAO;GAAQ;GAAQ,EACzB;GACE,MAAM;GACN,GAAI,OAAO,qBAAqB,UAAa,EAAE,kBAAkB,OAAO,kBAAkB;GAC3F,CACF;EACD,iBAEE;GAAE;GAAO;GAAQ;GAAQ,EACzB;GACE,MAAM;GACN,GAAI,OAAO,2BAA2B,UAAa,EAAE,wBAAwB,OAAO,wBAAwB;GAC7G,CACF;EACD,gBAEE;GAAE;GAAO;GAAQ;GAAQ,EACzB;GACE,MAAM;GACN,GAAI,OAAO,8BAA8B,UAAa,EACpD,2BAA2B,OAAO,2BACnC;GACD,GAAI,OAAO,wBAAwB,UAAa,EAAE,qBAAqB,OAAO,qBAAqB;GACnG,GAAI,OAAO,uBAAuB,UAAa,EAAE,oBAAoB,OAAO,oBAAoB;GACjG,CACF;EAID,aAAa;GAAE;GAAO;GAAQ,EAAE,EAAE,MAAM,SAAkB,CAAC;EAE3D,aAAa;GAAE;GAAO;GAAQ,EAAE,EAAE,MAAM,SAAkB,CAAC;EAE3D,aAAa;GAAE;GAAO;GAAQ,EAAE,EAAE,MAAM,QAAiB,CAAC;EAG1D,8BAA8B,EAAE,OAAO,CAAC;EAGxC,iBAAiB;GAAE;GAAO;GAAQ,CAAC;EAGnC,eAAe;GAAE;GAAO;GAAQ,CAAC;EAOjC,mBAAmB;GAAE;GAAO;GAAQ,CAAC;EAqBrC,iBAAiB;GAAE;GAAO;GAAQ,CAAC;EAGnC,cAAc,EAAE,OAAO,CAAC;EAGxB,aAAa;GAAE;GAAO;GAAQ,EAAE,EAAE,MAAM,SAAS,CAAC;EAClD,aAAa;GAAE;GAAO;GAAQ,EAAE,EAAE,MAAM,SAAS,CAAC;EAGlD,YAAY;GAAE;GAAO;GAAQ,CAAC;EAG9B,gBAAgB;GAAE;GAAO;GAAQ,CAAC;EAGlC,mBAAmB;GAAE;GAAO;GAAQ,CAAC;EAMrC,6BAA6B;GAAE;GAAO;GAAQ,CAAC;EAG/C,kBAAkB;GAAE;GAAO;GAAQ,CAAC;EACrC;AAID,QAAO,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG3C,QAAO;EACL;EACA;EACA;EACA,eAAe;AACb,YAAS,SAAS,YAAY,SAAS,CAAC;AACxC,qBAAkB;;EAErB"}

package/dist/default/dom/playback-engine.js

@@ -0,0 +1,4 @@
+import { createPlaybackEngine } from "./playback-engine/engine.js";
+import { SpfMedia } from "./playback-engine/adapter.js";
+
+export { SpfMedia, createPlaybackEngine };

package/dist/default/dom/text/parse-vtt-segment.js

@@ -0,0 +1,56 @@
+//#region src/dom/text/parse-vtt-segment.ts
+/**
+* Parse a VTT segment using browser's native parser.
+*
+* Creates a dummy video element with a track element to leverage
+* the browser's optimized VTT parsing. Returns parsed VTTCue objects.
+*/
+let dummyVideo = null;
+function ensureDummyVideo() {
+	if (!dummyVideo) {
+		dummyVideo = document.createElement("video");
+		dummyVideo.muted = true;
+		dummyVideo.preload = "none";
+		dummyVideo.style.display = "none";
+		dummyVideo.crossOrigin = "anonymous";
+	}
+	return dummyVideo;
+}
+function parseVttSegment(url) {
+	const video = ensureDummyVideo();
+	const track = document.createElement("track");
+	track.kind = "subtitles";
+	track.default = true;
+	return new Promise((resolve, reject) => {
+		const onLoad = () => {
+			const cues = [];
+			const textTrack = track.track;
+			if (textTrack.cues) for (let i = 0; i < textTrack.cues.length; i++) {
+				const cue = textTrack.cues[i];
+				if (cue) cues.push(cue);
+			}
+			cleanup();
+			resolve(cues);
+		};
+		const onError = () => {
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`Failed to load VTT segment: ${url}`));
+		};
+		const cleanup = () => {
+			track.removeEventListener("load", onLoad);
+			track.removeEventListener("error", onError);
+			video.removeChild(track);
+		};
+		track.addEventListener("load", onLoad);
+		track.addEventListener("error", onError);
+		video.appendChild(track);
+		track.src = url;
+	});
+}
+function destroyVttParser() {
+	dummyVideo = null;
+}
+
+//#endregion
+export { destroyVttParser, parseVttSegment };
+//# sourceMappingURL=parse-vtt-segment.js.map

package/dist/default/dom/text/parse-vtt-segment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-vtt-segment.js","names":[],"sources":["../../../../src/dom/text/parse-vtt-segment.ts"],"sourcesContent":["/**\n * Parse a VTT segment using browser's native parser.\n *\n * Creates a dummy video element with a track element to leverage\n * the browser's optimized VTT parsing. Returns parsed VTTCue objects.\n */\n\n// Singleton dummy video (reused across all parsing)\nlet dummyVideo: HTMLVideoElement | null = null;\n\nfunction ensureDummyVideo(): HTMLVideoElement {\n  if (!dummyVideo) {\n    dummyVideo = document.createElement('video');\n    dummyVideo.muted = true;\n    dummyVideo.preload = 'none';\n    dummyVideo.style.display = 'none';\n    dummyVideo.crossOrigin = 'anonymous';\n  }\n  return dummyVideo;\n}\n\nexport function parseVttSegment(url: string): Promise<VTTCue[]> {\n  const video = ensureDummyVideo();\n  const track = document.createElement('track');\n  track.kind = 'subtitles';\n  track.default = true;\n\n  return new Promise((resolve, reject) => {\n    const onLoad = (): void => {\n      const cues: VTTCue[] = [];\n      const textTrack = track.track;\n\n      if (textTrack.cues) {\n        for (let i = 0; i < textTrack.cues.length; i++) {\n          const cue = textTrack.cues[i];\n          if (cue) {\n            cues.push(cue as VTTCue);\n          }\n        }\n      }\n\n      cleanup();\n      resolve(cues);\n    };\n\n    const onError = (): void => {\n      cleanup();\n      reject(new Error(`Failed to load VTT segment: ${url}`));\n    };\n\n    const cleanup = (): void => {\n      track.removeEventListener('load', onLoad);\n      track.removeEventListener('error', onError);\n      video.removeChild(track);\n    };\n\n    track.addEventListener('load', onLoad);\n    track.addEventListener('error', onError);\n    video.appendChild(track);\n    track.src = url;\n  });\n}\n\nexport function destroyVttParser(): void {\n  dummyVideo = null;\n}\n"],"mappings":";;;;;;;AAQA,IAAI,aAAsC;AAE1C,SAAS,mBAAqC;AAC5C,KAAI,CAAC,YAAY;AACf,eAAa,SAAS,cAAc,QAAQ;AAC5C,aAAW,QAAQ;AACnB,aAAW,UAAU;AACrB,aAAW,MAAM,UAAU;AAC3B,aAAW,cAAc;;AAE3B,QAAO;;AAGT,SAAgB,gBAAgB,KAAgC;CAC9D,MAAM,QAAQ,kBAAkB;CAChC,MAAM,QAAQ,SAAS,cAAc,QAAQ;AAC7C,OAAM,OAAO;AACb,OAAM,UAAU;AAEhB,QAAO,IAAI,SAAS,SAAS,WAAW;EACtC,MAAM,eAAqB;GACzB,MAAM,OAAiB,EAAE;GACzB,MAAM,YAAY,MAAM;AAExB,OAAI,UAAU,KACZ,MAAK,IAAI,IAAI,GAAG,IAAI,UAAU,KAAK,QAAQ,KAAK;IAC9C,MAAM,MAAM,UAAU,KAAK;AAC3B,QAAI,IACF,MAAK,KAAK,IAAc;;AAK9B,YAAS;AACT,WAAQ,KAAK;;EAGf,MAAM,gBAAsB;AAC1B,YAAS;AACT,0BAAO,IAAI,MAAM,+BAA+B,MAAM,CAAC;;EAGzD,MAAM,gBAAsB;AAC1B,SAAM,oBAAoB,QAAQ,OAAO;AACzC,SAAM,oBAAoB,SAAS,QAAQ;AAC3C,SAAM,YAAY,MAAM;;AAG1B,QAAM,iBAAiB,QAAQ,OAAO;AACtC,QAAM,iBAAiB,SAAS,QAAQ;AACxC,QAAM,YAAY,MAAM;AACxB,QAAM,MAAM;GACZ;;AAGJ,SAAgB,mBAAyB;AACvC,cAAa"}

package/dist/default/dom.js

@@ -0,0 +1,11 @@
+import { loadSegments } from "./dom/features/load-segments.js";
+import { destroyVttParser, parseVttSegment } from "./dom/text/parse-vtt-segment.js";
+import { loadTextTrackCues } from "./dom/features/load-text-track-cues.js";
+import { trackCurrentTime } from "./dom/features/track-current-time.js";
+import { trackPlaybackInitiated } from "./dom/features/track-playback-initiated.js";
+import { trackPlaybackRate } from "./dom/features/track-playback-rate.js";
+import { appendSegment } from "./dom/media/append-segment.js";
+import { flushBuffer } from "./dom/media/buffer-flusher.js";
+import { SpfMedia } from "./dom/playback-engine/adapter.js";
+
+export { SpfMedia, appendSegment, destroyVttParser, flushBuffer, loadSegments, loadTextTrackCues, parseVttSegment, trackCurrentTime, trackPlaybackInitiated, trackPlaybackRate };

package/dist/{src-DRsS_H80.js → default/index.js}

@@ -10,5 +10,5 @@
 const VERSION = "0.1.0";
 
 //#endregion
-export { VERSION as t };
-//# sourceMappingURL=src-DRsS_H80.js.map
+export { VERSION };
+//# sourceMappingURL=index.js.map

package/dist/default/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/index.ts"],"sourcesContent":["/**\n * Stream Processing Framework (SPF) for Video.js 10\n *\n * Bundle size target: < 20KB (minified + gzipped)\n * Primary use case: CMAF HLS playback with Video.js v10\n *\n * @packageDocumentation\n */\n\n// Public API exports will be added here as features are implemented\n\nexport const VERSION = '0.1.0';\n"],"mappings":";;;;;;;;;AAWA,MAAa,UAAU"}

package/dist/dev/all.js

@@ -0,0 +1,16 @@
+import { VERSION } from "./index.js";
+import { createState } from "./core/state/create-state.js";
+import { resolveUrl } from "./core/hls/resolve-url.js";
+import { parseMediaPlaylist } from "./core/hls/parse-media-playlist.js";
+import { parseMultivariantPlaylist } from "./core/hls/parse-multivariant.js";
+import { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate, sampleBandwidth } from "./core/abr/bandwidth-estimator.js";
+import { DEFAULT_QUALITY_CONFIG, selectQuality } from "./core/abr/quality-selection.js";
+import { DEFAULT_BACK_BUFFER_CONFIG, calculateBackBufferFlushPoint } from "./core/buffer/back-buffer.js";
+import { DEFAULT_FORWARD_BUFFER_CONFIG, getSegmentsToLoad } from "./core/buffer/forward-buffer.js";
+import { hasPresentationDuration, isResolvedTrack } from "./core/types/index.js";
+import { attachMediaSource, createMediaSource, createSourceBuffer, isCodecSupported, supportsManagedMediaSource, supportsMediaSource, waitForSourceOpen } from "./dom/media/mediasource-setup.js";
+import { fetchResolvable, getResponseText } from "./dom/network/fetch.js";
+import { createEventStream } from "./core/events/create-event-stream.js";
+import { combineLatest } from "./core/reactive/combine-latest.js";
+import { canResolve, isUnresolved, resolvePresentation, shouldResolve, syncPreloadAttribute } from "./core/features/resolve-presentation.js";
+import { DEFAULT_SWITCHING_CONFIG, switchQuality } from "./core/features/quality-switching.js";

package/dist/dev/core/abr/bandwidth-estimator.d.ts

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

package/dist/dev/core/abr/bandwidth-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth-estimator.d.ts","names":[],"sources":["../../../../src/core/abr/bandwidth-estimator.ts"],"mappings":";;AAsBA;;;;;;;;;;;;;;;;;;UAAiB,cAAA;;EAEf,YAAA;;EAEA,eAAA;;EAEA,YAAA;;EAEA,eAAA;;EAEA,YAAA;AAAA"}

package/dist/dev/core/abr/bandwidth-estimator.js

@@ -0,0 +1,96 @@
+import { applyZeroFactor, calculateEwma } from "./ewma.js";
+
+//#region src/core/abr/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.
+*
+* @param state - Current estimator state
+* @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.bytesSampled < config.minTotalBytes) return defaultEstimate;
+	const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);
+	const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);
+	return Math.min(fastEstimate, slowEstimate);
+}
+
+//#endregion
+export { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate, sampleBandwidth };
+//# sourceMappingURL=bandwidth-estimator.js.map

package/dist/dev/core/abr/bandwidth-estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bandwidth-estimator.js","names":[],"sources":["../../../../src/core/abr/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.\n *\n * @param state - Current estimator state\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,\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.bytesSampled < config.minTotalBytes) {\n    return defaultEstimate;\n  }\n\n  // Apply zero-factor correction to both estimates\n  const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);\n\n  const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);\n\n  // Take the minimum - this is the key insight from Shaka Player\n  // It naturally provides \"down quickly, up slowly\" behavior\n  return Math.min(fastEstimate, slowEstimate);\n}\n\n/**\n * Check if the estimator has enough data to provide a reliable estimate.\n *\n * Requires both:\n * - Enough total bytes sampled (minTotalBytes threshold)\n * - At least one valid EWMA sample (totalWeight > 0)\n *\n * @param state - Current estimator state\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns True if we've sampled enough bytes to trust the estimate\n *\n * @example\n * if (hasGoodEstimate(state)) {\n *   const estimate = getBandwidthEstimate(state, 5_000_000);\n * }\n */\nexport function hasGoodEstimate(state: BandwidthState, config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG): boolean {\n  // Need enough total bytes AND at least one valid EWMA sample\n  return state.bytesSampled >= config.minTotalBytes && state.fastTotalWeight > 0 && state.slowTotalWeight > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;CACd;;;;;;;;;;;;;;;;;;;;;AAsBD,SAAgB,gBACd,OACA,YACA,UACA,SAA0B,0BACV;CAEhB,MAAM,sBAAsB,MAAM,eAAe;AAKjD,KAAI,WAAW,OAAO,SACpB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;AAMxD,KAAI,aAAa,OAAO,YACtB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;CAKxD,MAAM,YAAa,MAAO,WAAY;CAItC,MAAM,SAAS,aAAa;AAE5B,QAAO;EACL,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc;EACf;;;;;;;;;;;;;;;;;;;;AAqBH,SAAgB,qBACd,OACA,iBACA,SAA0B,0BAClB;AAER,KAAI,MAAM,eAAe,OAAO,cAC9B,QAAO;CAIT,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;CAEpG,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;AAIpG,QAAO,KAAK,IAAI,cAAc,aAAa"}

package/dist/dev/core/abr/ewma.js

@@ -0,0 +1,71 @@
+//#region src/core/abr/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, calculateEwma };
+//# sourceMappingURL=ewma.js.map

package/dist/dev/core/abr/ewma.js.map

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

package/dist/dev/core/abr/quality-selection.js

@@ -0,0 +1,53 @@
+//#region src/core/abr/quality-selection.ts
+/**
+* Default quality selection configuration.
+* Values match Shaka Player upgrade threshold (0.85 = 15% headroom).
+*/
+const DEFAULT_QUALITY_CONFIG = { safetyMargin: .85 };
+/**
+* Select the best video track based on current bandwidth estimate.
+*
+* Selects the highest quality track where bandwidth is sufficient with safety margin:
+* - currentBandwidth >= track.bandwidth / safetyMargin
+* - Default safetyMargin 0.85 means track uses ≤85% of bandwidth (15% headroom)
+* - At same bandwidth, prefers higher resolution
+*
+* @param tracks - Available video tracks (can be unsorted)
+* @param currentBandwidth - Current bandwidth estimate in bits per second
+* @param config - Optional quality selection configuration
+* @returns Selected track, or undefined if no tracks available
+*
+* @example
+* const tracks = [
+*   { id: '360p', bandwidth: 500_000, ... },
+*   { id: '720p', bandwidth: 2_000_000, ... },
+*   { id: '1080p', bandwidth: 4_000_000, ... },
+* ];
+*
+* // With 2.5 Mbps, selects 720p (1080p needs 4M/0.85 = 4.7 Mbps)
+* const selected = selectQuality(tracks, 2_500_000);
+*/
+function selectQuality(tracks, currentBandwidth, config = DEFAULT_QUALITY_CONFIG) {
+	if (tracks.length === 0) return;
+	const sortedTracks = tracks.slice().sort((a, b) => a.bandwidth - b.bandwidth);
+	let chosen;
+	for (const track of sortedTracks) if (currentBandwidth >= track.bandwidth / config.safetyMargin) {
+		if (!chosen || track.bandwidth > chosen.bandwidth || track.bandwidth === chosen.bandwidth && hasHigherResolution(track, chosen)) chosen = track;
+	}
+	return chosen ?? sortedTracks[0];
+}
+/**
+* Check if track A has higher resolution than track B.
+* Compares by total pixel count (width × height).
+*
+* @param trackA - First track to compare
+* @param trackB - Second track to compare
+* @returns True if trackA has more pixels than trackB
+*/
+function hasHigherResolution(trackA, trackB) {
+	return (trackA.width ?? 0) * (trackA.height ?? 0) > (trackB.width ?? 0) * (trackB.height ?? 0);
+}
+
+//#endregion
+export { DEFAULT_QUALITY_CONFIG, selectQuality };
+//# sourceMappingURL=quality-selection.js.map

package/dist/dev/core/abr/quality-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-selection.js","names":[],"sources":["../../../../src/core/abr/quality-selection.ts"],"sourcesContent":["/**\n * Quality Selection Algorithm\n *\n * Selects optimal video track based on bandwidth estimate with safety margin.\n * Stateless selection - picks highest quality that fits bandwidth.\n *\n * Key concepts:\n * - **Safety margin** (0.85): Pick track where bandwidth >= track.bandwidth / 0.85\n * - This ensures 15% headroom to avoid buffering\n * - At same bandwidth, prefer higher resolution\n */\n\nimport type { PartiallyResolvedVideoTrack } from '../types';\n\n/**\n * Quality selection configuration.\n */\nexport interface QualityConfig {\n  /**\n   * Safety margin (0-1).\n   * To select a track, need: currentBandwidth >= track.bandwidth / safetyMargin.\n   * Default 0.85 means track must use ≤85% of available bandwidth (15% headroom).\n   */\n  safetyMargin: number;\n}\n\n/**\n * Default quality selection configuration.\n * Values match Shaka Player upgrade threshold (0.85 = 15% headroom).\n */\nexport const DEFAULT_QUALITY_CONFIG: QualityConfig = {\n  safetyMargin: 0.85,\n};\n\n/**\n * Select the best video track based on current bandwidth estimate.\n *\n * Selects the highest quality track where bandwidth is sufficient with safety margin:\n * - currentBandwidth >= track.bandwidth / safetyMargin\n * - Default safetyMargin 0.85 means track uses ≤85% of bandwidth (15% headroom)\n * - At same bandwidth, prefers higher resolution\n *\n * @param tracks - Available video tracks (can be unsorted)\n * @param currentBandwidth - Current bandwidth estimate in bits per second\n * @param config - Optional quality selection configuration\n * @returns Selected track, or undefined if no tracks available\n *\n * @example\n * const tracks = [\n *   { id: '360p', bandwidth: 500_000, ... },\n *   { id: '720p', bandwidth: 2_000_000, ... },\n *   { id: '1080p', bandwidth: 4_000_000, ... },\n * ];\n *\n * // With 2.5 Mbps, selects 720p (1080p needs 4M/0.85 = 4.7 Mbps)\n * const selected = selectQuality(tracks, 2_500_000);\n */\nexport function selectQuality(\n  tracks: PartiallyResolvedVideoTrack[],\n  currentBandwidth: number,\n  config: QualityConfig = DEFAULT_QUALITY_CONFIG\n): PartiallyResolvedVideoTrack | undefined {\n  if (tracks.length === 0) {\n    return undefined;\n  }\n\n  // Sort tracks by bandwidth (lowest first)\n  const sortedTracks = tracks.slice().sort((a, b) => a.bandwidth - b.bandwidth);\n\n  // Start with no selection\n  let chosen: PartiallyResolvedVideoTrack | undefined;\n\n  for (const track of sortedTracks) {\n    // Check if we have enough bandwidth for this track with safety margin\n    // Required bandwidth = track.bandwidth / safetyMargin\n    const requiredBandwidth = track.bandwidth / config.safetyMargin;\n\n    if (currentBandwidth >= requiredBandwidth) {\n      // We can support this track - prefer it if better than current choice\n      if (\n        !chosen ||\n        track.bandwidth > chosen.bandwidth ||\n        (track.bandwidth === chosen.bandwidth && hasHigherResolution(track, chosen))\n      ) {\n        chosen = track;\n      }\n    }\n  }\n\n  // If no track fits with safety margin, fall back to lowest quality\n  return chosen ?? sortedTracks[0];\n}\n\n/**\n * Check if track A has higher resolution than track B.\n * Compares by total pixel count (width × height).\n *\n * @param trackA - First track to compare\n * @param trackB - Second track to compare\n * @returns True if trackA has more pixels than trackB\n */\nfunction hasHigherResolution(trackA: PartiallyResolvedVideoTrack, trackB: PartiallyResolvedVideoTrack): boolean {\n  const pixelsA = (trackA.width ?? 0) * (trackA.height ?? 0);\n  const pixelsB = (trackB.width ?? 0) * (trackB.height ?? 0);\n  return pixelsA > pixelsB;\n}\n"],"mappings":";;;;;AA8BA,MAAa,yBAAwC,EACnD,cAAc,KACf;;;;;;;;;;;;;;;;;;;;;;;;AAyBD,SAAgB,cACd,QACA,kBACA,SAAwB,wBACiB;AACzC,KAAI,OAAO,WAAW,EACpB;CAIF,MAAM,eAAe,OAAO,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,YAAY,EAAE,UAAU;CAG7E,IAAI;AAEJ,MAAK,MAAM,SAAS,aAKlB,KAAI,oBAFsB,MAAM,YAAY,OAAO,cAIjD;MACE,CAAC,UACD,MAAM,YAAY,OAAO,aACxB,MAAM,cAAc,OAAO,aAAa,oBAAoB,OAAO,OAAO,CAE3E,UAAS;;AAMf,QAAO,UAAU,aAAa;;;;;;;;;;AAWhC,SAAS,oBAAoB,QAAqC,QAA8C;AAG9G,SAFiB,OAAO,SAAS,MAAM,OAAO,UAAU,MACvC,OAAO,SAAS,MAAM,OAAO,UAAU"}