@videojs/spf 10.0.0-beta.3 → 10.0.0-beta.30

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

@@ -0,0 +1,377 @@
+//#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":";;;;;;;;;;;;UAgBiB;EACf;;;;;;;EAOA,WAAW;;;;;UAMI;EACf;EACA;IACE;IACA;;;;;;;UAyBa;EACf;EACA;;;;;KAUU;;;;;;;;UAaK;EACf;EACA;;;;;;;;KAaU,kBAAkB,UAAU,QAAQ,SAAS,KAAK,yCAAyC;EACrG;EACA;EACA;EACA;;;;;;;;;;;;KA6BU,QAAQ,MAClB,oBACA;EACE,MAAM;EACN;EACA;EACA;EACA;EACA,iBAAiB;EACjB,UAAU;;;;;;;;;;;;;;;EAeV;;;;;;;;;;;;;EAaA;;;;;;;;;;;;;;;;;;;;UAqBa;EACf;EACA;EACA;EACA;;;;;;;KAQU,cAAc,cAAc,cAAc;;;;KAK1C,aAAa,QACvB,SAAS,KAAK;EACZ;EAGA;EACA;EACA,YAAY;;;;;;;;EAQZ;;;;;KAMQ,aAAa,QACvB,SAAS,KAAK;EACZ;EACA;EACA;EACA;EACA;EACA;EACA;;;;;KAMQ,YAAY;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;KAgBU,gBAAgB;EAC1B;EACA;EACA,WAAW;;;;;;;;;;UAWI;EACf;EACA;EACA;;;;;;KAmBU,6BAA6B,kBAAkB;;;;KAK/C,gBAAgB,aAAa,aAAa;;;;;;;KAoB1C,eAAe,UAAU,QAAQ,SAAS;EACpD,MAAM;EACN,SAAS,kBAAkB,KAAK;;;;;;;;KA8BtB,eAAe,UAAU,QAAQ,SAAS;EACpD,MAAM;EACN,eAAe,eAAe;;;;;KAMpB,oBAAoB,eAAe;;;;KAKnC,oBAAoB,eAAe;;;;KAKnC,mBAAmB,eAAe;;;;;KAMlC,eAAe,oBAAoB,oBAAoB;;;;;;;;;;;;;;KAmBvD,UAAU,MAAM,oBAAoB;EAAa;;;;;;;;;;;;;;UA4B5C;EACf;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;EAmBA;;;;;;;;;;;;;EAaA;;;;;;;;;;;;EAYA;;;iBAOc,yBAAyB,KAAK,KAAK,mBAAmB;;;;;;KAa1D;;;;;;;;KAwCA,eAAe,MACzB,oBACA,QAAQ;EACN,eAAe;;;;;;EAMf,aAAa;;;;;;;;;;;KAYL,4BAA4B,oBAAoB,QAAQ,KAAK,oBAAoB"}

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

