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

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

@@ -1 +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/AcademySoftwareFoundation/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\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 (for future multi-period support).\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\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: { mimeType?: string; codecs?: string[] }) => 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 */\nexport type Segment = Ham & AddressableObject & TimeSpan;\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 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\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":";;;;;;;;;AAyUA,MAAa,uBAAuB;AA4DpC,SAAgB,gBAAgB,OAAuE;AACrG,QAAO,cAAc;;;;;;AAOvB,SAAgB,wBACd,cACkE;AAClE,QAAO,aAAa,aAAa,KAAA;;;;;;;;;;;AAYnC,SAAgB,uBACd,cAC8B;AAC9B,QAAO,iBAAiB,KAAA,KAAa,aAAa,OAAO,KAAA,KAAa,aAAa,kBAAkB,KAAA"}
+{"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/AcademySoftwareFoundation/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\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 (for future multi-period support).\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     * (`startTime`) — the media-time base value of the coordinate model, peer to\n     * `startTime` (presentation). Derived from the container\n     * (`tfdt.baseMediaDecodeTime ÷ mdhd.timescale`); the relocation offset is\n     * `startTime − startMediaTime`, never stored.\n     *\n     * Optional: absent until established (0-PTS sources never set it — their\n     * origin is already 0). Established once per source by the\n     * `establishStartMediaTime` reactor. See\n     * `internal/design/spf/presentation-timeline-model.md`.\n     */\n    startMediaTime?: 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: { mimeType?: string; codecs?: string[] }) => 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 */\nexport type Segment = Ham & AddressableObject & TimeSpan;\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 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\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":";;;;;;;;;AAsXA,MAAa,uBAAuB;AA4DpC,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/default/media/utils/cdn.js.map

@@ -1 +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;AAC5C,KAAI;AACF,SAAO,IAAI,IAAI,IAAI,CAAC;SACd;AACN,SAAO;;;AAUX,MAAM,oBAA+C;CAAE,OAAO;CAAG,OAAO;CAAG,MAAM;CAAG;;;;;;;;;;;;;;AAepF,SAAgB,iBAAiB,cAAyC,QAAkB,UAAoB;CAC9G,MAAM,uBAAO,IAAI,KAAa;CAC9B,MAAM,MAAgB,EAAE;CAExB,MAAM,gBAAgB,CAAC,GAAI,aAAa,iBAAiB,EAAE,CAAE,CAAC,MAC3D,GAAG,MAAM,kBAAkB,EAAE,QAAQ,kBAAkB,EAAE,MAC3D;AACD,MAAK,MAAM,gBAAgB,cACzB,MAAK,MAAM,gBAAgB,aAAa,cACtC,MAAK,MAAM,SAAS,aAAa,QAAQ;EACvC,MAAM,KAAK,MAAM,MAAM,IAAI;AAC3B,MAAI,KAAK,IAAI,GAAG,CAAE;AAClB,OAAK,IAAI,GAAG;AACZ,MAAI,KAAK,GAAG;;AAIlB,QAAO;;;;;;;;AAST,SAAgB,aAAa,QAA8B,KAAuB;AAChF,QAAO,QAAQ,SAAS,IAAI,GAAG,SAAS,CAAC,GAAI,UAAU,EAAE,EAAG,IAAI"}
+{"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/default/media/utils/preload.js.map

@@ -1 +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;AAC1E,QAAO,UAAU,UAAU,UAAU,cAAc,UAAU;;;;;;;AAQ/D,MAAa,kBAAkB;;;;;;AAO/B,SAAgB,kBACd,SACA,iBAAkC,iBACzB;AACT,SAAQ,WAAW,oBAAoB"}
+{"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/default/media/utils/track-selection.js

@@ -42,6 +42,6 @@ function getResolvedSelectedTrackDuration(state) {
 	}
 }
 //#endregion
-export { getResolvedSelectedTrackDuration, getSelectedTrack };
+export { SelectedTrackIdKeyByType, getResolvedSelectedTrackDuration, getSelectedTrack };
 
 //# sourceMappingURL=track-selection.js.map

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

@@ -1 +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;CACP;;;;;;;;;;;;AAaD,SAAgB,iBACd,OACA,MAOY;CACZ,MAAM,EAAE,iBAAiB;AAEzB,KAAI,CAAC,cAAc,cAAe,QAAO,KAAA;CAIzC,MAAM,UAAU,MADG,yBAAyB;AAE5C,QAAO,aAAa,cACjB,MAAM,EAAE,MAAM,uBAAuB,qBAAqB,KAAK,EAC9D,cAAc,IAAI,OAAO,MAAM,EAAE,SAAS,OAAO,QAAQ;;;;;;;;AAS/D,SAAgB,iCAAiC,OAAgD;AAC/F,KAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,QAAQ;AAC9C,MAAI,SAAS,gBAAgB,MAAM,CAAE,QAAO,MAAM;;AAEpD,KAAI,MAAM,sBAAsB;EAC9B,MAAM,QAAQ,iBAAiB,OAAO,QAAQ;AAC9C,MAAI,SAAS,gBAAgB,MAAM,CAAE,QAAO,MAAM"}
+{"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"}

package/dist/default/media/utils/tracks.js

@@ -53,19 +53,19 @@ function findTrackById(presentation, trackId) {
 function findResolvedTextTrack(presentation, trackId) {
 	if (!presentation || !trackId) return void 0;
 	const track = findTrack(presentation, "text", trackId);
-	if (!track || track.type !== "text" || !isResolvedTrack(track)) return void 0;
+	if (track?.type !== "text" || !isResolvedTrack(track)) return void 0;
 	return track;
 }
 function findResolvedVideoTrack(presentation, trackId) {
 	if (!presentation || !trackId) return void 0;
 	const track = findTrack(presentation, "video", trackId);
-	if (!track || track.type !== "video" || !isResolvedTrack(track)) return void 0;
+	if (track?.type !== "video" || !isResolvedTrack(track)) return void 0;
 	return track;
 }
 function findResolvedAudioTrack(presentation, trackId) {
 	if (!presentation || !trackId) return void 0;
 	const track = findTrack(presentation, "audio", trackId);
-	if (!track || track.type !== "audio" || !isResolvedTrack(track)) return void 0;
+	if (track?.type !== "audio" || !isResolvedTrack(track)) return void 0;
 	return track;
 }
 /**

package/dist/default/media/utils/tracks.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracks.js","names":[],"sources":["../../../../src/media/utils/tracks.ts"],"sourcesContent":["import type {\n  AudioTrack,\n  MaybeResolvedPresentation,\n  PartiallyResolvedTrack,\n  Presentation,\n  ResolvedTrack,\n  TextTrack,\n  TrackType,\n  VideoTrack,\n} from '../types';\nimport { isResolvedTrack } from '../types';\n\n/**\n * Get the tracks of the given type from a presentation's first switching set.\n *\n * Returns `[]` when the presentation is unresolved, when no selection set of\n * `type` exists, or when its first switching set is empty. Returned tracks may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n *\n * The \"first switching set\" assumption matches the rest of the codebase\n * (HLS typically has one switching set per type); multi-group / multi-period\n * support would generalize this.\n */\nexport function getTracksByType(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType\n): readonly (PartiallyResolvedTrack | ResolvedTrack)[] {\n  return presentation.selectionSets?.find(({ type: t }) => t === type)?.switchingSets[0]?.tracks ?? [];\n}\n\n/**\n * Find a track of the given type and id within a presentation.\n *\n * Returns the matching track from the first switching set of the matching\n * selection set, or `undefined` if either is missing. The returned track may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n */\nexport function findTrack(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  return getTracksByType(presentation, type).find(({ id }) => id === trackId);\n}\n\n/**\n * Find a track by id across all selection sets in a presentation, without\n * knowing its type up front. Used when the caller has a track id obtained\n * from a downstream consumer (e.g. `SourceBufferActor.initTrackId`) and\n * needs to locate the corresponding track in the presentation.\n *\n * Track ids are unique within a presentation per the HLS spec; the first\n * match wins.\n */\nexport function findTrackById(\n  presentation: MaybeResolvedPresentation,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  for (const selectionSet of presentation.selectionSets ?? []) {\n    const track = selectionSet.switchingSets[0]?.tracks.find(({ id }) => id === trackId);\n    if (track) return track;\n  }\n  return undefined;\n}\n\n/**\n * Find a text track of the given id within a presentation and narrow it to\n * the fully-resolved `TextTrack` shape (segments populated). Returns\n * `undefined` if no track matches the id, the matching track isn't a text\n * track, or it hasn't been resolved yet.\n *\n * The segments-non-empty check stays at the call site — a resolved track\n * with zero segments is a valid state, distinct from \"ready to load.\"\n */\nexport function findResolvedTextTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): TextTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'text', trackId);\n  // `findTrack` returns the wide union; narrow via discriminant before\n  // applying `isResolvedTrack`'s text-specific overload.\n  if (!track || track.type !== 'text' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\nexport function findResolvedVideoTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): VideoTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'video', trackId);\n  if (!track || track.type !== 'video' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\nexport function findResolvedAudioTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): AudioTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'audio', trackId);\n  if (!track || track.type !== 'audio' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\n/**\n * Whether a track carries a non-empty `codecs` array. Both partially-\n * resolved and fully-resolved tracks may carry codecs — they come from\n * the multivariant playlist's `EXT-X-STREAM-INF` line, not from the\n * per-type media playlist — so this works at either resolution stage.\n *\n * `TextTrack` doesn't declare a `codecs` field; the `'codecs' in track`\n * check narrows it out for the false branch.\n */\nexport function hasCodecs(track: PartiallyResolvedTrack | ResolvedTrack | undefined): boolean {\n  return !!track && 'codecs' in track && !!track.codecs?.length;\n}\n\n/**\n * Set `mimeType` on every track of one `type` (immutably). Used to propagate a\n * detected container across a type's renditions: an ABR ladder is the same\n * content at different bitrates, so one rendition's container holds for all of\n * them — capability probing + SourceBuffer setup then get the right MIME for the\n * whole type from a single resolved media playlist, without fetching the rest.\n *\n * Scoped to one type on purpose: propagating *across* audio/video would be wrong\n * for mixed-container sources (e.g. muxed-TS video + raw-`.aac` audio) and races\n * concurrent per-type resolution. Same-type writes are disjoint and safe.\n * Idempotent — tracks already at `mimeType` are left as-is.\n */\nexport function applyContainerMimeType(presentation: Presentation, type: TrackType, mimeType: string): Presentation {\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) =>\n      selectionSet.type === type\n        ? {\n            ...selectionSet,\n            switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n              ...switchingSet,\n              tracks: switchingSet.tracks.map((track) =>\n                track.mimeType === mimeType ? track : { ...track, mimeType }\n              ),\n            })),\n          }\n        : selectionSet\n    ),\n  } as Presentation;\n}\n\n/**\n * Updates a track within a presentation (immutably). Generic — works for\n * video, audio, or text tracks.\n */\nexport function updateTrackInPresentation<T extends ResolvedTrack>(\n  presentation: Presentation,\n  resolvedTrack: T\n): Presentation {\n  const trackId = resolvedTrack.id;\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) => ({\n      ...selectionSet,\n      switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n        ...switchingSet,\n        tracks: switchingSet.tracks.map((track) => (track.id === trackId ? resolvedTrack : track)),\n      })),\n    })),\n  } as Presentation;\n}\n"],"mappings":";;;;;;;;;;;;;;AAwBA,SAAgB,gBACd,cACA,MACqD;AACrD,QAAO,aAAa,eAAe,MAAM,EAAE,MAAM,QAAQ,MAAM,KAAK,EAAE,cAAc,IAAI,UAAU,EAAE;;;;;;;;;;AAWtG,SAAgB,UACd,cACA,MACA,SACoD;AACpD,QAAO,gBAAgB,cAAc,KAAK,CAAC,MAAM,EAAE,SAAS,OAAO,QAAQ;;;;;;;;;;;AAY7E,SAAgB,cACd,cACA,SACoD;AACpD,MAAK,MAAM,gBAAgB,aAAa,iBAAiB,EAAE,EAAE;EAC3D,MAAM,QAAQ,aAAa,cAAc,IAAI,OAAO,MAAM,EAAE,SAAS,OAAO,QAAQ;AACpF,MAAI,MAAO,QAAO;;;;;;;;;;;;AActB,SAAgB,sBACd,cACA,SACuB;AACvB,KAAI,CAAC,gBAAgB,CAAC,QAAS,QAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,QAAQ,QAAQ;AAGtD,KAAI,CAAC,SAAS,MAAM,SAAS,UAAU,CAAC,gBAAgB,MAAM,CAAE,QAAO,KAAA;AACvE,QAAO;;AAGT,SAAgB,uBACd,cACA,SACwB;AACxB,KAAI,CAAC,gBAAgB,CAAC,QAAS,QAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,SAAS,QAAQ;AACvD,KAAI,CAAC,SAAS,MAAM,SAAS,WAAW,CAAC,gBAAgB,MAAM,CAAE,QAAO,KAAA;AACxE,QAAO;;AAGT,SAAgB,uBACd,cACA,SACwB;AACxB,KAAI,CAAC,gBAAgB,CAAC,QAAS,QAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,SAAS,QAAQ;AACvD,KAAI,CAAC,SAAS,MAAM,SAAS,WAAW,CAAC,gBAAgB,MAAM,CAAE,QAAO,KAAA;AACxE,QAAO;;;;;;;;;;;AAYT,SAAgB,UAAU,OAAoE;AAC5F,QAAO,CAAC,CAAC,SAAS,YAAY,SAAS,CAAC,CAAC,MAAM,QAAQ;;;;;;;;;;;;;;AAezD,SAAgB,uBAAuB,cAA4B,MAAiB,UAAgC;AAClH,QAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,iBAC7C,aAAa,SAAS,OAClB;GACE,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAC/B,MAAM,aAAa,WAAW,QAAQ;KAAE,GAAG;KAAO;KAAU,CAC7D;IACF,EAAE;GACJ,GACD,aACL;EACF;;;;;;AAOH,SAAgB,0BACd,cACA,eACc;CACd,MAAM,UAAU,cAAc;AAC9B,QAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;GAC/D,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAAW,MAAM,OAAO,UAAU,gBAAgB,MAAO;IAC3F,EAAE;GACJ,EAAE;EACJ"}
+{"version":3,"file":"tracks.js","names":[],"sources":["../../../../src/media/utils/tracks.ts"],"sourcesContent":["import type {\n  AudioTrack,\n  MaybeResolvedPresentation,\n  PartiallyResolvedTrack,\n  Presentation,\n  ResolvedTrack,\n  TextTrack,\n  TrackType,\n  VideoTrack,\n} from '../types';\nimport { isResolvedTrack } from '../types';\n\n/**\n * Get the tracks of the given type from a presentation's first switching set.\n *\n * Returns `[]` when the presentation is unresolved, when no selection set of\n * `type` exists, or when its first switching set is empty. Returned tracks may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n *\n * The \"first switching set\" assumption matches the rest of the codebase\n * (HLS typically has one switching set per type); multi-group / multi-period\n * support would generalize this.\n */\nexport function getTracksByType(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType\n): readonly (PartiallyResolvedTrack | ResolvedTrack)[] {\n  return presentation.selectionSets?.find(({ type: t }) => t === type)?.switchingSets[0]?.tracks ?? [];\n}\n\n/**\n * Find a track of the given type and id within a presentation.\n *\n * Returns the matching track from the first switching set of the matching\n * selection set, or `undefined` if either is missing. The returned track may\n * be partially resolved (URL only) or fully resolved (with segments) — callers\n * narrow as needed.\n */\nexport function findTrack(\n  presentation: MaybeResolvedPresentation,\n  type: TrackType,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  return getTracksByType(presentation, type).find(({ id }) => id === trackId);\n}\n\n/**\n * Find a track by id across all selection sets in a presentation, without\n * knowing its type up front. Used when the caller has a track id obtained\n * from a downstream consumer (e.g. `SourceBufferActor.initTrackId`) and\n * needs to locate the corresponding track in the presentation.\n *\n * Track ids are unique within a presentation per the HLS spec; the first\n * match wins.\n */\nexport function findTrackById(\n  presentation: MaybeResolvedPresentation,\n  trackId: string\n): PartiallyResolvedTrack | ResolvedTrack | undefined {\n  for (const selectionSet of presentation.selectionSets ?? []) {\n    const track = selectionSet.switchingSets[0]?.tracks.find(({ id }) => id === trackId);\n    if (track) return track;\n  }\n  return undefined;\n}\n\n/**\n * Find a text track of the given id within a presentation and narrow it to\n * the fully-resolved `TextTrack` shape (segments populated). Returns\n * `undefined` if no track matches the id, the matching track isn't a text\n * track, or it hasn't been resolved yet.\n *\n * The segments-non-empty check stays at the call site — a resolved track\n * with zero segments is a valid state, distinct from \"ready to load.\"\n */\nexport function findResolvedTextTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): TextTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'text', trackId);\n  // `findTrack` returns the wide union; narrow via discriminant before\n  // applying `isResolvedTrack`'s text-specific overload.\n  if (track?.type !== 'text' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\nexport function findResolvedVideoTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): VideoTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'video', trackId);\n  if (track?.type !== 'video' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\nexport function findResolvedAudioTrack(\n  presentation: MaybeResolvedPresentation | undefined,\n  trackId: string | undefined\n): AudioTrack | undefined {\n  if (!presentation || !trackId) return undefined;\n  const track = findTrack(presentation, 'audio', trackId);\n  if (track?.type !== 'audio' || !isResolvedTrack(track)) return undefined;\n  return track;\n}\n\n/**\n * Whether a track carries a non-empty `codecs` array. Both partially-\n * resolved and fully-resolved tracks may carry codecs — they come from\n * the multivariant playlist's `EXT-X-STREAM-INF` line, not from the\n * per-type media playlist — so this works at either resolution stage.\n *\n * `TextTrack` doesn't declare a `codecs` field; the `'codecs' in track`\n * check narrows it out for the false branch.\n */\nexport function hasCodecs(track: PartiallyResolvedTrack | ResolvedTrack | undefined): boolean {\n  return !!track && 'codecs' in track && !!track.codecs?.length;\n}\n\n/**\n * Set `mimeType` on every track of one `type` (immutably). Used to propagate a\n * detected container across a type's renditions: an ABR ladder is the same\n * content at different bitrates, so one rendition's container holds for all of\n * them — capability probing + SourceBuffer setup then get the right MIME for the\n * whole type from a single resolved media playlist, without fetching the rest.\n *\n * Scoped to one type on purpose: propagating *across* audio/video would be wrong\n * for mixed-container sources (e.g. muxed-TS video + raw-`.aac` audio) and races\n * concurrent per-type resolution. Same-type writes are disjoint and safe.\n * Idempotent — tracks already at `mimeType` are left as-is.\n */\nexport function applyContainerMimeType(presentation: Presentation, type: TrackType, mimeType: string): Presentation {\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) =>\n      selectionSet.type === type\n        ? {\n            ...selectionSet,\n            switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n              ...switchingSet,\n              tracks: switchingSet.tracks.map((track) =>\n                track.mimeType === mimeType ? track : { ...track, mimeType }\n              ),\n            })),\n          }\n        : selectionSet\n    ),\n  } as Presentation;\n}\n\n/**\n * Updates a track within a presentation (immutably). Generic — works for\n * video, audio, or text tracks.\n */\nexport function updateTrackInPresentation<T extends ResolvedTrack>(\n  presentation: Presentation,\n  resolvedTrack: T\n): Presentation {\n  const trackId = resolvedTrack.id;\n  return {\n    ...presentation,\n    selectionSets: presentation.selectionSets.map((selectionSet) => ({\n      ...selectionSet,\n      switchingSets: selectionSet.switchingSets.map((switchingSet) => ({\n        ...switchingSet,\n        tracks: switchingSet.tracks.map((track) => (track.id === trackId ? resolvedTrack : track)),\n      })),\n    })),\n  } as Presentation;\n}\n"],"mappings":";;;;;;;;;;;;;;AAwBA,SAAgB,gBACd,cACA,MACqD;CACrD,OAAO,aAAa,eAAe,MAAM,EAAE,MAAM,QAAQ,MAAM,IAAI,CAAC,EAAE,cAAc,EAAE,EAAE,UAAU,CAAC;AACrG;;;;;;;;;AAUA,SAAgB,UACd,cACA,MACA,SACoD;CACpD,OAAO,gBAAgB,cAAc,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,OAAO,OAAO;AAC5E;;;;;;;;;;AAWA,SAAgB,cACd,cACA,SACoD;CACpD,KAAK,MAAM,gBAAgB,aAAa,iBAAiB,CAAC,GAAG;EAC3D,MAAM,QAAQ,aAAa,cAAc,EAAE,EAAE,OAAO,MAAM,EAAE,SAAS,OAAO,OAAO;EACnF,IAAI,OAAO,OAAO;CACpB;AAEF;;;;;;;;;;AAWA,SAAgB,sBACd,cACA,SACuB;CACvB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,QAAQ,OAAO;CAGrD,IAAI,OAAO,SAAS,UAAU,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAC9D,OAAO;AACT;AAEA,SAAgB,uBACd,cACA,SACwB;CACxB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,SAAS,OAAO;CACtD,IAAI,OAAO,SAAS,WAAW,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAC/D,OAAO;AACT;AAEA,SAAgB,uBACd,cACA,SACwB;CACxB,IAAI,CAAC,gBAAgB,CAAC,SAAS,OAAO,KAAA;CACtC,MAAM,QAAQ,UAAU,cAAc,SAAS,OAAO;CACtD,IAAI,OAAO,SAAS,WAAW,CAAC,gBAAgB,KAAK,GAAG,OAAO,KAAA;CAC/D,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,UAAU,OAAoE;CAC5F,OAAO,CAAC,CAAC,SAAS,YAAY,SAAS,CAAC,CAAC,MAAM,QAAQ;AACzD;;;;;;;;;;;;;AAcA,SAAgB,uBAAuB,cAA4B,MAAiB,UAAgC;CAClH,OAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,iBAC7C,aAAa,SAAS,OAClB;GACE,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAC/B,MAAM,aAAa,WAAW,QAAQ;KAAE,GAAG;KAAO;IAAS,CAC7D;GACF,EAAE;EACJ,IACA,YACN;CACF;AACF;;;;;AAMA,SAAgB,0BACd,cACA,eACc;CACd,MAAM,UAAU,cAAc;CAC9B,OAAO;EACL,GAAG;EACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;GAC/D,GAAG;GACH,eAAe,aAAa,cAAc,KAAK,kBAAkB;IAC/D,GAAG;IACH,QAAQ,aAAa,OAAO,KAAK,UAAW,MAAM,OAAO,UAAU,gBAAgB,KAAM;GAC3F,EAAE;EACJ,EAAE;CACJ;AACF"}

package/dist/default/media-tracks.js

@@ -0,0 +1,2 @@
+import { dedupedAudioTracks, dedupedVideoTracks, findAudioTrackById, findVideoTrackById, frameRateToNumber, isSameAudioTrack, isSameVideoTrack, toUserAudioTrackSelection, toUserVideoTrackSelection } from "./media/media-tracks/media-tracks.js";
+export { dedupedAudioTracks, dedupedVideoTracks, findAudioTrackById, findVideoTrackById, frameRateToNumber, isSameAudioTrack, isSameVideoTrack, toUserAudioTrackSelection, toUserVideoTrackSelection };

package/dist/default/network/bandwidth-estimator.js.map

@@ -1 +1 @@
-{"version":3,"file":"bandwidth-estimator.js","names":[],"sources":["../../../src/network/bandwidth-estimator.ts"],"sourcesContent":["/**\n * Dual EWMA Bandwidth Estimator\n *\n * Estimates available bandwidth using two EWMA calculations with different\n * half-lives, taking the minimum of both. This approach (from Shaka Player):\n *\n * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops\n * - **Slow EWMA** (5s half-life): Provides stability during fluctuations\n * - **min(fast, slow)**: Adapts down quickly, up slowly\n *\n * This naturally provides asymmetric behavior needed for good QoE:\n * avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).\n */\n\nimport { applyZeroFactor, calculateEwma } from './ewma';\n\n/**\n * Bandwidth estimator state.\n *\n * This state structure will be managed by O1 (State Container).\n * Functions in this module operate on this state immutably.\n */\nexport interface BandwidthState {\n  /** Fast-moving EWMA estimate (raw, uncorrected). */\n  fastEstimate: number;\n  /** Total weight accumulated in fast EWMA. */\n  fastTotalWeight: number;\n  /** Slow-moving EWMA estimate (raw, uncorrected). */\n  slowEstimate: number;\n  /** Total weight accumulated in slow EWMA. */\n  slowTotalWeight: number;\n  /** Total bytes sampled across all valid samples. */\n  bytesSampled: number;\n}\n\n/**\n * Configuration for bandwidth estimation.\n */\nexport interface BandwidthConfig {\n  /** Half-life for fast EWMA in seconds. */\n  fastHalfLife: number;\n  /** Half-life for slow EWMA in seconds. */\n  slowHalfLife: number;\n  /** Minimum total bytes before trusting the estimate. */\n  minTotalBytes: number;\n  /** Minimum bytes per sample to count (filters TTFB-dominated samples). */\n  minBytes: number;\n  /** Minimum sample duration in ms (filters cached responses). */\n  minDuration: number;\n}\n\n/**\n * Default bandwidth estimator configuration.\n *\n * Values match Shaka Player defaults based on experimentation.\n */\nexport const DEFAULT_BANDWIDTH_CONFIG: BandwidthConfig = {\n  fastHalfLife: 2, // 2 seconds\n  slowHalfLife: 5, // 5 seconds\n  minTotalBytes: 128_000, // 128 KB\n  minBytes: 16_000, // 16 KB\n  minDuration: 5, // 5 ms\n};\n\n/**\n * Add a bandwidth sample from a segment download.\n *\n * Samples are filtered based on:\n * - Minimum bytes (filters TTFB-dominated small segments)\n * - Minimum duration (filters cached responses)\n *\n * Valid samples update both fast and slow EWMA estimates.\n *\n * @param state - Current estimator state\n * @param durationMs - Download duration in milliseconds\n * @param numBytes - Number of bytes downloaded\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns New estimator state with sample incorporated (or unchanged if filtered)\n *\n * @example\n * let state = { fastEstimate: 0, fastTotalWeight: 0, ... };\n * // Sample: 1MB in 1 second\n * state = sampleBandwidth(state, 1000, 1_000_000);\n */\nexport function sampleBandwidth(\n  state: BandwidthState,\n  durationMs: number,\n  numBytes: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): BandwidthState {\n  // Always track bytes for startup phase calculation\n  const updatedBytesSampled = state.bytesSampled + numBytes;\n\n  // Filter: Ignore samples below minimum bytes (TTFB-dominated)\n  // Small segments' download time is mostly connection setup latency,\n  // which would artificially lower our bandwidth estimate\n  if (numBytes < config.minBytes) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Filter: Ignore samples faster than minimum duration (cached responses)\n  // Cached responses load nearly instantly and would artificially inflate\n  // our bandwidth estimate\n  if (durationMs < config.minDuration) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Calculate bandwidth in bits per second\n  // Formula: (bytes * 8 bits/byte * 1000 ms/s) / ms = bits/s\n  const bandwidth = (8000 * numBytes) / durationMs;\n\n  // Weight by duration in seconds\n  // Longer downloads are more reliable indicators of true bandwidth\n  const weight = durationMs / 1000;\n\n  return {\n    fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),\n    fastTotalWeight: state.fastTotalWeight + weight,\n    slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),\n    slowTotalWeight: state.slowTotalWeight + weight,\n    bytesSampled: updatedBytesSampled,\n  };\n}\n\n/**\n * Get the current bandwidth estimate.\n *\n * Returns the **minimum** of the fast and slow EWMA estimates.\n * This provides the key asymmetric behavior:\n * - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)\n * - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)\n *\n * Uses default estimate until enough data has been sampled — and when no\n * estimator state exists at all (`state === undefined`).\n *\n * @param state - Current estimator state, or `undefined` before any samples have been collected\n * @param defaultEstimate - Fallback estimate before sufficient samples (bps)\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns Bandwidth estimate in bits per second\n *\n * @example\n * const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default\n */\nexport function getBandwidthEstimate(\n  state: BandwidthState | undefined,\n  defaultEstimate: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): number {\n  // Use default until we have enough samples to trust our estimate\n  if (!state || state.bytesSampled < config.minTotalBytes) {\n    return defaultEstimate;\n  }\n\n  // Apply zero-factor correction to both estimates\n  const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);\n\n  const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);\n\n  // Take the minimum - this is the key insight from Shaka Player\n  // It naturally provides \"down quickly, up slowly\" behavior\n  return Math.min(fastEstimate, slowEstimate);\n}\n\n/**\n * Check if the estimator has enough data to provide a reliable estimate.\n *\n * Requires both:\n * - Enough total bytes sampled (minTotalBytes threshold)\n * - At least one valid EWMA sample (totalWeight > 0)\n *\n * @param state - Current estimator state\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns True if we've sampled enough bytes to trust the estimate\n *\n * @example\n * if (hasGoodEstimate(state)) {\n *   const estimate = getBandwidthEstimate(state, 5_000_000);\n * }\n */\nexport function hasGoodEstimate(state: BandwidthState, config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG): boolean {\n  // Need enough total bytes AND at least one valid EWMA sample\n  return state.bytesSampled >= config.minTotalBytes && state.fastTotalWeight > 0 && state.slowTotalWeight > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;CACd;;;;;;;;;;;;;;;;;;;;;AAsBD,SAAgB,gBACd,OACA,YACA,UACA,SAA0B,0BACV;CAEhB,MAAM,sBAAsB,MAAM,eAAe;AAKjD,KAAI,WAAW,OAAO,SACpB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;AAMxD,KAAI,aAAa,OAAO,YACtB,QAAO;EAAE,GAAG;EAAO,cAAc;EAAqB;CAKxD,MAAM,YAAa,MAAO,WAAY;CAItC,MAAM,SAAS,aAAa;AAE5B,QAAO;EACL,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,aAAa;EACvF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc;EACf;;;;;;;;;;;;;;;;;;;;;AAsBH,SAAgB,qBACd,OACA,iBACA,SAA0B,0BAClB;AAER,KAAI,CAAC,SAAS,MAAM,eAAe,OAAO,cACxC,QAAO;CAIT,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;CAEpG,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,aAAa;AAIpG,QAAO,KAAK,IAAI,cAAc,aAAa"}
+{"version":3,"file":"bandwidth-estimator.js","names":[],"sources":["../../../src/network/bandwidth-estimator.ts"],"sourcesContent":["/**\n * Dual EWMA Bandwidth Estimator\n *\n * Estimates available bandwidth using two EWMA calculations with different\n * half-lives, taking the minimum of both. This approach (from Shaka Player):\n *\n * - **Fast EWMA** (2s half-life): Reacts quickly to bandwidth drops\n * - **Slow EWMA** (5s half-life): Provides stability during fluctuations\n * - **min(fast, slow)**: Adapts down quickly, up slowly\n *\n * This naturally provides asymmetric behavior needed for good QoE:\n * avoiding stalls (quick downgrade) while preventing oscillation (slow upgrade).\n */\n\nimport { applyZeroFactor, calculateEwma } from './ewma';\n\n/**\n * Bandwidth estimator state.\n *\n * This state structure will be managed by O1 (State Container).\n * Functions in this module operate on this state immutably.\n */\nexport interface BandwidthState {\n  /** Fast-moving EWMA estimate (raw, uncorrected). */\n  fastEstimate: number;\n  /** Total weight accumulated in fast EWMA. */\n  fastTotalWeight: number;\n  /** Slow-moving EWMA estimate (raw, uncorrected). */\n  slowEstimate: number;\n  /** Total weight accumulated in slow EWMA. */\n  slowTotalWeight: number;\n  /** Total bytes sampled across all valid samples. */\n  bytesSampled: number;\n}\n\n/**\n * Configuration for bandwidth estimation.\n */\nexport interface BandwidthConfig {\n  /** Half-life for fast EWMA in seconds. */\n  fastHalfLife: number;\n  /** Half-life for slow EWMA in seconds. */\n  slowHalfLife: number;\n  /** Minimum total bytes before trusting the estimate. */\n  minTotalBytes: number;\n  /** Minimum bytes per sample to count (filters TTFB-dominated samples). */\n  minBytes: number;\n  /** Minimum sample duration in ms (filters cached responses). */\n  minDuration: number;\n}\n\n/**\n * Default bandwidth estimator configuration.\n *\n * Values match Shaka Player defaults based on experimentation.\n */\nexport const DEFAULT_BANDWIDTH_CONFIG: BandwidthConfig = {\n  fastHalfLife: 2, // 2 seconds\n  slowHalfLife: 5, // 5 seconds\n  minTotalBytes: 128_000, // 128 KB\n  minBytes: 16_000, // 16 KB\n  minDuration: 5, // 5 ms\n};\n\n/**\n * Add a bandwidth sample from a segment download.\n *\n * Samples are filtered based on:\n * - Minimum bytes (filters TTFB-dominated small segments)\n * - Minimum duration (filters cached responses)\n *\n * Valid samples update both fast and slow EWMA estimates.\n *\n * @param state - Current estimator state\n * @param durationMs - Download duration in milliseconds\n * @param numBytes - Number of bytes downloaded\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns New estimator state with sample incorporated (or unchanged if filtered)\n *\n * @example\n * let state = { fastEstimate: 0, fastTotalWeight: 0, ... };\n * // Sample: 1MB in 1 second\n * state = sampleBandwidth(state, 1000, 1_000_000);\n */\nexport function sampleBandwidth(\n  state: BandwidthState,\n  durationMs: number,\n  numBytes: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): BandwidthState {\n  // Always track bytes for startup phase calculation\n  const updatedBytesSampled = state.bytesSampled + numBytes;\n\n  // Filter: Ignore samples below minimum bytes (TTFB-dominated)\n  // Small segments' download time is mostly connection setup latency,\n  // which would artificially lower our bandwidth estimate\n  if (numBytes < config.minBytes) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Filter: Ignore samples faster than minimum duration (cached responses)\n  // Cached responses load nearly instantly and would artificially inflate\n  // our bandwidth estimate\n  if (durationMs < config.minDuration) {\n    return { ...state, bytesSampled: updatedBytesSampled };\n  }\n\n  // Calculate bandwidth in bits per second\n  // Formula: (bytes * 8 bits/byte * 1000 ms/s) / ms = bits/s\n  const bandwidth = (8000 * numBytes) / durationMs;\n\n  // Weight by duration in seconds\n  // Longer downloads are more reliable indicators of true bandwidth\n  const weight = durationMs / 1000;\n\n  return {\n    fastEstimate: calculateEwma(state.fastEstimate, bandwidth, weight, config.fastHalfLife),\n    fastTotalWeight: state.fastTotalWeight + weight,\n    slowEstimate: calculateEwma(state.slowEstimate, bandwidth, weight, config.slowHalfLife),\n    slowTotalWeight: state.slowTotalWeight + weight,\n    bytesSampled: updatedBytesSampled,\n  };\n}\n\n/**\n * Get the current bandwidth estimate.\n *\n * Returns the **minimum** of the fast and slow EWMA estimates.\n * This provides the key asymmetric behavior:\n * - When bandwidth drops, fast EWMA reacts first and dominates (quick adaptation)\n * - When bandwidth rises, slow EWMA lags behind and dominates (slow adaptation)\n *\n * Uses default estimate until enough data has been sampled — and when no\n * estimator state exists at all (`state === undefined`).\n *\n * @param state - Current estimator state, or `undefined` before any samples have been collected\n * @param defaultEstimate - Fallback estimate before sufficient samples (bps)\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns Bandwidth estimate in bits per second\n *\n * @example\n * const estimate = getBandwidthEstimate(state, 5_000_000); // 5 Mbps default\n */\nexport function getBandwidthEstimate(\n  state: BandwidthState | undefined,\n  defaultEstimate: number,\n  config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG\n): number {\n  // Use default until we have enough samples to trust our estimate\n  if (!state || state.bytesSampled < config.minTotalBytes) {\n    return defaultEstimate;\n  }\n\n  // Apply zero-factor correction to both estimates\n  const fastEstimate = applyZeroFactor(state.fastEstimate, state.fastTotalWeight, config.fastHalfLife);\n\n  const slowEstimate = applyZeroFactor(state.slowEstimate, state.slowTotalWeight, config.slowHalfLife);\n\n  // Take the minimum - this is the key insight from Shaka Player\n  // It naturally provides \"down quickly, up slowly\" behavior\n  return Math.min(fastEstimate, slowEstimate);\n}\n\n/**\n * Check if the estimator has enough data to provide a reliable estimate.\n *\n * Requires both:\n * - Enough total bytes sampled (minTotalBytes threshold)\n * - At least one valid EWMA sample (totalWeight > 0)\n *\n * @param state - Current estimator state\n * @param config - Optional estimator configuration (uses defaults if not provided)\n * @returns True if we've sampled enough bytes to trust the estimate\n *\n * @example\n * if (hasGoodEstimate(state)) {\n *   const estimate = getBandwidthEstimate(state, 5_000_000);\n * }\n */\nexport function hasGoodEstimate(state: BandwidthState, config: BandwidthConfig = DEFAULT_BANDWIDTH_CONFIG): boolean {\n  // Need enough total bytes AND at least one valid EWMA sample\n  return state.bytesSampled >= config.minTotalBytes && state.fastTotalWeight > 0 && state.slowTotalWeight > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,2BAA4C;CACvD,cAAc;CACd,cAAc;CACd,eAAe;CACf,UAAU;CACV,aAAa;AACf;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,gBACd,OACA,YACA,UACA,SAA0B,0BACV;CAEhB,MAAM,sBAAsB,MAAM,eAAe;CAKjD,IAAI,WAAW,OAAO,UACpB,OAAO;EAAE,GAAG;EAAO,cAAc;CAAoB;CAMvD,IAAI,aAAa,OAAO,aACtB,OAAO;EAAE,GAAG;EAAO,cAAc;CAAoB;CAKvD,MAAM,YAAa,MAAO,WAAY;CAItC,MAAM,SAAS,aAAa;CAE5B,OAAO;EACL,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,YAAY;EACtF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc,cAAc,MAAM,cAAc,WAAW,QAAQ,OAAO,YAAY;EACtF,iBAAiB,MAAM,kBAAkB;EACzC,cAAc;CAChB;AACF;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,qBACd,OACA,iBACA,SAA0B,0BAClB;CAER,IAAI,CAAC,SAAS,MAAM,eAAe,OAAO,eACxC,OAAO;CAIT,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,YAAY;CAEnG,MAAM,eAAe,gBAAgB,MAAM,cAAc,MAAM,iBAAiB,OAAO,YAAY;CAInG,OAAO,KAAK,IAAI,cAAc,YAAY;AAC5C"}

package/dist/default/network/chunked-stream-iterable.js.map

@@ -1 +1 @@
-{"version":3,"file":"chunked-stream-iterable.js","names":["#readableStream"],"sources":["../../../src/network/chunked-stream-iterable.ts"],"sourcesContent":["const DEFAULT_MIN_CHUNK_SIZE = 2 ** 17; // 128 KB\n\nexport interface ChunkedStreamIterableOptions {\n  minChunkSize?: number;\n}\n\n/**\n * Adapts a `ReadableStream<Uint8Array>` (e.g. `response.body`) into an\n * `AsyncIterable<Uint8Array>` that yields chunks no smaller than\n * `minChunkSize` bytes. Smaller network chunks are accumulated and yielded\n * together once the threshold is met. Any remainder is flushed on stream end.\n *\n * Errors from the underlying stream propagate naturally — the reader lock is\n * always released via `finally`.\n */\nexport class ChunkedStreamIterable implements AsyncIterable<Uint8Array> {\n  readonly minChunkSize: number;\n  #readableStream: ReadableStream<Uint8Array>;\n\n  constructor(\n    readableStream: ReadableStream<Uint8Array>,\n    { minChunkSize = DEFAULT_MIN_CHUNK_SIZE }: ChunkedStreamIterableOptions = {}\n  ) {\n    this.#readableStream = readableStream;\n    this.minChunkSize = minChunkSize;\n  }\n\n  async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {\n    let pending: Uint8Array | undefined;\n    const reader = this.#readableStream.getReader();\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) {\n          if (pending) yield pending;\n          break;\n        }\n\n        pending = pending ? concat(pending, value) : value;\n\n        if (pending.length >= this.minChunkSize) {\n          yield pending;\n          pending = undefined;\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n\nfunction concat(a: Uint8Array, b: Uint8Array): Uint8Array {\n  const result = new Uint8Array(a.length + b.length);\n  result.set(a);\n  result.set(b, a.length);\n  return result;\n}\n"],"mappings":";AAAA,MAAM,yBAAyB,KAAK;;;;;;;;;;AAepC,IAAa,wBAAb,MAAwE;CACtE;CACA;CAEA,YACE,gBACA,EAAE,eAAe,2BAAyD,EAAE,EAC5E;AACA,QAAA,iBAAuB;AACvB,OAAK,eAAe;;CAGtB,QAAQ,OAAO,iBAA6C;EAC1D,IAAI;EACJ,MAAM,SAAS,MAAA,eAAqB,WAAW;AAC/C,MAAI;AACF,UAAO,MAAM;IACX,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,MAAM;AAC3C,QAAI,MAAM;AACR,SAAI,QAAS,OAAM;AACnB;;AAGF,cAAU,UAAU,OAAO,SAAS,MAAM,GAAG;AAE7C,QAAI,QAAQ,UAAU,KAAK,cAAc;AACvC,WAAM;AACN,eAAU,KAAA;;;YAGN;AACR,UAAO,aAAa;;;;AAK1B,SAAS,OAAO,GAAe,GAA2B;CACxD,MAAM,SAAS,IAAI,WAAW,EAAE,SAAS,EAAE,OAAO;AAClD,QAAO,IAAI,EAAE;AACb,QAAO,IAAI,GAAG,EAAE,OAAO;AACvB,QAAO"}
+{"version":3,"file":"chunked-stream-iterable.js","names":["#readableStream"],"sources":["../../../src/network/chunked-stream-iterable.ts"],"sourcesContent":["const DEFAULT_MIN_CHUNK_SIZE = 2 ** 17; // 128 KB\n\nexport interface ChunkedStreamIterableOptions {\n  minChunkSize?: number;\n}\n\n/**\n * Adapts a `ReadableStream<Uint8Array>` (e.g. `response.body`) into an\n * `AsyncIterable<Uint8Array>` that yields chunks no smaller than\n * `minChunkSize` bytes. Smaller network chunks are accumulated and yielded\n * together once the threshold is met. Any remainder is flushed on stream end.\n *\n * Errors from the underlying stream propagate naturally — the reader lock is\n * always released via `finally`.\n */\nexport class ChunkedStreamIterable implements AsyncIterable<Uint8Array> {\n  readonly minChunkSize: number;\n  #readableStream: ReadableStream<Uint8Array>;\n\n  constructor(\n    readableStream: ReadableStream<Uint8Array>,\n    { minChunkSize = DEFAULT_MIN_CHUNK_SIZE }: ChunkedStreamIterableOptions = {}\n  ) {\n    this.#readableStream = readableStream;\n    this.minChunkSize = minChunkSize;\n  }\n\n  async *[Symbol.asyncIterator](): AsyncGenerator<Uint8Array> {\n    let pending: Uint8Array | undefined;\n    const reader = this.#readableStream.getReader();\n    try {\n      while (true) {\n        const { done, value } = await reader.read();\n        if (done) {\n          if (pending) yield pending;\n          break;\n        }\n\n        pending = pending ? concat(pending, value) : value;\n\n        if (pending.length >= this.minChunkSize) {\n          yield pending;\n          pending = undefined;\n        }\n      }\n    } finally {\n      reader.releaseLock();\n    }\n  }\n}\n\nfunction concat(a: Uint8Array, b: Uint8Array): Uint8Array {\n  const result = new Uint8Array(a.length + b.length);\n  result.set(a);\n  result.set(b, a.length);\n  return result;\n}\n"],"mappings":";AAAA,MAAM,yBAAyB,KAAK;;;;;;;;;;AAepC,IAAa,wBAAb,MAAwE;CACtE;CACA;CAEA,YACE,gBACA,EAAE,eAAe,2BAAyD,CAAC,GAC3E;EACA,KAAKA,kBAAkB;EACvB,KAAK,eAAe;CACtB;CAEA,QAAQ,OAAO,iBAA6C;EAC1D,IAAI;EACJ,MAAM,SAAS,KAAKA,gBAAgB,UAAU;EAC9C,IAAI;GACF,OAAO,MAAM;IACX,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;IAC1C,IAAI,MAAM;KACR,IAAI,SAAS,MAAM;KACnB;IACF;IAEA,UAAU,UAAU,OAAO,SAAS,KAAK,IAAI;IAE7C,IAAI,QAAQ,UAAU,KAAK,cAAc;KACvC,MAAM;KACN,UAAU,KAAA;IACZ;GACF;EACF,UAAU;GACR,OAAO,YAAY;EACrB;CACF;AACF;AAEA,SAAS,OAAO,GAAe,GAA2B;CACxD,MAAM,SAAS,IAAI,WAAW,EAAE,SAAS,EAAE,MAAM;CACjD,OAAO,IAAI,CAAC;CACZ,OAAO,IAAI,GAAG,EAAE,MAAM;CACtB,OAAO;AACT"}

package/dist/default/network/ewma.js

@@ -66,6 +66,6 @@ function applyZeroFactor(estimate, totalWeight, halfLife) {
 	return estimate / (1 - calculateAlpha(halfLife) ** totalWeight);
 }
 //#endregion
-export { applyZeroFactor, calculateEwma };
+export { applyZeroFactor, calculateAlpha, calculateEwma };
 
 //# sourceMappingURL=ewma.js.map

package/dist/default/network/ewma.js.map

@@ -1 +1 @@
-{"version":3,"file":"ewma.js","names":[],"sources":["../../../src/network/ewma.ts"],"sourcesContent":["/**\n * Exponentially Weighted Moving Average (EWMA)\n *\n * Pure functional implementation of EWMA calculations.\n * Based on Shaka Player's EWMA algorithm.\n */\n\n/**\n * Calculate alpha (decay factor) from half-life.\n *\n * Alpha determines how quickly old data \"expires\":\n * - alpha close to 1 = slow decay (long memory)\n * - alpha close to 0 = fast decay (short memory)\n *\n * @param halfLife - The quantity of prior samples (by weight) that make up\n *   half of the new estimate. Must be positive.\n * @returns Alpha value between 0 and 1\n *\n * @example\n * const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life\n */\nexport function calculateAlpha(halfLife: number): number {\n  return Math.exp(Math.log(0.5) / halfLife);\n}\n\n/**\n * Calculate exponentially weighted moving average.\n *\n * Updates an estimate by blending a new value with the previous estimate,\n * weighted by the sample duration. Longer samples have more influence.\n *\n * @param prevEstimate - Previous EWMA estimate\n * @param value - New sample value to incorporate\n * @param weight - Sample weight (typically duration in seconds)\n * @param halfLife - Half-life for decay (typically 2-5 seconds)\n * @returns Updated EWMA estimate\n *\n * @example\n * let estimate = 0;\n * estimate = calculateEwma(estimate, 1_000_000, 1, 2); // First sample\n * estimate = calculateEwma(estimate, 2_000_000, 1, 2); // Second sample\n */\nexport function calculateEwma(prevEstimate: number, value: number, weight: number, halfLife: number): number {\n  const alpha = calculateAlpha(halfLife);\n  const adjAlpha = alpha ** weight;\n  return value * (1 - adjAlpha) + adjAlpha * prevEstimate;\n}\n\n/**\n * Apply zero-factor correction to EWMA estimate.\n *\n * The zero-factor correction compensates for bias when starting from zero.\n * Without this correction, early estimates would be artificially low.\n *\n * As totalWeight increases, the correction factor approaches 1, meaning\n * the estimate becomes more reliable and needs less correction.\n *\n * @param estimate - Raw EWMA estimate (uncorrected)\n * @param totalWeight - Accumulated weight from all samples\n * @param halfLife - Half-life used in EWMA calculation\n * @returns Corrected estimate, or 0 if totalWeight is 0\n *\n * @example\n * const raw = calculateEwma(0, 1_000_000, 1, 2);\n * const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000\n */\nexport function applyZeroFactor(estimate: number, totalWeight: number, halfLife: number): number {\n  if (totalWeight === 0) {\n    return 0;\n  }\n\n  const alpha = calculateAlpha(halfLife);\n  const zeroFactor = 1 - alpha ** totalWeight;\n  return estimate / zeroFactor;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,UAA0B;AACvD,QAAO,KAAK,IAAI,KAAK,IAAI,GAAI,GAAG,SAAS;;;;;;;;;;;;;;;;;;;AAoB3C,SAAgB,cAAc,cAAsB,OAAe,QAAgB,UAA0B;CAE3G,MAAM,WADQ,eAAe,SAAS,IACZ;AAC1B,QAAO,SAAS,IAAI,YAAY,WAAW;;;;;;;;;;;;;;;;;;;;AAqB7C,SAAgB,gBAAgB,UAAkB,aAAqB,UAA0B;AAC/F,KAAI,gBAAgB,EAClB,QAAO;AAKT,QAAO,YADY,IADL,eAAe,SAAS,IACN"}
+{"version":3,"file":"ewma.js","names":[],"sources":["../../../src/network/ewma.ts"],"sourcesContent":["/**\n * Exponentially Weighted Moving Average (EWMA)\n *\n * Pure functional implementation of EWMA calculations.\n * Based on Shaka Player's EWMA algorithm.\n */\n\n/**\n * Calculate alpha (decay factor) from half-life.\n *\n * Alpha determines how quickly old data \"expires\":\n * - alpha close to 1 = slow decay (long memory)\n * - alpha close to 0 = fast decay (short memory)\n *\n * @param halfLife - The quantity of prior samples (by weight) that make up\n *   half of the new estimate. Must be positive.\n * @returns Alpha value between 0 and 1\n *\n * @example\n * const alpha = calculateAlpha(2); // ≈ 0.7071 for 2-second half-life\n */\nexport function calculateAlpha(halfLife: number): number {\n  return Math.exp(Math.log(0.5) / halfLife);\n}\n\n/**\n * Calculate exponentially weighted moving average.\n *\n * Updates an estimate by blending a new value with the previous estimate,\n * weighted by the sample duration. Longer samples have more influence.\n *\n * @param prevEstimate - Previous EWMA estimate\n * @param value - New sample value to incorporate\n * @param weight - Sample weight (typically duration in seconds)\n * @param halfLife - Half-life for decay (typically 2-5 seconds)\n * @returns Updated EWMA estimate\n *\n * @example\n * let estimate = 0;\n * estimate = calculateEwma(estimate, 1_000_000, 1, 2); // First sample\n * estimate = calculateEwma(estimate, 2_000_000, 1, 2); // Second sample\n */\nexport function calculateEwma(prevEstimate: number, value: number, weight: number, halfLife: number): number {\n  const alpha = calculateAlpha(halfLife);\n  const adjAlpha = alpha ** weight;\n  return value * (1 - adjAlpha) + adjAlpha * prevEstimate;\n}\n\n/**\n * Apply zero-factor correction to EWMA estimate.\n *\n * The zero-factor correction compensates for bias when starting from zero.\n * Without this correction, early estimates would be artificially low.\n *\n * As totalWeight increases, the correction factor approaches 1, meaning\n * the estimate becomes more reliable and needs less correction.\n *\n * @param estimate - Raw EWMA estimate (uncorrected)\n * @param totalWeight - Accumulated weight from all samples\n * @param halfLife - Half-life used in EWMA calculation\n * @returns Corrected estimate, or 0 if totalWeight is 0\n *\n * @example\n * const raw = calculateEwma(0, 1_000_000, 1, 2);\n * const corrected = applyZeroFactor(raw, 1, 2); // ≈ 1_000_000\n */\nexport function applyZeroFactor(estimate: number, totalWeight: number, halfLife: number): number {\n  if (totalWeight === 0) {\n    return 0;\n  }\n\n  const alpha = calculateAlpha(halfLife);\n  const zeroFactor = 1 - alpha ** totalWeight;\n  return estimate / zeroFactor;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,UAA0B;CACvD,OAAO,KAAK,IAAI,KAAK,IAAI,EAAG,IAAI,QAAQ;AAC1C;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,cAAc,cAAsB,OAAe,QAAgB,UAA0B;CAE3G,MAAM,WADQ,eAAe,QACR,KAAK;CAC1B,OAAO,SAAS,IAAI,YAAY,WAAW;AAC7C;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,gBAAgB,UAAkB,aAAqB,UAA0B;CAC/F,IAAI,gBAAgB,GAClB,OAAO;CAKT,OAAO,YADY,IADL,eAAe,QACF,KAAK;AAElC"}

package/dist/default/network/fetch.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.js","names":[],"sources":["../../../src/network/fetch.ts"],"sourcesContent":["/**\n * HTTP Fetch Wrapper\n *\n * Composable building blocks:\n * - fetchResolvable() — fetch a Resource (handles byte ranges); returns Response\n * - getResponseText() — extract text from Response\n * - fetchResolvableStream() — single-stage async generator over body chunks\n * - fetchStream() — two-stage: await connection establishment, then lazily\n *   iterate body chunks. Use when timing the connection start independently\n *   of body consumption matters (e.g., observable fetch timing for ABR).\n * - createTrackedFetch() — factory for a fetchStream-shape function that\n *   samples bandwidth (via EWMA) per chunk and notifies via callback.\n */\n\nimport { type BandwidthState, sampleBandwidth } from './bandwidth-estimator';\nimport { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from './chunked-stream-iterable';\n\n/**\n * Minimal Response-like interface for text extraction.\n * Allows testing without full Response object.\n */\nexport interface ResponseLike {\n  text(): Promise<string>;\n}\n\n/**\n * An HTTP-addressable resource — URL plus optional byte range.\n * Media's `AddressableObject` (and anything else with the same shape)\n * is structurally compatible; kept local so this module stays\n * domain-agnostic.\n */\nexport interface Resource {\n  url: string;\n  byteRange?: {\n    start: number;\n    end: number;\n  };\n}\n\n/**\n * Fetch resolvable from a Resource.\n *\n * Handles byte range requests if byteRange is present.\n * Returns native fetch Response for composability (can extract text, stream, etc.).\n *\n * @param addressable - Resource to fetch (url + optional byteRange)\n * @returns Promise resolving to Response\n *\n * @example\n * const response = await fetchResolvable({ url: 'https://example.com/segment.m4s' });\n * const text = await getResponseText(response);\n *\n * @example\n * // With byte range\n * const response = await fetchResolvable({\n *   url: 'https://example.com/file.mp4',\n *   byteRange: { start: 1000, end: 1999 }\n * });\n */\nexport async function fetchResolvable(addressable: Resource, options?: RequestInit): Promise<Response> {\n  const headers = new Headers(options?.headers);\n\n  // Add Range header for byte range requests\n  if (addressable.byteRange) {\n    const { start, end } = addressable.byteRange;\n    headers.set('Range', `bytes=${start}-${end}`);\n  }\n\n  const request = new Request(addressable.url, {\n    method: 'GET',\n    headers,\n    ...options,\n  });\n\n  return fetch(request);\n}\n\n/**\n * Fetch resolvable as bytes.\n *\n * Convenience wrapper around fetchResolvable that resolves the body as an\n * ArrayBuffer. Use this when you need the raw bytes (e.g. segment appends).\n * For text or streaming consumption, use fetchResolvable directly.\n */\nexport async function fetchResolvableBytes(addressable: Resource, options?: RequestInit): Promise<ArrayBuffer> {\n  const response = await fetchResolvable(addressable, options);\n  return response.arrayBuffer();\n}\n\n/**\n * Fetch resolvable as a stream of Uint8Array chunks.\n *\n * Convenience wrapper around fetchResolvable that yields the body as chunks\n * via ChunkedStreamIterable. Headers are awaited before the first chunk is\n * yielded (TTFB is accounted for before iteration begins).\n *\n * Throws if the response body is null (e.g. non-body HTTP status).\n * Errors from the underlying stream propagate naturally as thrown errors.\n */\nexport async function* fetchResolvableStream(\n  addressable: Resource,\n  options?: RequestInit & ChunkedStreamIterableOptions\n): AsyncGenerator<Uint8Array> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  yield* new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Extract text from Response.\n *\n * Accepts minimal Response-like object (just needs text() method).\n * Returns promise from response.text().\n *\n * @param response - Response-like object with text() method\n * @returns Promise resolving to text content\n *\n * @example\n * const response = await fetchResolvable(addressable);\n * const text = await getResponseText(response);\n */\nexport function getResponseText(response: ResponseLike): Promise<string> {\n  return response.text();\n}\n\n/**\n * Fetch a resource and resolve its text body — the text analog of\n * {@link FetchBytes}. A non-OK status rejects, so HTTP failures surface as\n * rejections that callers (and decorators like the failover tracker) handle\n * uniformly with network errors.\n */\nexport type FetchText = (addressable: Resource, options?: RequestInit) => Promise<string>;\n\n/** Default {@link FetchText}: fetch the resource, reject on non-OK, return text. */\nexport const fetchResolvableText: FetchText = async (addressable, options) => {\n  const response = await fetchResolvable(addressable, options);\n  if (!response.ok) {\n    throw new Error(`fetchResolvableText: ${response.status} ${response.statusText} for ${addressable.url}`);\n  }\n  return getResponseText(response);\n};\n\n/**\n * Two-stage fetch helper: eagerly starts the HTTP request (TTFB is awaited),\n * then returns a lazy iterable over the response body. Separating connection\n * start from body iteration makes fetch timing predictable and observable\n * regardless of when downstream consumers begin pulling chunks.\n *\n * Sibling to {@link fetchResolvableStream}, which is single-stage (calls\n * `fetch` only when iteration starts). Pick `fetchStream` when \"when did the\n * fetch start\" needs to be observable separately from \"when did the body\n * begin arriving.\"\n */\nexport type FetchOptions = RequestInit & ChunkedStreamIterableOptions;\n\nexport type FetchBytes = (addressable: Resource, options?: FetchOptions) => Promise<AsyncIterable<Uint8Array>>;\n\nexport async function fetchStream(addressable: Resource, options?: FetchOptions): Promise<AsyncIterable<Uint8Array>> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  return new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Returns a {@link FetchBytes} function that samples bandwidth via EWMA\n * per body chunk. The factory captures the running bandwidth state\n * internally; per chunk it computes the next state and notifies the\n * supplied `onSample` callback.\n *\n * The factory's internal accumulator is seeded from `initial` and updated\n * on every chunk; callers don't need to thread it back in. `onSample`\n * receives the *new* state after each chunk — typical use is to bridge\n * samples back into engine state for ABR consumers.\n *\n * @param initial - Starting `BandwidthState` (commonly zeros or the\n *   engine's current accumulator).\n * @param onSample - Called with the new `BandwidthState` after each chunk.\n */\nexport function createTrackedFetch(initial: BandwidthState, onSample: (next: BandwidthState) => void): FetchBytes {\n  let state = initial;\n  return async (addressable, options) => {\n    const { minChunkSize, ...fetchOptions } = options ?? {};\n    const response = await fetchResolvable(addressable, fetchOptions);\n    if (!response.body) throw new Error('Response has no body');\n    const body = response.body;\n    return {\n      [Symbol.asyncIterator]: async function* () {\n        let chunkStart = performance.now();\n        for await (const chunk of new ChunkedStreamIterable(\n          body,\n          ...(minChunkSize !== undefined ? [{ minChunkSize }] : [])\n        )) {\n          const elapsed = performance.now() - chunkStart;\n          state = sampleBandwidth(state, elapsed, chunk.byteLength);\n          onSample(state);\n          yield chunk;\n          chunkStart = performance.now();\n        }\n      },\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,eAAsB,gBAAgB,aAAuB,SAA0C;CACrG,MAAM,UAAU,IAAI,QAAQ,SAAS,QAAQ;AAG7C,KAAI,YAAY,WAAW;EACzB,MAAM,EAAE,OAAO,QAAQ,YAAY;AACnC,UAAQ,IAAI,SAAS,SAAS,MAAM,GAAG,MAAM;;CAG/C,MAAM,UAAU,IAAI,QAAQ,YAAY,KAAK;EAC3C,QAAQ;EACR;EACA,GAAG;EACJ,CAAC;AAEF,QAAO,MAAM,QAAQ;;;;;;;;;;;;;;;AAgDvB,SAAgB,gBAAgB,UAAyC;AACvE,QAAO,SAAS,MAAM;;;AAYxB,MAAa,sBAAiC,OAAO,aAAa,YAAY;CAC5E,MAAM,WAAW,MAAM,gBAAgB,aAAa,QAAQ;AAC5D,KAAI,CAAC,SAAS,GACZ,OAAM,IAAI,MAAM,wBAAwB,SAAS,OAAO,GAAG,SAAS,WAAW,OAAO,YAAY,MAAM;AAE1G,QAAO,gBAAgB,SAAS;;AAkBlC,eAAsB,YAAY,aAAuB,SAA4D;CACnH,MAAM,EAAE,cAAc,GAAG,iBAAiB,WAAW,EAAE;CACvD,MAAM,WAAW,MAAM,gBAAgB,aAAa,aAAa;AACjE,KAAI,CAAC,SAAS,KAAM,OAAM,IAAI,MAAM,uBAAuB;AAC3D,QAAO,IAAI,sBAAsB,SAAS,MAAM,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,cAAc,CAAC,GAAG,EAAE,CAAE;;;;;;;;;;;;;;;;;AAkB5G,SAAgB,mBAAmB,SAAyB,UAAsD;CAChH,IAAI,QAAQ;AACZ,QAAO,OAAO,aAAa,YAAY;EACrC,MAAM,EAAE,cAAc,GAAG,iBAAiB,WAAW,EAAE;EACvD,MAAM,WAAW,MAAM,gBAAgB,aAAa,aAAa;AACjE,MAAI,CAAC,SAAS,KAAM,OAAM,IAAI,MAAM,uBAAuB;EAC3D,MAAM,OAAO,SAAS;AACtB,SAAO,EACL,CAAC,OAAO,gBAAgB,mBAAmB;GACzC,IAAI,aAAa,YAAY,KAAK;AAClC,cAAW,MAAM,SAAS,IAAI,sBAC5B,MACA,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,cAAc,CAAC,GAAG,EAAE,CACzD,EAAE;IACD,MAAM,UAAU,YAAY,KAAK,GAAG;AACpC,YAAQ,gBAAgB,OAAO,SAAS,MAAM,WAAW;AACzD,aAAS,MAAM;AACf,UAAM;AACN,iBAAa,YAAY,KAAK;;KAGnC"}
+{"version":3,"file":"fetch.js","names":[],"sources":["../../../src/network/fetch.ts"],"sourcesContent":["/**\n * HTTP Fetch Wrapper\n *\n * Composable building blocks:\n * - fetchResolvable() — fetch a Resource (handles byte ranges); returns Response\n * - getResponseText() — extract text from Response\n * - fetchResolvableStream() — single-stage async generator over body chunks\n * - fetchStream() — two-stage: await connection establishment, then lazily\n *   iterate body chunks. Use when timing the connection start independently\n *   of body consumption matters (e.g., observable fetch timing for ABR).\n * - createTrackedFetch() — factory for a fetchStream-shape function that\n *   samples bandwidth (via EWMA) per chunk and notifies via callback.\n */\n\nimport { type BandwidthState, sampleBandwidth } from './bandwidth-estimator';\nimport { ChunkedStreamIterable, type ChunkedStreamIterableOptions } from './chunked-stream-iterable';\n\n/**\n * Minimal Response-like interface for text extraction.\n * Allows testing without full Response object.\n */\nexport interface ResponseLike {\n  text(): Promise<string>;\n}\n\n/**\n * An HTTP-addressable resource — URL plus optional byte range.\n * Media's `AddressableObject` (and anything else with the same shape)\n * is structurally compatible; kept local so this module stays\n * domain-agnostic.\n */\nexport interface Resource {\n  url: string;\n  byteRange?: {\n    start: number;\n    end: number;\n  };\n}\n\n/**\n * Fetch resolvable from a Resource.\n *\n * Handles byte range requests if byteRange is present.\n * Returns native fetch Response for composability (can extract text, stream, etc.).\n *\n * @param addressable - Resource to fetch (url + optional byteRange)\n * @returns Promise resolving to Response\n *\n * @example\n * const response = await fetchResolvable({ url: 'https://example.com/segment.m4s' });\n * const text = await getResponseText(response);\n *\n * @example\n * // With byte range\n * const response = await fetchResolvable({\n *   url: 'https://example.com/file.mp4',\n *   byteRange: { start: 1000, end: 1999 }\n * });\n */\nexport async function fetchResolvable(addressable: Resource, options?: RequestInit): Promise<Response> {\n  const headers = new Headers(options?.headers);\n\n  // Add Range header for byte range requests\n  if (addressable.byteRange) {\n    const { start, end } = addressable.byteRange;\n    headers.set('Range', `bytes=${start}-${end}`);\n  }\n\n  const request = new Request(addressable.url, {\n    method: 'GET',\n    headers,\n    ...options,\n  });\n\n  return fetch(request);\n}\n\n/**\n * Fetch resolvable as bytes.\n *\n * Convenience wrapper around fetchResolvable that resolves the body as an\n * ArrayBuffer. Use this when you need the raw bytes (e.g. segment appends).\n * For text or streaming consumption, use fetchResolvable directly.\n */\nexport async function fetchResolvableBytes(addressable: Resource, options?: RequestInit): Promise<ArrayBuffer> {\n  const response = await fetchResolvable(addressable, options);\n  return response.arrayBuffer();\n}\n\n/**\n * Fetch resolvable as a stream of Uint8Array chunks.\n *\n * Convenience wrapper around fetchResolvable that yields the body as chunks\n * via ChunkedStreamIterable. Headers are awaited before the first chunk is\n * yielded (TTFB is accounted for before iteration begins).\n *\n * Throws if the response body is null (e.g. non-body HTTP status).\n * Errors from the underlying stream propagate naturally as thrown errors.\n */\nexport async function* fetchResolvableStream(\n  addressable: Resource,\n  options?: RequestInit & ChunkedStreamIterableOptions\n): AsyncGenerator<Uint8Array> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  yield* new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Extract text from Response.\n *\n * Accepts minimal Response-like object (just needs text() method).\n * Returns promise from response.text().\n *\n * @param response - Response-like object with text() method\n * @returns Promise resolving to text content\n *\n * @example\n * const response = await fetchResolvable(addressable);\n * const text = await getResponseText(response);\n */\nexport function getResponseText(response: ResponseLike): Promise<string> {\n  return response.text();\n}\n\n/**\n * Fetch a resource and resolve its text body — the text analog of\n * {@link FetchBytes}. A non-OK status rejects, so HTTP failures surface as\n * rejections that callers (and decorators like the failover tracker) handle\n * uniformly with network errors.\n */\nexport type FetchText = (addressable: Resource, options?: RequestInit) => Promise<string>;\n\n/** Default {@link FetchText}: fetch the resource, reject on non-OK, return text. */\nexport const fetchResolvableText: FetchText = async (addressable, options) => {\n  const response = await fetchResolvable(addressable, options);\n  if (!response.ok) {\n    throw new Error(`fetchResolvableText: ${response.status} ${response.statusText} for ${addressable.url}`);\n  }\n  return getResponseText(response);\n};\n\n/**\n * Two-stage fetch helper: eagerly starts the HTTP request (TTFB is awaited),\n * then returns a lazy iterable over the response body. Separating connection\n * start from body iteration makes fetch timing predictable and observable\n * regardless of when downstream consumers begin pulling chunks.\n *\n * Sibling to {@link fetchResolvableStream}, which is single-stage (calls\n * `fetch` only when iteration starts). Pick `fetchStream` when \"when did the\n * fetch start\" needs to be observable separately from \"when did the body\n * begin arriving.\"\n */\nexport type FetchOptions = RequestInit & ChunkedStreamIterableOptions;\n\nexport type FetchBytes = (addressable: Resource, options?: FetchOptions) => Promise<AsyncIterable<Uint8Array>>;\n\nexport async function fetchStream(addressable: Resource, options?: FetchOptions): Promise<AsyncIterable<Uint8Array>> {\n  const { minChunkSize, ...fetchOptions } = options ?? {};\n  const response = await fetchResolvable(addressable, fetchOptions);\n  if (!response.body) throw new Error('Response has no body');\n  return new ChunkedStreamIterable(response.body, ...(minChunkSize !== undefined ? [{ minChunkSize }] : []));\n}\n\n/**\n * Returns a {@link FetchBytes} function that samples bandwidth via EWMA\n * per body chunk. The factory captures the running bandwidth state\n * internally; per chunk it computes the next state and notifies the\n * supplied `onSample` callback.\n *\n * The factory's internal accumulator is seeded from `initial` and updated\n * on every chunk; callers don't need to thread it back in. `onSample`\n * receives the *new* state after each chunk — typical use is to bridge\n * samples back into engine state for ABR consumers.\n *\n * @param initial - Starting `BandwidthState` (commonly zeros or the\n *   engine's current accumulator).\n * @param onSample - Called with the new `BandwidthState` after each chunk.\n */\nexport function createTrackedFetch(initial: BandwidthState, onSample: (next: BandwidthState) => void): FetchBytes {\n  let state = initial;\n  return async (addressable, options) => {\n    const { minChunkSize, ...fetchOptions } = options ?? {};\n    const response = await fetchResolvable(addressable, fetchOptions);\n    if (!response.body) throw new Error('Response has no body');\n    const body = response.body;\n    return {\n      [Symbol.asyncIterator]: async function* () {\n        let chunkStart = performance.now();\n        for await (const chunk of new ChunkedStreamIterable(\n          body,\n          ...(minChunkSize !== undefined ? [{ minChunkSize }] : [])\n        )) {\n          const elapsed = performance.now() - chunkStart;\n          state = sampleBandwidth(state, elapsed, chunk.byteLength);\n          onSample(state);\n          yield chunk;\n          chunkStart = performance.now();\n        }\n      },\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,eAAsB,gBAAgB,aAAuB,SAA0C;CACrG,MAAM,UAAU,IAAI,QAAQ,SAAS,OAAO;CAG5C,IAAI,YAAY,WAAW;EACzB,MAAM,EAAE,OAAO,QAAQ,YAAY;EACnC,QAAQ,IAAI,SAAS,SAAS,MAAM,GAAG,KAAK;CAC9C;CAEA,MAAM,UAAU,IAAI,QAAQ,YAAY,KAAK;EAC3C,QAAQ;EACR;EACA,GAAG;CACL,CAAC;CAED,OAAO,MAAM,OAAO;AACtB;;;;;;;;;;;;;;AA+CA,SAAgB,gBAAgB,UAAyC;CACvE,OAAO,SAAS,KAAK;AACvB;;AAWA,MAAa,sBAAiC,OAAO,aAAa,YAAY;CAC5E,MAAM,WAAW,MAAM,gBAAgB,aAAa,OAAO;CAC3D,IAAI,CAAC,SAAS,IACZ,MAAM,IAAI,MAAM,wBAAwB,SAAS,OAAO,GAAG,SAAS,WAAW,OAAO,YAAY,KAAK;CAEzG,OAAO,gBAAgB,QAAQ;AACjC;AAiBA,eAAsB,YAAY,aAAuB,SAA4D;CACnH,MAAM,EAAE,cAAc,GAAG,iBAAiB,WAAW,CAAC;CACtD,MAAM,WAAW,MAAM,gBAAgB,aAAa,YAAY;CAChE,IAAI,CAAC,SAAS,MAAM,MAAM,IAAI,MAAM,sBAAsB;CAC1D,OAAO,IAAI,sBAAsB,SAAS,MAAM,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CAAE;AAC3G;;;;;;;;;;;;;;;;AAiBA,SAAgB,mBAAmB,SAAyB,UAAsD;CAChH,IAAI,QAAQ;CACZ,OAAO,OAAO,aAAa,YAAY;EACrC,MAAM,EAAE,cAAc,GAAG,iBAAiB,WAAW,CAAC;EACtD,MAAM,WAAW,MAAM,gBAAgB,aAAa,YAAY;EAChE,IAAI,CAAC,SAAS,MAAM,MAAM,IAAI,MAAM,sBAAsB;EAC1D,MAAM,OAAO,SAAS;EACtB,OAAO,EACL,CAAC,OAAO,gBAAgB,mBAAmB;GACzC,IAAI,aAAa,YAAY,IAAI;GACjC,WAAW,MAAM,SAAS,IAAI,sBAC5B,MACA,GAAI,iBAAiB,KAAA,IAAY,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,CACzD,GAAG;IACD,MAAM,UAAU,YAAY,IAAI,IAAI;IACpC,QAAQ,gBAAgB,OAAO,SAAS,MAAM,UAAU;IACxD,SAAS,KAAK;IACd,MAAM;IACN,aAAa,YAAY,IAAI;GAC/B;EACF,EACF;CACF;AACF"}

package/dist/default/playback/actors/dom/segment-loader.js

@@ -1,106 +1,49 @@
 import { peek } from "../../../core/signals/primitives.js";
-import { effect } from "../../../core/signals/effect.js";
 import { SerialRunner, Task } from "../../../core/tasks/task.js";
 import { createMachineActor } from "../../../core/actors/create-machine-actor.js";
-import { DEFAULT_FORWARD_BUFFER_CONFIG, calculateForwardFlushPoint, getSegmentsToLoad } from "../../../media/buffer/forward-buffer.js";
 import "../../../media/types/index.js";
+import { DEFAULT_FORWARD_BUFFER_CONFIG, calculateForwardFlushPoint, getSegmentsToLoad, isTimeRangeCovered, mergeTimeRanges } from "../../../media/buffer/forward-buffer.js";
 import { DEFAULT_BACK_BUFFER_CONFIG, calculateBackBufferFlushPoint } from "../../../media/buffer/back-buffer.js";
+import { DEFAULT_MESSAGE_PIPELINES } from "../../primitives/segment-load-pipeline.js";
 //#region src/playback/actors/dom/segment-loader.ts
 /**
-* Resolves when the SourceBufferActor snapshot reaches 'idle'.
-* Rejects if the signal is aborted or the actor is destroyed.
-*
-* Used to sequence SourceBufferActor operations without awaiting send()
-* directly — send() is fire-and-forget; callers observe completion via
-* state transition.
+* Wraps a LoadTask descriptor into a Task that runs the op's message pipeline
+* (fetch/discover/stamp/dispatch, per the composition's `messagePipelines`).
+* Updates in-flight context around the async region so the loading handler can
+* make accurate continue/preempt decisions at any point, and checks the abort
+* signal before each step.
 */
-function waitForIdle(snapshot, signal) {
-	return new Promise((resolve, reject) => {
-		if (snapshot.get().value === "idle") {
-			resolve();
-			return;
-		}
-		if (snapshot.get().value === "destroyed") {
-			reject(new DOMException("Aborted", "AbortError"));
-			return;
-		}
-		if (signal.aborted) {
-			reject(signal.reason);
-			return;
-		}
-		let stop;
-		const cleanup = (fn) => {
-			stop?.();
-			signal.removeEventListener("abort", onAbort);
-			fn();
-		};
-		const onAbort = () => cleanup(() => reject(signal.reason));
-		stop = effect(() => {
-			const value = snapshot.get().value;
-			if (value === "idle") cleanup(resolve);
-			else if (value === "destroyed") cleanup(() => reject(new DOMException("Aborted", "AbortError")));
-		});
-		signal.addEventListener("abort", onAbort, { once: true });
-	});
-}
-/**
-* Wraps a LoadTask descriptor into a Task that fetches (if needed) and
-* forwards to SourceBufferActor. Updates in-flight context around async
-* operations so the loading handler can make accurate continue/preempt
-* decisions at any point.
-*/
-function makeLoadTask(op, { getContext, setContext, fetchBytes, sourceBufferActor }) {
+function makeLoadTask(op, { getContext, setContext, pipelines, deps }) {
 	return new Task(async (taskSignal) => {
 		if (taskSignal.aborted) return;
-		if (op.type === "remove") {
-			sourceBufferActor.send(op);
-			await waitForIdle(sourceBufferActor.snapshot, taskSignal);
-			return;
-		}
-		if (op.type === "append-init") {
-			setContext({
+		const frame = op.type === "append-segment" ? {
+			op,
+			meta: op.meta
+		} : { op };
+		try {
+			if (op.type === "append-init") setContext({
 				...getContext(),
 				inFlightInitTrackId: op.meta.trackId
 			});
-			try {
-				const data = await fetchBytes(op, {
-					signal: taskSignal,
-					minChunkSize: Infinity
-				});
-				if (!taskSignal.aborted) {
-					sourceBufferActor.send({
-						type: "append-init",
-						data,
-						meta: op.meta
-					});
-					await waitForIdle(sourceBufferActor.snapshot, taskSignal);
+			else if (op.type === "append-segment") setContext({
+				...getContext(),
+				inFlightSegment: {
+					id: op.meta.id,
+					trackId: op.meta.trackId
 				}
-			} finally {
-				setContext({
-					...getContext(),
-					inFlightInitTrackId: null
-				});
-			}
-			return;
-		}
-		setContext({
-			...getContext(),
-			inFlightSegmentId: op.meta.id
-		});
-		try {
-			const stream = await fetchBytes(op, { signal: taskSignal });
-			if (!taskSignal.aborted) {
-				sourceBufferActor.send({
-					type: "append-segment",
-					data: stream,
-					meta: op.meta
-				});
-				await waitForIdle(sourceBufferActor.snapshot, taskSignal);
+			});
+			for (const step of pipelines[op.type]) {
+				if (taskSignal.aborted) return;
+				await step(frame, taskSignal, deps);
 			}
 		} finally {
-			setContext({
+			if (op.type === "append-init") setContext({
+				...getContext(),
+				inFlightInitTrackId: null
+			});
+			else if (op.type === "append-segment") setContext({
 				...getContext(),
-				inFlightSegmentId: null
+				inFlightSegment: null
 			});
 		}
 	});
@@ -123,8 +66,16 @@ function makeLoadTask(op, { getContext, setContext, fetchBytes, sourceBufferActo
 * @param fetchBytes - Tracked fetch closure (owns throughput sampling for segments).
 *   Accepts an optional `minChunkSize` in options; init segments pass `Infinity`
 *   so the entire body accumulates as one chunk before appending.
+* @param compositionDeps - The composition's `state`/`context`/`config`, threaded
+*   opaquely into each step's {@link StepDeps} (the loader never reads them). Lets
+*   injected steps (relocation) read composition signals at call time. Defaults to
+*   empty for standalone / base-pipeline use.
 */
-function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
+function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}, compositionDeps = {
+	state: {},
+	context: {},
+	config: {}
+}) {
 	const forwardBufferConfig = {
 		...DEFAULT_FORWARD_BUFFER_CONFIG,
 		...config.forwardBuffer
@@ -133,9 +84,22 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 		...DEFAULT_BACK_BUFFER_CONFIG,
 		...config.backBuffer
 	};
+	const deps = {
+		state: compositionDeps.state,
+		context: compositionDeps.context,
+		config: {
+			...compositionDeps.config,
+			sourceBufferActor,
+			fetch: fetchBytes
+		}
+	};
+	const pipelines = (config.messagePipelines ?? DEFAULT_MESSAGE_PIPELINES)();
 	const getBufferedSegments = (allSegments) => {
-		const bufferedIds = new Set(peek(sourceBufferActor.snapshot).context.segments.filter((s) => !s.partial).map((s) => s.id));
-		return allSegments.filter((s) => bufferedIds.has(s.id));
+		const merged = mergeTimeRanges(peek(sourceBufferActor.snapshot).context.segments.filter((s) => !s.partial).map((s) => ({
+			start: s.startTime,
+			end: s.startTime + s.duration
+		})));
+		return allSegments.filter((s) => isTimeRangeCovered(s.startTime, s.startTime + s.duration, merged));
 	};
 	/**
 	* Translate a load message into an ordered LoadTask list based on committed
@@ -236,8 +200,8 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 			runner.schedule(makeLoadTask(op, {
 				getContext,
 				setContext,
-				fetchBytes,
-				sourceBufferActor
+				pipelines,
+				deps
 			})).then(void 0, (e) => {
 				if (e instanceof Error && e.name === "AbortError") return;
 				console.error("Unexpected error in segment loader:", e);
@@ -250,7 +214,7 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 		initial: "idle",
 		context: {
 			inFlightInitTrackId: null,
-			inFlightSegmentId: null
+			inFlightSegment: null
 		},
 		states: {
 			idle: { on: { load: (msg, ctx) => {
@@ -264,12 +228,14 @@ function createSegmentLoaderActor(sourceBufferActor, fetchBytes, config = {}) {
 				on: { load: (msg, ctx) => {
 					const { context, runner } = ctx;
 					const allTasks = planTasks(msg);
-					if (context.inFlightSegmentId !== null && allTasks.some((t) => t.type === "append-segment" && t.meta.id === context.inFlightSegmentId) || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)) {
+					const inFlight = context.inFlightSegment;
+					const segmentInFlightStillNeeded = (t) => t.type === "append-segment" && inFlight !== null && t.meta.id === inFlight.id && t.meta.trackId === inFlight.trackId;
+					if (inFlight !== null && allTasks.some(segmentInFlightStillNeeded) || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)) {
 						runner.abortPending();
-						scheduleAll(allTasks.filter((t) => !(t.type === "append-segment" && t.meta.id === context.inFlightSegmentId) && !(t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)), ctx);
+						scheduleAll(allTasks.filter((t) => !segmentInFlightStillNeeded(t) && !(t.type === "append-init" && t.meta.trackId === context.inFlightInitTrackId)), ctx);
 					} else {
 						runner.abortAll();
-						if (context.inFlightSegmentId !== null || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId !== context.inFlightInitTrackId)) sourceBufferActor.send({ type: "cancel" });
+						if (context.inFlightSegment !== null || context.inFlightInitTrackId !== null && allTasks.some((t) => t.type === "append-init" && t.meta.trackId !== context.inFlightInitTrackId)) sourceBufferActor.send({ type: "cancel" });
 						scheduleAll(allTasks, ctx);
 					}
 				} }