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

package/dist/dev/playback/behaviors/quality-switching.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"quality-switching.js","names":[],"sources":["../../../../src/playback/behaviors/quality-switching.ts"],"sourcesContent":["/**\n * **Manage the per-type ABR-eligible track selection slot.** While a\n * presentation is resolved, owns the slot's lifecycle: pick a default,\n * dynamically adjust based on media metrics (today: bandwidth via\n * `selectQuality`), and clear on src unload. User intent is expressed as a\n * partial-track description in a sibling slot (e.g.\n * `userVideoTrackSelection`) which constrains the candidate set for\n * selection — when the constraint narrows candidates to exactly one, the\n * choice is fully determined and ABR is short-circuited (no bandwidth read,\n * no effect re-fire on bandwidth changes).\n *\n * Lifecycle: `'presentation-unresolved'` ↔ `'presentation-resolved'`. The\n * `'presentation-resolved'` state owns the selection slot; its\n * entry-returned cleanup clears the slot on exit (canonical\n * cleanup-binds-to-setup per `reactors.md`).\n *\n * Hysteresis: downgrades apply immediately; upgrades require the optimal\n * track's bandwidth to exceed the current track's by `upgradeMargin`. No\n * temporal state — short-term smoothing is the bandwidth estimator's job.\n *\n * Initial pick is configurable via `config.picker` — pass any `TrackPicker`\n * to override the bandwidth-aware default for the empty-slot case. ABR\n * re-evaluation (downgrade/upgrade) is unaffected. Composing\n * `switchVideoQuality` with `picker: (p) => pickFirstTrackId(p, 'video')`\n * yields \"first track at load, ABR adjusts from there\" — a non-bandwidth\n * initial pick paired with bandwidth-driven re-evaluation.\n */\n\nimport { defineBehavior } from '../../core/composition/create-composition';\nimport { createMachineReactor } from '../../core/reactors/create-machine-reactor';\nimport { computed, peek, type ReadonlySignal, type Signal } from '../../core/signals/primitives';\nimport {\n  DEFAULT_QUALITY_CONFIG,\n  type QualityConfig,\n  selectLowestQuality,\n  selectQuality,\n} from '../../media/abr/quality-selection';\nimport type { TrackPicker } from '../../media/primitives/select-tracks';\nimport {\n  isResolvedPresentation,\n  type MaybeResolvedPresentation,\n  type PartiallyResolvedVideoTrack,\n  type VideoTrack,\n} from '../../media/types';\nimport { getTracksByType } from '../../media/utils/tracks';\nimport type { BandwidthConfig, BandwidthState } from '../../network/bandwidth-estimator';\nimport { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate } from '../../network/bandwidth-estimator';\n\nexport interface QualitySwitchingState {\n  presentation?: MaybeResolvedPresentation;\n  bandwidthState?: BandwidthState;\n  selectedVideoTrackId?: string;\n  /**\n   * Partial-track description expressing user intent. When set, narrows\n   * the ABR candidate set to tracks matching every present field. The\n   * common case is `{ id: 'specific-track-id' }` for a \"manual quality\"\n   * pick, but other partial shapes work — e.g., `{ height: 720 }` would\n   * constrain to 720p tracks; ABR continues to pick among them.\n   *\n   * When the narrowed candidates contain exactly one track, ABR is\n   * short-circuited entirely (no bandwidth read, no effect re-fire).\n   *\n   * When the filter matches no tracks in the current presentation (e.g.,\n   * user-picked id from a previous source doesn't exist here), falls back\n   * to the unfiltered set rather than stalling playback.\n   */\n  userVideoTrackSelection?: Partial<VideoTrack>;\n}\n\nexport interface QualitySwitchingConfig {\n  /**\n   * Quality-selection tuning. `safetyMargin` is the bandwidth-headroom\n   * multiplier; `upgradeMargin` is the hysteresis ratio gating upgrades.\n   * Defaults: `DEFAULT_QUALITY_CONFIG` (0.85 / 1.15).\n   */\n  quality?: Partial<QualityConfig>;\n\n  /**\n   * Bandwidth-estimator tuning passed through to `getBandwidthEstimate`.\n   * Merged over `DEFAULT_BANDWIDTH_CONFIG`.\n   */\n  bandwidth?: Partial<BandwidthConfig>;\n\n  /**\n   * Bandwidth estimate in bps to use before enough samples have been collected.\n   * Default: 5_000_000 (5 Mbps).\n   */\n  initialBandwidth?: number;\n\n  /**\n   * Override the initial-pick algorithm. When set, the picker is called the\n   * first time the slot is empty in the `'presentation-resolved'` state;\n   * its returned id is set verbatim (no bandwidth-aware logic). Subsequent\n   * ABR re-evaluation (downgrade/upgrade by bandwidth + hysteresis) is\n   * unaffected and runs as usual.\n   *\n   * Default (no picker): a bandwidth-aware initial pick driven by\n   * `initialBandwidth` and `quality.safetyMargin`, identical to ABR's\n   * downgrade branch.\n   *\n   * Honors of `userVideoTrackSelection` are the picker's responsibility\n   * when overridden. If the picker returns `undefined`, the bandwidth-aware\n   * default pick fires (graceful fallback).\n   */\n  picker?: TrackPicker<QualitySwitchingConfig>;\n}\n\n/** Default initial-bandwidth value used by quality-switching variants before measurements arrive. */\nexport const DEFAULT_INITIAL_BANDWIDTH = 5_000_000;\n\n// ============================================================================\n// Specialization helper\n//\n// `setupQualitySwitching` has the same shape as a Behavior `setup` function:\n// `({ state, config }) => Reactor`. Each `switchXQuality` export below calls\n// it from inside its own `defineBehavior` setup, passing the per-type slot\n// keys, track type, and selection algorithm explicitly via three generic\n// parameters — `S` (selection slot key), `U` (user-selection slot key), `T`\n// (ABR track type). The per-type export is the single point that ties them\n// together; the helper stays slot-agnostic.\n//\n// -- Design note: why narrow `SelectionKey` / `UserSelectionKey` unions ----\n// Goal we did not reach: have callers \"fully pass in\" the slot keys, with\n// the helper enforcing zero internal knowledge of which literals are valid.\n// What blocks it: indexing a mapped-type intersection by a generic key.\n// When `S extends keyof QualitySwitchingState` (or `string`), TS conservatively\n// treats `state[selectionKey]` as the union of every possible match across\n// the intersected mapped portions — including the fixed-key signals\n// (`presentation`, `bandwidthState`) — and widens to their value-type union.\n// The sibling pattern hits the same constraint and answers it the same way:\n// `SelectedTrackKey` in `select-tracks.ts:43` is a hardcoded narrow union\n// for the same reason.\n//\n// Routes considered for \"fully passed in\", with trade-offs (left here for\n// the larger-group conversation):\n//\n//   A. Derived constraint — `Exclude<keyof QualitySwitchingState, 'presentation'\n//      | 'bandwidthState'>`. Removes the literal enumeration; same narrowness,\n//      computed from the state shape. Still \"knows\" the fixed-key names.\n//   B. Broad constraint (`S extends keyof QualitySwitchingState`) + access-site\n//      casts (`state[selectionKey] as Signal<string | undefined>` at the top\n//      of the helper). Caller passes any keys; the type system stops checking\n//      S ≠ U or that the keys actually refer to selection slots. Once you\n//      cast at the top, the body is structurally the original remap pattern\n//      with extra ceremony.\n//   C. Remap pattern (pre-refactor) — caller passes signals under logical\n//      names (`selection`, `userSelection`); helper has no key generics.\n//      Cleanest types; inconsistent with the sibling helpers.\n//\n// Current pick is the narrow-union route because it matches siblings and\n// the unions read as documentation (\"these are the slots this helper\n// manages\") rather than restriction. Extending for audio is one literal\n// per union.\n// --------------------------------------------------------------------------\n// ============================================================================\n\ntype AbrTrack = { id: string; bandwidth: number };\n\ntype SelectionKey = 'selectedVideoTrackId';\ntype UserSelectionKey = 'userVideoTrackSelection';\n\n// Each mapped value references `P` so TS keeps the per-key dependency and\n// resolves `state[selectionKey]` / `state[userSelectionKey]` to the right\n// arm. `T` (track type) deliberately stays out of the state map — pulling\n// it in detaches the user-selection mapped value from `P` and TS collapses\n// the intersection. T flows through `QualitySwitchingSetupConfig` instead;\n// the user-filter access casts at the read site (see below).\ntype QualitySwitchingStateMap<S extends SelectionKey, U extends UserSelectionKey> = {\n  presentation: ReadonlySignal<QualitySwitchingState['presentation']>;\n  bandwidthState: ReadonlySignal<QualitySwitchingState['bandwidthState']>;\n} & { [P in S]: Signal<QualitySwitchingState[P]> } & { [P in U]: ReadonlySignal<QualitySwitchingState[P]> };\n\ninterface QualitySwitchingSetupConfig<S extends SelectionKey, U extends UserSelectionKey, T extends AbrTrack>\n  extends QualitySwitchingConfig {\n  selectionKey: S;\n  userSelectionKey: U;\n  getTracks: (presentation: MaybeResolvedPresentation) => readonly T[];\n  selectOptimal: (\n    tracks: readonly T[],\n    bandwidth: number,\n    opts: { safetyMargin: number; upgradeMargin: number; currentTrack?: T }\n  ) => T | undefined;\n}\n\nfunction setupQualitySwitching<S extends SelectionKey, U extends UserSelectionKey, T extends AbrTrack>({\n  state,\n  config,\n}: {\n  state: QualitySwitchingStateMap<S, U>;\n  config: QualitySwitchingSetupConfig<S, U, T>;\n}) {\n  const safetyMargin = config.quality?.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;\n  const upgradeMargin = config.quality?.upgradeMargin ?? DEFAULT_QUALITY_CONFIG.upgradeMargin;\n  const initialBandwidth = config.initialBandwidth ?? DEFAULT_INITIAL_BANDWIDTH;\n  const bandwidthConfig: BandwidthConfig = { ...DEFAULT_BANDWIDTH_CONFIG, ...config.bandwidth };\n  const { selectionKey, userSelectionKey, getTracks, selectOptimal } = config;\n\n  const derivedStateSignal = computed(() =>\n    isResolvedPresentation(state.presentation.get())\n      ? ('presentation-resolved' as const)\n      : ('presentation-unresolved' as const)\n  );\n\n  return createMachineReactor({\n    initial: 'presentation-unresolved',\n    monitor: () => derivedStateSignal.get(),\n    states: {\n      'presentation-unresolved': {},\n      'presentation-resolved': {\n        // Canonical cleanup-binds-to-setup: the selection slot's valid\n        // lifespan is exactly 'presentation-resolved'. Clear fires on\n        // 'presentation-resolved' exit, covering both src unload and\n        // behavior destroy.\n        entry: () => () => state[selectionKey].set(undefined),\n        effects: [\n          () => {\n            const presentation = peek(state.presentation);\n            if (!presentation) return;\n\n            const allTracks = getTracks(presentation);\n            const [firstAllTrack] = allTracks;\n            if (!firstAllTrack) return;\n\n            // State stores the filter as `Partial<VideoTrack>` (user-facing\n            // shape — includes V-only fields like `height`); the helper\n            // works against `Partial<T>` so filter and track access share\n            // one index type. Filter keys absent on a partially-resolved\n            // track read as `undefined` and just exclude that track.\n            const userFilter = state[userSelectionKey].get() as Partial<T> | undefined;\n            const matching = userFilter\n              ? allTracks.filter((track) => {\n                  for (const key in userFilter) {\n                    const filterValue = userFilter[key as keyof T];\n                    if (filterValue !== undefined && track[key as keyof T] !== filterValue) return false;\n                  }\n                  return true;\n                })\n              : allTracks;\n            // Fall back to all tracks when the filter excludes everything\n            // (e.g., user-picked id doesn't exist in the current source).\n            const candidates = matching.length > 0 ? matching : allTracks;\n            if (!candidates.length) return;\n\n            const selectedId = state[selectionKey].get();\n\n            // Common case: user has fully constrained the choice (e.g.,\n            // `{ id: 'specific-720p' }` narrows to a single track). Skip\n            // the ABR path — and crucially, don't read `bandwidthState`\n            // so the effect doesn't re-fire on bandwidth changes while\n            // the user's selection holds.\n            if (candidates.length === 1) {\n              if (candidates[0]!.id !== selectedId) state[selectionKey].set(candidates[0]!.id);\n              return;\n            }\n\n            // Read bandwidth up front to establish the signal subscription —\n            // future bandwidth changes must re-fire this effect even when\n            // the picker branch below takes the early-return path. (If the\n            // picker bails out without ever touching `bandwidthState`, ABR\n            // would otherwise be deaf to subsequent bandwidth changes.)\n            //\n            // Single path for pre-trust and post-trust:\n            // `getBandwidthEstimate` returns `initialBandwidth` when state\n            // is undefined or bytes sampled hasn't crossed `minTotalBytes`,\n            // so the initial pick + early-ABR window run the same\n            // `selectOptimal` path as a fully-trusted measurement.\n            const bandwidth = getBandwidthEstimate(state.bandwidthState.get(), initialBandwidth, bandwidthConfig);\n\n            // Picker-driven initial pick: when the slot is empty and the\n            // caller supplied a `picker`, defer to it instead of the\n            // bandwidth-aware default. The picker sees the full\n            // presentation (not narrowed by `userVideoTrackSelection`) —\n            // honoring the filter is the picker's responsibility when\n            // overridden. Returning `undefined` falls through to the\n            // bandwidth-aware default (graceful fallback).\n            //\n            // ABR re-evaluation (downgrade/upgrade by bandwidth) runs as\n            // usual on subsequent effect re-runs once the slot is set.\n            if (!selectedId && config.picker) {\n              const id = config.picker(presentation, config);\n              if (id) {\n                state[selectionKey].set(id);\n                return;\n              }\n            }\n            // `selectOptimal` decides the track to apply now given current\n            // selection + bandwidth + tuning. It returns:\n            //   - the optimal when no current track or on a downgrade\n            //   - the optimal when an upgrade clears `upgradeMargin`\n            //   - the current track itself when an upgrade doesn't clear margin\n            //     (caller's id-compare below no-ops in that case)\n            // Outer `?? selectLowestQuality` is defensive — `selectQuality` falls\n            // back to lowest internally; this catches future impls that don't.\n            // `selectLowestQuality` returns `undefined` only on empty input,\n            // and `candidates.length >= 2` here.\n            const currentTrack = candidates.find((t) => t.id === selectedId);\n            const optimal =\n              selectOptimal(candidates, bandwidth, { safetyMargin, upgradeMargin, currentTrack }) ??\n              selectLowestQuality(candidates)!;\n            if (optimal.id !== selectedId) state[selectionKey].set(optimal.id);\n          },\n        ],\n      },\n    },\n  });\n}\n\n// ============================================================================\n// Specialized exports — one per ABR-enabled track type\n// ============================================================================\n\n/**\n * Manage `selectedVideoTrackId`: pick a default on src load, dynamically\n * adjust based on bandwidth, clear on src unload. Honors\n * `userVideoTrackSelection` as a partial-track constraint on candidates;\n * short-circuits ABR when the constraint narrows to a single track.\n *\n * @example\n * const reactor = switchVideoQuality.setup({ state });\n */\nexport const switchVideoQuality = defineBehavior({\n  stateKeys: ['presentation', 'bandwidthState', 'selectedVideoTrackId', 'userVideoTrackSelection'],\n  contextKeys: [],\n  setup: ({\n    state,\n    config,\n  }: {\n    state: QualitySwitchingStateMap<'selectedVideoTrackId', 'userVideoTrackSelection'>;\n    config?: QualitySwitchingConfig;\n  }) =>\n    setupQualitySwitching<'selectedVideoTrackId', 'userVideoTrackSelection', PartiallyResolvedVideoTrack | VideoTrack>({\n      state,\n      config: {\n        ...config,\n        selectionKey: 'selectedVideoTrackId',\n        userSelectionKey: 'userVideoTrackSelection',\n        getTracks: (presentation) =>\n          getTracksByType(presentation, 'video') as readonly (PartiallyResolvedVideoTrack | VideoTrack)[],\n        selectOptimal: selectQuality,\n      },\n    }),\n});\n"],"mappings":";;;;;;;AAwLA,SAAS,sBAA8F,EACrG,OACA,UAIC;CACD,MAAM,eAAe,OAAO,SAAS,gBAAgB,uBAAuB;CAC5E,MAAM,gBAAgB,OAAO,SAAS,iBAAiB,uBAAuB;CAC9E,MAAM,mBAAmB,OAAO,oBAAA;CAChC,MAAM,kBAAmC;EAAE,GAAG;EAA0B,GAAG,OAAO;EAAW;CAC7F,MAAM,EAAE,cAAc,kBAAkB,WAAW,kBAAkB;CAErE,MAAM,qBAAqB,eACzB,uBAAuB,MAAM,aAAa,KAAK,CAAC,GAC3C,0BACA,0BACN;AAED,QAAO,qBAAqB;EAC1B,SAAS;EACT,eAAe,mBAAmB,KAAK;EACvC,QAAQ;GACN,2BAA2B,EAAE;GAC7B,yBAAyB;IAKvB,mBAAmB,MAAM,cAAc,IAAI,KAAA,EAAU;IACrD,SAAS,OACD;KACJ,MAAM,eAAe,KAAK,MAAM,aAAa;AAC7C,SAAI,CAAC,aAAc;KAEnB,MAAM,YAAY,UAAU,aAAa;KACzC,MAAM,CAAC,iBAAiB;AACxB,SAAI,CAAC,cAAe;KAOpB,MAAM,aAAa,MAAM,kBAAkB,KAAK;KAChD,MAAM,WAAW,aACb,UAAU,QAAQ,UAAU;AAC1B,WAAK,MAAM,OAAO,YAAY;OAC5B,MAAM,cAAc,WAAW;AAC/B,WAAI,gBAAgB,KAAA,KAAa,MAAM,SAAoB,YAAa,QAAO;;AAEjF,aAAO;OACP,GACF;KAGJ,MAAM,aAAa,SAAS,SAAS,IAAI,WAAW;AACpD,SAAI,CAAC,WAAW,OAAQ;KAExB,MAAM,aAAa,MAAM,cAAc,KAAK;AAO5C,SAAI,WAAW,WAAW,GAAG;AAC3B,UAAI,WAAW,GAAI,OAAO,WAAY,OAAM,cAAc,IAAI,WAAW,GAAI,GAAG;AAChF;;KAcF,MAAM,YAAY,qBAAqB,MAAM,eAAe,KAAK,EAAE,kBAAkB,gBAAgB;AAYrG,SAAI,CAAC,cAAc,OAAO,QAAQ;MAChC,MAAM,KAAK,OAAO,OAAO,cAAc,OAAO;AAC9C,UAAI,IAAI;AACN,aAAM,cAAc,IAAI,GAAG;AAC3B;;;KAcJ,MAAM,UACJ,cAAc,YAAY,WAAW;MAAE;MAAc;MAAe,cAFjD,WAAW,MAAM,MAAM,EAAE,OAAO,WAAW;MAEoB,CAAC,IACnF,oBAAoB,WAAW;AACjC,SAAI,QAAQ,OAAO,WAAY,OAAM,cAAc,IAAI,QAAQ,GAAG;MAErE;IACF;GACF;EACF,CAAC;;;;;;;;;;;AAgBJ,MAAa,qBAAqB,eAAe;CAC/C,WAAW;EAAC;EAAgB;EAAkB;EAAwB;EAA0B;CAChG,aAAa,EAAE;CACf,QAAQ,EACN,OACA,aAKA,sBAAmH;EACjH;EACA,QAAQ;GACN,GAAG;GACH,cAAc;GACd,kBAAkB;GAClB,YAAY,iBACV,gBAAgB,cAAc,QAAQ;GACxC,eAAe;GAChB;EACF,CAAC;CACL,CAAC"}

