@videojs/spf 10.0.0-beta.9 → 10.0.0-rc.2

package/dist/dev/media/types/index.d.ts

@@ -0,0 +1,306 @@
+//#region src/media/types/index.d.ts
+/**
+ * Core SPF Types
+ *
+ * Based on CMAF-HAM (Common Media Application Format - Hypothetical Application Model) Protocol-agnostic representation
+ * of streaming media content.
+ *
+ * @see https://github.com/streaming-video-technology-alliance/common-media-library
+ */
+/** Base identifier type for all HAM objects. */
+interface Ham {
+  id: string;
+  /**
+   * Format-/protocol-specific values that aren't part of the generic CMAF-HAM model — kept in an open bag so the model
+   * stays format-neutral (mirrors how CMAF-HAM itself stashes protocol extras rather than growing the model). Typed
+   * reads go through dedicated accessors (e.g. `getMediaPlaylistMetadata`).
+   */
+  metadata?: Record<string, unknown>;
+}
+/** Addressable resource with optional byte range. */
+interface AddressableObject {
+  url: string;
+  byteRange?: {
+    start: number;
+    end: number;
+  };
+}
+/** Time span with start time and duration. Used for segments and other timed ranges. */
+interface TimeSpan {
+  startTime: number;
+  duration: number;
+}
+/** Track content type. */
+type TrackType = 'video' | 'audio' | 'text';
+/**
+ * Video frame rate expressed as numerator/denominator.
+ *
+ * Examples: - 30 fps: { frameRateNumerator: 30 } - 29.97 fps: { frameRateNumerator: 30000, frameRateDenominator: 1001 }
+ */
+interface FrameRate {
+  frameRateNumerator: number;
+  frameRateDenominator?: number;
+}
+/**
+ * Generic type for partially resolved tracks. Removes fields that come from media playlist parsing.
+ *
+ * @param T - Track type to make partially resolved (must extend Track)
+ */
+type PartiallyResolved<T extends Track = Track> = Omit<T, 'segments' | 'initialization' | keyof TimeSpan> & {
+  segments?: never;
+  duration?: never;
+  startTime?: never;
+  initialization?: never;
+};
+/**
+ * Base track type containing common properties for all resolved tracks. A resolved track has segments, duration, and
+ * initialization data. All URLs are fully qualified (parsers resolve relative URLs).
+ */
+/**
+ * Track startTime is always 0 — the presentation-timeline origin (and future multi-period base). The live
+ * sliding-window edge is `segments[0].startTime`, derived — never stored here.
+ */
+type Track = Ham & AddressableObject & TimeSpan & {
+  type: TrackType;
+  codecs?: string[];
+  mimeType: string;
+  language?: string | undefined;
+  bandwidth: number;
+  initialization?: AddressableObject;
+  segments: Segment[];
+  /**
+   * Media-timeline (decode/encode) coordinate of the track's timeline origin (presentation-0) — the media-time base
+   * value of the coordinate model, peer to `startTime` (presentation). Derived from the container
+   * (`tfdt.baseMediaDecodeTime ÷ mdhd.timescale`); the relocation offset is `−startMediaTime` (targets presentation-0
+   * — `Track.startTime` plays no part), never stored.
+   *
+   * Optional: `undefined` means not yet established, or never establishable (e.g. text tracks carry no container
+   * origin); a near-zero/native origin is established as `0` (no relocation). Established once per source by the
+   * `establishStartMediaTime` reactor. See `internal/design/spf/presentation-timeline-model.md`.
+   */
+  startMediaTime?: number;
+  /**
+   * Wall-clock time (epoch seconds) at the track's timeline origin (presentation-0) — pure playlist arithmetic over
+   * any PDT-bearing segment: `segment.startDate − segment.startTime`, invariant along a linear timeline. Optional:
+   * absent when no segment carries `startDate`.
+   *
+   * The wall-clock member of the coordinate triple (peer to `startTime` and `startMediaTime`). For live it is the
+   * anchor segments are PDT-placed against on every parse; equal `startDate` across tracks marks the same
+   * presentation instant. See `internal/design/spf/live-presentation-timeline-model.md`.
+   */
+  startDate?: number;
+};
+/**
+ * Per-track-type origin-establishment data, accumulated across appends (the media track's `track_id` + `mdhd` timescale
+ * from the init, `tfdt` baseMediaDecodeTime of that same track from the first media segment) — hence optional. The
+ * transient input the `establishStartMediaTime` reactor reduces into `Track.startMediaTime`.
+ *
+ * `trackId` is the ISO-BMFF `track_ID` of the buffered media track (`vide`/`soun`), read from the init's `tkhd`; it
+ * ties the timescale to the _same_ track's `baseMediaDecodeTime` (matched via `tfhd.track_id`) so a muxed segment
+ * carrying a second track (e.g. `clcp` captions) reads the right `tfdt` rather than the first one.
+ *
+ * `segmentStartTime` is the 0-based presentation start of the segment `baseMediaDecodeTime` was read from — _not_ a
+ * container value (it's the playlist position), but co-located because the origin is `baseMediaDecodeTime/timescale −
+ * segmentStartTime`: the first _loaded_ segment isn't necessarily the 0th (a non-zero initial `currentTime`, or
+ * live/DVR), so the decode time alone isn't the stream origin.
+ */
+interface MediaContainerData {
+  trackId?: number;
+  timescale?: number;
+  baseMediaDecodeTime?: number;
+  segmentStartTime?: number;
+}
+/**
+ * Raw media-segment bytes — a complete buffer or a byte stream. The transport-neutral payload the loader pipeline
+ * carries; `AppendData` (the MSE `SourceBuffer` append input in `media/dom/mse`) is an alias of this at the DOM
+ * boundary.
+ */
+type SegmentData = ArrayBuffer | AsyncIterable<Uint8Array>;
+/** Resolved video track with segments. */
+type VideoTrack = Track & Required<Pick<Track, 'initialization' | 'codecs'>> & {
+  type: 'video';
+  width?: number;
+  height?: number;
+  frameRate?: FrameRate;
+  /**
+   * Audio groups (`EXT-X-STREAM-INF:AUDIO`) this video rendition can pair with. A list because one rendition is
+   * typically listed across multiple `EXT-X-STREAM-INF` entries — one per audio group (the HLS cross-product) — which
+   * the parser collapses into a single track carrying every group it advertised.
+   */
+  audioGroupIds?: string[];
+};
+/** Resolved audio track with segments. */
+type AudioTrack = Track & Required<Pick<Track, 'initialization' | 'codecs'>> & {
+  type: 'audio';
+  groupId: string;
+  name: string;
+  sampleRate: number;
+  channels: number;
+  default?: boolean;
+  autoselect?: boolean;
+};
+/** Resolved text track with segments. */
+type TextTrack = Track & {
+  type: 'text';
+  groupId: string;
+  label: string;
+  kind: 'subtitles' | 'captions';
+  default?: boolean;
+  autoselect?: boolean;
+  forced?: boolean;
+};
+/**
+ * Predicate that answers "can this environment decode this track?" — the capability-probing surface, read by the
+ * track-switching hard-constraint pre-pass (`excludeUnplayableTracks`) to drop undecodable renditions before selection.
+ * Kept DOM-free here (a plain function type over a minimal track shape) so DOM-free behaviors can consume it; the DOM
+ * implementation (`canPlayTrack` in `media/dom/capabilities.ts`) wraps `MediaSource.isTypeSupported`.
+ *
+ * Takes the minimal codec-bearing shape both video and audio candidates carry. `mimeType` is optional so unprobeable
+ * candidates (no MIME) can be passed straight through as playable rather than dropped.
+ */
+type CanPlayTrack = (track: {
+  mimeType?: string;
+  codecs?: string[];
+  metadata?: Record<string, unknown>;
+}) => boolean;
+/**
+ * Minimal text-track cue shape — start time, end time, and display text.
+ *
+ * Host-agnostic representation. `VTTCue` structurally satisfies this interface, so DOM consumers pass `VTTCue` values
+ * directly. Non-DOM hosts (workers, test fakes, non-browser engines) can satisfy the same shape without pulling in DOM
+ * types.
+ */
+interface Cue {
+  startTime: number;
+  endTime: number;
+  text: string;
+}
+/**
+ * Partially resolved text track from multivariant playlist. Has metadata but no segments or initialization yet (media
+ * playlist not fetched).
+ */
+type PartiallyResolvedTextTrack = PartiallyResolved<TextTrack>;
+/** Union of all resolved track types. */
+type ResolvedTrack = VideoTrack | AudioTrack | TextTrack;
+/**
+ * Generic switching set type. A group of tracks that can be switched between seamlessly.
+ *
+ * @param T - Track type (VideoTrack, AudioTrack, or TextTrack)
+ */
+type SwitchingSetOf<T extends Track = Track> = Ham & {
+  type: T['type'];
+  tracks: (PartiallyResolved<T> | T)[];
+};
+/**
+ * Generic selection set type. Groups switching sets by track type.
+ *
+ * @param T - Track type (VideoTrack, AudioTrack, or TextTrack)
+ */
+type SelectionSetOf<T extends Track = Track> = Ham & {
+  type: T['type'];
+  switchingSets: SwitchingSetOf<T>[];
+};
+/** Video selection set - contains only video switching sets. */
+type VideoSelectionSet = SelectionSetOf<VideoTrack>;
+/** Audio selection set - contains only audio switching sets. */
+type AudioSelectionSet = SelectionSetOf<AudioTrack>;
+/** Text selection set - contains only text switching sets. */
+type TextSelectionSet = SelectionSetOf<TextTrack>;
+/** Selection set - groups switching sets by track type. Discriminated union ensures type-safe track access. */
+type SelectionSet = VideoSelectionSet | AudioSelectionSet | TextSelectionSet;
+/**
+ * Media segment with timing information. Follows CMAF-HAM composition pattern.
+ *
+ * `startDate` is the absolute wall-clock time of the segment's first sample, in **epoch seconds** (unit-consistent with
+ * `startTime`/`duration`), derived from `#EXT-X-PROGRAM-DATE-TIME` (explicit or interpolated forward via `EXTINF`).
+ * Unlike the per-track-relative `startTime`, it is comparable across tracks, so it is the cross-track sync anchor for
+ * demuxed audio/video and the exact recovery value on a full live-window turnover. Optional: absent when the source
+ * carries no PDT (allowed by RFC 8216, required by Apple's HLS authoring spec — so present on conformant content).
+ */
+type Segment = Ham & AddressableObject & TimeSpan & {
+  startDate?: number;
+};
+/**
+ * Playlist-level metadata surfaced from a parsed media playlist. HLS delivery specifics — not part of the generic
+ * CMAF-HAM model — so they live under `Ham.metadata` (read via `getMediaPlaylistMetadata`) rather than as first-class
+ * `Track` fields:
+ *
+ * - `targetDuration` (`#EXT-X-TARGETDURATION`) — reload-cadence basis.
+ * - `mediaSequence` (`#EXT-X-MEDIA-SEQUENCE`, default 0) — sequence number of `segments[0]`; the join key for merging
+ *   successive reload snapshots.
+ * - `playlistType` (`#EXT-X-PLAYLIST-TYPE`) — `VOD` / `EVENT` / undefined.
+ * - `endList` (`#EXT-X-ENDLIST`) — playlist is complete; stop reloading.
+ */
+interface MediaPlaylistMetadata {
+  targetDuration: number;
+  mediaSequence: number;
+  playlistType?: 'VOD' | 'EVENT';
+  endList: boolean;
+  /**
+   * Whether this rendition carries encrypted segments — any `#EXT-X-KEY` whose `METHOD` isn't `NONE`. Detection only:
+   * enough to tell that playback needs decryption support, not enough to perform it.
+   *
+   * Deliberately _not_ a model-level `protection` shape. CMAF-HAM puts `protection` on `SwitchingSet`, but that can't
+   * express two real cases: a clear lead (`METHOD=NONE` segments followed by encrypted ones — protection varies along
+   * the timeline within one rendition) or key rotation (its single `defaultKid` can't represent a key changing over
+   * time). Modeling it properly belongs to DRM support; until then this records the one fact a playlist reliably gives
+   * us. Per-rendition because that's HLS's granularity — `EXT-X-KEY` is a media-playlist tag.
+   *
+   * Conservative for a clear lead: a rendition whose opening segments are clear still reads as encrypted, so it's
+   * judged unplayable rather than played until it breaks.
+   */
+  encrypted?: boolean;
+  /**
+   * `EXT-X-SERVER-CONTROL` `HOLD-BACK` (seconds) — the server's declared distance from the live edge for clients
+   * playing _complete_ segments. Absent when the server doesn't advertise it, in which case the spec default (3 ×
+   * target duration) applies. Deliberately HLS vocabulary living in the playlist metadata rather than on `Track`:
+   * whether a wall-clock holdback generalizes across delivery formats is unresolved.
+   *
+   * `PART-HOLD-BACK` is **not** captured — it only applies to clients playing partial segments, and using it while
+   * fetching whole segments would put the playhead ahead of the last complete segment. Add it with LL-HLS support.
+   */
+  holdBack?: number;
+  /**
+   * Whether the server is delivering this rendition as Low-Latency HLS — any of `#EXT-X-PART`, `#EXT-X-PART-INF`, or
+   * `EXT-X-SERVER-CONTROL`'s `PART-HOLD-BACK`.
+   *
+   * Detection only, and deliberately so: partial segments are ignored by the parser and the loader fetches whole
+   * segments, so an LL-HLS playlist plays as standard live at standard latency. Recording the fact is what lets a
+   * composition _say_ that rather than silently under-delivering the latency the publisher configured.
+   */
+  lowLatency?: boolean;
+}
+/** Typed read of the media-playlist metadata stashed in `ham.metadata`. */
+declare function getMediaPlaylistMetadata(ham: Pick<Ham, 'metadata'>): MediaPlaylistMetadata | undefined;
+/**
+ * The source's semantic nature — live vs on-demand. A model concept (consumer-facing), distinct from completeness /
+ * duration: a live stream that has _ended_ is still `'live'`.
+ */
+type StreamType = 'live' | 'on-demand';
+/**
+ * Presentation - a single playable period of content. Uses TimeSpan fields (startTime always 0, duration optional until
+ * track resolved).
+ *
+ * Extends AddressableObject so `url` contains the original manifest URL. All URLs are fully qualified (parsers resolve
+ * relative URLs).
+ */
+type Presentation = Ham & AddressableObject & Partial<TimeSpan> & {
+  selectionSets: SelectionSet[];
+  /**
+   * Live vs on-demand — the source's semantic nature. Populated once a media playlist is parsed (derived from
+   * `#EXT-X-PLAYLIST-TYPE` via `deriveStreamType`); orthogonal to duration / completeness.
+   */
+  streamType?: StreamType;
+};
+/**
+ * State-shaped presentation that may or may not be resolved yet.
+ *
+ * The lifecycle is a single value: a caller writes `{ url }`, and the resolver populates the rest in place. `url` is
+ * always present; resolved fields (`id`, `selectionSets`, duration) appear once parsing succeeds.
+ *
+ * Use `isResolvedPresentation` to narrow to `Presentation`.
+ */
+type MaybeResolvedPresentation = AddressableObject & Partial<Omit<Presentation, keyof AddressableObject>>;
+//#endregion
+export { AddressableObject, AudioSelectionSet, AudioTrack, CanPlayTrack, Cue, FrameRate, Ham, MaybeResolvedPresentation, MediaContainerData, MediaPlaylistMetadata, PartiallyResolved, PartiallyResolvedTextTrack, Presentation, ResolvedTrack, Segment, SegmentData, SelectionSet, SelectionSetOf, StreamType, SwitchingSetOf, TextSelectionSet, TextTrack, TimeSpan, Track, TrackType, VideoSelectionSet, VideoTrack, getMediaPlaylistMetadata };
+//# sourceMappingURL=index.d.ts.map