@@ -0,0 +1,50 @@
+//#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)\n * Protocol-agnostic representation 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/**\n * Base identifier type for all HAM objects.\n */\nexport interface Ham {\n  id: string;\n  /**\n   * Format-/protocol-specific values that aren't part of the generic CMAF-HAM\n   * model — kept in an open bag so the model stays format-neutral (mirrors how\n   * CMAF-HAM itself stashes protocol extras rather than growing the model).\n   * Typed reads go through dedicated accessors (e.g. `getMediaPlaylistMetadata`).\n   */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Addressable resource with optional byte range.\n */\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.\n * Captures minimal shape needed for orchestration without DOM dependencies.\n * HTMLMediaElement satisfies this interface.\n */\nexport interface MediaElementLike {\n  preload: string;\n}\n\n// =============================================================================\n// Time and Duration\n// =============================================================================\n\n/**\n * Time span with start time and duration.\n * Used for segments and other timed ranges.\n */\nexport interface TimeSpan {\n  startTime: number;\n  duration: number;\n}\n\n// =============================================================================\n// Enums\n// =============================================================================\n\n/**\n * Track content type.\n */\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:\n * - 30 fps: { frameRateNumerator: 30 }\n * - 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.\n * 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.\n * Has metadata but no segments or initialization yet (media playlist not fetched).\n */\nexport type PartiallyResolvedVideoTrack = PartiallyResolved<VideoTrack>;\n\n/**\n * Partially resolved audio track from multivariant playlist.\n * Has metadata but no segments or initialization yet (media 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.\n * A resolved track has segments, duration, and initialization data.\n * All URLs are fully qualified (parsers resolve relative URLs).\n */\n/**\n * Track startTime is always 0 — the presentation-timeline origin (and future\n * multi-period base). The live sliding-window edge is `segments[0].startTime`,\n * 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\n     * (presentation-0) — the media-time base value of the coordinate model, peer\n     * to `startTime` (presentation). Derived from the container\n     * (`tfdt.baseMediaDecodeTime ÷ mdhd.timescale`); the relocation offset is\n     * `−startMediaTime` (targets presentation-0 — `Track.startTime` plays no\n     * part), never stored.\n     *\n     * Optional: `undefined` means not yet established, or never establishable\n     * (e.g. text tracks carry no container origin); a near-zero/native origin is\n     * established as `0` (no relocation). Established once per source by the\n     * `establishStartMediaTime` reactor. See\n     * `internal/design/spf/presentation-timeline-model.md`.\n     */\n    startMediaTime?: number;\n    /**\n     * Wall-clock time (epoch seconds) at the track's timeline origin\n     * (presentation-0) — pure playlist arithmetic over any PDT-bearing segment:\n     * `segment.startDate − segment.startTime`, invariant along a linear\n     * timeline. Optional: absent when no segment carries `startDate`.\n     *\n     * The wall-clock member of the coordinate triple (peer to `startTime` and\n     * `startMediaTime`). For live it is the anchor segments are PDT-placed\n     * against on every parse; equal `startDate` across tracks marks the same\n     * presentation instant. See\n     * `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\n * track's `track_id` + `mdhd` timescale from the init, `tfdt` baseMediaDecodeTime of\n * that same track from the first media segment) — hence optional. The transient input\n * the `establishStartMediaTime` reactor reduces into `Track.startMediaTime`.\n *\n * `trackId` is the ISO-BMFF `track_ID` of the buffered media track (`vide`/`soun`),\n * read from the init's `tkhd`; it ties the timescale to the *same* track's\n * `baseMediaDecodeTime` (matched via `tfhd.track_id`) so a muxed segment carrying a\n * 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\n * `baseMediaDecodeTime` was read from — *not* a container value (it's the playlist\n * position), but co-located because the origin is `baseMediaDecodeTime/timescale −\n * segmentStartTime`: the first *loaded* segment isn't necessarily the 0th (a\n * non-zero initial `currentTime`, or live/DVR), so the decode time alone isn't the\n * 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\n * payload the loader pipeline carries; `AppendData` (the MSE `SourceBuffer` append\n * input in `media/dom/mse`) is an alias of this at the DOM boundary.\n */\nexport type SegmentData = ArrayBuffer | AsyncIterable<Uint8Array>;\n\n/**\n * Resolved video track with segments.\n */\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\n     * with. A list because one rendition is typically listed across multiple\n     * `EXT-X-STREAM-INF` entries — one per audio group (the HLS cross-product) —\n     * which the parser collapses into a single track carrying every group it\n     * advertised.\n     */\n    audioGroupIds?: string[];\n  };\n\n/**\n * Resolved audio track with segments.\n */\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/**\n * Resolved text track with segments.\n */\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\n * capability-probing surface, read by the track-switching hard-constraint\n * pre-pass (`excludeUnplayableTracks`) to drop undecodable renditions before\n * selection. Kept DOM-free here (a plain function type over a minimal track\n * shape) so DOM-free behaviors can consume it; the DOM implementation\n * (`canPlayTrack` in `media/dom/capabilities.ts`) wraps\n * `MediaSource.isTypeSupported`.\n *\n * Takes the minimal codec-bearing shape both video and audio candidates\n * carry. `mimeType` is optional so unprobeable candidates (no MIME) can be\n * 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\n * interface, so DOM consumers pass `VTTCue` values directly. Non-DOM\n * hosts (workers, test fakes, non-browser engines) can satisfy the same\n * shape without pulling in DOM 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\n * which text tracks are currently mounted on the media. `HTMLMediaElement`\n * structurally satisfies this (its `textTracks` is a `TextTrackList`,\n * which is iterable with `{ 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.\n * Has metadata but no segments or initialization yet (media playlist not fetched).\n */\nexport type PartiallyResolvedTextTrack = PartiallyResolved<TextTrack>;\n\n/**\n * Union of all resolved track types.\n */\nexport type ResolvedTrack = VideoTrack | AudioTrack | TextTrack;\n\n/**\n * Union of all partially resolved track types.\n */\nexport type PartiallyResolvedTrack =\n  | PartiallyResolvedVideoTrack\n  | PartiallyResolvedAudioTrack\n  | PartiallyResolvedTextTrack;\n\n// =============================================================================\n// Switching and Selection Sets\n// =============================================================================\n\n/**\n * Generic switching set type.\n * 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/**\n * Video switching set - contains only video tracks (partially resolved or fully resolved).\n */\nexport type VideoSwitchingSet = SwitchingSetOf<VideoTrack>;\n\n/**\n * Audio switching set - contains only audio tracks (partially resolved or fully resolved).\n */\nexport type AudioSwitchingSet = SwitchingSetOf<AudioTrack>;\n\n/**\n * Text switching set - contains only text tracks (partially resolved or fully resolved).\n */\nexport type TextSwitchingSet = SwitchingSetOf<TextTrack>;\n\n/**\n * Switching set - a group of tracks that can be switched between seamlessly.\n * Discriminated by track type.\n */\nexport type SwitchingSet = VideoSwitchingSet | AudioSwitchingSet | TextSwitchingSet;\n\n/**\n * Generic selection set type.\n * 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/**\n * Video selection set - contains only video switching sets.\n */\nexport type VideoSelectionSet = SelectionSetOf<VideoTrack>;\n\n/**\n * Audio selection set - contains only audio switching sets.\n */\nexport type AudioSelectionSet = SelectionSetOf<AudioTrack>;\n\n/**\n * Text selection set - contains only text switching sets.\n */\nexport type TextSelectionSet = SelectionSetOf<TextTrack>;\n\n/**\n * Selection set - groups switching sets by track type.\n * Discriminated union ensures type-safe track access.\n */\nexport type SelectionSet = VideoSelectionSet | AudioSelectionSet | TextSelectionSet;\n\n// =============================================================================\n// Segment\n// =============================================================================\n\n/**\n * Media segment with timing information.\n * Follows CMAF-HAM composition pattern.\n *\n * `startDate` is the absolute wall-clock time of the segment's first\n * sample, in **epoch seconds** (unit-consistent with `startTime`/`duration`),\n * derived from `#EXT-X-PROGRAM-DATE-TIME` (explicit or interpolated forward via\n * `EXTINF`). Unlike the per-track-relative `startTime`, it is comparable across\n * tracks, so it is the cross-track sync anchor for demuxed audio/video and the\n * exact recovery value on a full live-window turnover. Optional: absent when the\n * source carries no PDT (allowed by RFC 8216, required by Apple's HLS authoring\n * 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\n * segments are considered the same position when\n * `Math.abs(a.startTime - b.startTime) < SEGMENT_TIME_EPSILON`. Used by\n * the source-buffer dedup and segment-loader quality-aware filter to\n * tolerate sub-millisecond drift in segment timestamps across multiple\n * playlists / quality 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\n * specifics — not part of the generic CMAF-HAM model — so they live under\n * `Ham.metadata` (read via `getMediaPlaylistMetadata`) rather than as\n * first-class `Track` fields:\n *\n * - `targetDuration` (`#EXT-X-TARGETDURATION`) — reload-cadence basis.\n * - `mediaSequence` (`#EXT-X-MEDIA-SEQUENCE`, default 0) — sequence number of\n *   `segments[0]`; the join key for merging 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\n   * `METHOD` isn't `NONE`. Detection only: enough to tell that playback needs\n   * decryption support, not enough to perform it.\n   *\n   * Deliberately *not* a model-level `protection` shape. CMAF-HAM puts\n   * `protection` on `SwitchingSet`, but that can't express two real cases: a\n   * clear lead (`METHOD=NONE` segments followed by encrypted ones — protection\n   * varies along the timeline within one rendition) or key rotation (its single\n   * `defaultKid` can't represent a key changing over time). Modeling it properly\n   * belongs to DRM support; until then this records the one fact a playlist\n   * reliably gives us. Per-rendition because that's HLS's granularity —\n   * `EXT-X-KEY` is a media-playlist tag.\n   *\n   * Conservative for a clear lead: a rendition whose opening segments are clear\n   * still reads as encrypted, so it's judged unplayable rather than played until\n   * it breaks.\n   */\n  encrypted?: boolean;\n  /**\n   * `EXT-X-SERVER-CONTROL` `HOLD-BACK` (seconds) — the server's declared distance\n   * from the live edge for clients playing *complete* segments. Absent when the\n   * server doesn't advertise it, in which case the spec default (3 × target\n   * duration) applies. Deliberately HLS vocabulary living in the playlist\n   * metadata rather than on `Track`: whether a wall-clock holdback generalizes\n   * across delivery formats is unresolved.\n   *\n   * `PART-HOLD-BACK` is **not** captured — it only applies to clients playing\n   * partial segments, and using it while fetching whole segments would put the\n   * 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\n   * `#EXT-X-PART`, `#EXT-X-PART-INF`, or `EXT-X-SERVER-CONTROL`'s\n   * `PART-HOLD-BACK`.\n   *\n   * Detection only, and deliberately so: partial segments are ignored by the\n   * parser and the loader fetches whole segments, so an LL-HLS playlist plays as\n   * standard live at standard latency. Recording the fact is what lets a\n   * composition *say* that rather than silently under-delivering the latency the\n   * 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\n * (consumer-facing), distinct from completeness / duration: a live stream that\n * 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,\n * only `#EXT-X-PLAYLIST-TYPE:VOD` marks on-demand; everything else (EVENT, or\n * 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/**\n * Intermediate representation of a parsed media playlist.\n * Used internally before assembling into full Track structure.\n */\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.\n * Uses TimeSpan fields (startTime always 0, duration optional until track resolved).\n *\n * Extends AddressableObject so `url` contains the original manifest URL.\n * All URLs are fully qualified (parsers resolve 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\n     * playlist is parsed (derived from `#EXT-X-PLAYLIST-TYPE` via\n     * `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\n * resolver populates the rest in place. `url` is always present; resolved\n * 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/**\n * Check if a track is resolved (has segments).\n * Works for all track types with overloaded signatures for type narrowing.\n */\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/**\n * Check if a presentation has duration (at least one track resolved).\n * Narrows type to include required duration.\n */\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\n * manifest and populated both `id` and `selectionSets`. Both must be\n * present — a partial value with only one of them isn't usable, and\n * letting it through would have downstream behaviors crash when they\n * 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":";;;;;;;;;AA2ZA,MAAa,uBAAuB;;AAsEpC,MAAa,8BAA8B;;AAG3C,SAAgB,yBAAyB,KAA+D;CACtG,OAAO,IAAI,WAAW;AACxB;;;;;;AAkBA,SAAgB,iBAAiB,UAAyD;CACxF,OAAO,UAAU,iBAAiB,QAAQ,cAAc;AAC1D;AAkEA,SAAgB,gBAAgB,OAAuE;CACrG,OAAO,cAAc;AACvB;;;;;AAMA,SAAgB,wBACd,cACkE;CAClE,OAAO,aAAa,aAAa,KAAA;AACnC;;;;;;;;;;AAWA,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,13 @@
+//#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":";;;;;;;;;KAUY,YAAY"}

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

