@videojs/spf 10.0.0-beta.23 → 10.0.0-beta.25

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":";;;AAyBA,MAAa,mCAA8D;CACzE,KAAK;CACL,SAAS;CACT,MAAM;CACN,OAAO;CACP,UAAU;CACV,eAAe,KAAA;CAChB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCD,SAAgB,0BAAyD,WAAiB;CACxF,MAAM,iCAAiC,UAAU;EAC/C;EACA;EACA;EACA,WAA8C,iCAAiC;EAC/E,QAAiB,iCAAiC;EAClD,SAAkB,iCAAiC;EACnD,YAAqB,iCAAiC;EACtD;;EAGA,qBAA0C;EAE1C,YAAY,GAAG,MAAa;AAC1B,SAAM,GAAG,KAAK;GAEd,MAAM,EAAE,WAAW,OAAO,MAAM,EAAE;AAClC,SAAA,SAAe;AAEf,SAAA,gBAAsB,QAAQ;AAC9B,SAAA,SAAe,MAAA,cAAoB;;EAGrC,IAAI,SAAgF;AAClF,UAAO,MAAA;;EAOT,OAAO,cAAsC;AAC3C,SAAM,SAAS,aAAa;AAI5B,gBAAa,OAAO,MAAA;AACpB,gBAAa,QAAQ,MAAA;AACrB,gBAAa,WAAW,MAAA;AAExB,SAAA,QAAc,QAAQ,aAAa,IAAI,aAAa;;EAGtD,SAAe;AACb,SAAA,mBAAyB;AACzB,SAAA,QAAc,QAAQ,aAAa,IAAI,KAAA,EAAU;AACjD,SAAM,UAAU;;EAGlB,UAAgB;AACd,SAAA,mBAAyB;AACzB,SAAA,OAAa,SAAS;;EAOxB,IAAI,UAA6C;AAC/C,UAAO,MAAA;;EAGT,IAAI,QAAQ,QAA2C;EAUvD,IAAI,OAAgB;AAClB,UAAO,MAAA;;EAGT,IAAI,KAAK,QAAiB;EAI1B,IAAI,QAAiB;AACnB,UAAO,MAAA;;EAGT,IAAI,MAAM,QAAiB;EAI3B,IAAI,WAAoB;AACtB,UAAO,MAAA;;EAGT,IAAI,SAAS,QAAiB;EAW9B,IAAI,gBAA6C;AAC/C,UAAO,MAAA;;;;;;;EAQT,IAAI,cAAc,OAAoC;AACpD,OAAI,UAAU,MAAA,cAAqB;AACnC,SAAA,gBAAsB;;EASxB,IAAI,MAAc;AAChB,UAAO,MAAA,QAAc,MAAM,aAAa,KAAK,EAAE,OAAO;;EAGxD,IAAI,IAAI,OAAe;AACrB,SAAA,mBAAyB;AAEzB,OAAI,MACF,OAAA,QAAc,MAAM,aAAa,IAAI,EAAE,KAAK,OAAO,CAAC;OAEpD,OAAA,QAAc,MAAM,aAAa,IAAI,KAAA,EAAU;;EASnD,MAAM,OAAsB;GAC1B,MAAM,eAAe,MAAA,QAAc,QAAQ,aAAa,KAAK;AAC7D,OAAI,CAAC,aACH,QAAO,QAAQ,uBAAO,IAAI,MAAM,yDAAyD,CAAC;AAG5F,OAAI;AACF,WAAO,MAAM,aAAa,MAAM;YACzB,KAAK;AAIZ,QAAI,KAAK,IACP,QAAO,IAAI,SAAe,SAAS,WAAW;KAC5C,MAAM,iBAAiB;AACrB,YAAA,oBAA0B;AAC1B,mBAAa,MAAM,CAAC,KAAK,SAAS,OAAO;;AAE3C,WAAA,oBAA0B;AAC1B,kBAAa,iBAAiB,aAAa,UAAU,EAAE,MAAM,MAAM,CAAC;MACpE;AAEJ,UAAM;;;EAQV,gBAAuF;GACrF,MAAM,iBAA8B,iBAAiB;AAGnD,WAAO,yBAFU,aAAa,eAAe,MAAM,MAAM,EAAE,SAAS,QAAQ,GACnD,cAAc,IAAI,UAAU,EAAE,EAChB,yBAAyB,MAAA,cAAoB,CAAC,EAAE;;AAGzF,UAAO,4BAA4B;IACjC,QAAQ;IACR,GAAG,MAAA;IACH,iBAAiB,YAAY;AAC3B,WAAA,UAAgB;;IAEnB,CAAC;;EAGJ,qBAA2B;AACzB,OAAI,CAAC,MAAA,kBAAyB;AACT,SAAA,QAAc,QAAQ,aAAa,KAAK,EAC/C,oBAAoB,aAAa,MAAA,kBAAwB;AACvE,SAAA,oBAA0B;;;AAI9B,QAAO;;;AAIT,IAAa,8BAAb,cAAiD,0BAA0B,MAAM,GAAG,CAAC"}

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

