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

package/dist/dev/playback/behaviors/track-switching.d.ts

@@ -0,0 +1,110 @@
+import { MaybeResolvedPresentation } from "../../media/types/index.js";
+import { ReadonlySignal, Signal } from "../../core/signals/primitives.js";
+import { AnySlotMap } from "../../core/composition/create-composition.js";
+import "../../index.js";
+import { CodecPreferenceConfig, DEFAULT_PREFERRED_CODECS, SelectionRule, SelectionRuleDeps, preferCodecFamilies } from "../primitives/selection-rules.js";
+import "./collect-errors.js";
+//#region src/playback/behaviors/track-switching.d.ts
+/**
+ * The slots `setupTrackSwitching` itself owns: the `presentation` gate it reads and the per-type `selected*TrackId` it
+ * writes. Rule-only inputs are deliberately absent — `user*TrackSelection` and `bandwidthState` belong to whoever
+ * materializes them (the embedder via `shareSignals`, the buffer-actor sampler), and each rule declares the signal it
+ * consults as an optional slot on its own deps map, so the behavior never assumes a rule's signal exists.
+ */
+interface TrackSwitchingState {
+  presentation?: MaybeResolvedPresentation;
+  selectedVideoTrackId?: string;
+  selectedAudioTrackId?: string;
+  selectedTextTrackId?: string;
+}
+/**
+ * Minimum candidate-track shape consumed by the helper and its rules: an `id` (the pick), a `url` (the active-CDN scope
+ * derives the CDN from it), an optional `bandwidth` (the ranker's throughput sort), and optional `width`/`height` (the
+ * ranker's equal-bitrate tie-break — absent on audio, so audio candidates area-compare equal). Every
+ * resolved/partially-resolved video track carries them all; audio tracks omit the dimensions.
+ */
+type SwitchableTrack = {
+  id: string;
+  url: string;
+  bandwidth?: number;
+  width?: number;
+  height?: number;
+  mimeType?: string;
+  codecs?: string[];
+};
+/**
+ * Map the rule chain's surviving candidates to the final selection id, or `undefined` for a deliberate no-selection.
+ * Defaults to the chain head (`selectChainHead`) — the always-pick contract video and audio rely on (`applyRules`
+ * guarantees a non-empty result, so the head is always there). A variant whose selection is legitimately optional
+ * (text: opt-in captions, explicit off) supplies its own picker that may return `undefined`; the helper writes that
+ * straight through to the slot, clearing it.
+ */
+type ResolveSelection<T extends SwitchableTrack, State = unknown, Context = unknown, Config = unknown> = (candidates: readonly T[], deps: SelectionRuleDeps<State, Context, Config>) => string | undefined;
+type SelectionKey = 'selectedVideoTrackId' | 'selectedAudioTrackId' | 'selectedTextTrackId';
+type TrackSwitchingStateMap<S extends SelectionKey> = {
+  presentation: ReadonlySignal<TrackSwitchingState['presentation']>;
+} & { [P in S]: Signal<TrackSwitchingState[P]>; };
+/**
+ * Config `setupTrackSwitching` itself reads — its own wiring: which selection slot to write and clear (`selectionKey`),
+ * how to enumerate candidate tracks (`getTracks`), the optional **hard-constraints pre-pass** (`constraints`, applied
+ * before the chain to prune the unplayable), and the **rule chain** to run (`rules`), and how to map the chain's
+ * survivors to the final pick (`resolveSelection`, defaulting to the chain head). Rule-/constraint-specific config is
+ * deliberately absent — each declares the fields it reads as _optional_ on its own config view (`UserSelectionConfig`,
+ * `BandwidthRankerConfig`), so the behavior never enumerates them. The variant builds the concrete config as this base
+ * plus whatever its chain consults; it flows through untouched as the `C` type param on `setupTrackSwitching`.
+ */
+interface TrackSwitchingConfig<S extends SelectionKey, T extends SwitchableTrack> {
+  selectionKey: S;
+  getTracks: (presentation: MaybeResolvedPresentation) => readonly T[];
+  constraints?: readonly SelectionRule<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>[];
+  rules: readonly SelectionRule<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>[];
+  /**
+   * Map the chain's surviving candidates to the final selection id. Optional — absent means the chain head
+   * (`selectChainHead`), the always-pick path video and audio use. A variant with optional selection (text) supplies
+   * one that may return `undefined`.
+   */
+  resolveSelection?: ResolveSelection<T, TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>;
+  /**
+   * SVTA code to report when this type _has_ tracks but the constraints pruned every one. Per-variant because the
+   * condition isn't universally an error: video and audio supply {@link SVTA_NO_SUPPORTED_VIDEO_TRACK} /
+   * {@link SVTA_NO_SUPPORTED_AUDIO_TRACK}, while text supplies none — an unavailable subtitle track is a legitimate
+   * outcome, not a playback failure. Absent → the selection still clears, nothing is reported.
+   */
+  noSupportedTrackCode?: number;
+}
+/**
+ * Codec-family sticky constraint — a _hard_ filter for the constraints pre-pass, shared by video and audio, and the
+ * reason the re-evaluating variants can run ABR over a mixed-codec source at all: SPF implements no
+ * `SourceBuffer.changeType()`, so once segments of the selected track's codec families are what a buffer was created
+ * for, a pick outside them could never play — constraint semantics ("can't play here"), not preference. Removes the
+ * candidates whose codec-family set doesn't _equal_ the selected track's (set-equality so a muxed `hvc1,mp4a` rendition
+ * can't pass as a match for `avc1,mp4a` on its audio half). Purely relational: the lock _is_ the current selection's
+ * families, no state of its own. Pruned pre-pass, a cross-family user selection mid-stream never reaches the user
+ * filter, which falls through unhonored instead of killing playback. Before any selection exists (the initial pick) it
+ * removes nothing, which is what leaves the initial family choice to the rule chain (user intent, then
+ * `preferCodecFamilies`).
+ *
+ * The selected track's families come from the _presentation's_ track list, not the already-pruned candidates: a CDN
+ * entering cooldown may prune the current track itself while same-family renditions survive on another host, and the
+ * lock must carry over to them. Removes nothing when: no selection yet, a selection the presentation no longer carries,
+ * or a selected track without codecs (then no candidate's compatibility is decidable — same inertness as
+ * `preferCodecFamilies` on a codec-less ladder).
+ *
+ * When the selected family genuinely vanishes from the playable set, the pre-pass empties: the behavior reports the
+ * type's no-supported-track code and clears the selection — an explicable stop instead of a cross-family append
+ * surfacing as an opaque decode error. Clearing also releases the lock (it keys on the live selection), so a following
+ * pick may land in the surviving family on freshly-created buffer actors; whether the append layer survives that
+ * rebuild is the changeType gap, out of this constraint's hands. If `changeType` support ever lands, this constraint is
+ * what relaxes.
+ *
+ * Reading the selection here — a slot the picking effect itself writes, from inside the candidate-set computed — is
+ * safe only because the effect scheduler revalidates an effect's sources after each run; see `core/signals/effect.ts`
+ * (`revalidateSources`) for the lost-wakeup it prevents.
+ *
+ * Composed only into the re-evaluating `switch*` variants: the pinned `selectVideoTrack` (background compositions)
+ * evaluates once and never re-picks, so it's immune by construction.
+ */
+declare function stickToSelectedCodecs<S extends SelectionKey, T extends SwitchableTrack>(tracks: readonly T[], { state, config }: SelectionRuleDeps<TrackSwitchingStateMap<S>, AnySlotMap, TrackSwitchingConfig<S, T>>): readonly T[];
+//#endregion
+export { ResolveSelection, TrackSwitchingState, TrackSwitchingStateMap, stickToSelectedCodecs };
+//# sourceMappingURL=track-switching.d.ts.map