@@ -0,0 +1,56 @@
+//#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\n * pure (deliberately not a `resolve*` — no fetch). Consumers override the\n * default via the engine's `getCdnId` config (e.g. to key on Mux's `cdn=` query\n * param instead of the host); every CDN-identity site reads that same function\n * so keys stay comparable across `cdnPriority`, `failedCdns`, and the\n * 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\n * to the raw string when the URL can't be parsed, so the return value is always\n * 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\n * first, then audio, then text (manifest order within a type). The head is the\n * 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\n * no tracks.\n *\n * Redundant-stream sources list the same content on multiple hosts (e.g. Mux's\n * `?redundant_streams=true`), so each host contributes its own candidate tracks;\n * 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\n * 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  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        seen.add(id);\n        ids.push(id);\n      }\n    }\n  }\n  return ids;\n}\n\n/**\n * Add a CDN id to a failed-CDN list, preserving order and ignoring duplicates.\n * Idempotent: re-adding an already-present id returns the same array reference\n * (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":";;;;;;AAiBA,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;;;;;;;;;;;;;;AAenF,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;CACA,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;EAClB,KAAK,IAAI,EAAE;EACX,IAAI,KAAK,EAAE;CACb;CAGJ,OAAO;AACT;;;;;;;AAQA,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,22 @@
+//#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`). Matches the
+* `<video>`/`<audio>` element's implicit default.
+*/
+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.\n * SPF allows extended values (e.g. `'canplay'`) on `state.preload`, which\n * 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\n * (`syncPreload`, `resolvePresentation`, `isBlockingPreload`). Matches the\n * `<video>`/`<audio>` element's implicit default.\n */\nexport const DEFAULT_PRELOAD = 'metadata';\n\n/**\n * True when the preload value blocks initial resolution / loading.\n * Falsy values (undefined, empty) fall back to `defaultPreload` (default\n * `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":";AAOA,SAAgB,kBAAkB,OAA0C;CAC1E,OAAO,UAAU,UAAU,UAAU,cAAc,UAAU;AAC/D;;;;;;AAOA,MAAa,kBAAkB;;;;;;AAO/B,SAAgB,kBACd,SACA,iBAAkC,iBACzB;CACT,QAAQ,WAAW,oBAAoB;AACzC"}

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