@@ -0,0 +1,107 @@
+import { Composition, ContextSignals, StateSignals } from "../../../core/composition/create-composition.js";
+import { ShareSignalsConfig } from "../../../core/composition/share-signals.js";
+import { MaybeResolvedPresentation } from "../../../media/types/index.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":";;;;;;;;;;;;AAqCA;;;;;;;UAAiB,0BAAA;EAQf;;;AAMF;EATE,YAAA,GAAe,yBAAA;EACf,OAAA;EACA,oBAAA;EACA,aAAA;AAAA;;;;UAMe,4BAAA;EACf,YAAA,GAAe,gBAAA;EACf,WAAA,GAAc,WAAA;EACd,gBAAA,GAAmB,iBAAA;EACnB,uBAAA,GAA0B,kBAAA;AAAA;;;;;AAS5B;;KAAY,4BAAA;EACV,KAAA,EAAO,YAAA,CAAa,0BAAA;EACpB,OAAA,EAAS,cAAA,CAAe,4BAAA;AAAA;;;;;;;;;UAWT,2BAAA,SACP,kBAAA,CAAmB,0BAAA,EAA4B,4BAAA;EAZH;;AAWtD;;;;;;;EAWE,MAAA,GAAS,WAAA,CAAY,sBAAA;EAVb;;;;EAeR,iBAAA,GAAoB,iBAAA;AAAA;;;;;;;;AAuCtB;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,2BAAA,CACd,MAAA,GAAQ,2BAAA,GACP,WAAA,CAAY,0BAAA,EAA4B,4BAAA"}

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,kBAA4E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCjG,SAAgB,4BACd,SAAsC,EAAE,EAC+B;CACvE,MAAM,cAAc;EAClB,GAAG;EACH,QAAQ,OAAO,UAAU;EACzB,mBAAmB,OAAO,qBAAqB;EAC/C,iBAAiB;EAClB;AAED,QAAO,kBACL;EACE;EAEA;EAGA;EAEA;EAEA;EAGA;EACA;EACA;EAGA;EAGA;EAKA;EACD,EACD;EACE,QAAQ;EACR,cAAc,EAEZ,eAAe,MAChB;EACF,CACF"}

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

@@ -0,0 +1,45 @@
+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';
+}
+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 / 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,4BAAA;EACf,GAAA;EACA,OAAA;AAAA;AAAA,cAGW,mCAAA,EAAqC,4BAAA;AAAA,UAKjC,0BAAA,SAAmC,4BAAA;EAAA,SACzC,MAAA,EAAQ,WAAA,CAAY,6BAAA,EAA+B,+BAAA;EAC5D,MAAA,CAAO,YAAA,EAAc,gBAAA;EACrB,MAAA;EACA,OAAA;EACA,IAAA,IAAQ,OAAA;AAAA;AALV;;;;;;;;;;;;;;;;;;;AAAA,iBA2BgB,4BAAA,cAA0C,WAAA,MAAA,CAAkB,SAAA,EAAW,IAAA,GA4IpC,WAAA,CAAY,IAAA,EAAM,0BAAA;AAAA,cACpE,mCAAA;;;;cAGY,8BAAA,SAAuC,mCAAA"}

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