package/dist/dev/media/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../../src/media/types/index.ts"],"mappings":";;;;;;;;;;UAciB;EACf;;;;;;EAMA,WAAW;;;UAII;EACf;EACA;IACE;IACA;;;;UA4Ba;EACf;EACA;;;KAQU;;;;;;UAWK;EACf;EACA;;;;;;;KAYU,kBAAkB,UAAU,QAAQ,SAAS,KAAK,yCAAyC;EACrG;EACA;EACA;EACA;;;;;;;;;;KA2BU,QAAQ,MAClB,oBACA;EACE,MAAM;EACN;EACA;EACA;EACA;EACA,iBAAiB;EACjB,UAAU;;;;;;;;;;;EAWV;;;;;;;;;;EAUA;;;;;;;;;;;;;;;;UAiBa;EACf;EACA;EACA;EACA;;;;;;;KAQU,cAAc,cAAc,cAAc;;KAG1C,aAAa,QACvB,SAAS,KAAK;EACZ;EAGA;EACA;EACA,YAAY;;;;;;EAMZ;;;KAIQ,aAAa,QACvB,SAAS,KAAK;EACZ;EACA;EACA;EACA;EACA;EACA;EACA;;;KAIQ,YAAY;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;KAYU,gBAAgB;EAC1B;EACA;EACA,WAAW;;;;;;;;;UAUI;EACf;EACA;EACA;;;;;;KAkBU,6BAA6B,kBAAkB;;KAG/C,gBAAgB,aAAa,aAAa;;;;;;KAiB1C,eAAe,UAAU,QAAQ,SAAS;EACpD,MAAM;EACN,SAAS,kBAAkB,KAAK;;;;;;;KAoBtB,eAAe,UAAU,QAAQ,SAAS;EACpD,MAAM;EACN,eAAe,eAAe;;;KAIpB,oBAAoB,eAAe;;KAGnC,oBAAoB,eAAe;;KAGnC,mBAAmB,eAAe;;KAGlC,eAAe,oBAAoB,oBAAoB;;;;;;;;;;KAevD,UAAU,MAAM,oBAAoB;EAAa;;;;;;;;;;;;;UAyB5C;EACf;EACA;EACA;EACA;;;;;;;;;;;;;;EAcA;;;;;;;;;;EAUA;;;;;;;;;EASA;;;iBAOc,yBAAyB,KAAK,KAAK,mBAAmB;;;;;KAY1D;;;;;;;;KAoCA,eAAe,MACzB,oBACA,QAAQ;EACN,eAAe;;;;;EAKf,aAAa;;;;;;;;;;KAWL,4BAA4B,oBAAoB,QAAQ,KAAK,oBAAoB"}