@@ -0,0 +1,47 @@
+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/**\n * State shape for track selection.\n * Minimal shape containing presentation and selected track IDs.\n */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string | undefined;\n  selectedAudioTrackId?: string | undefined;\n  selectedTextTrackId?: string | undefined;\n}\n\n/**\n * Map track type to selected track ID property key in state.\n */\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.\n * Returns properly typed track (partially or fully resolved) or undefined.\n * Type 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\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  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\n * video over audio. A track is \"resolved\" once its media playlist has been\n * parsed (per {@link isResolvedTrack}). Returns `undefined` if neither\n * selected track is 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  if (state.selectedAudioTrackId) {\n    const audio = getSelectedTrack(state, 'audio');\n    if (audio && isResolvedTrack(audio)) return audio.duration;\n  }\n  return undefined;\n}\n"],"mappings":";;;;;AA0BA,MAAa,2BAA2B;CACtC,OAAO;CACP,OAAO;CACP,MAAM;AACR;;;;;;;;;;;;AAaA,SAAgB,iBACd,OACA,MAOY;CACZ,MAAM,EAAE,iBAAiB;CAEzB,IAAI,CAAC,cAAc,eAAe,OAAO,KAAA;CAIzC,MAAM,UAAU,MADG,yBAAyB;CAE5C,OAAO,aAAa,cACjB,MAAM,EAAE,MAAM,uBAAuB,qBAAqB,IAAI,CAAC,EAC9D,cAAc,EAAE,EAAE,OAAO,MAAM,EAAE,SAAS,OAAO,OAAO;AAC9D;;;;;;;AAQA,SAAgB,iCAAiC,OAAgD;CAC/F,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;CACA,IAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,OAAO;EAC7C,IAAI,SAAS,gBAAgB,KAAK,GAAG,OAAO,MAAM;CACpD;AAEF"}