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

package/dist/dev/playback/engines/background-video/adapter.js

@@ -0,0 +1,158 @@
+import { maxResolutionToPixelArea, pickTrackUnderPixelArea } from "../../../media/primitives/select-tracks.js";
+import { createBackgroundVideoEngine } from "./engine.js";
+//#region src/playback/engines/background-video/adapter.ts
+const backgroundVideoMediaDefaultProps = {
+	src: "",
+	preload: "auto",
+	loop: true,
+	muted: true,
+	autoplay: true,
+	maxResolution: void 0
+};
+/**
+* Mixin that adds the background-video SPF playback engine to any
+* base class.
+*
+* Implements the WHATWG HTML media element contract (`src`, `preload`,
+* `loop`, `muted`, `autoplay`, `play()`) so it can be dropped in anywhere a
+* media element API is expected. Compared to `SimpleHlsMediaMixin`, this
+* variant:
+*
+* - exposes `loop`, `muted`, and `autoplay` as adapter-owned native
+*   passthroughs, all defaulting to `true` — the use case is silent
+*   autoplay-looping video, so muted + autoplay satisfy browser autoplay
+*   policies and loop is the defining behavior;
+* - drives the underlying engine with the background-video
+*   composition (single-rendition, video-only, autoplay-from-construction).
+*
+* A new engine is created on every src assignment — this fully tears down
+* all state, SourceBuffers, and in-flight requests from the previous
+* source before the next one begins. The media element reference is
+* preserved across src changes and re-applied to the new engine
+* automatically.
+*
+* @example
+* class BackgroundVideoMedia extends BackgroundVideoMediaMixin(HTMLVideoElementHost) {}
+*
+* const media = new BackgroundVideoMedia();
+* media.attach(document.querySelector('video'));
+* media.src = 'https://stream.mux.com/abc123.m3u8';
+* media.play();
+*/
+function BackgroundVideoMediaMixin(BaseClass) {
+	class BackgroundVideoMediaImpl extends BaseClass {
+		#engine;
+		#config;
+		#signals;
+		#preload = backgroundVideoMediaDefaultProps.preload;
+		#loop = backgroundVideoMediaDefaultProps.loop;
+		#muted = backgroundVideoMediaDefaultProps.muted;
+		#autoplay = backgroundVideoMediaDefaultProps.autoplay;
+		#maxResolution;
+		/** Pending loadstart listener from a deferred play() retry, if any. */
+		#loadstartListener = null;
+		constructor(...args) {
+			super(...args);
+			const { config } = args?.[0] ?? {};
+			this.#config = config;
+			this.#maxResolution = config?.maxResolution;
+			this.#engine = this.#createEngine();
+		}
+		get engine() {
+			return this.#engine;
+		}
+		attach(mediaElement) {
+			super.attach?.(mediaElement);
+			mediaElement.loop = this.#loop;
+			mediaElement.muted = this.#muted;
+			mediaElement.autoplay = this.#autoplay;
+			this.#signals.context.mediaElement.set(mediaElement);
+		}
+		detach() {
+			this.#cancelPendingPlay();
+			this.#signals.context.mediaElement.set(void 0);
+			super.detach?.();
+		}
+		destroy() {
+			this.#cancelPendingPlay();
+			this.#engine.destroy();
+		}
+		get preload() {
+			return this.#preload;
+		}
+		set preload(_value) {}
+		get loop() {
+			return this.#loop;
+		}
+		set loop(_value) {}
+		get muted() {
+			return this.#muted;
+		}
+		set muted(_value) {}
+		get autoplay() {
+			return this.#autoplay;
+		}
+		set autoplay(_value) {}
+		get maxResolution() {
+			return this.#maxResolution;
+		}
+		/**
+		* Set the cap. Accepts `"720p"` / `"1080p"` etc., a bare number
+		* (interpreted as pixel area), or `undefined` to clear. Unrecognized
+		* values are treated as no cap.
+		*/
+		set maxResolution(value) {
+			if (value === this.#maxResolution) return;
+			this.#maxResolution = value;
+		}
+		get src() {
+			return this.#signals.state.presentation.get()?.url ?? "";
+		}
+		set src(value) {
+			this.#cancelPendingPlay();
+			if (value) this.#signals.state.presentation.set({ url: value });
+			else this.#signals.state.presentation.set(void 0);
+		}
+		async play() {
+			const mediaElement = this.#signals.context.mediaElement.get();
+			if (!mediaElement) return Promise.reject(/* @__PURE__ */ new Error("BackgroundVideoMediaElement: no media element attached"));
+			try {
+				return await mediaElement.play();
+			} catch (err) {
+				if (this.src) return new Promise((resolve, reject) => {
+					const listener = () => {
+						this.#loadstartListener = null;
+						mediaElement.play().then(resolve, reject);
+					};
+					this.#loadstartListener = listener;
+					mediaElement.addEventListener("loadstart", listener, { once: true });
+				});
+				throw err;
+			}
+		}
+		#createEngine() {
+			const adapterPicker = (presentation) => {
+				return pickTrackUnderPixelArea((presentation.selectionSets?.find((s) => s.type === "video"))?.switchingSets[0]?.tracks ?? [], maxResolutionToPixelArea(this.#maxResolution))?.id;
+			};
+			return createBackgroundVideoEngine({
+				picker: adapterPicker,
+				...this.#config,
+				onSignalsReady: (signals) => {
+					this.#signals = signals;
+				}
+			});
+		}
+		#cancelPendingPlay() {
+			if (!this.#loadstartListener) return;
+			this.#signals.context.mediaElement.get()?.removeEventListener("loadstart", this.#loadstartListener);
+			this.#loadstartListener = null;
+		}
+	}
+	return BackgroundVideoMediaImpl;
+}
+/** Standalone SPF background-video adapter with no base class. */
+var BackgroundVideoMediaElement = class extends BackgroundVideoMediaMixin(class {}) {};
+//#endregion
+export { BackgroundVideoMediaElement, BackgroundVideoMediaMixin, backgroundVideoMediaDefaultProps };
+
+//# sourceMappingURL=adapter.js.map

package/dist/dev/playback/engines/background-video/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","names":["#config","#maxResolution","#engine","#createEngine","#loop","#muted","#autoplay","#signals","#cancelPendingPlay","#preload","#loadstartListener"],"sources":["../../../../../src/playback/engines/background-video/adapter.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport type { Composition } from '../../../core/composition/create-composition';\nimport {\n  maxResolutionToPixelArea,\n  pickTrackUnderPixelArea,\n  type TrackPicker,\n} from '../../../media/primitives/select-tracks';\nimport type { VideoSelectionSet } from '../../../media/types';\nimport {\n  type BackgroundVideoEngineConfig,\n  type BackgroundVideoEngineContext,\n  type BackgroundVideoEngineSignals,\n  type BackgroundVideoEngineState,\n  createBackgroundVideoEngine,\n} from './engine';\n\nexport interface BackgroundVideoMediaProps {\n  src: string;\n  preload: '' | 'none' | 'metadata' | 'auto';\n  loop: boolean;\n  muted: boolean;\n  autoplay: boolean;\n  maxResolution: string | number | undefined;\n}\n\nexport const backgroundVideoMediaDefaultProps: BackgroundVideoMediaProps = {\n  src: '',\n  preload: 'auto',\n  loop: true,\n  muted: true,\n  autoplay: true,\n  maxResolution: undefined,\n};\n\nexport interface BackgroundVideoMediaAPI extends BackgroundVideoMediaProps {\n  readonly engine: Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Mixin that adds the background-video SPF playback engine to any\n * base class.\n *\n * Implements the WHATWG HTML media element contract (`src`, `preload`,\n * `loop`, `muted`, `autoplay`, `play()`) so it can be dropped in anywhere a\n * media element API is expected. Compared to `SimpleHlsMediaMixin`, this\n * variant:\n *\n * - exposes `loop`, `muted`, and `autoplay` as adapter-owned native\n *   passthroughs, all defaulting to `true` — the use case is silent\n *   autoplay-looping video, so muted + autoplay satisfy browser autoplay\n *   policies and loop is the defining behavior;\n * - drives the underlying engine with the background-video\n *   composition (single-rendition, video-only, autoplay-from-construction).\n *\n * A new engine is created on every src assignment — this fully tears down\n * all state, SourceBuffers, and in-flight requests from the previous\n * source before the next one begins. The media element reference is\n * preserved across src changes and re-applied to the new engine\n * automatically.\n *\n * @example\n * class BackgroundVideoMedia extends BackgroundVideoMediaMixin(HTMLVideoElementHost) {}\n *\n * const media = new BackgroundVideoMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/abc123.m3u8';\n * media.play();\n */\nexport function BackgroundVideoMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class BackgroundVideoMediaImpl extends BaseClass {\n    #engine: Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;\n    #config: BackgroundVideoEngineConfig;\n    #signals!: BackgroundVideoEngineSignals;\n    #preload: '' | 'none' | 'metadata' | 'auto' = backgroundVideoMediaDefaultProps.preload;\n    #loop: boolean = backgroundVideoMediaDefaultProps.loop;\n    #muted: boolean = backgroundVideoMediaDefaultProps.muted;\n    #autoplay: boolean = backgroundVideoMediaDefaultProps.autoplay;\n    #maxResolution: string | number | undefined;\n\n    /** Pending loadstart listener from a deferred play() retry, if any. */\n    #loadstartListener: (() => void) | null = null;\n\n    constructor(...args: any[]) {\n      super(...args);\n\n      const { config } = args?.[0] ?? {};\n      this.#config = config;\n\n      this.#maxResolution = config?.maxResolution;\n      this.#engine = this.#createEngine();\n    }\n\n    get engine(): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n      return this.#engine;\n    }\n\n    // -------------------------------------------------------------------------\n    // Media element lifecycle\n    // -------------------------------------------------------------------------\n\n    attach(mediaElement: HTMLMediaElement): void {\n      super.attach?.(mediaElement);\n      // Apply adapter-owned native props before the engine takes over —\n      // the underlying element needs `loop` / `muted` / `autoplay` set for\n      // the use case's autoplay-looping semantics.\n      mediaElement.loop = this.#loop;\n      mediaElement.muted = this.#muted;\n      mediaElement.autoplay = this.#autoplay;\n\n      this.#signals.context.mediaElement.set(mediaElement);\n    }\n\n    detach(): void {\n      this.#cancelPendingPlay();\n      this.#signals.context.mediaElement.set(undefined);\n      super.detach?.();\n    }\n\n    destroy(): void {\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n    }\n\n    // -------------------------------------------------------------------------\n    // preload — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // -------------------------------------------------------------------------\n\n    get preload(): '' | 'none' | 'metadata' | 'auto' {\n      return this.#preload;\n    }\n\n    set preload(_value: '' | 'none' | 'metadata' | 'auto') {\n      // Noop for this phase\n    }\n\n    // -------------------------------------------------------------------------\n    // loop / muted / autoplay — adapter-owned IDL attributes mirrored onto\n    // the attached media element. The engine itself has no opinion on any\n    // of them.\n    // -------------------------------------------------------------------------\n\n    get loop(): boolean {\n      return this.#loop;\n    }\n\n    set loop(_value: boolean) {\n      // Noop for this phase\n    }\n\n    get muted(): boolean {\n      return this.#muted;\n    }\n\n    set muted(_value: boolean) {\n      // Noop for this phase\n    }\n\n    get autoplay(): boolean {\n      return this.#autoplay;\n    }\n\n    set autoplay(_value: boolean) {\n      // Noop for this phase\n    }\n\n    // -------------------------------------------------------------------------\n    // maxResolution — adapter-owned cap on the picked rendition. The engine's\n    // closure picker (see `#createEngine`) reads this field at pick time, so\n    // setter writes take effect on the next `presentation-resolved` transition\n    // without an engine rebuild.\n    // -------------------------------------------------------------------------\n\n    get maxResolution(): string | number | undefined {\n      return this.#maxResolution;\n    }\n\n    /**\n     * Set the cap. Accepts `\"720p\"` / `\"1080p\"` etc., a bare number\n     * (interpreted as pixel area), or `undefined` to clear. Unrecognized\n     * values are treated as no cap.\n     */\n    set maxResolution(value: string | number | undefined) {\n      if (value === this.#maxResolution) return;\n      this.#maxResolution = value;\n    }\n\n    // -------------------------------------------------------------------------\n    // src — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // Each assignment destroys the current engine and starts a fresh one,\n    // matching the browser's load algorithm reset on src change.\n    // -------------------------------------------------------------------------\n\n    get src(): string {\n      return this.#signals.state.presentation.get()?.url ?? '';\n    }\n\n    set src(value: string) {\n      this.#cancelPendingPlay();\n\n      if (value) {\n        this.#signals.state.presentation.set({ url: value });\n      } else {\n        this.#signals.state.presentation.set(undefined);\n      }\n    }\n\n    // -------------------------------------------------------------------------\n    // play() — WHATWG §4.8.11.8\n    // Delegates to the attached media element's native play().\n    // -------------------------------------------------------------------------\n\n    async play(): Promise<void> {\n      const mediaElement = this.#signals.context.mediaElement.get();\n      if (!mediaElement) {\n        return Promise.reject(new Error('BackgroundVideoMediaElement: no media element attached'));\n      }\n\n      try {\n        return await mediaElement.play();\n      } catch (err) {\n        // If we have a pending HLS source, the rejection may be because MSE\n        // hasn't attached a blob URL yet. Wait for loadstart (src assigned\n        // by MSE setup) and retry once.\n        if (this.src) {\n          return new Promise<void>((resolve, reject) => {\n            const listener = () => {\n              this.#loadstartListener = null;\n              mediaElement.play().then(resolve, reject);\n            };\n            this.#loadstartListener = listener;\n            mediaElement.addEventListener('loadstart', listener, { once: true });\n          });\n        }\n        throw err;\n      }\n    }\n\n    // -------------------------------------------------------------------------\n    // Private\n    // -------------------------------------------------------------------------\n\n    #createEngine(): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n      const adapterPicker: TrackPicker = (presentation) => {\n        const videoSet = presentation.selectionSets?.find((s) => s.type === 'video') as VideoSelectionSet | undefined;\n        const tracks = videoSet?.switchingSets[0]?.tracks ?? [];\n        return pickTrackUnderPixelArea(tracks, maxResolutionToPixelArea(this.#maxResolution))?.id;\n      };\n\n      return createBackgroundVideoEngine({\n        picker: adapterPicker,\n        ...this.#config,\n        onSignalsReady: (signals) => {\n          this.#signals = signals;\n        },\n      });\n    }\n\n    #cancelPendingPlay(): void {\n      if (!this.#loadstartListener) return;\n      const mediaElement = this.#signals.context.mediaElement.get();\n      mediaElement?.removeEventListener('loadstart', this.#loadstartListener);\n      this.#loadstartListener = null;\n    }\n  }\n\n  return BackgroundVideoMediaImpl as unknown as MixinReturn<Base, BackgroundVideoMediaAPI>;\n}\n\n/** Standalone SPF background-video adapter with no base class. */\nexport class BackgroundVideoMediaElement extends BackgroundVideoMediaMixin(class {}) {}\n"],"mappings":"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"}

package/dist/dev/playback/engines/background-video/engine.d.ts

@@ -0,0 +1,106 @@
+import { MaybeResolvedPresentation } from "../../../media/types/index.js";
+import { Composition, ContextSignals, StateSignals } from "../../../core/composition/create-composition.js";
+import { ShareSignalsConfig } from "../../../core/composition/share-signals.js";
+import { SourceBufferActor } from "../../actors/dom/source-buffer.js";
+import { SegmentLoaderActor } from "../../actors/dom/segment-loader.js";
+import { TrackPicker } from "../../../media/primitives/select-tracks.js";
+import { ParsePresentation } from "../../behaviors/resolve-presentation.js";
+import { SelectVideoTrackConfig } from "../../behaviors/select-tracks.js";
+//#region src/playback/engines/background-video/engine.d.ts
+/**
+ * State shape for the background-video playback engine.
+ *
+ * Narrower than `SimpleHlsEngineState`: audio/text track slots are absent
+ * because their selection/resolution behaviors are subtracted. `bandwidthState`
+ * is present because `setupVideoBufferActors` declares it and `loadVideoSegments`
+ * samples into it (wasted work in this variant — a Phase 3 alt-impl will skip
+ * sampling).
+ */
+interface BackgroundVideoEngineState {
+  /**
+   * The presentation being played. A caller writes `{ url }`;
+   * `resolvePresentation` parses the manifest and populates the rest.
+   */
+  presentation?: MaybeResolvedPresentation;
+  preload?: 'auto' | 'metadata' | 'none';
+  selectedVideoTrackId?: string;
+  loadActivated?: boolean;
+}
+/**
+ * Context shape for the background-video engine.
+ */
+interface BackgroundVideoEngineContext {
+  mediaElement?: HTMLMediaElement | undefined;
+  mediaSource?: MediaSource;
+  videoBufferActor?: SourceBufferActor;
+  videoSegmentLoaderActor?: SegmentLoaderActor;
+}
+/**
+ * The composition signal refs handed to `onSignalsReady` callers — the
+ * canonical way to drive the engine externally (writes) or observe its
+ * state (reads) without touching `composition.state` / `composition.context`
+ * directly.
+ */
+type BackgroundVideoEngineSignals = {
+  state: StateSignals<BackgroundVideoEngineState>;
+  context: ContextSignals<BackgroundVideoEngineContext>;
+};
+/**
+ * Configuration for the background-video engine.
+ *
+ * Each option is consumed by the appropriate behavior — the engine itself
+ * has no config beyond what its behaviors read. Compared to
+ * `SimpleHlsEngineConfig`, audio/text/ABR/bandwidth/quality knobs are
+ * dropped: the variant subtracts the behaviors that read them.
+ */
+interface BackgroundVideoEngineConfig extends ShareSignalsConfig<BackgroundVideoEngineState, BackgroundVideoEngineContext> {
+  /**
+   * Track picker handed to `selectVideoTrack`. Default:
+   * `pickHighestResolutionVideoTrack` — picks the highest-resolution variant on
+   * presentation resolve and pins it for the session. Override for
+   * mobile-aware or content-aware caps.
+   *
+   * Adapters (e.g. `BackgroundVideoMediaElement`) install their own
+   * picker; this default applies when the engine is constructed directly.
+   */
+  picker?: TrackPicker<SelectVideoTrackConfig>;
+  /**
+   * Manifest parser handed to `resolvePresentation`. Defaults to the HLS
+   * multivariant-playlist parser.
+   */
+  parsePresentation?: ParsePresentation;
+}
+/**
+ * Create a background-video playback engine.
+ *
+ * Subtractive composition over the HLS engine baseline:
+ * audio-side, text-side, ABR-driven, preload-monitoring, and play/seek
+ * load-trigger behaviors are removed. `selectVideoTrack` (with a
+ * max-resolution picker by default) replaces `switchVideoQuality`, pinning
+ * a single rendition for the session. The initial state seeds
+ * `loadActivated: true` so the composition behaves as if preload has
+ * already been activated — appropriate for ambient / hero / GIF-replacement
+ * surfaces that should start loading the moment a src is set.
+ *
+ * Native `loop` / `muted` / `autoplay` are adapter concerns and live on
+ * `BackgroundVideoMediaElement` rather than the engine.
+ *
+ * @example
+ * ```ts
+ * let signals: BackgroundVideoEngineSignals;
+ * const engine = createBackgroundVideoEngine({
+ *   onSignalsReady: (refs) => {
+ *     signals = refs;
+ *   },
+ * });
+ *
+ * signals.context.mediaElement.set(videoEl);
+ * signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });
+ *
+ * await engine.destroy();
+ * ```
+ */
+declare function createBackgroundVideoEngine(config?: BackgroundVideoEngineConfig): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext>;
+//#endregion
+export { BackgroundVideoEngineConfig, BackgroundVideoEngineContext, BackgroundVideoEngineSignals, BackgroundVideoEngineState, createBackgroundVideoEngine };
+//# sourceMappingURL=engine.d.ts.map

package/dist/dev/playback/engines/background-video/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","names":[],"sources":["../../../../../src/playback/engines/background-video/engine.ts"],"mappings":";;;;;;;;;;;;;;;;;;UAqCiB;;;;;EAKf,eAAe;EACf;EACA;EACA;;;;;UAMe;EACf,eAAe;EACf,cAAc;EACd,mBAAmB;EACnB,0BAA0B;;;;;;;;KAShB;EACV,OAAO,aAAa;EACpB,SAAS,eAAe;;;;;;;;;;UAWT,oCACP,mBAAmB,4BAA4B;;;;;;;;;;EAUvD,SAAS,YAAY;;;;;EAKrB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuCN,4BACd,SAAQ,8BACP,YAAY,4BAA4B"}

package/dist/dev/playback/engines/background-video/engine.js

@@ -0,0 +1,75 @@
+import { createComposition } from "../../../core/composition/create-composition.js";
+import { makeShareSignals } from "../../../core/composition/share-signals.js";
+import { loadVideoSegments } from "../../behaviors/dom/load-segments.js";
+import { trackCurrentTime } from "../../behaviors/dom/track-current-time.js";
+import { parseMultivariantPlaylist } from "../../../media/hls/parse-multivariant.js";
+import { getResolvedSelectedTrackDuration } from "../../../media/utils/track-selection.js";
+import { calculatePresentationDuration } from "../../behaviors/calculate-presentation-duration.js";
+import { endOfStream } from "../../behaviors/dom/end-of-stream.js";
+import { setupVideoBufferActors } from "../../behaviors/dom/setup-buffer-actors.js";
+import { setupMediaSource } from "../../behaviors/dom/setup-mediasource.js";
+import { updateMediaSourceDuration } from "../../behaviors/dom/update-mediasource-duration.js";
+import { resolvePresentation } from "../../behaviors/resolve-presentation.js";
+import { resolveVideoTrack } from "../../behaviors/resolve-track.js";
+import { pickHighestResolutionVideoTrack } from "../../../media/primitives/select-tracks.js";
+import { selectVideoTrack } from "../../behaviors/select-tracks.js";
+//#region src/playback/engines/background-video/engine.ts
+const shareSignals = makeShareSignals();
+/**
+* Create a background-video playback engine.
+*
+* Subtractive composition over the HLS engine baseline:
+* audio-side, text-side, ABR-driven, preload-monitoring, and play/seek
+* load-trigger behaviors are removed. `selectVideoTrack` (with a
+* max-resolution picker by default) replaces `switchVideoQuality`, pinning
+* a single rendition for the session. The initial state seeds
+* `loadActivated: true` so the composition behaves as if preload has
+* already been activated — appropriate for ambient / hero / GIF-replacement
+* surfaces that should start loading the moment a src is set.
+*
+* Native `loop` / `muted` / `autoplay` are adapter concerns and live on
+* `BackgroundVideoMediaElement` rather than the engine.
+*
+* @example
+* ```ts
+* let signals: BackgroundVideoEngineSignals;
+* const engine = createBackgroundVideoEngine({
+*   onSignalsReady: (refs) => {
+*     signals = refs;
+*   },
+* });
+*
+* signals.context.mediaElement.set(videoEl);
+* signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });
+*
+* await engine.destroy();
+* ```
+*/
+function createBackgroundVideoEngine(config = {}) {
+	const finalConfig = {
+		...config,
+		picker: config.picker ?? pickHighestResolutionVideoTrack,
+		parsePresentation: config.parsePresentation ?? parseMultivariantPlaylist,
+		resolveDuration: getResolvedSelectedTrackDuration
+	};
+	return createComposition([
+		resolvePresentation,
+		calculatePresentationDuration,
+		selectVideoTrack,
+		resolveVideoTrack,
+		loadVideoSegments,
+		setupMediaSource,
+		updateMediaSourceDuration,
+		setupVideoBufferActors,
+		trackCurrentTime,
+		endOfStream,
+		shareSignals
+	], {
+		config: finalConfig,
+		initialState: { loadActivated: true }
+	});
+}
+//#endregion
+export { createBackgroundVideoEngine };
+
+//# sourceMappingURL=engine.js.map

package/dist/dev/playback/engines/background-video/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","names":[],"sources":["../../../../../src/playback/engines/background-video/engine.ts"],"sourcesContent":["import {\n  type Composition,\n  type ContextSignals,\n  createComposition,\n  type StateSignals,\n} from '../../../core/composition/create-composition';\nimport { makeShareSignals, type ShareSignalsConfig } from '../../../core/composition/share-signals';\nimport { parseMultivariantPlaylist } from '../../../media/hls/parse-multivariant';\nimport { pickHighestResolutionVideoTrack, type TrackPicker } from '../../../media/primitives/select-tracks';\nimport type { MaybeResolvedPresentation } from '../../../media/types';\nimport { getResolvedSelectedTrackDuration } from '../../../media/utils/track-selection';\nimport type { SegmentLoaderActor } from '../../actors/dom/segment-loader';\nimport type { SourceBufferActor } from '../../actors/dom/source-buffer';\nimport { calculatePresentationDuration } from '../../behaviors/calculate-presentation-duration';\nimport { endOfStream } from '../../behaviors/dom/end-of-stream';\nimport { loadVideoSegments } from '../../behaviors/dom/load-segments';\nimport { setupVideoBufferActors } from '../../behaviors/dom/setup-buffer-actors';\nimport { setupMediaSource } from '../../behaviors/dom/setup-mediasource';\nimport { trackCurrentTime } from '../../behaviors/dom/track-current-time';\nimport { updateMediaSourceDuration } from '../../behaviors/dom/update-mediasource-duration';\nimport { type ParsePresentation, resolvePresentation } from '../../behaviors/resolve-presentation';\nimport { resolveVideoTrack } from '../../behaviors/resolve-track';\nimport { type SelectVideoTrackConfig, selectVideoTrack } from '../../behaviors/select-tracks';\n\n// ============================================================================\n// Background-video engine state & context\n// ============================================================================\n\n/**\n * State shape for the background-video playback engine.\n *\n * Narrower than `SimpleHlsEngineState`: audio/text track slots are absent\n * because their selection/resolution behaviors are subtracted. `bandwidthState`\n * is present because `setupVideoBufferActors` declares it and `loadVideoSegments`\n * samples into it (wasted work in this variant — a Phase 3 alt-impl will skip\n * sampling).\n */\nexport interface BackgroundVideoEngineState {\n  /**\n   * The presentation being played. A caller writes `{ url }`;\n   * `resolvePresentation` parses the manifest and populates the rest.\n   */\n  presentation?: MaybeResolvedPresentation;\n  preload?: 'auto' | 'metadata' | 'none';\n  selectedVideoTrackId?: string;\n  loadActivated?: boolean;\n}\n\n/**\n * Context shape for the background-video engine.\n */\nexport interface BackgroundVideoEngineContext {\n  mediaElement?: HTMLMediaElement | undefined;\n  mediaSource?: MediaSource;\n  videoBufferActor?: SourceBufferActor;\n  videoSegmentLoaderActor?: SegmentLoaderActor;\n}\n\n/**\n * The composition signal refs handed to `onSignalsReady` callers — the\n * canonical way to drive the engine externally (writes) or observe its\n * state (reads) without touching `composition.state` / `composition.context`\n * directly.\n */\nexport type BackgroundVideoEngineSignals = {\n  state: StateSignals<BackgroundVideoEngineState>;\n  context: ContextSignals<BackgroundVideoEngineContext>;\n};\n\n/**\n * Configuration for the background-video engine.\n *\n * Each option is consumed by the appropriate behavior — the engine itself\n * has no config beyond what its behaviors read. Compared to\n * `SimpleHlsEngineConfig`, audio/text/ABR/bandwidth/quality knobs are\n * dropped: the variant subtracts the behaviors that read them.\n */\nexport interface BackgroundVideoEngineConfig\n  extends ShareSignalsConfig<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n  /**\n   * Track picker handed to `selectVideoTrack`. Default:\n   * `pickHighestResolutionVideoTrack` — picks the highest-resolution variant on\n   * presentation resolve and pins it for the session. Override for\n   * mobile-aware or content-aware caps.\n   *\n   * Adapters (e.g. `BackgroundVideoMediaElement`) install their own\n   * picker; this default applies when the engine is constructed directly.\n   */\n  picker?: TrackPicker<SelectVideoTrackConfig>;\n  /**\n   * Manifest parser handed to `resolvePresentation`. Defaults to the HLS\n   * multivariant-playlist parser.\n   */\n  parsePresentation?: ParsePresentation;\n}\n\n// ============================================================================\n// Background-video playback engine\n// ============================================================================\n\nconst shareSignals = makeShareSignals<BackgroundVideoEngineState, BackgroundVideoEngineContext>();\n\n/**\n * Create a background-video playback engine.\n *\n * Subtractive composition over the HLS engine baseline:\n * audio-side, text-side, ABR-driven, preload-monitoring, and play/seek\n * load-trigger behaviors are removed. `selectVideoTrack` (with a\n * max-resolution picker by default) replaces `switchVideoQuality`, pinning\n * a single rendition for the session. The initial state seeds\n * `loadActivated: true` so the composition behaves as if preload has\n * already been activated — appropriate for ambient / hero / GIF-replacement\n * surfaces that should start loading the moment a src is set.\n *\n * Native `loop` / `muted` / `autoplay` are adapter concerns and live on\n * `BackgroundVideoMediaElement` rather than the engine.\n *\n * @example\n * ```ts\n * let signals: BackgroundVideoEngineSignals;\n * const engine = createBackgroundVideoEngine({\n *   onSignalsReady: (refs) => {\n *     signals = refs;\n *   },\n * });\n *\n * signals.context.mediaElement.set(videoEl);\n * signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });\n *\n * await engine.destroy();\n * ```\n */\nexport function createBackgroundVideoEngine(\n  config: BackgroundVideoEngineConfig = {}\n): Composition<BackgroundVideoEngineState, BackgroundVideoEngineContext> {\n  const finalConfig = {\n    ...config,\n    picker: config.picker ?? pickHighestResolutionVideoTrack,\n    parsePresentation: config.parsePresentation ?? parseMultivariantPlaylist,\n    resolveDuration: getResolvedSelectedTrackDuration,\n  };\n\n  return createComposition(\n    [\n      resolvePresentation,\n      // Presentation duration\n      calculatePresentationDuration,\n\n      // Track selection - pinned single-rendition pick on presentation resolve.\n      selectVideoTrack,\n      // Resolve selected video track (fetch its media playlist)\n      resolveVideoTrack,\n      // Segment loading — video-only.\n      loadVideoSegments,\n\n      // MSE setup — video-only.\n      setupMediaSource,\n      updateMediaSourceDuration,\n      setupVideoBufferActors,\n\n      // Playback tracking\n      trackCurrentTime,\n\n      // End of stream coordination\n      endOfStream,\n\n      // Behavior whose sole purpose is to expose signal refs via a callback\n      // (e.g. to an adapter). Listed last so initial signal setup has run\n      // before the callback fires.\n      shareSignals,\n    ],\n    {\n      config: finalConfig,\n      initialState: {\n        // Note: Set to true until we add preload configuration\n        loadActivated: true,\n      },\n    }\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoGA,MAAM,eAAe,iBAA2E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgChG,SAAgB,4BACd,SAAsC,CAAC,GACgC;CACvE,MAAM,cAAc;EAClB,GAAG;EACH,QAAQ,OAAO,UAAU;EACzB,mBAAmB,OAAO,qBAAqB;EAC/C,iBAAiB;CACnB;CAEA,OAAO,kBACL;EACE;EAEA;EAGA;EAEA;EAEA;EAGA;EACA;EACA;EAGA;EAGA;EAKA;CACF,GACA;EACE,QAAQ;EACR,cAAc,EAEZ,eAAe,KACjB;CACF,CACF;AACF"}

package/dist/dev/playback/engines/hls/adapter-audio-only.d.ts

@@ -0,0 +1,46 @@
+import { Composition } from "../../../core/composition/create-composition.js";
+import { SimpleHlsAudioOnlyEngineContext, SimpleHlsAudioOnlyEngineState } from "./engine-audio-only.js";
+import { Constructor, MixinReturn } from "@videojs/utils/types";
+//#region src/playback/engines/hls/adapter-audio-only.d.ts
+interface SimpleHlsAudioOnlyMediaProps {
+  src: string;
+  preload: '' | 'none' | 'metadata' | 'auto';
+  disableRemotePlayback: boolean;
+}
+declare const simpleHlsAudioOnlyMediaDefaultProps: SimpleHlsAudioOnlyMediaProps;
+interface SimpleHlsAudioOnlyMediaAPI extends SimpleHlsAudioOnlyMediaProps {
+  readonly engine: Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext>;
+  attach(mediaElement: HTMLMediaElement): void;
+  detach(): void;
+  destroy(): void;
+  play(): Promise<void>;
+}
+/**
+ * Mixin that adds SPF audio-only HLS playback to any base class.
+ *
+ * Parallel to `SimpleHlsMediaMixin` with one substantive difference: the
+ * underlying engine is the audio-only variant (`createHlsAudioOnlyEngine`),
+ * which omits video and text-track behaviors. The src / preload /
+ * disableRemotePlayback / play() contract per the WHATWG HTML spec is identical
+ * to the default adapter.
+ *
+ * Selecting this adapter is the variant decision: instantiating
+ * `SimpleHlsAudioOnlyMediaElement` opts the consumer into audio-only
+ * delivery even when the source is a mixed-AV HLS manifest.
+ *
+ * @example
+ * class SimpleHlsAudioOnlyMedia extends SimpleHlsAudioOnlyMediaMixin(HTMLVideoElementHost) {}
+ *
+ * const media = new SimpleHlsAudioOnlyMedia();
+ * media.attach(document.querySelector('video'));
+ * media.src = 'https://stream.mux.com/abc123.m3u8';
+ */
+declare function SimpleHlsAudioOnlyMediaMixin<Base extends Constructor<any>>(BaseClass: Base): MixinReturn<Base, SimpleHlsAudioOnlyMediaAPI>;
+declare const SimpleHlsAudioOnlyMediaElement_base: MixinReturn<{
+  new (): {};
+}, SimpleHlsAudioOnlyMediaAPI>;
+/** Standalone SPF audio-only media adapter with no base class. */
+declare class SimpleHlsAudioOnlyMediaElement extends SimpleHlsAudioOnlyMediaElement_base {}
+//#endregion
+export { SimpleHlsAudioOnlyMediaAPI, SimpleHlsAudioOnlyMediaElement, SimpleHlsAudioOnlyMediaMixin, SimpleHlsAudioOnlyMediaProps, simpleHlsAudioOnlyMediaDefaultProps };
+//# sourceMappingURL=adapter-audio-only.d.ts.map

package/dist/dev/playback/engines/hls/adapter-audio-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-audio-only.d.ts","names":[],"sources":["../../../../../src/playback/engines/hls/adapter-audio-only.ts"],"mappings":";;;;UAUiB;EACf;EACA;EACA;;cAGW,qCAAqC;UAMjC,mCAAmC;WACzC,QAAQ,YAAY,+BAA+B;EAC5D,OAAO,cAAc;EACrB;EACA;EACA,QAAQ;;;;;;;;;;;;;;;;;;;;;;iBAuBM,6BAA6B,aAAa,kBAAkB,WAAW,OAuJpC,YAAY,MAAM;;;;;cAIxD,uCAAuC"}

package/dist/dev/playback/engines/hls/adapter-audio-only.js

@@ -0,0 +1,124 @@
+import { createHlsAudioOnlyEngine } from "./engine-audio-only.js";
+//#region src/playback/engines/hls/adapter-audio-only.ts
+const simpleHlsAudioOnlyMediaDefaultProps = {
+	src: "",
+	preload: "",
+	disableRemotePlayback: false
+};
+/**
+* Mixin that adds SPF audio-only HLS playback to any base class.
+*
+* Parallel to `SimpleHlsMediaMixin` with one substantive difference: the
+* underlying engine is the audio-only variant (`createHlsAudioOnlyEngine`),
+* which omits video and text-track behaviors. The src / preload /
+* disableRemotePlayback / play() contract per the WHATWG HTML spec is identical
+* to the default adapter.
+*
+* Selecting this adapter is the variant decision: instantiating
+* `SimpleHlsAudioOnlyMediaElement` opts the consumer into audio-only
+* delivery even when the source is a mixed-AV HLS manifest.
+*
+* @example
+* class SimpleHlsAudioOnlyMedia extends SimpleHlsAudioOnlyMediaMixin(HTMLVideoElementHost) {}
+*
+* const media = new SimpleHlsAudioOnlyMedia();
+* media.attach(document.querySelector('video'));
+* media.src = 'https://stream.mux.com/abc123.m3u8';
+*/
+function SimpleHlsAudioOnlyMediaMixin(BaseClass) {
+	class SimpleHlsAudioOnlyMediaImpl extends BaseClass {
+		#engine;
+		#config;
+		#signals;
+		#preload = simpleHlsAudioOnlyMediaDefaultProps.preload;
+		#disableRemotePlayback = simpleHlsAudioOnlyMediaDefaultProps.disableRemotePlayback;
+		/** Pending loadstart listener from a deferred play() retry, if any. */
+		#loadstartListener = null;
+		constructor(...args) {
+			super(...args);
+			const { config } = args?.[0] ?? {};
+			this.#config = config;
+			this.#engine = this.#createEngine();
+		}
+		/**
+		* Underlying playback engine — the low-level SPF reactive composition that
+		* drives playback. An advanced escape hatch for direct engine access;
+		* normal playback is driven through this element's own properties and
+		* methods.
+		*/
+		get engine() {
+			return this.#engine;
+		}
+		attach(mediaElement) {
+			super.attach?.(mediaElement);
+			this.#signals.context.mediaElement.set(mediaElement);
+		}
+		detach() {
+			this.#cancelPendingPlay();
+			this.#signals.context.mediaElement.set(void 0);
+			super.detach?.();
+		}
+		destroy() {
+			this.#cancelPendingPlay();
+			this.#engine.destroy();
+		}
+		/** Preload type (`'none'` / `'metadata'` / `'auto'`). */
+		get preload() {
+			return this.#preload;
+		}
+		set preload(value) {
+			this.#preload = value;
+			if (value) this.#signals.state.preload.set(value);
+		}
+		get disableRemotePlayback() {
+			return this.#disableRemotePlayback;
+		}
+		set disableRemotePlayback(value) {
+			this.#disableRemotePlayback = value;
+			this.#signals.state.disableRemotePlayback.set(value);
+		}
+		get src() {
+			return this.#signals.state.presentation.get()?.url ?? "";
+		}
+		set src(value) {
+			this.#cancelPendingPlay();
+			this.#signals.state.presentation.set(value ? { url: value } : void 0);
+		}
+		play() {
+			const mediaElement = this.#signals.context.mediaElement.get();
+			if (!mediaElement) return Promise.reject(/* @__PURE__ */ new Error("SimpleHlsAudioOnlyMediaElement: no media element attached"));
+			this.#signals.state.loadActivated.set(true);
+			return mediaElement.play().catch((err) => {
+				if (this.src) return new Promise((resolve, reject) => {
+					const listener = () => {
+						this.#loadstartListener = null;
+						mediaElement.play().then(resolve, reject);
+					};
+					this.#loadstartListener = listener;
+					mediaElement.addEventListener("loadstart", listener, { once: true });
+				});
+				throw err;
+			});
+		}
+		#createEngine() {
+			return createHlsAudioOnlyEngine({
+				...this.#config,
+				onSignalsReady: (signals) => {
+					this.#signals = signals;
+				}
+			});
+		}
+		#cancelPendingPlay() {
+			if (!this.#loadstartListener) return;
+			this.#signals.context.mediaElement.get()?.removeEventListener("loadstart", this.#loadstartListener);
+			this.#loadstartListener = null;
+		}
+	}
+	return SimpleHlsAudioOnlyMediaImpl;
+}
+/** Standalone SPF audio-only media adapter with no base class. */
+var SimpleHlsAudioOnlyMediaElement = class extends SimpleHlsAudioOnlyMediaMixin(class {}) {};
+//#endregion
+export { SimpleHlsAudioOnlyMediaElement, SimpleHlsAudioOnlyMediaMixin, simpleHlsAudioOnlyMediaDefaultProps };
+
+//# sourceMappingURL=adapter-audio-only.js.map

package/dist/dev/playback/engines/hls/adapter-audio-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-audio-only.js","names":["#engine","#config","#createEngine","#signals","#cancelPendingPlay","#preload","#disableRemotePlayback","#loadstartListener"],"sources":["../../../../../src/playback/engines/hls/adapter-audio-only.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport type { Composition } from '../../../core/composition/create-composition';\nimport {\n  createHlsAudioOnlyEngine,\n  type SimpleHlsAudioOnlyEngineConfig,\n  type SimpleHlsAudioOnlyEngineContext,\n  type SimpleHlsAudioOnlyEngineSignals,\n  type SimpleHlsAudioOnlyEngineState,\n} from './engine-audio-only';\n\nexport interface SimpleHlsAudioOnlyMediaProps {\n  src: string;\n  preload: '' | 'none' | 'metadata' | 'auto';\n  disableRemotePlayback: boolean;\n}\n\nexport const simpleHlsAudioOnlyMediaDefaultProps: SimpleHlsAudioOnlyMediaProps = {\n  src: '',\n  preload: '',\n  disableRemotePlayback: false,\n};\n\nexport interface SimpleHlsAudioOnlyMediaAPI extends SimpleHlsAudioOnlyMediaProps {\n  readonly engine: Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext>;\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Mixin that adds SPF audio-only HLS playback to any base class.\n *\n * Parallel to `SimpleHlsMediaMixin` with one substantive difference: the\n * underlying engine is the audio-only variant (`createHlsAudioOnlyEngine`),\n * which omits video and text-track behaviors. The src / preload /\n * disableRemotePlayback / play() contract per the WHATWG HTML spec is identical\n * to the default adapter.\n *\n * Selecting this adapter is the variant decision: instantiating\n * `SimpleHlsAudioOnlyMediaElement` opts the consumer into audio-only\n * delivery even when the source is a mixed-AV HLS manifest.\n *\n * @example\n * class SimpleHlsAudioOnlyMedia extends SimpleHlsAudioOnlyMediaMixin(HTMLVideoElementHost) {}\n *\n * const media = new SimpleHlsAudioOnlyMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/abc123.m3u8';\n */\nexport function SimpleHlsAudioOnlyMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class SimpleHlsAudioOnlyMediaImpl extends BaseClass {\n    readonly #engine: Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext>;\n    #config: SimpleHlsAudioOnlyEngineConfig;\n    #signals!: SimpleHlsAudioOnlyEngineSignals;\n    #preload: '' | 'none' | 'metadata' | 'auto' = simpleHlsAudioOnlyMediaDefaultProps.preload;\n    #disableRemotePlayback: boolean = simpleHlsAudioOnlyMediaDefaultProps.disableRemotePlayback;\n\n    /** Pending loadstart listener from a deferred play() retry, if any. */\n    #loadstartListener: (() => void) | null = null;\n\n    constructor(...args: any[]) {\n      super(...args);\n\n      const { config } = args?.[0] ?? {};\n      this.#config = config;\n      this.#engine = this.#createEngine();\n    }\n\n    /**\n     * Underlying playback engine — the low-level SPF reactive composition that\n     * drives playback. An advanced escape hatch for direct engine access;\n     * normal playback is driven through this element's own properties and\n     * methods.\n     */\n    get engine(): Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext> {\n      return this.#engine;\n    }\n\n    // -------------------------------------------------------------------------\n    // Media element lifecycle\n    // -------------------------------------------------------------------------\n\n    attach(mediaElement: HTMLMediaElement): void {\n      super.attach?.(mediaElement);\n      this.#signals.context.mediaElement.set(mediaElement);\n    }\n\n    detach(): void {\n      this.#cancelPendingPlay();\n      this.#signals.context.mediaElement.set(undefined);\n      super.detach?.();\n    }\n\n    destroy(): void {\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n    }\n\n    // -------------------------------------------------------------------------\n    // preload — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // -------------------------------------------------------------------------\n\n    /** Preload type (`'none'` / `'metadata'` / `'auto'`). */\n    get preload(): '' | 'none' | 'metadata' | 'auto' {\n      return this.#preload;\n    }\n\n    set preload(value: '' | 'none' | 'metadata' | 'auto') {\n      this.#preload = value;\n      if (value) {\n        this.#signals.state.preload.set(value);\n      }\n    }\n\n    // -------------------------------------------------------------------------\n    // disableRemotePlayback — synchronous IDL attribute (WHATWG Remote Playback)\n    // Author intent for whether the AirPlay/remote picker is offered. Mirrors\n    // the DOM attribute name; the value flows to `state.disableRemotePlayback`,\n    // which `setupAirPlay` reads to honor an explicit opt-out. The underlying\n    // media element's own `disableRemotePlayback` stays programmatically managed\n    // (ManagedMediaSource needs it `true` to open; AirPlay flips it `false` once\n    // the source is open), so author intent and the effective flag stay distinct.\n    // -------------------------------------------------------------------------\n\n    get disableRemotePlayback(): boolean {\n      return this.#disableRemotePlayback;\n    }\n\n    set disableRemotePlayback(value: boolean) {\n      this.#disableRemotePlayback = value;\n      this.#signals.state.disableRemotePlayback.set(value);\n    }\n\n    // -------------------------------------------------------------------------\n    // src — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // Each assignment overwrites the engine's presentation state in place. The\n    // resolver FSM routes back through teardown → rebuild on the same engine,\n    // mirroring how the browser's load algorithm resets media state on src change\n    // — without recreating the engine or re-capturing its signals. Setting an\n    // empty src un-resolves the presentation, tearing the current source down to\n    // the engine's fresh-but-attached \"no source\" state.\n    // -------------------------------------------------------------------------\n\n    get src(): string {\n      return this.#signals.state.presentation.get()?.url ?? '';\n    }\n\n    set src(value: string) {\n      this.#cancelPendingPlay();\n      this.#signals.state.presentation.set(value ? { url: value } : undefined);\n    }\n\n    // -------------------------------------------------------------------------\n    // play() — WHATWG §4.8.11.8\n    // -------------------------------------------------------------------------\n\n    play(): Promise<void> {\n      const mediaElement = this.#signals.context.mediaElement.get();\n      if (!mediaElement) {\n        return Promise.reject(new Error('SimpleHlsAudioOnlyMediaElement: no media element attached'));\n      }\n\n      this.#signals.state.loadActivated.set(true);\n\n      return mediaElement.play().catch((err: unknown) => {\n        if (this.src) {\n          return new Promise<void>((resolve, reject) => {\n            const listener = () => {\n              this.#loadstartListener = null;\n              mediaElement.play().then(resolve, reject);\n            };\n            this.#loadstartListener = listener;\n            mediaElement.addEventListener('loadstart', listener, { once: true });\n          });\n        }\n        throw err;\n      });\n    }\n\n    // -------------------------------------------------------------------------\n    // Private\n    // -------------------------------------------------------------------------\n\n    #createEngine(): Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext> {\n      return createHlsAudioOnlyEngine({\n        ...this.#config,\n        onSignalsReady: (signals) => {\n          this.#signals = signals;\n        },\n      });\n    }\n\n    #cancelPendingPlay(): void {\n      if (!this.#loadstartListener) return;\n      const mediaElement = this.#signals.context.mediaElement.get();\n      mediaElement?.removeEventListener('loadstart', this.#loadstartListener);\n      this.#loadstartListener = null;\n    }\n  }\n\n  return SimpleHlsAudioOnlyMediaImpl as unknown as MixinReturn<Base, SimpleHlsAudioOnlyMediaAPI>;\n}\n\n/** Standalone SPF audio-only media adapter with no base class. */\nexport class SimpleHlsAudioOnlyMediaElement extends SimpleHlsAudioOnlyMediaMixin(class {}) {}\n"],"mappings":";;AAgBA,MAAa,sCAAoE;CAC/E,KAAK;CACL,SAAS;CACT,uBAAuB;AACzB;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,6BAA4D,WAAiB;CAC3F,MAAM,oCAAoC,UAAU;EAClD;EACA;EACA;EACA,WAA8C,oCAAoC;EAClF,yBAAkC,oCAAoC;;EAGtE,qBAA0C;EAE1C,YAAY,GAAG,MAAa;GAC1B,MAAM,GAAG,IAAI;GAEb,MAAM,EAAE,WAAW,OAAO,MAAM,CAAC;GACjC,KAAKC,UAAU;GACf,KAAKD,UAAU,KAAKE,cAAc;EACpC;;;;;;;EAQA,IAAI,SAAsF;GACxF,OAAO,KAAKF;EACd;EAMA,OAAO,cAAsC;GAC3C,MAAM,SAAS,YAAY;GAC3B,KAAKG,SAAS,QAAQ,aAAa,IAAI,YAAY;EACrD;EAEA,SAAe;GACb,KAAKC,mBAAmB;GACxB,KAAKD,SAAS,QAAQ,aAAa,IAAI,KAAA,CAAS;GAChD,MAAM,SAAS;EACjB;EAEA,UAAgB;GACd,KAAKC,mBAAmB;GACxB,KAAKJ,QAAQ,QAAQ;EACvB;;EAOA,IAAI,UAA6C;GAC/C,OAAO,KAAKK;EACd;EAEA,IAAI,QAAQ,OAA0C;GACpD,KAAKA,WAAW;GAChB,IAAI,OACF,KAAKF,SAAS,MAAM,QAAQ,IAAI,KAAK;EAEzC;EAYA,IAAI,wBAAiC;GACnC,OAAO,KAAKG;EACd;EAEA,IAAI,sBAAsB,OAAgB;GACxC,KAAKA,yBAAyB;GAC9B,KAAKH,SAAS,MAAM,sBAAsB,IAAI,KAAK;EACrD;EAYA,IAAI,MAAc;GAChB,OAAO,KAAKA,SAAS,MAAM,aAAa,IAAI,CAAC,EAAE,OAAO;EACxD;EAEA,IAAI,IAAI,OAAe;GACrB,KAAKC,mBAAmB;GACxB,KAAKD,SAAS,MAAM,aAAa,IAAI,QAAQ,EAAE,KAAK,MAAM,IAAI,KAAA,CAAS;EACzE;EAMA,OAAsB;GACpB,MAAM,eAAe,KAAKA,SAAS,QAAQ,aAAa,IAAI;GAC5D,IAAI,CAAC,cACH,OAAO,QAAQ,uBAAO,IAAI,MAAM,2DAA2D,CAAC;GAG9F,KAAKA,SAAS,MAAM,cAAc,IAAI,IAAI;GAE1C,OAAO,aAAa,KAAK,CAAC,CAAC,OAAO,QAAiB;IACjD,IAAI,KAAK,KACP,OAAO,IAAI,SAAe,SAAS,WAAW;KAC5C,MAAM,iBAAiB;MACrB,KAAKI,qBAAqB;MAC1B,aAAa,KAAK,CAAC,CAAC,KAAK,SAAS,MAAM;KAC1C;KACA,KAAKA,qBAAqB;KAC1B,aAAa,iBAAiB,aAAa,UAAU,EAAE,MAAM,KAAK,CAAC;IACrE,CAAC;IAEH,MAAM;GACR,CAAC;EACH;EAMA,gBAA6F;GAC3F,OAAO,yBAAyB;IAC9B,GAAG,KAAKN;IACR,iBAAiB,YAAY;KAC3B,KAAKE,WAAW;IAClB;GACF,CAAC;EACH;EAEA,qBAA2B;GACzB,IAAI,CAAC,KAAKI,oBAAoB;GAE9B,KAD0BJ,SAAS,QAAQ,aAAa,IAC7C,CAAC,EAAE,oBAAoB,aAAa,KAAKI,kBAAkB;GACtE,KAAKA,qBAAqB;EAC5B;CACF;CAEA,OAAO;AACT;;AAGA,IAAa,iCAAb,cAAoD,6BAA6B,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/dev/playback/engines/hls/adapter.d.ts

@@ -1,11 +1,11 @@
 import { Composition } from "../../../core/composition/create-composition.js";
 import { SimpleHlsEngineContext, SimpleHlsEngineState } from "./engine.js";
 import { Constructor, MixinReturn } from "@videojs/utils/types";
-
 //#region src/playback/engines/hls/adapter.d.ts
 interface SimpleHlsMediaProps {
   src: string;
   preload: '' | 'none' | 'metadata' | 'auto';
+  disableRemotePlayback: boolean;
 }
 declare const simpleHlsMediaDefaultProps: SimpleHlsMediaProps;
 interface SimpleHlsMediaAPI extends SimpleHlsMediaProps {
@@ -21,10 +21,8 @@ interface SimpleHlsMediaAPI extends SimpleHlsMediaProps {
  * Implements the src/play() contract per the WHATWG HTML spec so that SPF can
  * be used anywhere a media element API is expected.
  *
- * A new engine is created on every src assignment — this fully tears down all
- * state, SourceBuffers, and in-flight requests from the previous source before
- * the next one begins. The media element reference is preserved across src
- * changes and re-applied to the new engine automatically.
+ * A single engine instance is created at construction and recycled across src
+ * changes.
  *
  * @example
  * class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}

package/dist/dev/playback/engines/hls/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","names":[],"sources":["../../../../../src/playback/engines/hls/adapter.ts"],"mappings":";;;;;UAUiB,mBAAA;EACf,GAAA;EACA,OAAA;AAAA;AAAA,cAGW,0BAAA,EAA4B,mBAAA;AAAA,UAKxB,iBAAA,SAA0B,mBAAA;EAAA,SAChC,MAAA,EAAQ,WAAA,CAAY,oBAAA,EAAsB,sBAAA;EACnD,MAAA,CAAO,YAAA,EAAc,gBAAA;EACrB,MAAA;EACA,OAAA;EACA,IAAA,IAAQ,OAAA;AAAA;AALV;;;;;;;;;;;;;;;;;;AAAA,iBA0BgB,mBAAA,cAAiC,WAAA,MAAA,CAAkB,SAAA,EAAW,IAAA,GAmJpC,WAAA,CAAY,IAAA,EAAM,iBAAA;AAAA,cAC3D,0BAAA;;;;cAGY,qBAAA,SAA8B,0BAAA"}
+{"version":3,"file":"adapter.d.ts","names":[],"sources":["../../../../../src/playback/engines/hls/adapter.ts"],"mappings":";;;;UAUiB;EACf;EACA;EACA;;cAGW,4BAA4B;UAMxB,0BAA0B;WAChC,QAAQ,YAAY,sBAAsB;EACnD,OAAO,cAAc;EACrB;EACA;EACA,QAAQ;;;;;;;;;;;;;;;;;;iBAmBM,oBAAoB,aAAa,kBAAkB,WAAW,OA+JpC,YAAY,MAAM;;;;;cAI/C,8BAA8B"}