package/dist/dev/media/types/index.js

@@ -0,0 +1,42 @@
+//#region src/media/types/index.ts
+/**
+* Floating-point tolerance for matching segments by `startTime`. Two segments are considered the same position when
+* `Math.abs(a.startTime - b.startTime) < SEGMENT_TIME_EPSILON`. Used by the source-buffer dedup and segment-loader
+* quality-aware filter to tolerate sub-millisecond drift in segment timestamps across multiple playlists / quality
+* levels.
+*/
+const SEGMENT_TIME_EPSILON = 1e-4;
+/** Key under `Ham.metadata` where {@link MediaPlaylistMetadata} is stored. */
+const MEDIA_PLAYLIST_METADATA_KEY = "mediaPlaylist";
+/** Typed read of the media-playlist metadata stashed in `ham.metadata`. */
+function getMediaPlaylistMetadata(ham) {
+	return ham.metadata?.[MEDIA_PLAYLIST_METADATA_KEY];
+}
+/**
+* Derive {@link StreamType} from a media playlist's metadata. Per the model, only `#EXT-X-PLAYLIST-TYPE:VOD` marks
+* on-demand; everything else (EVENT, or the tag absent) is live — completeness (`endList`) never factors in.
+*/
+function deriveStreamType(metadata) {
+	return metadata?.playlistType === "VOD" ? "on-demand" : "live";
+}
+function isResolvedTrack(track) {
+	return "segments" in track;
+}
+/** Check if a presentation has duration (at least one track resolved). Narrows type to include required duration. */
+function hasPresentationDuration(presentation) {
+	return presentation.duration !== void 0;
+}
+/**
+* Narrows a `MaybeResolvedPresentation` to a fully resolved `Presentation`.
+*
+* A presentation is resolved once `resolvePresentation` has parsed the manifest and populated both `id` and
+* `selectionSets`. Both must be present — a partial value with only one of them isn't usable, and letting it through
+* would have downstream behaviors crash when they access `selectionSets`.
+*/
+function isResolvedPresentation(presentation) {
+	return presentation !== void 0 && presentation.id !== void 0 && presentation.selectionSets !== void 0;
+}
+//#endregion
+export { MEDIA_PLAYLIST_METADATA_KEY, SEGMENT_TIME_EPSILON, deriveStreamType, getMediaPlaylistMetadata, hasPresentationDuration, isResolvedPresentation, isResolvedTrack };
+
+//# sourceMappingURL=index.js.map