package/dist/dev/playback/behaviors/track-types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"track-types.js","names":[],"sources":["../../../../src/playback/behaviors/track-types.ts"],"sourcesContent":["/**\n * **Per-type config bundles for per-type behavior variants.**\n *\n * Each `*_TYPE_CONFIG` constant names the per-type slot keys that\n * per-type-variant setup-shape helpers consume. Variants reference the\n * shared constant at their `defineBehavior` setup body rather than\n * constructing the config inline, so the per-type identity (which state\n * slot, which context slot, which discriminant) lives in one place per\n * type.\n *\n * Variants spread their composition-time `config` over the defaults so\n * engines can layer composition-supplied additions on top (e.g. a\n * custom fetch closure, a non-default segment resolver). Defaults\n * first, engine config second.\n *\n * Helpers continue to consume their slice via the existing typed-key\n * generics (`<K extends SelectedTrackKey>` etc.); the extra fields on\n * the config object (carrying facets other helpers care about) are fine\n * under structural typing.\n */\n\n/**\n * Type-identity bundle for video-track-typed behaviors.\n *\n * @see setupVideoBufferActors, loadVideoSegments\n */\nexport const VIDEO_TYPE_CONFIG = {\n  type: 'video',\n  selectedKey: 'selectedVideoTrackId',\n  actorKey: 'videoBufferActor',\n  loaderKey: 'videoSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for audio-track-typed behaviors.\n *\n * @see setupAudioBufferActors, loadAudioSegments\n */\nexport const AUDIO_TYPE_CONFIG = {\n  type: 'audio',\n  selectedKey: 'selectedAudioTrackId',\n  actorKey: 'audioBufferActor',\n  loaderKey: 'audioSegmentLoaderActor',\n} as const;\n\n/**\n * Type-identity bundle for text-track-typed behaviors. Text tracks have\n * no `SourceBufferActor` (MSE doesn't apply), so this bundle omits\n * `actorKey`. The `loaderKey` points at the text-track-segment-loader\n * actor (a `MessageActor` with continue-vs-preempt semantics, parallel\n * to v/a's `SegmentLoaderActor`).\n *\n * @see loadTextTrackSegments, setupTextTrackActors\n */\nexport const TEXT_TYPE_CONFIG = {\n  type: 'text',\n  selectedKey: 'selectedTextTrackId',\n  loaderKey: 'textTrackSegmentLoaderActor',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;CACZ;;;;;;AAOD,MAAa,oBAAoB;CAC/B,MAAM;CACN,aAAa;CACb,UAAU;CACV,WAAW;CACZ;;;;;;;;;;AAWD,MAAa,mBAAmB;CAC9B,MAAM;CACN,aAAa;CACb,WAAW;CACZ"}