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

package/dist/dev/playback/engines/hls/adapter.js

@@ -2,7 +2,8 @@ import { createSimpleHlsEngine } from "./engine.js";
 //#region src/playback/engines/hls/adapter.ts
 const simpleHlsMediaDefaultProps = {
 	src: "",
-	preload: ""
+	preload: "",
+	disableRemotePlayback: false
 };
 /**
 * Mixin that adds SPF playback engine behavior to any base class.
@@ -10,10 +11,8 @@ const simpleHlsMediaDefaultProps = {
 * 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) {}
@@ -28,6 +27,7 @@ function SimpleHlsMediaMixin(BaseClass) {
 		#config;
 		#signals;
 		#preload = simpleHlsMediaDefaultProps.preload;
+		#disableRemotePlayback = simpleHlsMediaDefaultProps.disableRemotePlayback;
 		/** Pending loadstart listener from a deferred play() retry, if any. */
 		#loadstartListener = null;
 		constructor(...args) {
@@ -36,6 +36,12 @@ function SimpleHlsMediaMixin(BaseClass) {
 			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;
 		}
@@ -52,6 +58,7 @@ function SimpleHlsMediaMixin(BaseClass) {
 			this.#cancelPendingPlay();
 			this.#engine.destroy();
 		}
+		/** Preload type (`'none'` / `'metadata'` / `'auto'`). */
 		get preload() {
 			return this.#preload;
 		}
@@ -59,17 +66,19 @@ function SimpleHlsMediaMixin(BaseClass) {
 			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) {
-			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 });
+			this.#signals.state.presentation.set(value ? { url: value } : void 0);
 		}
 		play() {
 			const mediaElement = this.#signals.context.mediaElement.get();

package/dist/dev/playback/engines/hls/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","names":["#config","#engine","#createEngine","#signals","#cancelPendingPlay","#preload","#loadstartListener"],"sources":["../../../../../src/playback/engines/hls/adapter.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport type { Composition } from '../../../core/composition/create-composition';\nimport {\n  createSimpleHlsEngine,\n  type SimpleHlsEngineConfig,\n  type SimpleHlsEngineContext,\n  type SimpleHlsEngineSignals,\n  type SimpleHlsEngineState,\n} from './engine';\n\nexport interface SimpleHlsMediaProps {\n  src: string;\n  preload: '' | 'none' | 'metadata' | 'auto';\n}\n\nexport const simpleHlsMediaDefaultProps: SimpleHlsMediaProps = {\n  src: '',\n  preload: '',\n};\n\nexport interface SimpleHlsMediaAPI extends SimpleHlsMediaProps {\n  readonly engine: Composition<SimpleHlsEngineState, SimpleHlsEngineContext>;\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Mixin that adds SPF playback engine behavior to any base class.\n *\n * Implements the src/play() contract per the WHATWG HTML spec so that SPF can\n * be used anywhere a media element API is expected.\n *\n * A new engine is created on every src assignment — this fully tears down all\n * state, SourceBuffers, and in-flight requests from the previous source before\n * the next one begins. The media element reference is preserved across src\n * changes and re-applied to the new engine automatically.\n *\n * @example\n * class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}\n *\n * const media = new SimpleHlsMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/abc123.m3u8';\n */\nexport function SimpleHlsMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class SimpleHlsMediaImpl extends BaseClass {\n    #engine: Composition<SimpleHlsEngineState, SimpleHlsEngineContext>;\n    #config: SimpleHlsEngineConfig;\n    #signals!: SimpleHlsEngineSignals;\n    #preload: '' | 'none' | 'metadata' | 'auto' = simpleHlsMediaDefaultProps.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    get engine(): Composition<SimpleHlsEngineState, SimpleHlsEngineContext> {\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    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      // value = '' clears #preload (so the next engine recreation won't re-apply\n      // an explicit value) but does not patch current state — the existing preload\n      // stays in effect until the next src change creates a fresh engine.\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, exactly\n    // as the browser's load algorithm resets all media element state 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      const prevMediaElement = this.#signals.context.mediaElement.get();\n\n      this.#cancelPendingPlay();\n      this.#engine.destroy();\n      this.#engine = this.#createEngine();\n\n      // Apply explicit preload before setting context so it's already in\n      // state.preload when syncPreload's read effect runs on the attach —\n      // the read effect only overwrites when the element's `preload` is a\n      // W3C value (which a freshly-created <video> with no attribute is not).\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    // Delegates to the attached media element's native play().\n    // -------------------------------------------------------------------------\n\n    play(): Promise<void> {\n      const mediaElement = this.#signals.context.mediaElement.get();\n      if (!mediaElement) {\n        return Promise.reject(new Error('SimpleHlsMediaElement: no media element attached'));\n      }\n\n      // Signal play intent — enables loading even with preload=\"none\"\n      this.#signals.state.loadActivated.set(true);\n\n      return mediaElement.play().catch((err: unknown) => {\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<SimpleHlsEngineState, SimpleHlsEngineContext> {\n      return createSimpleHlsEngine({\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 SimpleHlsMediaImpl as unknown as MixinReturn<Base, SimpleHlsMediaAPI>;\n}\n\n/** Standalone SPF media adapter with no base class. */\nexport class SimpleHlsMediaElement extends SimpleHlsMediaMixin(class {}) {}\n"],"mappings":";;AAeA,MAAa,6BAAkD;CAC7D,KAAK;CACL,SAAS;CACV;;;;;;;;;;;;;;;;;;;AA4BD,SAAgB,oBAAmD,WAAiB;CAClF,MAAM,2BAA2B,UAAU;EACzC;EACA;EACA;EACA,WAA8C,2BAA2B;;EAGzE,qBAA0C;EAE1C,YAAY,GAAG,MAAa;AAC1B,SAAM,GAAG,KAAK;GAEd,MAAM,EAAE,WAAW,OAAO,MAAM,EAAE;AAClC,SAAA,SAAe;AACf,SAAA,SAAe,MAAA,cAAoB;;EAGrC,IAAI,SAAoE;AACtE,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;;EAOxB,IAAI,UAA6C;AAC/C,UAAO,MAAA;;EAGT,IAAI,QAAQ,OAA0C;AACpD,SAAA,UAAgB;AAChB,OAAI,MACF,OAAA,QAAc,MAAM,QAAQ,IAAI,MAAM;;EAa1C,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;AAMnC,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;;EASxD,OAAsB;GACpB,MAAM,eAAe,MAAA,QAAc,QAAQ,aAAa,KAAK;AAC7D,OAAI,CAAC,aACH,QAAO,QAAQ,uBAAO,IAAI,MAAM,mDAAmD,CAAC;AAItF,SAAA,QAAc,MAAM,cAAc,IAAI,KAAK;AAE3C,UAAO,aAAa,MAAM,CAAC,OAAO,QAAiB;AAIjD,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,gBAA2E;AACzE,UAAO,sBAAsB;IAC3B,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,wBAAb,cAA2C,oBAAoB,MAAM,GAAG,CAAC"}
+{"version":3,"file":"adapter.js","names":["#engine","#config","#createEngine","#signals","#cancelPendingPlay","#preload","#disableRemotePlayback","#loadstartListener"],"sources":["../../../../../src/playback/engines/hls/adapter.ts"],"sourcesContent":["import type { Constructor, MixinReturn } from '@videojs/utils/types';\nimport type { Composition } from '../../../core/composition/create-composition';\nimport {\n  createSimpleHlsEngine,\n  type SimpleHlsEngineConfig,\n  type SimpleHlsEngineContext,\n  type SimpleHlsEngineSignals,\n  type SimpleHlsEngineState,\n} from './engine';\n\nexport interface SimpleHlsMediaProps {\n  src: string;\n  preload: '' | 'none' | 'metadata' | 'auto';\n  disableRemotePlayback: boolean;\n}\n\nexport const simpleHlsMediaDefaultProps: SimpleHlsMediaProps = {\n  src: '',\n  preload: '',\n  disableRemotePlayback: false,\n};\n\nexport interface SimpleHlsMediaAPI extends SimpleHlsMediaProps {\n  readonly engine: Composition<SimpleHlsEngineState, SimpleHlsEngineContext>;\n  attach(mediaElement: HTMLMediaElement): void;\n  detach(): void;\n  destroy(): void;\n  play(): Promise<void>;\n}\n\n/**\n * Mixin that adds SPF playback engine behavior to any base class.\n *\n * Implements the src/play() contract per the WHATWG HTML spec so that SPF can\n * be used anywhere a media element API is expected.\n *\n * A single engine instance is created at construction and recycled across src\n * changes.\n *\n * @example\n * class SimpleHlsMedia extends SimpleHlsMediaMixin(HTMLVideoElementHost) {}\n *\n * const media = new SimpleHlsMedia();\n * media.attach(document.querySelector('video'));\n * media.src = 'https://stream.mux.com/abc123.m3u8';\n */\nexport function SimpleHlsMediaMixin<Base extends Constructor<any>>(BaseClass: Base) {\n  class SimpleHlsMediaImpl extends BaseClass {\n    readonly #engine: Composition<SimpleHlsEngineState, SimpleHlsEngineContext>;\n    #config: SimpleHlsEngineConfig;\n    #signals!: SimpleHlsEngineSignals;\n    #preload: '' | 'none' | 'metadata' | 'auto' = simpleHlsMediaDefaultProps.preload;\n    #disableRemotePlayback: boolean = simpleHlsMediaDefaultProps.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<SimpleHlsEngineState, SimpleHlsEngineContext> {\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      // value = '' resets the IDL mirror (so `get preload` reflects '') but does\n      // not patch state — the engine keeps its current preload until an explicit\n      // W3C value replaces it.\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    // <video>'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    // Delegates to the attached media element's native play().\n    // -------------------------------------------------------------------------\n\n    play(): Promise<void> {\n      const mediaElement = this.#signals.context.mediaElement.get();\n      if (!mediaElement) {\n        return Promise.reject(new Error('SimpleHlsMediaElement: no media element attached'));\n      }\n\n      // Signal play intent — enables loading even with preload=\"none\"\n      this.#signals.state.loadActivated.set(true);\n\n      return mediaElement.play().catch((err: unknown) => {\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<SimpleHlsEngineState, SimpleHlsEngineContext> {\n      return createSimpleHlsEngine({\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 SimpleHlsMediaImpl as unknown as MixinReturn<Base, SimpleHlsMediaAPI>;\n}\n\n/** Standalone SPF media adapter with no base class. */\nexport class SimpleHlsMediaElement extends SimpleHlsMediaMixin(class {}) {}\n"],"mappings":";;AAgBA,MAAa,6BAAkD;CAC7D,KAAK;CACL,SAAS;CACT,uBAAuB;AACzB;;;;;;;;;;;;;;;;;AA0BA,SAAgB,oBAAmD,WAAiB;CAClF,MAAM,2BAA2B,UAAU;EACzC;EACA;EACA;EACA,WAA8C,2BAA2B;EACzE,yBAAkC,2BAA2B;;EAG7D,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,SAAoE;GACtE,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;EAKzC;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;EAOA,OAAsB;GACpB,MAAM,eAAe,KAAKA,SAAS,QAAQ,aAAa,IAAI;GAC5D,IAAI,CAAC,cACH,OAAO,QAAQ,uBAAO,IAAI,MAAM,kDAAkD,CAAC;GAIrF,KAAKA,SAAS,MAAM,cAAc,IAAI,IAAI;GAE1C,OAAO,aAAa,KAAK,CAAC,CAAC,OAAO,QAAiB;IAIjD,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,gBAA2E;GACzE,OAAO,sBAAsB;IAC3B,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,wBAAb,cAA2C,oBAAoB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,156 @@
+import { AudioTrack, CanPlayTrack, MaybeResolvedPresentation, MediaContainerData } from "../../../media/types/index.js";
+import { Composition, ContextSignals, StateSignals } from "../../../core/composition/create-composition.js";
+import { ShareSignalsConfig } from "../../../core/composition/share-signals.js";
+import { BackBufferConfig } from "../../../media/buffer/back-buffer.js";
+import { ForwardBufferConfig } from "../../../media/buffer/forward-buffer.js";
+import { SourceBufferActor } from "../../actors/dom/source-buffer.js";
+import { SegmentLoaderActor } from "../../actors/dom/segment-loader.js";
+import { ParsePresentation } from "../../behaviors/resolve-presentation.js";
+import { DeriveStartMediaTime } from "../../primitives/derive-start-media-time.js";
+import "../../behaviors/establish-start-media-time.js";
+import { GetCdnId } from "../../../media/utils/cdn.js";
+import { PresentationDurationResolver } from "../../behaviors/calculate-presentation-duration.js";
+import { FailoverMonitorConfig } from "../../behaviors/setup-failover-monitor.js";
+//#region src/playback/engines/hls/engine-audio-only.d.ts
+/**
+ * State shape for the audio-only HLS playback engine.
+ *
+ * Subset of `SimpleHlsEngineState` covering only the slots written and read
+ * by audio-side behaviors. Video and text-track slots are absent —
+ * subtractive composition removes the behaviors that declare them.
+ */
+interface SimpleHlsAudioOnlyEngineState {
+  presentation?: MaybeResolvedPresentation;
+  preload?: 'auto' | 'metadata' | 'none';
+  selectedAudioTrackId?: string;
+  mediaContainerData?: Record<string, MediaContainerData>;
+  /**
+   * Consumer-driven constraint narrowing the audio candidate set. Sibling
+   * of `userVideoTrackSelection` in the default engine. Partial-track
+   * shape — `{ language: 'es' }`, `{ id: 'audio-en' }`, etc.
+   * `selectAudioTrack` reads this and re-picks when it changes.
+   * Multi-language-audio Tier 2 programmatic-write path.
+   */
+  userAudioTrackSelection?: Partial<AudioTrack>;
+  /**
+   * The CDNs the source is served from, in manifest priority order (mirrors
+   * HLS content steering's `PATHWAY-PRIORITY`). Owned by `deriveCdnPriority`,
+   * read by `track-switching`'s `preferActiveCdn` scope. Only meaningful for
+   * redundant-stream sources; a single-CDN source has one entry.
+   */
+  cdnPriority?: string[];
+  /**
+   * CDN ids currently in failover cooldown — read by `track-switching`'s
+   * `excludeFailedCdns` constraint, which prunes their tracks so the active-CDN
+   * scope falls to the next CDN. Empty / absent means all CDNs are eligible.
+   */
+  failedCdns?: string[];
+  currentTime?: number;
+  loadActivated?: boolean;
+  /**
+   * One-shot command: start the current source at this position
+   * (presentation-timeline seconds). Written by consumers or by
+   * `setupAirPlay`'s session-end snapshot; consumed (cleared) by
+   * `applyStartPosition` once the element seeks. See
+   * `behaviors/dom/apply-start-position.ts`.
+   */
+  startPosition?: number;
+  /**
+   * Intent-level loading policy: initiate no new loading work while `true`.
+   * Written by `setupAirPlay` (the only behavior declaring the key) while a
+   * remote-playback session owns presentation; observed by `loadAudioSegments`
+   * (parks in `'dormant'`) and by `setupMediaSource` (a pending rebuild
+   * waits). See `SegmentLoadingState['loadingSuspended']`.
+   */
+  loadingSuspended?: boolean;
+  /**
+   * Author intent for the AirPlay/remote-playback picker, written by the media
+   * adapter's `disableRemotePlayback` IDL property. `true` is an explicit
+   * opt-out: `setupAirPlay` reads it at attach and sets nothing up, leaving the
+   * element's remote playback disabled. Distinct from the underlying media
+   * element's own `disableRemotePlayback`, which stays programmatically managed
+   * (ManagedMediaSource / AirPlay).
+   */
+  disableRemotePlayback?: boolean;
+}
+/**
+ * Context shape for the audio-only HLS playback engine.
+ *
+ * Subset of `SimpleHlsEngineContext` covering only the platform objects and
+ * actor refs managed by audio-side behaviors.
+ */
+interface SimpleHlsAudioOnlyEngineContext {
+  mediaElement?: HTMLMediaElement | undefined;
+  mediaSource?: MediaSource;
+  audioBufferActor?: SourceBufferActor;
+  audioSegmentLoaderActor?: SegmentLoaderActor;
+}
+type SimpleHlsAudioOnlyEngineSignals = {
+  state: StateSignals<SimpleHlsAudioOnlyEngineState>;
+  context: ContextSignals<SimpleHlsAudioOnlyEngineContext>;
+};
+/**
+ * Configuration for the audio-only HLS playback engine.
+ *
+ * Subset of `SimpleHlsEngineConfig` — video-quality, bandwidth-estimator,
+ * and text-track config fields are omitted (no behavior consumes them).
+ */
+interface SimpleHlsAudioOnlyEngineConfig extends ShareSignalsConfig<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext> {
+  preferredAudioLanguage?: string;
+  /**
+   * Codec capability probe read by `track-switching`'s `excludeUnplayableTracks`
+   * constraint. Defaults to the `MediaSource.isTypeSupported`-backed
+   * `canPlayTrack`; override to force-exclude a codec. Mirrors the default
+   * engine — without it, capability probing (and TS / raw-AAC detection) would
+   * be inert for audio-only playback.
+   */
+  canPlayTrack?: CanPlayTrack;
+  resolveDuration?: PresentationDurationResolver;
+  parsePresentation?: ParsePresentation;
+  forwardBuffer?: Partial<ForwardBufferConfig>;
+  backBuffer?: Partial<BackBufferConfig>;
+  /** Multi-CDN failover monitor tuning. Defaults: `DEFAULT_FAILOVER_MONITOR_CONFIG`. */
+  failover?: Partial<FailoverMonitorConfig>;
+  /**
+   * Derive a CDN grouping key from a track URL (used by `cdnPriority`, the
+   * failover trip, and the track-switching CDN rules — one function read by all).
+   * Defaults to the URL origin; override to key on e.g. Mux's `cdn=` param.
+   */
+  getCdnId?: GetCdnId;
+  /** Non-zero-PTS relocation (spike): the reduce seam (tier knob); defaults to per-track own. */
+  deriveStartMediaTime?: DeriveStartMediaTime;
+}
+/**
+ * Create an audio-only HLS playback engine.
+ *
+ * Subtractive composition variant of `createSimpleHlsEngine`: omits
+ * video-side behaviors (`resolveVideoTrack`, `switchVideoTrack`,
+ * `setupVideoBufferActors`, `loadVideoSegments`) and text-track behaviors
+ * (`switchTextTrack`, `resolveTextTrack`, `syncTextTracks`,
+ * `setupTextTrackActors`, `loadTextTrackSegments`). The remaining audio
+ * pipeline composes unchanged.
+ *
+ * Handles both truly audio-only HLS sources (no video stream-inf) and
+ * mixed-AV HLS sources where the audio rendition is selected and video /
+ * subtitle renditions are ignored at composition time. The variant decision
+ * is encoded by adapter choice; this engine does not branch on source
+ * shape.
+ *
+ * @example
+ * ```ts
+ * let signals: SimpleHlsAudioOnlyEngineSignals;
+ * const engine = createHlsAudioOnlyEngine({
+ *   preferredAudioLanguage: 'en',
+ *   onSignalsReady: (refs) => {
+ *     signals = refs;
+ *   },
+ * });
+ *
+ * signals.context.mediaElement.set(audioEl);
+ * signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });
+ * ```
+ */
+declare function createHlsAudioOnlyEngine(config?: SimpleHlsAudioOnlyEngineConfig): Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext>;
+//#endregion
+export { SimpleHlsAudioOnlyEngineConfig, SimpleHlsAudioOnlyEngineContext, SimpleHlsAudioOnlyEngineSignals, SimpleHlsAudioOnlyEngineState, createHlsAudioOnlyEngine };
+//# sourceMappingURL=engine-audio-only.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine-audio-only.d.ts","names":[],"sources":["../../../../../src/playback/engines/hls/engine-audio-only.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;UA0DiB;EACf,eAAe;EACf;EACA;EAGA,qBAAqB,eAAe;;;;;;;;EAQpC,0BAA0B,QAAQ;;;;;;;EAOlC;;;;;;EAMA;EACA;EACA;;;;;;;;EAQA;;;;;;;;EAQA;;;;;;;;;EASA;;;;;;;;UASe;EACf,eAAe;EACf,cAAc;EACd,mBAAmB;EACnB,0BAA0B;;KAGhB;EACV,OAAO,aAAa;EACpB,SAAS,eAAe;;;;;;;;UAST,uCACP,mBAAmB,+BAA+B;EAC1D;;;;;;;;EAQA,eAAe;EACf,kBAAkB;EAClB,oBAAoB;EACpB,gBAAgB,QAAQ;EACxB,aAAa,QAAQ;;EAErB,WAAW,QAAQ;;;;;;EAMnB,WAAW;;EAEX,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+CT,yBACd,SAAQ,iCACP,YAAY,+BAA+B"}

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

@@ -0,0 +1,94 @@
+import { createComposition } from "../../../core/composition/create-composition.js";
+import { makeShareSignals } from "../../../core/composition/share-signals.js";
+import { loadAudioSegments } from "../../behaviors/dom/load-segments.js";
+import { trackCurrentTime } from "../../behaviors/dom/track-current-time.js";
+import { trackLoadTriggers } from "../../behaviors/dom/track-load-triggers.js";
+import { deriveSharedMinStartMediaTime, establishStartMediaTime } from "../../behaviors/establish-start-media-time.js";
+import { attachMediaSourceAsSourceElement } from "../../../media/dom/mse/mediasource-setup.js";
+import { canPlayTrack } from "../../../media/dom/capabilities.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 { deriveCdnPriority } from "../../behaviors/derive-cdn-priority.js";
+import { setupAirPlay } from "../../behaviors/dom/airplay.js";
+import { applyStartPosition } from "../../behaviors/dom/apply-start-position.js";
+import { endOfStream } from "../../behaviors/dom/end-of-stream.js";
+import { recoverEndStall } from "../../behaviors/dom/recover-end-stall.js";
+import { setupAudioBufferActors } 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 { resolveAudioTrack } from "../../behaviors/resolve-track.js";
+import { setupFailoverMonitor } from "../../behaviors/setup-failover-monitor.js";
+import { syncPreload } from "../../behaviors/sync-preload.js";
+import { switchAudioTrack } from "../../behaviors/track-switching.js";
+import { relocationPipelinesFor } from "../../primitives/relocation-pipelines.js";
+//#region src/playback/engines/hls/engine-audio-only.ts
+const shareSignals = makeShareSignals(["userAudioTrackSelection", "disableRemotePlayback"]);
+/**
+* Create an audio-only HLS playback engine.
+*
+* Subtractive composition variant of `createSimpleHlsEngine`: omits
+* video-side behaviors (`resolveVideoTrack`, `switchVideoTrack`,
+* `setupVideoBufferActors`, `loadVideoSegments`) and text-track behaviors
+* (`switchTextTrack`, `resolveTextTrack`, `syncTextTracks`,
+* `setupTextTrackActors`, `loadTextTrackSegments`). The remaining audio
+* pipeline composes unchanged.
+*
+* Handles both truly audio-only HLS sources (no video stream-inf) and
+* mixed-AV HLS sources where the audio rendition is selected and video /
+* subtitle renditions are ignored at composition time. The variant decision
+* is encoded by adapter choice; this engine does not branch on source
+* shape.
+*
+* @example
+* ```ts
+* let signals: SimpleHlsAudioOnlyEngineSignals;
+* const engine = createHlsAudioOnlyEngine({
+*   preferredAudioLanguage: 'en',
+*   onSignalsReady: (refs) => {
+*     signals = refs;
+*   },
+* });
+*
+* signals.context.mediaElement.set(audioEl);
+* signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });
+* ```
+*/
+function createHlsAudioOnlyEngine(config = {}) {
+	const deriveStartMediaTime = config.deriveStartMediaTime ?? deriveSharedMinStartMediaTime;
+	const finalConfig = {
+		...config,
+		deriveStartMediaTime,
+		attachMediaSource: attachMediaSourceAsSourceElement,
+		canPlayTrack: config.canPlayTrack ?? canPlayTrack,
+		resolveDuration: config.resolveDuration ?? getResolvedSelectedTrackDuration,
+		parsePresentation: config.parsePresentation ?? parseMultivariantPlaylist,
+		audioMessagePipelines: relocationPipelinesFor("audio", deriveStartMediaTime)
+	};
+	return createComposition([
+		syncPreload,
+		trackLoadTriggers,
+		resolvePresentation,
+		deriveCdnPriority,
+		setupFailoverMonitor,
+		switchAudioTrack,
+		resolveAudioTrack,
+		calculatePresentationDuration,
+		setupMediaSource,
+		updateMediaSourceDuration,
+		establishStartMediaTime,
+		setupAudioBufferActors,
+		setupAirPlay,
+		trackCurrentTime,
+		applyStartPosition,
+		loadAudioSegments,
+		endOfStream,
+		recoverEndStall,
+		shareSignals
+	], { config: finalConfig });
+}
+//#endregion
+export { createHlsAudioOnlyEngine };
+
+//# sourceMappingURL=engine-audio-only.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine-audio-only.js","names":[],"sources":["../../../../../src/playback/engines/hls/engine-audio-only.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 type { BackBufferConfig } from '../../../media/buffer/back-buffer';\nimport type { ForwardBufferConfig } from '../../../media/buffer/forward-buffer';\nimport { canPlayTrack } from '../../../media/dom/capabilities';\nimport { attachMediaSourceAsSourceElement } from '../../../media/dom/mse/mediasource-setup';\nimport { parseMultivariantPlaylist } from '../../../media/hls/parse-multivariant';\nimport type { AudioTrack, CanPlayTrack, MaybeResolvedPresentation, MediaContainerData } from '../../../media/types';\nimport type { GetCdnId } from '../../../media/utils/cdn';\nimport { getResolvedSelectedTrackDuration } from '../../../media/utils/track-selection';\nimport type { SegmentLoaderActor } from '../../actors/dom/segment-loader';\nimport type { SourceBufferActor } from '../../actors/dom/source-buffer';\nimport {\n  calculatePresentationDuration,\n  type PresentationDurationResolver,\n} from '../../behaviors/calculate-presentation-duration';\nimport { deriveCdnPriority } from '../../behaviors/derive-cdn-priority';\nimport { setupAirPlay } from '../../behaviors/dom/airplay';\nimport { applyStartPosition } from '../../behaviors/dom/apply-start-position';\nimport { endOfStream } from '../../behaviors/dom/end-of-stream';\nimport { loadAudioSegments } from '../../behaviors/dom/load-segments';\nimport { recoverEndStall } from '../../behaviors/dom/recover-end-stall';\nimport { setupAudioBufferActors } from '../../behaviors/dom/setup-buffer-actors';\nimport { setupMediaSource } from '../../behaviors/dom/setup-mediasource';\nimport { trackCurrentTime } from '../../behaviors/dom/track-current-time';\nimport { trackLoadTriggers } from '../../behaviors/dom/track-load-triggers';\nimport { updateMediaSourceDuration } from '../../behaviors/dom/update-mediasource-duration';\n// Non-zero-PTS relocation (spike): remove this import, the composed reactor, the\n// `audioMessagePipelines` finalConfig entry, the `mediaContainerData` state slot,\n// and the `deriveStartMediaTime` config field to drop relocation from audio-only.\nimport {\n  type DeriveStartMediaTime,\n  deriveSharedMinStartMediaTime,\n  establishStartMediaTime,\n} from '../../behaviors/establish-start-media-time';\nimport { type ParsePresentation, resolvePresentation } from '../../behaviors/resolve-presentation';\nimport { resolveAudioTrack } from '../../behaviors/resolve-track';\nimport { type FailoverMonitorConfig, setupFailoverMonitor } from '../../behaviors/setup-failover-monitor';\nimport { syncPreload } from '../../behaviors/sync-preload';\nimport { switchAudioTrack } from '../../behaviors/track-switching';\nimport { relocationPipelinesFor } from '../../primitives/relocation-pipelines';\n\n// ============================================================================\n// Audio-Only HLS Engine State & Context\n// ============================================================================\n\n/**\n * State shape for the audio-only HLS playback engine.\n *\n * Subset of `SimpleHlsEngineState` covering only the slots written and read\n * by audio-side behaviors. Video and text-track slots are absent —\n * subtractive composition removes the behaviors that declare them.\n */\nexport interface SimpleHlsAudioOnlyEngineState {\n  presentation?: MaybeResolvedPresentation;\n  preload?: 'auto' | 'metadata' | 'none';\n  selectedAudioTrackId?: string;\n  // Non-zero-PTS relocation (spike): transient per-track container data owned by\n  // `establishStartMediaTime`. Remove with the composed reactor.\n  mediaContainerData?: Record<string, MediaContainerData>;\n  /**\n   * Consumer-driven constraint narrowing the audio candidate set. Sibling\n   * of `userVideoTrackSelection` in the default engine. Partial-track\n   * shape — `{ language: 'es' }`, `{ id: 'audio-en' }`, etc.\n   * `selectAudioTrack` reads this and re-picks when it changes.\n   * Multi-language-audio Tier 2 programmatic-write path.\n   */\n  userAudioTrackSelection?: Partial<AudioTrack>;\n  /**\n   * The CDNs the source is served from, in manifest priority order (mirrors\n   * HLS content steering's `PATHWAY-PRIORITY`). Owned by `deriveCdnPriority`,\n   * read by `track-switching`'s `preferActiveCdn` scope. Only meaningful for\n   * redundant-stream sources; a single-CDN source has one entry.\n   */\n  cdnPriority?: string[];\n  /**\n   * CDN ids currently in failover cooldown — read by `track-switching`'s\n   * `excludeFailedCdns` constraint, which prunes their tracks so the active-CDN\n   * scope falls to the next CDN. Empty / absent means all CDNs are eligible.\n   */\n  failedCdns?: string[];\n  currentTime?: number;\n  loadActivated?: boolean;\n  /**\n   * One-shot command: start the current source at this position\n   * (presentation-timeline seconds). Written by consumers or by\n   * `setupAirPlay`'s session-end snapshot; consumed (cleared) by\n   * `applyStartPosition` once the element seeks. See\n   * `behaviors/dom/apply-start-position.ts`.\n   */\n  startPosition?: number;\n  /**\n   * Intent-level loading policy: initiate no new loading work while `true`.\n   * Written by `setupAirPlay` (the only behavior declaring the key) while a\n   * remote-playback session owns presentation; observed by `loadAudioSegments`\n   * (parks in `'dormant'`) and by `setupMediaSource` (a pending rebuild\n   * waits). See `SegmentLoadingState['loadingSuspended']`.\n   */\n  loadingSuspended?: boolean;\n  /**\n   * Author intent for the AirPlay/remote-playback picker, written by the media\n   * adapter's `disableRemotePlayback` IDL property. `true` is an explicit\n   * opt-out: `setupAirPlay` reads it at attach and sets nothing up, leaving the\n   * element's remote playback disabled. Distinct from the underlying media\n   * element's own `disableRemotePlayback`, which stays programmatically managed\n   * (ManagedMediaSource / AirPlay).\n   */\n  disableRemotePlayback?: boolean;\n}\n\n/**\n * Context shape for the audio-only HLS playback engine.\n *\n * Subset of `SimpleHlsEngineContext` covering only the platform objects and\n * actor refs managed by audio-side behaviors.\n */\nexport interface SimpleHlsAudioOnlyEngineContext {\n  mediaElement?: HTMLMediaElement | undefined;\n  mediaSource?: MediaSource;\n  audioBufferActor?: SourceBufferActor;\n  audioSegmentLoaderActor?: SegmentLoaderActor;\n}\n\nexport type SimpleHlsAudioOnlyEngineSignals = {\n  state: StateSignals<SimpleHlsAudioOnlyEngineState>;\n  context: ContextSignals<SimpleHlsAudioOnlyEngineContext>;\n};\n\n/**\n * Configuration for the audio-only HLS playback engine.\n *\n * Subset of `SimpleHlsEngineConfig` — video-quality, bandwidth-estimator,\n * and text-track config fields are omitted (no behavior consumes them).\n */\nexport interface SimpleHlsAudioOnlyEngineConfig\n  extends ShareSignalsConfig<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext> {\n  preferredAudioLanguage?: string;\n  /**\n   * Codec capability probe read by `track-switching`'s `excludeUnplayableTracks`\n   * constraint. Defaults to the `MediaSource.isTypeSupported`-backed\n   * `canPlayTrack`; override to force-exclude a codec. Mirrors the default\n   * engine — without it, capability probing (and TS / raw-AAC detection) would\n   * be inert for audio-only playback.\n   */\n  canPlayTrack?: CanPlayTrack;\n  resolveDuration?: PresentationDurationResolver;\n  parsePresentation?: ParsePresentation;\n  forwardBuffer?: Partial<ForwardBufferConfig>;\n  backBuffer?: Partial<BackBufferConfig>;\n  /** Multi-CDN failover monitor tuning. Defaults: `DEFAULT_FAILOVER_MONITOR_CONFIG`. */\n  failover?: Partial<FailoverMonitorConfig>;\n  /**\n   * Derive a CDN grouping key from a track URL (used by `cdnPriority`, the\n   * failover trip, and the track-switching CDN rules — one function read by all).\n   * Defaults to the URL origin; override to key on e.g. Mux's `cdn=` param.\n   */\n  getCdnId?: GetCdnId;\n  /** Non-zero-PTS relocation (spike): the reduce seam (tier knob); defaults to per-track own. */\n  deriveStartMediaTime?: DeriveStartMediaTime;\n}\n\n// ============================================================================\n// Audio-Only HLS Playback Engine\n// ============================================================================\n\n// Materializes input slots no composed behavior produces — `userAudioTrackSelection`\n// (switchAudioTrack only reads it) and `disableRemotePlayback` (setupAirPlay only\n// reads it) — in addition to forwarding refs. `failedCdns` is owned by\n// `setupFailoverMonitor`, so it's already materialized and reachable on the\n// `onSignalsReady` refs without being listed here.\nconst shareSignals = makeShareSignals<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext>([\n  'userAudioTrackSelection',\n  'disableRemotePlayback',\n]);\n\n/**\n * Create an audio-only HLS playback engine.\n *\n * Subtractive composition variant of `createSimpleHlsEngine`: omits\n * video-side behaviors (`resolveVideoTrack`, `switchVideoTrack`,\n * `setupVideoBufferActors`, `loadVideoSegments`) and text-track behaviors\n * (`switchTextTrack`, `resolveTextTrack`, `syncTextTracks`,\n * `setupTextTrackActors`, `loadTextTrackSegments`). The remaining audio\n * pipeline composes unchanged.\n *\n * Handles both truly audio-only HLS sources (no video stream-inf) and\n * mixed-AV HLS sources where the audio rendition is selected and video /\n * subtitle renditions are ignored at composition time. The variant decision\n * is encoded by adapter choice; this engine does not branch on source\n * shape.\n *\n * @example\n * ```ts\n * let signals: SimpleHlsAudioOnlyEngineSignals;\n * const engine = createHlsAudioOnlyEngine({\n *   preferredAudioLanguage: 'en',\n *   onSignalsReady: (refs) => {\n *     signals = refs;\n *   },\n * });\n *\n * signals.context.mediaElement.set(audioEl);\n * signals.state.presentation.set({ url: 'https://example.com/stream.m3u8' });\n * ```\n */\nexport function createHlsAudioOnlyEngine(\n  config: SimpleHlsAudioOnlyEngineConfig = {}\n): Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext> {\n  const deriveStartMediaTime = config.deriveStartMediaTime ?? deriveSharedMinStartMediaTime;\n  const finalConfig = {\n    ...config,\n    deriveStartMediaTime,\n    // Baked (not user-overridable): this engine composes `setupAirPlay`,\n    // whose native fallback `<source>` requires the MSE attachment to keep\n    // sibling source alternatives part of resource selection. The helper's\n    // `video/mp4` source type is inert here — resource selection probes it\n    // with `canPlayType`, which answers `'maybe'` on an audio element too.\n    attachMediaSource: attachMediaSourceAsSourceElement,\n    canPlayTrack: config.canPlayTrack ?? canPlayTrack,\n    resolveDuration: config.resolveDuration ?? getResolvedSelectedTrackDuration,\n    parsePresentation: config.parsePresentation ?? parseMultivariantPlaylist,\n    // Non-zero-PTS relocation (spike): pair the audio loader with the relocation steps\n    // `establishStartMediaTime` derives from; same `deriveStartMediaTime` seam. Remove\n    // with the reactor.\n    audioMessagePipelines: relocationPipelinesFor('audio', deriveStartMediaTime),\n  };\n\n  return createComposition(\n    [\n      syncPreload,\n      trackLoadTriggers,\n      resolvePresentation,\n\n      // Session-level CDN priority for redundant-stream sources. Owns\n      // `cdnPriority`; switchAudioTrack's preferActiveCdn scope reads it. No-op\n      // for single-CDN sources.\n      //\n      // With a single track type there's no cross-type coherence to enforce and\n      // the first pick is the primary CDN regardless, so composition order is\n      // not load-bearing here today. It earns its place for forward-consistency\n      // with the default engine and for future failover / steering, where the\n      // active CDN changes dynamically (and selection stays reactive either way).\n      deriveCdnPriority,\n\n      // CDN failover cooldown: watches `failedCdns` (tripped directly by audio\n      // track resolution on a failed media-playlist fetch) and removes each CDN\n      // once its cooldown lapses.\n      setupFailoverMonitor,\n\n      // Audio track selection — slot owner with filter reactivity.\n      // Mid-stream flush on language switch is handled in segment-loader's\n      // planTasks, not here.\n      switchAudioTrack,\n\n      // Resolve selected tracks — audio only.\n      resolveAudioTrack,\n\n      // Presentation duration\n      calculatePresentationDuration,\n\n      // MSE setup. Single audio buffer; no video buffer to coordinate with,\n      // so the Firefox `mozHasAudio` registration ordering is moot here.\n      setupMediaSource,\n      updateMediaSourceDuration,\n\n      // Non-zero-PTS relocation (spike): establishes per-track startMediaTime;\n      // MUST precede setupAudioBufferActors. Remove this line + the import + the\n      // finalConfig/state entries to drop relocation. (Selection is optional in the\n      // reactor, so it works with only audio in scope.)\n      establishStartMediaTime,\n\n      setupAudioBufferActors,\n\n      // AirPlay/MSE bridge (WebKit only; no-op elsewhere). Audio-only sources\n      // AirPlay to audio receivers (HomePod, AirPlay speakers) through the same\n      // native-HLS fallback `<source>`; `webkitCurrentPlaybackTargetIsWireless`\n      // and the picker are HTMLMediaElement-level, so an `<audio>` host is\n      // AirPlay-capable on the same terms as a `<video>` one.\n      setupAirPlay,\n\n      // Playback tracking\n      trackCurrentTime,\n      // After trackCurrentTime: the one-shot currentTime seed must land after\n      // the mirror's attach-time sync (see apply-start-position.ts).\n      applyStartPosition,\n\n      // Segment loading — audio only.\n      loadAudioSegments,\n\n      // End of stream coordination. `endOfStream` iterates buffer actors via\n      // `[videoBufferActor, audioBufferActor].filter(Boolean)` and reads\n      // `mediaSource.sourceBuffers` aggregately — composes unchanged with\n      // only audio in scope.\n      endOfStream,\n      // Force native `ended` if Chrome freezes the playhead short of the buffered end\n      // after `endOfStream`. Inert for a clean-ending single-track source.\n      recoverEndStall,\n\n      // Adapter signal callback.\n      shareSignals,\n    ],\n    {\n      config: finalConfig,\n    }\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA+KA,MAAM,eAAe,iBAAiF,CACpG,2BACA,uBACF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCD,SAAgB,yBACd,SAAyC,CAAC,GACmC;CAC7E,MAAM,uBAAuB,OAAO,wBAAwB;CAC5D,MAAM,cAAc;EAClB,GAAG;EACH;EAMA,mBAAmB;EACnB,cAAc,OAAO,gBAAgB;EACrC,iBAAiB,OAAO,mBAAmB;EAC3C,mBAAmB,OAAO,qBAAqB;EAI/C,uBAAuB,uBAAuB,SAAS,oBAAoB;CAC7E;CAEA,OAAO,kBACL;EACE;EACA;EACA;EAWA;EAKA;EAKA;EAGA;EAGA;EAIA;EACA;EAMA;EAEA;EAOA;EAGA;EAGA;EAGA;EAMA;EAGA;EAGA;CACF,GACA,EACE,QAAQ,YACV,CACF;AACF"}

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

@@ -1,18 +1,23 @@
+import { AudioTrack, CanPlayTrack, MaybeResolvedPresentation, MediaContainerData, TextTrack, VideoTrack } from "../../../media/types/index.js";
 import { Composition, ContextSignals, StateSignals } from "../../../core/composition/create-composition.js";
 import { ShareSignalsConfig } from "../../../core/composition/share-signals.js";
-import { MaybeResolvedPresentation, VideoTrack } from "../../../media/types/index.js";
 import { BackBufferConfig } from "../../../media/buffer/back-buffer.js";
 import { ForwardBufferConfig } from "../../../media/buffer/forward-buffer.js";
 import { SourceBufferActor } from "../../actors/dom/source-buffer.js";
 import { SegmentLoaderActor } from "../../actors/dom/segment-loader.js";
+import { TextTrackSegmentResolver } from "../../primitives/text-segment-load-pipeline.js";
 import { TextTracksActor } from "../../actors/text-tracks.js";
-import { TextTrackSegmentLoaderActor, TextTrackSegmentResolver } from "../../actors/text-track-segment-loader.js";
+import { TextTrackSegmentLoaderActor } from "../../actors/text-track-segment-loader.js";
+import { ParsePresentation } from "../../behaviors/resolve-presentation.js";
+import { DeriveStartMediaTime } from "../../primitives/derive-start-media-time.js";
+import "../../behaviors/establish-start-media-time.js";
 import { QualityConfig } from "../../../media/abr/quality-selection.js";
 import { addSubtitlesTracksToMedia, getShowingSubtitlesTrackFromMedia, removeAllSubtitlesTracksFromMedia } from "../../../media/dom/text/text-track-slots.js";
+import { GetCdnId } from "../../../media/utils/cdn.js";
 import { BandwidthConfig, BandwidthState } from "../../../network/bandwidth-estimator.js";
+import "../../actors/dom/text-tracks.js";
 import { PresentationDurationResolver } from "../../behaviors/calculate-presentation-duration.js";
-import { ParsePresentation } from "../../behaviors/resolve-presentation.js";
-
+import { FailoverMonitorConfig } from "../../behaviors/setup-failover-monitor.js";
 //#region src/playback/engines/hls/engine.d.ts
 /**
  * State shape for the HLS playback engine.
@@ -32,9 +37,70 @@ interface SimpleHlsEngineState {
   selectedAudioTrackId?: string;
   selectedTextTrackId?: string;
   bandwidthState?: BandwidthState;
+  mediaContainerData?: Record<string, MediaContainerData>;
   userVideoTrackSelection?: Partial<VideoTrack>;
+  /**
+   * Consumer-driven constraint narrowing the audio candidate set. Sibling
+   * of `userVideoTrackSelection`. Partial-track shape — `{ language: 'es' }`,
+   * `{ id: 'audio-en' }`, etc. `selectAudioTrack` reads this and re-picks
+   * when it changes. Multi-language-audio Tier 2 programmatic-write path.
+   */
+  userAudioTrackSelection?: Partial<AudioTrack>;
+  /**
+   * Consumer-driven *intent* for text selection, resolved into
+   * `selectedTextTrackId` by `switchTextTrack`. A language-based partial
+   * (`{ language: 'es' }`) selects captions, `'off'` disables them, and absence
+   * means auto (the engine's `preferredSubtitleLanguage` / DEFAULT-track policy).
+   * Also the write path for the DOM caption UI (via `syncTextTracks`); unlike the
+   * resolved id it persists across source changes (sticky preference).
+   */
+  userTextTrackSelection?: Partial<TextTrack> | 'off';
+  /**
+   * The CDNs the source is served from (track-URL origins), in manifest
+   * priority order — most-preferred first (mirrors HLS content steering's
+   * `PATHWAY-PRIORITY`). Owned by `deriveCdnPriority`, read by
+   * `track-switching`'s `preferActiveCdn` scope, which narrows to the
+   * highest-priority CDN with surviving tracks so video / audio / text stay on
+   * one host. Only meaningful for redundant-stream sources; a single-CDN source
+   * has one entry.
+   */
+  cdnPriority?: string[];
+  /**
+   * CDN ids (origins) currently in failover cooldown — written by the CDN
+   * monitor when a host fails too often, read by `track-switching`'s
+   * `excludeFailedCdns` hard constraint, which prunes their tracks so the
+   * active-CDN scope falls to the next CDN in `cdnPriority`. Empty / absent
+   * means all CDNs are eligible.
+   */
+  failedCdns?: string[];
   currentTime?: number;
   loadActivated?: boolean;
+  /**
+   * One-shot command: start the current source at this position
+   * (presentation-timeline seconds). Written by consumers or by
+   * `setupAirPlay`'s session-end snapshot; consumed (cleared) by
+   * `applyStartPosition` once the element seeks. See
+   * `behaviors/dom/apply-start-position.ts`.
+   */
+  startPosition?: number;
+  /**
+   * Intent-level loading policy: initiate no new loading work while `true`.
+   * Written by `setupAirPlay` (the only behavior declaring the key) while a
+   * remote-playback session owns presentation; observed by the
+   * `loadXSegments` dispatchers (park in `'dormant'`) and by
+   * `setupMediaSource` (a pending rebuild waits). See
+   * `SegmentLoadingState['loadingSuspended']`.
+   */
+  loadingSuspended?: boolean;
+  /**
+   * Author intent for the AirPlay/remote-playback picker, written by the media
+   * adapter's `disableRemotePlayback` IDL property. `true` is an explicit
+   * opt-out: `setupAirPlay` reads it at attach and sets nothing up, leaving the
+   * element's remote playback disabled. Distinct from the underlying
+   * `<video>.disableRemotePlayback`, which stays programmatically managed
+   * (ManagedMediaSource / AirPlay).
+   */
+  disableRemotePlayback?: boolean;
 }
 /**
  * Context shape for the HLS playback engine.
@@ -73,6 +139,14 @@ interface SimpleHlsEngineConfig extends ShareSignalsConfig<SimpleHlsEngineState,
    * collected. Default: `DEFAULT_INITIAL_BANDWIDTH` (5 Mbps).
    */
   initialBandwidth?: number;
+  /**
+   * Codec capability probe injected into `track-switching`'s
+   * `excludeUnplayableTracks` constraint — drops renditions the environment
+   * can't decode before selection. Defaults to the `MediaSource.isTypeSupported`
+   * -backed `canPlayTrack`; supply your own to override (e.g. force-exclude a
+   * codec).
+   */
+  canPlayTrack?: CanPlayTrack;
   preferredAudioLanguage?: string;
   preferredSubtitleLanguage?: string;
   includeForcedTracks?: boolean;
@@ -144,6 +218,37 @@ interface SimpleHlsEngineConfig extends ShareSignalsConfig<SimpleHlsEngineState,
    * ratio gating ABR upgrades. Defaults: `DEFAULT_QUALITY_CONFIG` (0.85 / 1.15).
    */
   quality?: Partial<QualityConfig>;
+  /**
+   * Multi-CDN failover monitor tuning. `cooldownMs` is how long a CDN stays
+   * excluded after a failed fetch trips it. Defaults:
+   * `DEFAULT_FAILOVER_MONITOR_CONFIG` (300s). Only meaningful for redundant-stream
+   * sources.
+   */
+  failover?: Partial<FailoverMonitorConfig>;
+  /**
+   * How to derive a CDN grouping key from a track URL — used to build
+   * `cdnPriority`, to record the failover trip in `failedCdns`, and by the
+   * track-switching CDN scope + failover constraint. One function, read by all of
+   * them, so the keys stay comparable. Defaults to the URL origin; override to
+   * key on something else (e.g. Mux's `cdn=` query param).
+   */
+  getCdnId?: GetCdnId;
+  /**
+   * Non-zero-PTS relocation (spike): the reduce seam consumed by the
+   * `establishStartMediaTime` reactor. Defaults to per-track own origin (Tier 1);
+   * a Tier-2 variant returns the shared `min` across selected A/V. Relocation is
+   * composed into the standard engine below — see the marked block — so this only
+   * needs setting to swap the tier policy. See
+   * `internal/design/spf/presentation-timeline-model.md`.
+   */
+  deriveStartMediaTime?: DeriveStartMediaTime;
+  /**
+   * Proximity window (seconds) for the `recoverEndStall` behavior — how close the
+   * playhead must be to the reachable buffered end for a `waiting` to be treated as the
+   * end-of-stream freeze and nudged to `ended`. Defaults to `0.2`. See
+   * `behaviors/dom/recover-end-stall`.
+   */
+  endStallNudgeWindow?: number;
 }
 /**
  * Create an HLS playback engine.

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

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","names":[],"sources":["../../../../../src/playback/engines/hls/engine.ts"],"mappings":";;;;;;;;;;;;;;;;;;;AAsDA;;;;UAAiB,oBAAA;EAWmB;;;;EANlC,YAAA,GAAe,yBAAA;EACf,OAAA;EACA,oBAAA;EACA,oBAAA;EACA,mBAAA;EACA,cAAA,GAAiB,cAAA;EACjB,uBAAA,GAA0B,OAAA,CAAQ,UAAA;EAClC,WAAA;EACA,aAAA;AAAA;;;;;;UAQe,sBAAA;EACf,YAAA,GAAe,gBAAA;EACf,WAAA,GAAc,WAAA;EACd,gBAAA,GAAmB,iBAAA;EACnB,gBAAA,GAAmB,iBAAA;EACnB,uBAAA,GAA0B,kBAAA;EAC1B,uBAAA,GAA0B,kBAAA;EAC1B,eAAA,GAAkB,eAAA;EAClB,2BAAA,GAA8B,2BAAA;AAAA;;;;;;;KASpB,sBAAA;EACV,KAAA,EAAO,YAAA,CAAa,oBAAA;EACpB,OAAA,EAAS,cAAA,CAAe,sBAAA;AAAA;;;;;;;UAST,qBAAA,SAA8B,kBAAA,CAAmB,oBAAA,EAAsB,sBAAA;EApBtF;;;;EAyBA,gBAAA;EACA,sBAAA;EACA,yBAAA;EACA,mBAAA;EACA,kBAAA;EAlBwB;;;;;EAwBxB,uBAAA,GAA0B,wBAAA,CAAyB,MAAA;EAzB/B;;;;;;AAUtB;;EAwBE,eAAA,GAAkB,4BAAA;EAxB8C;;;;;EA8BhE,iBAAA,GAAoB,iBAAA;EAMe;;;;;EAAnC,yBAAA,UAAmC,yBAAA;EA2BtB;;;;;EArBb,iCAAA,UAA2C,iCAAA;EA1CoB;;;;;EAgD/D,iCAAA,UAA2C,iCAAA;EA1C3C;;;;;;;EAkDA,aAAA,GAAgB,OAAA,CAAQ,mBAAA;EAhCN;;;;;;EAuClB,UAAA,GAAa,OAAA,CAAQ,gBAAA;EAfrB;;;;;;EAsBA,SAAA,GAAY,OAAA,CAAQ,eAAA;EAPC;;;;;EAarB,OAAA,GAAU,OAAA,CAAQ,aAAA;AAAA;;;AAwCpB;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,qBAAA,CACd,MAAA,GAAQ,qBAAA,GACP,WAAA,CAAY,oBAAA,EAAsB,sBAAA"}
+{"version":3,"file":"engine.d.ts","names":[],"sources":["../../../../../src/playback/engines/hls/engine.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;UA+EiB;;;;;EAKf,eAAe;EACf;EACA;EACA;EACA;EACA,iBAAiB;EAGjB,qBAAqB,eAAe;EACpC,0BAA0B,QAAQ;;;;;;;EAOlC,0BAA0B,QAAQ;;;;;;;;;EASlC,yBAAyB,QAAQ;;;;;;;;;;EAUjC;;;;;;;;EAQA;EACA;EACA;;;;;;;;EAQA;;;;;;;;;EASA;;;;;;;;;EASA;;;;;;;UAQe;EACf,eAAe;EACf,cAAc;EACd,mBAAmB;EACnB,mBAAmB;EACnB,0BAA0B;EAC1B,0BAA0B;EAC1B,kBAAkB;EAClB,8BAA8B;;;;;;;;KASpB;EACV,OAAO,aAAa;EACpB,SAAS,eAAe;;;;;;;;UAST,8BAA8B,mBAAmB,sBAAsB;;;;;EAKtF;;;;;;;;EAQA,eAAe;EACf;EACA;EACA;EACA;;;;;;EAMA,0BAA0B,yBAAyB;;;;;;;;;EASnD,kBAAkB;;;;;;EAMlB,oBAAoB;;;;;;EAMpB,mCAAmC;;;;;;EAMnC,2CAA2C;;;;;;EAM3C,2CAA2C;;;;;;;;EAQ3C,gBAAgB,QAAQ;;;;;;;EAOxB,aAAa,QAAQ;;;;;;;EAOrB,YAAY,QAAQ;;;;;;EAMpB,UAAU,QAAQ;;;;;;;EAOlB,WAAW,QAAQ;;;;;;;;EAQnB,WAAW;;;;;;;;;EASX,uBAAuB;;;;;;;EAOvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiDc,sBACd,SAAQ,wBACP,YAAY,sBAAsB"}