package/dist/dev/media/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/media/types/index.ts"],"sourcesContent":["/**\n * Core SPF Types\n *\n * Based on CMAF-HAM (Common Media Application Format - Hypothetical Application Model) Protocol-agnostic representation\n * of streaming media content.\n *\n * @see https://github.com/streaming-video-technology-alliance/common-media-library\n */\n\n// =============================================================================\n// Base Types\n// =============================================================================\n\n/** Base identifier type for all HAM objects. */\nexport interface Ham {\n  id: string;\n  /**\n   * Format-/protocol-specific values that aren't part of the generic CMAF-HAM model — kept in an open bag so the model\n   * stays format-neutral (mirrors how CMAF-HAM itself stashes protocol extras rather than growing the model). Typed\n   * reads go through dedicated accessors (e.g. `getMediaPlaylistMetadata`).\n   */\n  metadata?: Record<string, unknown>;\n}\n\n/** Addressable resource with optional byte range. */\nexport interface AddressableObject {\n  url: string;\n  byteRange?: {\n    start: number;\n    end: number;\n  };\n}\n\n// =============================================================================\n// Platform-agnostic Media Element\n// =============================================================================\n\n/**\n * Platform-agnostic media element interface. Captures minimal shape needed for orchestration without DOM dependencies.\n * HTMLMediaElement satisfies this interface.\n */\nexport interface MediaElementLike {\n  preload: string;\n  /**\n   * DOM attribute-reflection surface, present on real elements. Where it exists, reflected IDL properties like\n   * `preload` report a browser-dependent UA default even when no attribute was authored — so consumers that need author\n   * intent must gate property reads on attribute presence. A non-DOM implementation may omit it; its properties carry\n   * no UA defaults and are authored by construction.\n   */\n  hasAttribute?(qualifiedName: string): boolean;\n}\n\n// =============================================================================\n// Time and Duration\n// =============================================================================\n\n/** Time span with start time and duration. Used for segments and other timed ranges. */\nexport interface TimeSpan {\n  startTime: number;\n  duration: number;\n}\n\n// =============================================================================\n// Enums\n// =============================================================================\n\n/** Track content type. */\nexport type TrackType = 'video' | 'audio' | 'text';\n\n// =============================================================================\n// Frame Rate\n// =============================================================================\n\n/**\n * Video frame rate expressed as numerator/denominator.\n *\n * Examples: - 30 fps: { frameRateNumerator: 30 } - 29.97 fps: { frameRateNumerator: 30000, frameRateDenominator: 1001 }\n */\nexport interface FrameRate {\n  frameRateNumerator: number;\n  frameRateDenominator?: number;\n}\n\n// =============================================================================\n// Partially Resolved Tracks (before media playlist is fetched)\n// =============================================================================\n\n/**\n * Generic type for partially resolved tracks. Removes fields that come from media playlist parsing.\n *\n * @param T - Track type to make partially resolved (must extend Track)\n */\nexport type PartiallyResolved<T extends Track = Track> = Omit<T, 'segments' | 'initialization' | keyof TimeSpan> & {\n  segments?: never;\n  duration?: never;\n  startTime?: never;\n  initialization?: never;\n};\n\n/**\n * Partially resolved video track from multivariant playlist. Has metadata but no segments or initialization yet (media\n * playlist not fetched).\n */\nexport type PartiallyResolvedVideoTrack = PartiallyResolved<VideoTrack>;\n\n/**\n * Partially resolved audio track from multivariant playlist. Has metadata but no segments or initialization yet (media\n * playlist not fetched).\n */\nexport type PartiallyResolvedAudioTrack = PartiallyResolved<AudioTrack>;\n\n// =============================================================================\n// Resolved Track Types (with segments from media playlist)\n// =============================================================================\n\n/**\n * Base track type containing common properties for all resolved tracks. A resolved track has segments, duration, and\n * initialization data. All URLs are fully qualified (parsers resolve relative URLs).\n */\n/**\n * Track startTime is always 0 — the presentation-timeline origin (and future multi-period base). The live\n * sliding-window edge is `segments[0].startTime`, derived — never stored here.\n */\nexport type Track = Ham &\n  AddressableObject &\n  TimeSpan & {\n    type: TrackType;\n    codecs?: string[]; // Optional per HLS spec\n    mimeType: string;\n    language?: string | undefined;\n    bandwidth: number;\n    initialization?: AddressableObject;\n    segments: Segment[];\n    /**\n     * Media-timeline (decode/encode) coordinate of the track's timeline origin (presentation-0) — the media-time base\n     * value of the coordinate model, peer to `startTime` (presentation). Derived from the container\n     * (`tfdt.baseMediaDecodeTime ÷ mdhd.timescale`); the relocation offset is `−startMediaTime` (targets presentation-0\n     * — `Track.startTime` plays no part), never stored.\n     *\n     * Optional: `undefined` means not yet established, or never establishable (e.g. text tracks carry no container\n     * origin); a near-zero/native origin is established as `0` (no relocation). Established once per source by the\n     * `establishStartMediaTime` reactor. See `internal/design/spf/presentation-timeline-model.md`.\n     */\n    startMediaTime?: number;\n    /**\n     * Wall-clock time (epoch seconds) at the track's timeline origin (presentation-0) — pure playlist arithmetic over\n     * any PDT-bearing segment: `segment.startDate − segment.startTime`, invariant along a linear timeline. Optional:\n     * absent when no segment carries `startDate`.\n     *\n     * The wall-clock member of the coordinate triple (peer to `startTime` and `startMediaTime`). For live it is the\n     * anchor segments are PDT-placed against on every parse; equal `startDate` across tracks marks the same\n     * presentation instant. See `internal/design/spf/live-presentation-timeline-model.md`.\n     */\n    startDate?: number;\n  };\n\n/**\n * Per-track-type origin-establishment data, accumulated across appends (the media track's `track_id` + `mdhd` timescale\n * from the init, `tfdt` baseMediaDecodeTime of that same track from the first media segment) — hence optional. The\n * transient input the `establishStartMediaTime` reactor reduces into `Track.startMediaTime`.\n *\n * `trackId` is the ISO-BMFF `track_ID` of the buffered media track (`vide`/`soun`), read from the init's `tkhd`; it\n * ties the timescale to the _same_ track's `baseMediaDecodeTime` (matched via `tfhd.track_id`) so a muxed segment\n * carrying a second track (e.g. `clcp` captions) reads the right `tfdt` rather than the first one.\n *\n * `segmentStartTime` is the 0-based presentation start of the segment `baseMediaDecodeTime` was read from — _not_ a\n * container value (it's the playlist position), but co-located because the origin is `baseMediaDecodeTime/timescale −\n * segmentStartTime`: the first _loaded_ segment isn't necessarily the 0th (a non-zero initial `currentTime`, or\n * live/DVR), so the decode time alone isn't the stream origin.\n */\nexport interface MediaContainerData {\n  trackId?: number;\n  timescale?: number;\n  baseMediaDecodeTime?: number;\n  segmentStartTime?: number;\n}\n\n/**\n * Raw media-segment bytes — a complete buffer or a byte stream. The transport-neutral payload the loader pipeline\n * carries; `AppendData` (the MSE `SourceBuffer` append input in `media/dom/mse`) is an alias of this at the DOM\n * boundary.\n */\nexport type SegmentData = ArrayBuffer | AsyncIterable<Uint8Array>;\n\n/** Resolved video track with segments. */\nexport type VideoTrack = Track &\n  Required<Pick<Track, 'initialization' | 'codecs'>> & {\n    type: 'video';\n\n    // Optional metadata from multivariant (per HLS spec)\n    width?: number;\n    height?: number;\n    frameRate?: FrameRate;\n    /**\n     * Audio groups (`EXT-X-STREAM-INF:AUDIO`) this video rendition can pair with. A list because one rendition is\n     * typically listed across multiple `EXT-X-STREAM-INF` entries — one per audio group (the HLS cross-product) — which\n     * the parser collapses into a single track carrying every group it advertised.\n     */\n    audioGroupIds?: string[];\n  };\n\n/** Resolved audio track with segments. */\nexport type AudioTrack = Track &\n  Required<Pick<Track, 'initialization' | 'codecs'>> & {\n    type: 'audio';\n    groupId: string;\n    name: string;\n    sampleRate: number;\n    channels: number;\n    default?: boolean;\n    autoselect?: boolean;\n  };\n\n/** Resolved text track with segments. */\nexport type TextTrack = Track & {\n  type: 'text';\n  groupId: string;\n  label: string;\n  kind: 'subtitles' | 'captions';\n  default?: boolean;\n  autoselect?: boolean;\n  forced?: boolean;\n};\n\n/**\n * Predicate that answers \"can this environment decode this track?\" — the capability-probing surface, read by the\n * track-switching hard-constraint pre-pass (`excludeUnplayableTracks`) to drop undecodable renditions before selection.\n * Kept DOM-free here (a plain function type over a minimal track shape) so DOM-free behaviors can consume it; the DOM\n * implementation (`canPlayTrack` in `media/dom/capabilities.ts`) wraps `MediaSource.isTypeSupported`.\n *\n * Takes the minimal codec-bearing shape both video and audio candidates carry. `mimeType` is optional so unprobeable\n * candidates (no MIME) can be passed straight through as playable rather than dropped.\n */\nexport type CanPlayTrack = (track: {\n  mimeType?: string;\n  codecs?: string[];\n  metadata?: Record<string, unknown>;\n}) => boolean;\n\n/**\n * Minimal text-track cue shape — start time, end time, and display text.\n *\n * Host-agnostic representation. `VTTCue` structurally satisfies this interface, so DOM consumers pass `VTTCue` values\n * directly. Non-DOM hosts (workers, test fakes, non-browser engines) can satisfy the same shape without pulling in DOM\n * types.\n */\nexport interface Cue {\n  startTime: number;\n  endTime: number;\n  text: string;\n}\n\n/**\n * Media element with an iterable text-track list, host-agnostic.\n *\n * Extends `MediaElementLike` with the minimum surface needed to observe which text tracks are currently mounted on the\n * media. `HTMLMediaElement` structurally satisfies this (its `textTracks` is a `TextTrackList`, which is iterable with\n * `{ id }` items).\n */\nexport interface MediaElementWithTextTracks extends MediaElementLike {\n  readonly textTracks: Iterable<{ readonly id: string }>;\n}\n\n/**\n * Partially resolved text track from multivariant playlist. Has metadata but no segments or initialization yet (media\n * playlist not fetched).\n */\nexport type PartiallyResolvedTextTrack = PartiallyResolved<TextTrack>;\n\n/** Union of all resolved track types. */\nexport type ResolvedTrack = VideoTrack | AudioTrack | TextTrack;\n\n/** Union of all partially resolved track types. */\nexport type PartiallyResolvedTrack =\n  | PartiallyResolvedVideoTrack\n  | PartiallyResolvedAudioTrack\n  | PartiallyResolvedTextTrack;\n\n// =============================================================================\n// Switching and Selection Sets\n// =============================================================================\n\n/**\n * Generic switching set type. A group of tracks that can be switched between seamlessly.\n *\n * @param T - Track type (VideoTrack, AudioTrack, or TextTrack)\n */\nexport type SwitchingSetOf<T extends Track = Track> = Ham & {\n  type: T['type'];\n  tracks: (PartiallyResolved<T> | T)[];\n};\n\n/** Video switching set - contains only video tracks (partially resolved or fully resolved). */\nexport type VideoSwitchingSet = SwitchingSetOf<VideoTrack>;\n\n/** Audio switching set - contains only audio tracks (partially resolved or fully resolved). */\nexport type AudioSwitchingSet = SwitchingSetOf<AudioTrack>;\n\n/** Text switching set - contains only text tracks (partially resolved or fully resolved). */\nexport type TextSwitchingSet = SwitchingSetOf<TextTrack>;\n\n/** Switching set - a group of tracks that can be switched between seamlessly. Discriminated by track type. */\nexport type SwitchingSet = VideoSwitchingSet | AudioSwitchingSet | TextSwitchingSet;\n\n/**\n * Generic selection set type. Groups switching sets by track type.\n *\n * @param T - Track type (VideoTrack, AudioTrack, or TextTrack)\n */\nexport type SelectionSetOf<T extends Track = Track> = Ham & {\n  type: T['type'];\n  switchingSets: SwitchingSetOf<T>[];\n};\n\n/** Video selection set - contains only video switching sets. */\nexport type VideoSelectionSet = SelectionSetOf<VideoTrack>;\n\n/** Audio selection set - contains only audio switching sets. */\nexport type AudioSelectionSet = SelectionSetOf<AudioTrack>;\n\n/** Text selection set - contains only text switching sets. */\nexport type TextSelectionSet = SelectionSetOf<TextTrack>;\n\n/** Selection set - groups switching sets by track type. Discriminated union ensures type-safe track access. */\nexport type SelectionSet = VideoSelectionSet | AudioSelectionSet | TextSelectionSet;\n\n// =============================================================================\n// Segment\n// =============================================================================\n\n/**\n * Media segment with timing information. Follows CMAF-HAM composition pattern.\n *\n * `startDate` is the absolute wall-clock time of the segment's first sample, in **epoch seconds** (unit-consistent with\n * `startTime`/`duration`), derived from `#EXT-X-PROGRAM-DATE-TIME` (explicit or interpolated forward via `EXTINF`).\n * Unlike the per-track-relative `startTime`, it is comparable across tracks, so it is the cross-track sync anchor for\n * demuxed audio/video and the exact recovery value on a full live-window turnover. Optional: absent when the source\n * carries no PDT (allowed by RFC 8216, required by Apple's HLS authoring spec — so present on conformant content).\n */\nexport type Segment = Ham & AddressableObject & TimeSpan & { startDate?: number };\n\n/**\n * Floating-point tolerance for matching segments by `startTime`. Two segments are considered the same position when\n * `Math.abs(a.startTime - b.startTime) < SEGMENT_TIME_EPSILON`. Used by the source-buffer dedup and segment-loader\n * quality-aware filter to tolerate sub-millisecond drift in segment timestamps across multiple playlists / quality\n * levels.\n */\nexport const SEGMENT_TIME_EPSILON = 0.0001;\n\n// =============================================================================\n// Media Playlist Metadata\n// =============================================================================\n\n/**\n * Playlist-level metadata surfaced from a parsed media playlist. HLS delivery specifics — not part of the generic\n * CMAF-HAM model — so they live under `Ham.metadata` (read via `getMediaPlaylistMetadata`) rather than as first-class\n * `Track` fields:\n *\n * - `targetDuration` (`#EXT-X-TARGETDURATION`) — reload-cadence basis.\n * - `mediaSequence` (`#EXT-X-MEDIA-SEQUENCE`, default 0) — sequence number of `segments[0]`; the join key for merging\n *   successive reload snapshots.\n * - `playlistType` (`#EXT-X-PLAYLIST-TYPE`) — `VOD` / `EVENT` / undefined.\n * - `endList` (`#EXT-X-ENDLIST`) — playlist is complete; stop reloading.\n */\nexport interface MediaPlaylistMetadata {\n  targetDuration: number;\n  mediaSequence: number;\n  playlistType?: 'VOD' | 'EVENT';\n  endList: boolean;\n  /**\n   * Whether this rendition carries encrypted segments — any `#EXT-X-KEY` whose `METHOD` isn't `NONE`. Detection only:\n   * enough to tell that playback needs decryption support, not enough to perform it.\n   *\n   * Deliberately _not_ a model-level `protection` shape. CMAF-HAM puts `protection` on `SwitchingSet`, but that can't\n   * express two real cases: a clear lead (`METHOD=NONE` segments followed by encrypted ones — protection varies along\n   * the timeline within one rendition) or key rotation (its single `defaultKid` can't represent a key changing over\n   * time). Modeling it properly belongs to DRM support; until then this records the one fact a playlist reliably gives\n   * us. Per-rendition because that's HLS's granularity — `EXT-X-KEY` is a media-playlist tag.\n   *\n   * Conservative for a clear lead: a rendition whose opening segments are clear still reads as encrypted, so it's\n   * judged unplayable rather than played until it breaks.\n   */\n  encrypted?: boolean;\n  /**\n   * `EXT-X-SERVER-CONTROL` `HOLD-BACK` (seconds) — the server's declared distance from the live edge for clients\n   * playing _complete_ segments. Absent when the server doesn't advertise it, in which case the spec default (3 ×\n   * target duration) applies. Deliberately HLS vocabulary living in the playlist metadata rather than on `Track`:\n   * whether a wall-clock holdback generalizes across delivery formats is unresolved.\n   *\n   * `PART-HOLD-BACK` is **not** captured — it only applies to clients playing partial segments, and using it while\n   * fetching whole segments would put the playhead ahead of the last complete segment. Add it with LL-HLS support.\n   */\n  holdBack?: number;\n  /**\n   * Whether the server is delivering this rendition as Low-Latency HLS — any of `#EXT-X-PART`, `#EXT-X-PART-INF`, or\n   * `EXT-X-SERVER-CONTROL`'s `PART-HOLD-BACK`.\n   *\n   * Detection only, and deliberately so: partial segments are ignored by the parser and the loader fetches whole\n   * segments, so an LL-HLS playlist plays as standard live at standard latency. Recording the fact is what lets a\n   * composition _say_ that rather than silently under-delivering the latency the publisher configured.\n   */\n  lowLatency?: boolean;\n}\n\n/** Key under `Ham.metadata` where {@link MediaPlaylistMetadata} is stored. */\nexport const MEDIA_PLAYLIST_METADATA_KEY = 'mediaPlaylist';\n\n/** Typed read of the media-playlist metadata stashed in `ham.metadata`. */\nexport function getMediaPlaylistMetadata(ham: Pick<Ham, 'metadata'>): MediaPlaylistMetadata | undefined {\n  return ham.metadata?.[MEDIA_PLAYLIST_METADATA_KEY] as MediaPlaylistMetadata | undefined;\n}\n\n// =============================================================================\n// Stream Type\n// =============================================================================\n\n/**\n * The source's semantic nature — live vs on-demand. A model concept (consumer-facing), distinct from completeness /\n * duration: a live stream that has _ended_ is still `'live'`.\n */\nexport type StreamType = 'live' | 'on-demand';\n\n/**\n * Derive {@link StreamType} from a media playlist's metadata. Per the model, only `#EXT-X-PLAYLIST-TYPE:VOD` marks\n * on-demand; everything else (EVENT, or the tag absent) is live — completeness (`endList`) never factors in.\n */\nexport function deriveStreamType(metadata: MediaPlaylistMetadata | undefined): StreamType {\n  return metadata?.playlistType === 'VOD' ? 'on-demand' : 'live';\n}\n\n// =============================================================================\n// Media Playlist Info\n// =============================================================================\n\n/** Intermediate representation of a parsed media playlist. Used internally before assembling into full Track structure. */\nexport interface MediaPlaylistInfo {\n  version: number;\n  targetDuration: number;\n  playlistType: 'VOD' | 'EVENT' | undefined;\n  initSegment: AddressableObject | null;\n  segments: Segment[];\n  duration: number;\n  endList: boolean;\n}\n\n// =============================================================================\n// Presentation\n// =============================================================================\n\n/**\n * Presentation - a single playable period of content. Uses TimeSpan fields (startTime always 0, duration optional until\n * track resolved).\n *\n * Extends AddressableObject so `url` contains the original manifest URL. All URLs are fully qualified (parsers resolve\n * relative URLs).\n */\nexport type Presentation = Ham &\n  AddressableObject &\n  Partial<TimeSpan> & {\n    selectionSets: SelectionSet[];\n    /**\n     * Live vs on-demand — the source's semantic nature. Populated once a media playlist is parsed (derived from\n     * `#EXT-X-PLAYLIST-TYPE` via `deriveStreamType`); orthogonal to duration / completeness.\n     */\n    streamType?: StreamType;\n  };\n\n/**\n * State-shaped presentation that may or may not be resolved yet.\n *\n * The lifecycle is a single value: a caller writes `{ url }`, and the resolver populates the rest in place. `url` is\n * always present; resolved fields (`id`, `selectionSets`, duration) appear once parsing succeeds.\n *\n * Use `isResolvedPresentation` to narrow to `Presentation`.\n */\nexport type MaybeResolvedPresentation = AddressableObject & Partial<Omit<Presentation, keyof AddressableObject>>;\n\n// =============================================================================\n// Type Guards\n// =============================================================================\n\n/** Check if a track is resolved (has segments). Works for all track types with overloaded signatures for type narrowing. */\nexport function isResolvedTrack(track: PartiallyResolvedVideoTrack | VideoTrack): track is VideoTrack;\nexport function isResolvedTrack(track: PartiallyResolvedAudioTrack | AudioTrack): track is AudioTrack;\nexport function isResolvedTrack(track: PartiallyResolvedTextTrack | TextTrack): track is TextTrack;\nexport function isResolvedTrack(track: PartiallyResolvedTrack | ResolvedTrack): track is ResolvedTrack;\nexport function isResolvedTrack(track: PartiallyResolvedTrack | ResolvedTrack): track is ResolvedTrack {\n  return 'segments' in track;\n}\n\n/** Check if a presentation has duration (at least one track resolved). Narrows type to include required duration. */\nexport function hasPresentationDuration(\n  presentation: MaybeResolvedPresentation\n): presentation is MaybeResolvedPresentation & { duration: number } {\n  return presentation.duration !== undefined;\n}\n\n/**\n * Narrows a `MaybeResolvedPresentation` to a fully resolved `Presentation`.\n *\n * A presentation is resolved once `resolvePresentation` has parsed the manifest and populated both `id` and\n * `selectionSets`. Both must be present — a partial value with only one of them isn't usable, and letting it through\n * would have downstream behaviors crash when they access `selectionSets`.\n */\nexport function isResolvedPresentation(\n  presentation: MaybeResolvedPresentation | undefined\n): presentation is Presentation {\n  return presentation !== undefined && presentation.id !== undefined && presentation.selectionSets !== undefined;\n}\n"],"mappings":";;;;;;;AA2VA,MAAa,uBAAuB;;AA0DpC,MAAa,8BAA8B;;AAG3C,SAAgB,yBAAyB,KAA+D;CACtG,OAAO,IAAI,WAAW;AACxB;;;;;AAgBA,SAAgB,iBAAiB,UAAyD;CACxF,OAAO,UAAU,iBAAiB,QAAQ,cAAc;AAC1D;AA0DA,SAAgB,gBAAgB,OAAuE;CACrG,OAAO,cAAc;AACvB;;AAGA,SAAgB,wBACd,cACkE;CAClE,OAAO,aAAa,aAAa,KAAA;AACnC;;;;;;;;AASA,SAAgB,uBACd,cAC8B;CAC9B,OAAO,iBAAiB,KAAA,KAAa,aAAa,OAAO,KAAA,KAAa,aAAa,kBAAkB,KAAA;AACvG"}