@@ -0,0 +1,119 @@
+import { createHlsAudioOnlyEngine } from "./engine-audio-only.js";
+//#region src/playback/engines/hls/adapter-audio-only.ts
+const simpleHlsAudioOnlyMediaDefaultProps = {
+	src: "",
+	preload: ""
+};
+/**
+* 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 / 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;
+		/** 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 src() {
+			return this.#signals.state.presentation.get()?.url ?? "";
+		}
+		set src(value) {
+			const prevMediaElement = this.#signals.context.mediaElement.get();
+			this.#cancelPendingPlay();
+			this.#engine.destroy();
+			this.#engine = this.#createEngine();
+			if (this.#preload) this.#signals.state.preload.set(this.#preload);
+			if (prevMediaElement) this.#signals.context.mediaElement.set(prevMediaElement);
+			if (value) this.#signals.state.presentation.set({ url: value });
+		}
+		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":["#config","#engine","#createEngine","#signals","#cancelPendingPlay","#preload","#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}\n\nexport const simpleHlsAudioOnlyMediaDefaultProps: SimpleHlsAudioOnlyMediaProps = {\n  src: '',\n  preload: '',\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 / play()\n * contract per the WHATWG HTML spec is identical 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    #engine: Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext>;\n    #config: SimpleHlsAudioOnlyEngineConfig;\n    #signals!: SimpleHlsAudioOnlyEngineSignals;\n    #preload: '' | 'none' | 'metadata' | 'auto' = simpleHlsAudioOnlyMediaDefaultProps.preload;\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    // src — synchronous IDL attribute (WHATWG §4.8.11.2)\n    // -------------------------------------------------------------------------\n\n    get src(): string {\n      return this.#signals.state.presentation.get()?.url ?? '';\n    }\n\n    set src(value: string) {\n      const prevMediaElement = this.#signals.context.mediaElement.get();\n\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n      this.#engine = this.#createEngine();\n\n      if (this.#preload) {\n        this.#signals.state.preload.set(this.#preload);\n      }\n\n      if (prevMediaElement) {\n        this.#signals.context.mediaElement.set(prevMediaElement);\n      }\n\n      if (value) {\n        this.#signals.state.presentation.set({ url: value });\n      }\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":";;AAeA,MAAa,sCAAoE;CAC/E,KAAK;CACL,SAAS;CACV;;;;;;;;;;;;;;;;;;;;AA6BD,SAAgB,6BAA4D,WAAiB;CAC3F,MAAM,oCAAoC,UAAU;EAClD;EACA;EACA;EACA,WAA8C,oCAAoC;;EAGlF,qBAA0C;EAE1C,YAAY,GAAG,MAAa;AAC1B,SAAM,GAAG,KAAK;GAEd,MAAM,EAAE,WAAW,OAAO,MAAM,EAAE;AAClC,SAAA,SAAe;AACf,SAAA,SAAe,MAAA,cAAoB;;;;;;;;EASrC,IAAI,SAAsF;AACxF,UAAO,MAAA;;EAOT,OAAO,cAAsC;AAC3C,SAAM,SAAS,aAAa;AAC5B,SAAA,QAAc,QAAQ,aAAa,IAAI,aAAa;;EAGtD,SAAe;AACb,SAAA,mBAAyB;AACzB,SAAA,QAAc,QAAQ,aAAa,IAAI,KAAA,EAAU;AACjD,SAAM,UAAU;;EAGlB,UAAgB;AACd,SAAA,mBAAyB;AACzB,SAAA,OAAa,SAAS;;;EAQxB,IAAI,UAA6C;AAC/C,UAAO,MAAA;;EAGT,IAAI,QAAQ,OAA0C;AACpD,SAAA,UAAgB;AAChB,OAAI,MACF,OAAA,QAAc,MAAM,QAAQ,IAAI,MAAM;;EAQ1C,IAAI,MAAc;AAChB,UAAO,MAAA,QAAc,MAAM,aAAa,KAAK,EAAE,OAAO;;EAGxD,IAAI,IAAI,OAAe;GACrB,MAAM,mBAAmB,MAAA,QAAc,QAAQ,aAAa,KAAK;AAEjE,SAAA,mBAAyB;AACzB,SAAA,OAAa,SAAS;AACtB,SAAA,SAAe,MAAA,cAAoB;AAEnC,OAAI,MAAA,QACF,OAAA,QAAc,MAAM,QAAQ,IAAI,MAAA,QAAc;AAGhD,OAAI,iBACF,OAAA,QAAc,QAAQ,aAAa,IAAI,iBAAiB;AAG1D,OAAI,MACF,OAAA,QAAc,MAAM,aAAa,IAAI,EAAE,KAAK,OAAO,CAAC;;EAQxD,OAAsB;GACpB,MAAM,eAAe,MAAA,QAAc,QAAQ,aAAa,KAAK;AAC7D,OAAI,CAAC,aACH,QAAO,QAAQ,uBAAO,IAAI,MAAM,4DAA4D,CAAC;AAG/F,SAAA,QAAc,MAAM,cAAc,IAAI,KAAK;AAE3C,UAAO,aAAa,MAAM,CAAC,OAAO,QAAiB;AACjD,QAAI,KAAK,IACP,QAAO,IAAI,SAAe,SAAS,WAAW;KAC5C,MAAM,iBAAiB;AACrB,YAAA,oBAA0B;AAC1B,mBAAa,MAAM,CAAC,KAAK,SAAS,OAAO;;AAE3C,WAAA,oBAA0B;AAC1B,kBAAa,iBAAiB,aAAa,UAAU,EAAE,MAAM,MAAM,CAAC;MACpE;AAEJ,UAAM;KACN;;EAOJ,gBAA6F;AAC3F,UAAO,yBAAyB;IAC9B,GAAG,MAAA;IACH,iBAAiB,YAAY;AAC3B,WAAA,UAAgB;;IAEnB,CAAC;;EAGJ,qBAA2B;AACzB,OAAI,CAAC,MAAA,kBAAyB;AACT,SAAA,QAAc,QAAQ,aAAa,KAAK,EAC/C,oBAAoB,aAAa,MAAA,kBAAwB;AACvE,SAAA,oBAA0B;;;AAI9B,QAAO;;;AAIT,IAAa,iCAAb,cAAoD,6BAA6B,MAAM,GAAG,CAAC"}

package/dist/dev/{dom/playback-engine → playback/engines/hls}/adapter.d.ts

@@ -1,14 +1,15 @@
-import { PlaybackEngine } from "./engine.js";
+import { Composition } from "../../../core/composition/create-composition.js";
+import { SimpleHlsEngineContext, SimpleHlsEngineState } from "./engine.js";
 import { Constructor, MixinReturn } from "@videojs/utils/types";
 
-//#region src/dom/playback-engine/adapter.d.ts
-interface SpfMediaProps {
+//#region src/playback/engines/hls/adapter.d.ts
+interface SimpleHlsMediaProps {
   src: string;
   preload: '' | 'none' | 'metadata' | 'auto';
 }
-declare const spfMediaDefaultProps: SpfMediaProps;
-interface SpfMediaAPI extends SpfMediaProps {
-  readonly engine: PlaybackEngine;
+declare const simpleHlsMediaDefaultProps: SimpleHlsMediaProps;
+interface SimpleHlsMediaAPI extends SimpleHlsMediaProps {
+  readonly engine: Composition<SimpleHlsEngineState, SimpleHlsEngineContext>;
   attach(mediaElement: HTMLMediaElement): void;
   detach(): void;
   destroy(): void;
@@ -26,18 +27,18 @@ interface SpfMediaAPI extends SpfMediaProps {
  * changes and re-applied to the new engine automatically.
  *
  * @example
- * class SimpleHlsMedia extends SpfMediaMixin(HTMLVideoElementHost) {}
+ * class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}
  *
  * const media = new SimpleHlsMedia();
  * media.attach(document.querySelector('video'));
  * media.src = 'https://stream.mux.com/abc123.m3u8';
  */
-declare function SpfMediaMixin<Base extends Constructor<any>>(BaseClass: Base): MixinReturn<Base, SpfMediaAPI>;
-declare const SpfMedia_base: MixinReturn<{
+declare function SimpleHlsMediaMixin<Base extends Constructor<any>>(BaseClass: Base): MixinReturn<Base, SimpleHlsMediaAPI>;
+declare const SimpleHlsMediaElement_base: MixinReturn<{
   new (): {};
-}, SpfMediaAPI>;
+}, SimpleHlsMediaAPI>;
 /** Standalone SPF media adapter with no base class. */
-declare class SpfMedia extends SpfMedia_base {}
+declare class SimpleHlsMediaElement extends SimpleHlsMediaElement_base {}
 //#endregion
-export { SpfMedia, SpfMediaAPI, SpfMediaMixin, SpfMediaProps, spfMediaDefaultProps };
+export { SimpleHlsMediaAPI, SimpleHlsMediaElement, SimpleHlsMediaMixin, SimpleHlsMediaProps, simpleHlsMediaDefaultProps };
 //# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +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,GA0JpC,WAAA,CAAY,IAAA,EAAM,iBAAA;AAAA,cAC3D,0BAAA;;;;cAGY,qBAAA,SAA8B,0BAAA"}