package/dist/dev/playback/behaviors/track-switching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-switching.d.ts","names":[],"sources":["../../../../src/playback/behaviors/track-switching.ts"],"mappings":";;;;;;;;;;;;;UAyGiB;EACf,eAAe;EACf;EACA;EACA;;;;;;;;KAyFG;EACH;EACA;EACA;EACA;EACA;EAIA;EACA;;;;;;;;;KAUU,iBAAiB,UAAU,iBAAiB,iBAAiB,mBAAmB,qBAC1F,qBAAqB,KACrB,MAAM,kBAAkB,OAAO,SAAS;KAGrC;KAeO,uBAAuB,UAAU;EAC3C,cAAc,eAAe;OACxB,KAAK,IAAI,OAAO,oBAAoB;;;;;;;;;;UAkBjC,qBAAqB,UAAU,cAAc,UAAU;EAC/D,cAAc;EACd,YAAY,cAAc,uCAAuC;EACjE,uBAAuB,cAAc,GAAG,uBAAuB,IAAI,YAAY,qBAAqB,GAAG;EACvG,gBAAgB,cAAc,GAAG,uBAAuB,IAAI,YAAY,qBAAqB,GAAG;;;;;;EAMhG,mBAAmB,iBAAiB,GAAG,uBAAuB,IAAI,YAAY,qBAAqB,GAAG;;;;;;;EAOtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwOc,sBAAsB,UAAU,cAAc,UAAU,iBACtE,iBAAiB,OACf,OAAO,UAAU,kBAAkB,uBAAuB,IAAI,YAAY,qBAAqB,GAAG,eAC1F"}