package/dist/dev/media/utils/cdn.d.ts

@@ -0,0 +1,11 @@
+//#region src/media/utils/cdn.d.ts
+/**
+ * Derive a stable grouping key for the CDN a URL is served from. Synchronous and pure (deliberately not a `resolve*` —
+ * no fetch). Consumers override the default via the engine's `getCdnId` config (e.g. to key on Mux's `cdn=` query param
+ * instead of the host); every CDN-identity site reads that same function so keys stay comparable across `cdnPriority`,
+ * `failedCdns`, and the track-switching constraint + scope.
+ */
+type GetCdnId = (url: string) => string;
+//#endregion
+export { GetCdnId };
+//# sourceMappingURL=cdn.d.ts.map

package/dist/dev/media/utils/cdn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdn.d.ts","names":[],"sources":["../../../../src/media/utils/cdn.ts"],"mappings":";;;;;;;KAQY,YAAY"}

package/dist/dev/media/utils/cdn.js

@@ -0,0 +1,50 @@
+//#region src/media/utils/cdn.ts
+/**
+* Default {@link GetCdnId}: the URL's origin (scheme + host + port); falls back to the raw string when the URL can't be
+* parsed, so the return value is always a stable grouping key.
+*/
+function getCdnId(url) {
+	try {
+		return new URL(url).origin;
+	} catch {
+		return url;
+	}
+}
+const CDN_TYPE_PRIORITY = {
+	video: 0,
+	audio: 1,
+	text: 2
+};
+/**
+* The distinct CDNs a presentation's tracks are served from, ordered video CDNs first, then audio, then text (manifest
+* order within a type). The head is the primary CDN — the one a sticky pick defaults to — and is always video-derived
+* when the source has video. Returns `[]` for an unresolved presentation with no tracks.
+*
+* Redundant-stream sources list the same content on multiple hosts (e.g. Mux's `?redundant_streams=true`), so each host
+* contributes its own candidate tracks; this collapses them to the set of CDNs across every track type. The CDN-id
+* derivation defaults to {@link getCdnId}; pass a consumer-configured `getId` to key on something other than origin.
+*/
+function getOrderedCdnIds(presentation, getId = getCdnId) {
+	const seen = /* @__PURE__ */ new Set();
+	const ids = [];
+	const selectionSets = [...presentation.selectionSets ?? []].sort((a, b) => CDN_TYPE_PRIORITY[a.type] - CDN_TYPE_PRIORITY[b.type]);
+	for (const selectionSet of selectionSets) for (const switchingSet of selectionSet.switchingSets) for (const track of switchingSet.tracks) {
+		const id = getId(track.url);
+		if (seen.has(id)) continue;
+		seen.add(id);
+		ids.push(id);
+	}
+	return ids;
+}
+/**
+* Add a CDN id to a failed-CDN list, preserving order and ignoring duplicates. Idempotent: re-adding an already-present
+* id returns the same array reference (so a no-op trip doesn't churn the `failedCdns` signal). The failover trip in
+* `resolve-track` and the segment loaders feed this into `failedCdns` via `update`.
+*/
+function addFailedCdn(failed, cdn) {
+	return failed?.includes(cdn) ? failed : [...failed ?? [], cdn];
+}
+//#endregion
+export { addFailedCdn, getCdnId, getOrderedCdnIds };
+
+//# sourceMappingURL=cdn.js.map

package/dist/dev/media/utils/cdn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdn.js","names":[],"sources":["../../../../src/media/utils/cdn.ts"],"sourcesContent":["import type { MaybeResolvedPresentation, TrackType } from '../types';\n\n/**\n * Derive a stable grouping key for the CDN a URL is served from. Synchronous and pure (deliberately not a `resolve*` —\n * no fetch). Consumers override the default via the engine's `getCdnId` config (e.g. to key on Mux's `cdn=` query param\n * instead of the host); every CDN-identity site reads that same function so keys stay comparable across `cdnPriority`,\n * `failedCdns`, and the track-switching constraint + scope.\n */\nexport type GetCdnId = (url: string) => string;\n\n/**\n * Default {@link GetCdnId}: the URL's origin (scheme + host + port); falls back to the raw string when the URL can't be\n * parsed, so the return value is always a stable grouping key.\n */\nexport function getCdnId(url: string): string {\n  try {\n    return new URL(url).origin;\n  } catch {\n    return url;\n  }\n}\n\n// Track-type priority for CDN ordering: video first, then audio, then text.\n// Selection sets are visited in this order so the head of the returned list is\n// always video-derived. `preferActiveCdn` anchors every track type to the\n// first CDN with surviving tracks (the head), so this makes \"the primary CDN\n// is the video CDN\" a guarantee of `getOrderedCdnIds` rather than a side effect\n// of the order tracks happen to be parsed in.\nconst CDN_TYPE_PRIORITY: Record<TrackType, number> = { video: 0, audio: 1, text: 2 };\n\n/**\n * The distinct CDNs a presentation's tracks are served from, ordered video CDNs first, then audio, then text (manifest\n * order within a type). The head is the primary CDN — the one a sticky pick defaults to — and is always video-derived\n * when the source has video. Returns `[]` for an unresolved presentation with no tracks.\n *\n * Redundant-stream sources list the same content on multiple hosts (e.g. Mux's `?redundant_streams=true`), so each host\n * contributes its own candidate tracks; this collapses them to the set of CDNs across every track type. The CDN-id\n * derivation defaults to {@link getCdnId}; pass a consumer-configured `getId` to key on something other than origin.\n */\nexport function getOrderedCdnIds(presentation: MaybeResolvedPresentation, getId: GetCdnId = getCdnId): string[] {\n  const seen = new Set<string>();\n  const ids: string[] = [];\n  // Stable sort keeps manifest order among same-type selection sets.\n  const selectionSets = [...(presentation.selectionSets ?? [])].sort(\n    (a, b) => CDN_TYPE_PRIORITY[a.type] - CDN_TYPE_PRIORITY[b.type]\n  );\n\n  for (const selectionSet of selectionSets) {\n    for (const switchingSet of selectionSet.switchingSets) {\n      for (const track of switchingSet.tracks) {\n        const id = getId(track.url);\n        if (seen.has(id)) continue;\n\n        seen.add(id);\n        ids.push(id);\n      }\n    }\n  }\n\n  return ids;\n}\n\n/**\n * Add a CDN id to a failed-CDN list, preserving order and ignoring duplicates. Idempotent: re-adding an already-present\n * id returns the same array reference (so a no-op trip doesn't churn the `failedCdns` signal). The failover trip in\n * `resolve-track` and the segment loaders feed this into `failedCdns` via `update`.\n */\nexport function addFailedCdn(failed: string[] | undefined, cdn: string): string[] {\n  return failed?.includes(cdn) ? failed : [...(failed ?? []), cdn];\n}\n"],"mappings":";;;;;AAcA,SAAgB,SAAS,KAAqB;CAC5C,IAAI;EACF,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;CACtB,QAAQ;EACN,OAAO;CACT;AACF;AAQA,MAAM,oBAA+C;CAAE,OAAO;CAAG,OAAO;CAAG,MAAM;AAAE;;;;;;;;;;AAWnF,SAAgB,iBAAiB,cAAyC,QAAkB,UAAoB;CAC9G,MAAM,uBAAO,IAAI,IAAY;CAC7B,MAAM,MAAgB,CAAC;CAEvB,MAAM,gBAAgB,CAAC,GAAI,aAAa,iBAAiB,CAAC,CAAE,CAAC,CAAC,MAC3D,GAAG,MAAM,kBAAkB,EAAE,QAAQ,kBAAkB,EAAE,KAC5D;CAEA,KAAK,MAAM,gBAAgB,eACzB,KAAK,MAAM,gBAAgB,aAAa,eACtC,KAAK,MAAM,SAAS,aAAa,QAAQ;EACvC,MAAM,KAAK,MAAM,MAAM,GAAG;EAC1B,IAAI,KAAK,IAAI,EAAE,GAAG;EAElB,KAAK,IAAI,EAAE;EACX,IAAI,KAAK,EAAE;CACb;CAIJ,OAAO;AACT;;;;;;AAOA,SAAgB,aAAa,QAA8B,KAAuB;CAChF,OAAO,QAAQ,SAAS,GAAG,IAAI,SAAS,CAAC,GAAI,UAAU,CAAC,GAAI,GAAG;AACjE"}

package/dist/dev/media/utils/preload.js

@@ -0,0 +1,21 @@
+//#region src/media/utils/preload.ts
+function isStandardPreload(value) {
+	return value === "auto" || value === "metadata" || value === "none";
+}
+/**
+* Default `preload` value used as the fallback across behaviors (`syncPreload`, `resolvePresentation`,
+* `isBlockingPreload`). SPF's own default, deliberately independent of the `<video>`/`<audio>` element's implicit
+* default — that one is UA policy and browser-dependent (`'metadata'` Chromium, `'auto'` WebKit), never a source.
+*/
+const DEFAULT_PRELOAD = "metadata";
+/**
+* True when the preload value blocks initial resolution / loading. Falsy values (undefined, empty) fall back to
+* `defaultPreload` (default `DEFAULT_PRELOAD`); the resolved value blocks iff it is `'none'`.
+*/
+function isBlockingPreload(preload, defaultPreload = DEFAULT_PRELOAD) {
+	return (preload || defaultPreload) === "none";
+}
+//#endregion
+export { DEFAULT_PRELOAD, isBlockingPreload, isStandardPreload };
+
+//# sourceMappingURL=preload.js.map

package/dist/dev/media/utils/preload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload.js","names":[],"sources":["../../../../src/media/utils/preload.ts"],"sourcesContent":["/**\n * The W3C-standard set of `<video>`/`<audio>` `preload` attribute values. SPF allows extended values (e.g. `'canplay'`)\n * on `state.preload`, which are _not_ reflected to the DOM — predicate below is the discriminator.\n */\nexport type StandardPreload = 'auto' | 'metadata' | 'none';\n\nexport function isStandardPreload(value: unknown): value is StandardPreload {\n  return value === 'auto' || value === 'metadata' || value === 'none';\n}\n\n/**\n * Default `preload` value used as the fallback across behaviors (`syncPreload`, `resolvePresentation`,\n * `isBlockingPreload`). SPF's own default, deliberately independent of the `<video>`/`<audio>` element's implicit\n * default — that one is UA policy and browser-dependent (`'metadata'` Chromium, `'auto'` WebKit), never a source.\n */\nexport const DEFAULT_PRELOAD = 'metadata';\n\n/**\n * True when the preload value blocks initial resolution / loading. Falsy values (undefined, empty) fall back to\n * `defaultPreload` (default `DEFAULT_PRELOAD`); the resolved value blocks iff it is `'none'`.\n */\nexport function isBlockingPreload(\n  preload: string | undefined,\n  defaultPreload: StandardPreload = DEFAULT_PRELOAD\n): boolean {\n  return (preload || defaultPreload) === 'none';\n}\n"],"mappings":";AAMA,SAAgB,kBAAkB,OAA0C;CAC1E,OAAO,UAAU,UAAU,UAAU,cAAc,UAAU;AAC/D;;;;;;AAOA,MAAa,kBAAkB;;;;;AAM/B,SAAgB,kBACd,SACA,iBAAkC,iBACzB;CACT,QAAQ,WAAW,oBAAoB;AACzC"}

package/dist/dev/media/utils/track-selection.js

@@ -0,0 +1,43 @@
+import { isResolvedTrack } from "../types/index.js";
+//#region src/media/utils/track-selection.ts
+/** Map track type to selected track ID property key in state. */
+const SelectedTrackIdKeyByType = {
+	video: "selectedVideoTrackId",
+	audio: "selectedAudioTrackId",
+	text: "selectedTextTrackId"
+};
+/**
+* Get selected track from state by type. Returns properly typed track (partially or fully resolved) or undefined. Type
+* parameter T is inferred from the type argument.
+*
+* @example
+*   const videoTrack = getSelectedTrack(state, 'video');
+*   if (videoTrack && isResolvedTrack(videoTrack)) {
+*     // videoTrack is VideoTrack
+*   }
+*/
+function getSelectedTrack(state, type) {
+	const { presentation } = state;
+	if (!presentation?.selectionSets) return void 0;
+	const trackId = state[SelectedTrackIdKeyByType[type]];
+	return presentation.selectionSets.find(({ type: selectionSetType }) => selectionSetType === type)?.switchingSets[0]?.tracks.find(({ id }) => id === trackId);
+}
+/**
+* Returns the duration of the first resolved selected track, preferring video over audio. A track is "resolved" once
+* its media playlist has been parsed (per {@link isResolvedTrack}). Returns `undefined` if neither selected track is
+* resolved.
+*/
+function getResolvedSelectedTrackDuration(state) {
+	if (state.selectedVideoTrackId) {
+		const video = getSelectedTrack(state, "video");
+		if (video && isResolvedTrack(video)) return video.duration;
+	}
+	if (state.selectedAudioTrackId) {
+		const audio = getSelectedTrack(state, "audio");
+		if (audio && isResolvedTrack(audio)) return audio.duration;
+	}
+}
+//#endregion
+export { SelectedTrackIdKeyByType, getResolvedSelectedTrackDuration, getSelectedTrack };
+
+//# sourceMappingURL=track-selection.js.map

package/dist/dev/media/utils/track-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-selection.js","names":[],"sources":["../../../../src/media/utils/track-selection.ts"],"sourcesContent":["import type {\n  AudioTrack,\n  MaybeResolvedPresentation,\n  PartiallyResolvedAudioTrack,\n  PartiallyResolvedTextTrack,\n  PartiallyResolvedVideoTrack,\n  TextTrack,\n  TrackType,\n  VideoTrack,\n} from '../types';\nimport { isResolvedTrack } from '../types';\n\n/** State shape for track selection. Minimal shape containing presentation and selected track IDs. */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string | undefined;\n  selectedAudioTrackId?: string | undefined;\n  selectedTextTrackId?: string | undefined;\n}\n\n/** Map track type to selected track ID property key in state. */\nexport const SelectedTrackIdKeyByType = {\n  video: 'selectedVideoTrackId',\n  audio: 'selectedAudioTrackId',\n  text: 'selectedTextTrackId',\n} as const;\n\n/**\n * Get selected track from state by type. Returns properly typed track (partially or fully resolved) or undefined. Type\n * parameter T is inferred from the type argument.\n *\n * @example\n *   const videoTrack = getSelectedTrack(state, 'video');\n *   if (videoTrack && isResolvedTrack(videoTrack)) {\n *     // videoTrack is VideoTrack\n *   }\n */\nexport function getSelectedTrack<T extends TrackType>(\n  state: TrackSelectionState,\n  type: T\n): T extends 'video'\n  ? PartiallyResolvedVideoTrack | VideoTrack | undefined\n  : T extends 'audio'\n    ? PartiallyResolvedAudioTrack | AudioTrack | undefined\n    : T extends 'text'\n      ? PartiallyResolvedTextTrack | TextTrack | undefined\n      : never {\n  const { presentation } = state;\n  if (!presentation?.selectionSets) return undefined as any;\n\n  // Get track ID based on type\n  const trackIdKey = SelectedTrackIdKeyByType[type];\n  const trackId = state[trackIdKey];\n\n  return presentation.selectionSets\n    .find(({ type: selectionSetType }) => selectionSetType === type)\n    ?.switchingSets[0]?.tracks.find(({ id }) => id === trackId) as any;\n}\n\n/**\n * Returns the duration of the first resolved selected track, preferring video over audio. A track is \"resolved\" once\n * its media playlist has been parsed (per {@link isResolvedTrack}). Returns `undefined` if neither selected track is\n * resolved.\n */\nexport function getResolvedSelectedTrackDuration(state: TrackSelectionState): number | undefined {\n  if (state.selectedVideoTrackId) {\n    const video = getSelectedTrack(state, 'video');\n    if (video && isResolvedTrack(video)) return video.duration;\n  }\n\n  if (state.selectedAudioTrackId) {\n    const audio = getSelectedTrack(state, 'audio');\n    if (audio && isResolvedTrack(audio)) return audio.duration;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;AAqBA,MAAa,2BAA2B;CACtC,OAAO;CACP,OAAO;CACP,MAAM;AACR;;;;;;;;;;;AAYA,SAAgB,iBACd,OACA,MAOY;CACZ,MAAM,EAAE,iBAAiB;CACzB,IAAI,CAAC,cAAc,eAAe,OAAO,KAAA;CAIzC,MAAM,UAAU,MADG,yBAAyB;CAG5C,OAAO,aAAa,cACjB,MAAM,EAAE,MAAM,uBAAuB,qBAAqB,IAAI,CAAC,EAC9D,cAAc,EAAE,EAAE,OAAO,MAAM,EAAE,SAAS,OAAO,OAAO;AAC9D;;;;;;AAOA,SAAgB,iCAAiC,OAAgD;CAC/F,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;CAEA,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;AAGF"}