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

package/dist/dev/media/primitives/select-tracks.js.map

@@ -1 +1 @@
-{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/media/primitives/select-tracks.ts"],"sourcesContent":["import type { MaybeResolvedPresentation, PartiallyResolvedTextTrack, TextTrack } from '../types';\n\n/**\n * State shape for track selection.\n */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n}\n\n/**\n * Configuration for audio track selection.\n */\nexport interface AudioSelectionConfig {\n  /**\n   * Preferred audio language (ISO 639 code, e.g., \"en\", \"es\").\n   * If not specified, selects first audio track.\n   */\n  preferredAudioLanguage?: string;\n}\n\n/**\n * Configuration for text track selection.\n */\nexport interface TextSelectionConfig {\n  /**\n   * Preferred subtitle language (ISO 639 code, e.g., \"en\", \"es\").\n   * If specified, selects matching track if available.\n   */\n  preferredSubtitleLanguage?: string;\n\n  /**\n   * Include FORCED subtitle tracks in selection.\n   * Default: false (follows hls.js/http-streaming pattern)\n   *\n   * Note: Per Apple's HLS spec, if content has forced and regular subtitles\n   * in the same language, the regular track MUST contain both forced and\n   * regular content. Therefore, forced-only tracks are redundant and excluded\n   * by default.\n   */\n  includeForcedTracks?: boolean;\n\n  /**\n   * Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS).\n   * Default: false (user opt-in, matches hls.js/http-streaming)\n   *\n   * When enabled, tracks marked with both DEFAULT=YES and AUTOSELECT=YES\n   * will be automatically selected if no user preference matches.\n   */\n  enableDefaultTrack?: boolean;\n}\n\n// =============================================================================\n// Helper Functions (Pure Selection Logic)\n//\n// Candidate-list policies and track geometry, for the selection rules in\n// `playback/behaviors/select-tracks.ts` and `playback/behaviors/track-switching.ts`\n// to compose. Nothing here consults a whole presentation or returns a single id:\n// narrowing a list and ordering a list are the two shapes a rule can take, and the\n// rule chain takes the head of what they leave.\n// =============================================================================\n\n/**\n * Test whether a track matches a partial-track description: every present,\n * defined field of `filter` equals the track's. Absent or `undefined` filter\n * fields don't constrain. Used to narrow candidates by a user selection\n * (`{ id }`, `{ language }`, `{ height }`, …).\n *\n * @param track - The track to test\n * @param filter - Partial-track description; only present, defined fields constrain\n * @returns `true` when the track matches every constraining field\n */\nexport function matchesPartialTrack<T>(track: T, filter: Partial<T>): boolean {\n  for (const key in filter) {\n    const filterValue = filter[key as keyof T];\n    if (filterValue !== undefined && track[key as keyof T] !== filterValue) return false;\n  }\n  return true;\n}\n\ntype RankableTrack = { id: string; width?: number; height?: number; bandwidth?: number };\n\n/** Missing dimensions are treated as area `0`, so a track without them ranks last. */\nfunction pixelArea(track: RankableTrack): number {\n  return (track.width ?? 0) * (track.height ?? 0);\n}\n\n/**\n * Narrow to the tracks at or below `maxPixelArea`, and nothing else: no ordering,\n * no fallback. Survivors keep their incoming order, and an empty result is a real\n * answer — \"none of these fit\".\n *\n * Deliberately only the filter, because as a selection rule this composes under\n * `applyRules`, which already owns both halves a caller might expect here: an empty\n * result is skipped, so a preference can never narrow the candidate set to nothing;\n * and ordering the survivors is a separate rule's job\n * ({@link byDescendingResolution}, bandwidth ABR). Doing either here would duplicate\n * the composer and give one rule two responsibilities.\n */\nexport function tracksUnderPixelArea<T extends RankableTrack>(\n  tracks: readonly T[],\n  maxPixelArea: number = Number.POSITIVE_INFINITY\n): readonly T[] {\n  return tracks.filter((track) => pixelArea(track) <= maxPixelArea);\n}\n\n/**\n * The smallest track area that still covers `minPixelArea`, or `undefined` when\n * no track reaches it.\n *\n * The cap a surface-size rule wants when it should round *up* to the ladder: a\n * surface between two tiers is covered by the upper one, and capping at the\n * surface's own area instead would serve a picture smaller than the surface and\n * upscale it.\n *\n * Tracks declaring no dimensions compare as area `0` and so never cover anything,\n * which keeps them out of the cap rather than pinning it to zero.\n */\nexport function smallestCoveringPixelArea(tracks: readonly RankableTrack[], minPixelArea: number): number | undefined {\n  const covering = tracks.map(pixelArea).filter((area) => area >= minPixelArea);\n\n  return covering.length ? Math.min(...covering) : undefined;\n}\n\n/**\n * Compare two tracks by resolution, largest first, with bandwidth as the tiebreak\n * for renditions of identical dimensions. Missing dimensions are treated as area\n * `0`, so a track without them sorts last.\n *\n * A comparator rather than a \"highest track\" function: the selection-rule chain\n * takes the head of the list it produces, so ranking never has to collapse to a\n * single track. `preferHighestResolution` is `sort` over this and nothing more.\n */\nexport function byDescendingResolution(a: RankableTrack, b: RankableTrack): number {\n  return pixelArea(b) - pixelArea(a) || (b.bandwidth ?? 0) - (a.bandwidth ?? 0);\n}\n\n/**\n * Default audio policy over a candidate list: the three-tier pick a selection-rule\n * chain applies once it has narrowed the candidates.\n *\n * Priority: `preferredAudioLanguage` match → `DEFAULT=YES` → first track.\n */\nexport function pickAudioTrackFromTracks(\n  tracks: readonly { id: string; language?: string | undefined; default?: boolean | undefined }[],\n  config?: AudioSelectionConfig\n): string | undefined {\n  // Try preferred language first\n  if (config?.preferredAudioLanguage) {\n    const languageMatch = tracks.find((track) => track.language === config.preferredAudioLanguage);\n    if (languageMatch) {\n      return languageMatch.id;\n    }\n  }\n\n  // Try default track\n  const defaultTrack = tracks.find((track) => track.default === true);\n  if (defaultTrack) {\n    return defaultTrack.id;\n  }\n\n  // Fall back to first track\n  return tracks[0]?.id;\n}\n\n/**\n * Default text-track policy over a candidate list: the opt-in three-tier pick\n * `switchTextTrack`'s terminal applies once it has narrowed the renditions to the\n * constrained, CDN-scoped set.\n *\n * Priority: `preferredSubtitleLanguage` match → `DEFAULT=YES + AUTOSELECT=YES`\n * (only when `enableDefaultTrack`) → `undefined` (opt-in). FORCED tracks are\n * excluded unless `includeForcedTracks` (Apple-spec: a regular track must carry\n * forced content when both exist, so a forced-only track is redundant).\n */\nexport function pickTextTrackFromTracks(\n  tracks: readonly (PartiallyResolvedTextTrack | TextTrack)[],\n  config?: TextSelectionConfig\n): string | undefined {\n  const availableTracks = config?.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);\n  if (availableTracks.length === 0) return undefined;\n\n  const { preferredSubtitleLanguage, enableDefaultTrack = false } = config ?? {};\n\n  if (preferredSubtitleLanguage) {\n    const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);\n    if (languageMatch) return languageMatch.id;\n  }\n\n  if (enableDefaultTrack) {\n    const defaultTrack = availableTracks.find((track) => track.default === true);\n    if (defaultTrack) return defaultTrack.id;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;AA0EA,SAAgB,oBAAuB,OAAU,QAA6B;CAC5E,KAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,cAAc,OAAO;EAC3B,IAAI,gBAAgB,KAAA,KAAa,MAAM,SAAoB,aAAa,OAAO;CACjF;CACA,OAAO;AACT;;AAKA,SAAS,UAAU,OAA8B;CAC/C,QAAQ,MAAM,SAAS,MAAM,MAAM,UAAU;AAC/C;;;;;;;;;;;;;AAcA,SAAgB,qBACd,QACA,eAAuB,OAAO,mBAChB;CACd,OAAO,OAAO,QAAQ,UAAU,UAAU,KAAK,KAAK,YAAY;AAClE;;;;;;;;;;;;;AAcA,SAAgB,0BAA0B,QAAkC,cAA0C;CACpH,MAAM,WAAW,OAAO,IAAI,SAAS,CAAC,CAAC,QAAQ,SAAS,QAAQ,YAAY;CAE5E,OAAO,SAAS,SAAS,KAAK,IAAI,GAAG,QAAQ,IAAI,KAAA;AACnD;;;;;;;;;;AAWA,SAAgB,uBAAuB,GAAkB,GAA0B;CACjF,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,EAAE,aAAa,MAAM,EAAE,aAAa;AAC7E;;;;;;;AAQA,SAAgB,yBACd,QACA,QACoB;CAEpB,IAAI,QAAQ,wBAAwB;EAClC,MAAM,gBAAgB,OAAO,MAAM,UAAU,MAAM,aAAa,OAAO,sBAAsB;EAC7F,IAAI,eACF,OAAO,cAAc;CAEzB;CAGA,MAAM,eAAe,OAAO,MAAM,UAAU,MAAM,YAAY,IAAI;CAClE,IAAI,cACF,OAAO,aAAa;CAItB,OAAO,OAAO,EAAE,EAAE;AACpB;;;;;;;;;;;AAYA,SAAgB,wBACd,QACA,QACoB;CACpB,MAAM,kBAAkB,QAAQ,sBAAsB,SAAS,OAAO,QAAQ,UAAU,CAAC,MAAM,MAAM;CACrG,IAAI,gBAAgB,WAAW,GAAG,OAAO,KAAA;CAEzC,MAAM,EAAE,2BAA2B,qBAAqB,UAAU,UAAU,CAAC;CAE7E,IAAI,2BAA2B;EAC7B,MAAM,gBAAgB,gBAAgB,MAAM,UAAU,MAAM,aAAa,yBAAyB;EAClG,IAAI,eAAe,OAAO,cAAc;CAC1C;CAEA,IAAI,oBAAoB;EACtB,MAAM,eAAe,gBAAgB,MAAM,UAAU,MAAM,YAAY,IAAI;EAC3E,IAAI,cAAc,OAAO,aAAa;CACxC;AAGF"}
+{"version":3,"file":"select-tracks.js","names":[],"sources":["../../../../src/media/primitives/select-tracks.ts"],"sourcesContent":["import type { MaybeResolvedPresentation, PartiallyResolvedTextTrack, TextTrack } from '../types';\n\n/** State shape for track selection. */\nexport interface TrackSelectionState {\n  presentation?: MaybeResolvedPresentation;\n  selectedVideoTrackId?: string;\n  selectedAudioTrackId?: string;\n  selectedTextTrackId?: string;\n}\n\n/** Configuration for audio track selection. */\nexport interface AudioSelectionConfig {\n  /** Preferred audio language (ISO 639 code, e.g., \"en\", \"es\"). If not specified, selects first audio track. */\n  preferredAudioLanguage?: string;\n}\n\n/** Configuration for text track selection. */\nexport interface TextSelectionConfig {\n  /** Preferred subtitle language (ISO 639 code, e.g., \"en\", \"es\"). If specified, selects matching track if available. */\n  preferredSubtitleLanguage?: string;\n\n  /**\n   * Include FORCED subtitle tracks in selection. Default: false (follows hls.js/http-streaming pattern)\n   *\n   * Note: Per Apple's HLS spec, if content has forced and regular subtitles in the same language, the regular track\n   * MUST contain both forced and regular content. Therefore, forced-only tracks are redundant and excluded by default.\n   */\n  includeForcedTracks?: boolean;\n\n  /**\n   * Auto-select DEFAULT track (requires DEFAULT=YES + AUTOSELECT=YES in HLS). Default: false (user opt-in, matches\n   * hls.js/http-streaming)\n   *\n   * When enabled, tracks marked with both DEFAULT=YES and AUTOSELECT=YES will be automatically selected if no user\n   * preference matches.\n   */\n  enableDefaultTrack?: boolean;\n}\n\n// =============================================================================\n// Helper Functions (Pure Selection Logic)\n//\n// Candidate-list policies and track geometry, for the selection rules in\n// `playback/behaviors/select-tracks.ts` and `playback/behaviors/track-switching.ts`\n// to compose. Nothing here consults a whole presentation or returns a single id:\n// narrowing a list and ordering a list are the two shapes a rule can take, and the\n// rule chain takes the head of what they leave.\n// =============================================================================\n\n/**\n * Test whether a track matches a partial-track description: every present, defined field of `filter` equals the\n * track's. Absent or `undefined` filter fields don't constrain. Used to narrow candidates by a user selection (`{ id\n * }`, `{ language }`, `{ height }`, …).\n *\n * @param track - The track to test\n * @param filter - Partial-track description; only present, defined fields constrain\n * @returns `true` when the track matches every constraining field\n */\nexport function matchesPartialTrack<T>(track: T, filter: Partial<T>): boolean {\n  for (const key in filter) {\n    const filterValue = filter[key as keyof T];\n    if (filterValue !== undefined && track[key as keyof T] !== filterValue) return false;\n  }\n\n  return true;\n}\n\ntype RankableTrack = { id: string; width?: number; height?: number; bandwidth?: number };\n\n/** Missing dimensions are treated as area `0`, so a track without them ranks last. */\nfunction pixelArea(track: RankableTrack): number {\n  return (track.width ?? 0) * (track.height ?? 0);\n}\n\n/**\n * Narrow to the tracks at or below `maxPixelArea`, and nothing else: no ordering, no fallback. Survivors keep their\n * incoming order, and an empty result is a real answer — \"none of these fit\".\n *\n * Deliberately only the filter, because as a selection rule this composes under `applyRules`, which already owns both\n * halves a caller might expect here: an empty result is skipped, so a preference can never narrow the candidate set to\n * nothing; and ordering the survivors is a separate rule's job ({@link byDescendingResolution}, bandwidth ABR). Doing\n * either here would duplicate the composer and give one rule two responsibilities.\n */\nexport function tracksUnderPixelArea<T extends RankableTrack>(\n  tracks: readonly T[],\n  maxPixelArea: number = Number.POSITIVE_INFINITY\n): readonly T[] {\n  return tracks.filter((track) => pixelArea(track) <= maxPixelArea);\n}\n\n/**\n * The smallest track area that still covers `minPixelArea`, or `undefined` when no track reaches it.\n *\n * The cap a surface-size rule wants when it should round _up_ to the ladder: a surface between two tiers is covered by\n * the upper one, and capping at the surface's own area instead would serve a picture smaller than the surface and\n * upscale it.\n *\n * Tracks declaring no dimensions compare as area `0` and so never cover anything, which keeps them out of the cap\n * rather than pinning it to zero.\n */\nexport function smallestCoveringPixelArea(tracks: readonly RankableTrack[], minPixelArea: number): number | undefined {\n  const covering = tracks.map(pixelArea).filter((area) => area >= minPixelArea);\n\n  return covering.length ? Math.min(...covering) : undefined;\n}\n\n/**\n * Compare two tracks by resolution, largest first, with bandwidth as the tiebreak for renditions of identical\n * dimensions. Missing dimensions are treated as area `0`, so a track without them sorts last.\n *\n * A comparator rather than a \"highest track\" function: the selection-rule chain takes the head of the list it produces,\n * so ranking never has to collapse to a single track. `preferHighestResolution` is `sort` over this and nothing more.\n */\nexport function byDescendingResolution(a: RankableTrack, b: RankableTrack): number {\n  return pixelArea(b) - pixelArea(a) || (b.bandwidth ?? 0) - (a.bandwidth ?? 0);\n}\n\n/**\n * Default audio policy over a candidate list: the three-tier pick a selection-rule chain applies once it has narrowed\n * the candidates.\n *\n * Priority: `preferredAudioLanguage` match → `DEFAULT=YES` → first track.\n */\nexport function pickAudioTrackFromTracks(\n  tracks: readonly { id: string; language?: string | undefined; default?: boolean | undefined }[],\n  config?: AudioSelectionConfig\n): string | undefined {\n  // Try preferred language first\n  if (config?.preferredAudioLanguage) {\n    const languageMatch = tracks.find((track) => track.language === config.preferredAudioLanguage);\n    if (languageMatch) return languageMatch.id;\n  }\n\n  // Try default track\n  const defaultTrack = tracks.find((track) => track.default === true);\n  if (defaultTrack) return defaultTrack.id;\n\n  // Fall back to first track\n  return tracks[0]?.id;\n}\n\n/**\n * Default text-track policy over a candidate list: the opt-in three-tier pick `switchTextTrack`'s terminal applies once\n * it has narrowed the renditions to the constrained, CDN-scoped set.\n *\n * Priority: `preferredSubtitleLanguage` match → `DEFAULT=YES + AUTOSELECT=YES` (only when `enableDefaultTrack`) →\n * `undefined` (opt-in). FORCED tracks are excluded unless `includeForcedTracks` (Apple-spec: a regular track must carry\n * forced content when both exist, so a forced-only track is redundant).\n */\nexport function pickTextTrackFromTracks(\n  tracks: readonly (PartiallyResolvedTextTrack | TextTrack)[],\n  config?: TextSelectionConfig\n): string | undefined {\n  const availableTracks = config?.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);\n  if (availableTracks.length === 0) return undefined;\n\n  const { preferredSubtitleLanguage, enableDefaultTrack = false } = config ?? {};\n\n  if (preferredSubtitleLanguage) {\n    const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);\n    if (languageMatch) return languageMatch.id;\n  }\n\n  if (enableDefaultTrack) {\n    const defaultTrack = availableTracks.find((track) => track.default === true);\n    if (defaultTrack) return defaultTrack.id;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;AA0DA,SAAgB,oBAAuB,OAAU,QAA6B;CAC5E,KAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,cAAc,OAAO;EAC3B,IAAI,gBAAgB,KAAA,KAAa,MAAM,SAAoB,aAAa,OAAO;CACjF;CAEA,OAAO;AACT;;AAKA,SAAS,UAAU,OAA8B;CAC/C,QAAQ,MAAM,SAAS,MAAM,MAAM,UAAU;AAC/C;;;;;;;;;;AAWA,SAAgB,qBACd,QACA,eAAuB,OAAO,mBAChB;CACd,OAAO,OAAO,QAAQ,UAAU,UAAU,KAAK,KAAK,YAAY;AAClE;;;;;;;;;;;AAYA,SAAgB,0BAA0B,QAAkC,cAA0C;CACpH,MAAM,WAAW,OAAO,IAAI,SAAS,CAAC,CAAC,QAAQ,SAAS,QAAQ,YAAY;CAE5E,OAAO,SAAS,SAAS,KAAK,IAAI,GAAG,QAAQ,IAAI,KAAA;AACnD;;;;;;;;AASA,SAAgB,uBAAuB,GAAkB,GAA0B;CACjF,OAAO,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,EAAE,aAAa,MAAM,EAAE,aAAa;AAC7E;;;;;;;AAQA,SAAgB,yBACd,QACA,QACoB;CAEpB,IAAI,QAAQ,wBAAwB;EAClC,MAAM,gBAAgB,OAAO,MAAM,UAAU,MAAM,aAAa,OAAO,sBAAsB;EAC7F,IAAI,eAAe,OAAO,cAAc;CAC1C;CAGA,MAAM,eAAe,OAAO,MAAM,UAAU,MAAM,YAAY,IAAI;CAClE,IAAI,cAAc,OAAO,aAAa;CAGtC,OAAO,OAAO,EAAE,EAAE;AACpB;;;;;;;;;AAUA,SAAgB,wBACd,QACA,QACoB;CACpB,MAAM,kBAAkB,QAAQ,sBAAsB,SAAS,OAAO,QAAQ,UAAU,CAAC,MAAM,MAAM;CACrG,IAAI,gBAAgB,WAAW,GAAG,OAAO,KAAA;CAEzC,MAAM,EAAE,2BAA2B,qBAAqB,UAAU,UAAU,CAAC;CAE7E,IAAI,2BAA2B;EAC7B,MAAM,gBAAgB,gBAAgB,MAAM,UAAU,MAAM,aAAa,yBAAyB;EAClG,IAAI,eAAe,OAAO,cAAc;CAC1C;CAEA,IAAI,oBAAoB;EACtB,MAAM,eAAe,gBAAgB,MAAM,UAAU,MAAM,YAAY,IAAI;EAC3E,IAAI,cAAc,OAAO,aAAa;CACxC;AAGF"}

package/dist/dev/media/text/parse-vtt-timestamp-map.js

@@ -1,15 +1,13 @@
 //#region src/media/text/parse-vtt-timestamp-map.ts
 const TIMESTAMP_MAP_PREFIX = "X-TIMESTAMP-MAP=";
 /**
-* Scrape a WebVTT segment's `X-TIMESTAMP-MAP` header into a {@link TimestampMap}
-* — the only header line we need to correlate LOCAL cue times with the media
-* presentation timeline. Deliberately *not* a WebVTT parser: cue parsing stays
-* with the browser's native `<track>` parser (which drops this line); this reads
-* just the one header field the native path discards.
+* Scrape a WebVTT segment's `X-TIMESTAMP-MAP` header into a {@link TimestampMap} — the only header line we need to
+* correlate LOCAL cue times with the media presentation timeline. Deliberately _not_ a WebVTT parser: cue parsing stays
+* with the browser's native `<track>` parser (which drops this line); this reads just the one header field the native
+* path discards.
 *
-* Returns `undefined` when the segment carries no map (e.g. cues already in
-* absolute presentation time) — per the HLS spec that means LOCAL 0 maps to
-* MPEGTS 0. Tolerant of attribute order and `[HH:]MM:SS.mmm` LOCAL forms.
+* Returns `undefined` when the segment carries no map (e.g. cues already in absolute presentation time) — per the HLS
+* spec that means LOCAL 0 maps to MPEGTS 0. Tolerant of attribute order and `[HH:]MM:SS.mmm` LOCAL forms.
 */
 function parseVttTimestampMap(text) {
 	const timestampMapLine = text.split(/\r\n|\r|\n/).find((line) => line.startsWith(TIMESTAMP_MAP_PREFIX));

package/dist/dev/media/text/parse-vtt-timestamp-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse-vtt-timestamp-map.js","names":[],"sources":["../../../../src/media/text/parse-vtt-timestamp-map.ts"],"sourcesContent":["/**\n * WebVTT-in-HLS `X-TIMESTAMP-MAP`: correlates a cue's LOCAL (in-file) time with\n * an MPEG-2 presentation timestamp, so LOCAL-authored cues can be placed on the\n * media presentation timeline. Stored raw — the LOCAL→native correction is\n * `mpegts / 90000 - local` — so it stays independent of how (or whether) the\n * presentation is later re-origined. See the HLS spec, RFC 8216bis §3.5.\n */\nexport interface TimestampMap {\n  /** The MPEG-2 presentation timestamp, in 90 kHz ticks, as authored. */\n  mpegts: number;\n  /** The LOCAL cue time the `mpegts` value maps to, in seconds. */\n  local: number;\n}\n\nconst TIMESTAMP_MAP_PREFIX = 'X-TIMESTAMP-MAP=';\n\n/**\n * Scrape a WebVTT segment's `X-TIMESTAMP-MAP` header into a {@link TimestampMap}\n * — the only header line we need to correlate LOCAL cue times with the media\n * presentation timeline. Deliberately *not* a WebVTT parser: cue parsing stays\n * with the browser's native `<track>` parser (which drops this line); this reads\n * just the one header field the native path discards.\n *\n * Returns `undefined` when the segment carries no map (e.g. cues already in\n * absolute presentation time) — per the HLS spec that means LOCAL 0 maps to\n * MPEGTS 0. Tolerant of attribute order and `[HH:]MM:SS.mmm` LOCAL forms.\n */\nexport function parseVttTimestampMap(text: string): TimestampMap | undefined {\n  const timestampMapLine = text.split(/\\r\\n|\\r|\\n/).find((line) => line.startsWith(TIMESTAMP_MAP_PREFIX));\n  return timestampMapLine ? parseTimestampMapBody(timestampMapLine.slice(TIMESTAMP_MAP_PREFIX.length)) : undefined;\n}\n\nconst TimeStampMapParserMap = {\n  LOCAL: parseWebVttTimestamp,\n  MPEGTS: (v: string) => +v,\n} as const;\n\ntype TimeStampMapParserMap = typeof TimeStampMapParserMap;\n\nfunction parseTimestampMapBody(body: string): TimestampMap | undefined {\n  return Object.fromEntries(\n    body.split(',').map((kvStr) => {\n      const [k, v] = kvStr.split(/:(.*)/).map((kOrV) => kOrV.trim());\n      return [k?.toLowerCase(), TimeStampMapParserMap[k as keyof TimeStampMapParserMap](v as string)];\n    })\n  ) as TimestampMap;\n}\n\n/** Seconds-per-unit for the `[HH:]MM:SS.mmm` parts, right-aligned so a missing HH just drops the leading weight. */\nconst VTT_TIMESTAMP_WEIGHTS = [3600, 60, 1, 0.001];\n\nfunction parseWebVttTimestamp(value: string): number {\n  const parts = value.split(/[:.]/);\n  return parts.reduce((acc, val, i) => acc + +val * (VTT_TIMESTAMP_WEIGHTS[i + 4 - parts.length] ?? 0), 0);\n}\n"],"mappings":";AAcA,MAAM,uBAAuB;;;;;;;;;;;;AAa7B,SAAgB,qBAAqB,MAAwC;CAC3E,MAAM,mBAAmB,KAAK,MAAM,YAAY,CAAC,CAAC,MAAM,SAAS,KAAK,WAAW,oBAAoB,CAAC;CACtG,OAAO,mBAAmB,sBAAsB,iBAAiB,MAAM,EAA2B,CAAC,IAAI,KAAA;AACzG;AAEA,MAAM,wBAAwB;CAC5B,OAAO;CACP,SAAS,MAAc,CAAC;AAC1B;AAIA,SAAS,sBAAsB,MAAwC;CACrE,OAAO,OAAO,YACZ,KAAK,MAAM,GAAG,CAAC,CAAC,KAAK,UAAU;EAC7B,MAAM,CAAC,GAAG,KAAK,MAAM,MAAM,OAAO,CAAC,CAAC,KAAK,SAAS,KAAK,KAAK,CAAC;EAC7D,OAAO,CAAC,GAAG,YAAY,GAAG,sBAAsB,EAAiC,CAAC,CAAW,CAAC;CAChG,CAAC,CACH;AACF;;AAGA,MAAM,wBAAwB;CAAC;CAAM;CAAI;CAAG;AAAK;AAEjD,SAAS,qBAAqB,OAAuB;CACnD,MAAM,QAAQ,MAAM,MAAM,MAAM;CAChC,OAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,MAAM,CAAC,OAAO,sBAAsB,IAAI,IAAI,MAAM,WAAW,IAAI,CAAC;AACzG"}
+{"version":3,"file":"parse-vtt-timestamp-map.js","names":[],"sources":["../../../../src/media/text/parse-vtt-timestamp-map.ts"],"sourcesContent":["/**\n * WebVTT-in-HLS `X-TIMESTAMP-MAP`: correlates a cue's LOCAL (in-file) time with an MPEG-2 presentation timestamp, so\n * LOCAL-authored cues can be placed on the media presentation timeline. Stored raw — the LOCAL→native correction is\n * `mpegts / 90000 - local` — so it stays independent of how (or whether) the presentation is later re-origined. See the\n * HLS spec, RFC 8216bis §3.5.\n */\nexport interface TimestampMap {\n  /** The MPEG-2 presentation timestamp, in 90 kHz ticks, as authored. */\n  mpegts: number;\n  /** The LOCAL cue time the `mpegts` value maps to, in seconds. */\n  local: number;\n}\n\nconst TIMESTAMP_MAP_PREFIX = 'X-TIMESTAMP-MAP=';\n\n/**\n * Scrape a WebVTT segment's `X-TIMESTAMP-MAP` header into a {@link TimestampMap} — the only header line we need to\n * correlate LOCAL cue times with the media presentation timeline. Deliberately _not_ a WebVTT parser: cue parsing stays\n * with the browser's native `<track>` parser (which drops this line); this reads just the one header field the native\n * path discards.\n *\n * Returns `undefined` when the segment carries no map (e.g. cues already in absolute presentation time) — per the HLS\n * spec that means LOCAL 0 maps to MPEGTS 0. Tolerant of attribute order and `[HH:]MM:SS.mmm` LOCAL forms.\n */\nexport function parseVttTimestampMap(text: string): TimestampMap | undefined {\n  const timestampMapLine = text.split(/\\r\\n|\\r|\\n/).find((line) => line.startsWith(TIMESTAMP_MAP_PREFIX));\n\n  return timestampMapLine ? parseTimestampMapBody(timestampMapLine.slice(TIMESTAMP_MAP_PREFIX.length)) : undefined;\n}\n\nconst TimeStampMapParserMap = {\n  LOCAL: parseWebVttTimestamp,\n  MPEGTS: (v: string) => +v,\n} as const;\n\ntype TimeStampMapParserMap = typeof TimeStampMapParserMap;\n\nfunction parseTimestampMapBody(body: string): TimestampMap | undefined {\n  return Object.fromEntries(\n    body.split(',').map((kvStr) => {\n      const [k, v] = kvStr.split(/:(.*)/).map((kOrV) => kOrV.trim());\n\n      return [k?.toLowerCase(), TimeStampMapParserMap[k as keyof TimeStampMapParserMap](v as string)];\n    })\n  ) as TimestampMap;\n}\n\n/** Seconds-per-unit for the `[HH:]MM:SS.mmm` parts, right-aligned so a missing HH just drops the leading weight. */\nconst VTT_TIMESTAMP_WEIGHTS = [3600, 60, 1, 0.001];\n\nfunction parseWebVttTimestamp(value: string): number {\n  const parts = value.split(/[:.]/);\n\n  return parts.reduce((acc, val, i) => acc + +val * (VTT_TIMESTAMP_WEIGHTS[i + 4 - parts.length] ?? 0), 0);\n}\n"],"mappings":";AAaA,MAAM,uBAAuB;;;;;;;;;;AAW7B,SAAgB,qBAAqB,MAAwC;CAC3E,MAAM,mBAAmB,KAAK,MAAM,YAAY,CAAC,CAAC,MAAM,SAAS,KAAK,WAAW,oBAAoB,CAAC;CAEtG,OAAO,mBAAmB,sBAAsB,iBAAiB,MAAM,EAA2B,CAAC,IAAI,KAAA;AACzG;AAEA,MAAM,wBAAwB;CAC5B,OAAO;CACP,SAAS,MAAc,CAAC;AAC1B;AAIA,SAAS,sBAAsB,MAAwC;CACrE,OAAO,OAAO,YACZ,KAAK,MAAM,GAAG,CAAC,CAAC,KAAK,UAAU;EAC7B,MAAM,CAAC,GAAG,KAAK,MAAM,MAAM,OAAO,CAAC,CAAC,KAAK,SAAS,KAAK,KAAK,CAAC;EAE7D,OAAO,CAAC,GAAG,YAAY,GAAG,sBAAsB,EAAiC,CAAC,CAAW,CAAC;CAChG,CAAC,CACH;AACF;;AAGA,MAAM,wBAAwB;CAAC;CAAM;CAAI;CAAG;AAAK;AAEjD,SAAS,qBAAqB,OAAuB;CACnD,MAAM,QAAQ,MAAM,MAAM,MAAM;CAEhC,OAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,MAAM,CAAC,OAAO,sBAAsB,IAAI,IAAI,MAAM,WAAW,IAAI,CAAC;AACzG"}

package/dist/dev/media/text/resolve-vtt-metadata.js

@@ -1,21 +1,20 @@
 import { parseVttTimestampMap } from "./parse-vtt-timestamp-map.js";
 //#region src/media/text/resolve-vtt-metadata.ts
 /**
-* Header-level text-segment metadata — the `X-TIMESTAMP-MAP` correlation scraped from
-* a VTT segment's raw bytes. DOM-free (a plain fetch + regex parse): the native
-* `<track>` parser in `media/dom/text` (`resolveVttSegment`) discards this header, so a
-* caller that needs it (e.g. non-zero-PTS relocation) fetches the bytes itself.
+* Header-level text-segment metadata — the `X-TIMESTAMP-MAP` correlation scraped from a VTT segment's raw bytes.
+* DOM-free (a plain fetch + regex parse): the native `<track>` parser in `media/dom/text` (`resolveVttSegment`)
+* discards this header, so a caller that needs it (e.g. non-zero-PTS relocation) fetches the bytes itself.
 */
 /**
 * Fetch a VTT segment and scrape only its header metadata (no cue parsing).
 *
-* The native `<track>` parser (`media/dom/text`'s `resolveVttSegment`) discards
-* `X-TIMESTAMP-MAP`, so reading it requires the raw bytes. This is a separate,
-* caller-controlled fetch — the caller decides *when* metadata is needed (e.g.
-* once per source) rather than paying for it on every segment.
+* The native `<track>` parser (`media/dom/text`'s `resolveVttSegment`) discards `X-TIMESTAMP-MAP`, so reading it
+* requires the raw bytes. This is a separate, caller-controlled fetch — the caller decides _when_ metadata is needed
+* (e.g. once per source) rather than paying for it on every segment.
 */
 async function resolveVttSegmentMetadata(url) {
-	return { timestampMap: parseVttTimestampMap(await fetch(url).then((response) => response.text())) };
+	const text = await fetch(url).then((response) => response.text());
+	return { timestampMap: parseVttTimestampMap(text) };
 }
 //#endregion
 export { resolveVttSegmentMetadata };

package/dist/dev/media/text/resolve-vtt-metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-vtt-metadata.js","names":[],"sources":["../../../../src/media/text/resolve-vtt-metadata.ts"],"sourcesContent":["/**\n * Header-level text-segment metadata — the `X-TIMESTAMP-MAP` correlation scraped from\n * a VTT segment's raw bytes. DOM-free (a plain fetch + regex parse): the native\n * `<track>` parser in `media/dom/text` (`resolveVttSegment`) discards this header, so a\n * caller that needs it (e.g. non-zero-PTS relocation) fetches the bytes itself.\n */\nimport { parseVttTimestampMap, type TimestampMap } from './parse-vtt-timestamp-map';\n\n/**\n * Header-level metadata for a text segment, surfaced alongside its cues. Each\n * field is present only when the segment declared it.\n */\nexport interface TextSegmentMetadata {\n  timestampMap?: TimestampMap;\n}\n\n/**\n * Fetch a VTT segment and scrape only its header metadata (no cue parsing).\n *\n * The native `<track>` parser (`media/dom/text`'s `resolveVttSegment`) discards\n * `X-TIMESTAMP-MAP`, so reading it requires the raw bytes. This is a separate,\n * caller-controlled fetch — the caller decides *when* metadata is needed (e.g.\n * once per source) rather than paying for it on every segment.\n */\nexport async function resolveVttSegmentMetadata(url: string): Promise<TextSegmentMetadata> {\n  const text = await fetch(url).then((response) => response.text());\n  return { timestampMap: parseVttTimestampMap(text) };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAwBA,eAAsB,0BAA0B,KAA2C;CAEzF,OAAO,EAAE,cAAc,qBAAqB,MADzB,MAAM,GAAG,CAAC,CAAC,MAAM,aAAa,SAAS,KAAK,CAAC,CAChB,EAAE;AACpD"}
+{"version":3,"file":"resolve-vtt-metadata.js","names":[],"sources":["../../../../src/media/text/resolve-vtt-metadata.ts"],"sourcesContent":["/**\n * Header-level text-segment metadata — the `X-TIMESTAMP-MAP` correlation scraped from a VTT segment's raw bytes.\n * DOM-free (a plain fetch + regex parse): the native `<track>` parser in `media/dom/text` (`resolveVttSegment`)\n * discards this header, so a caller that needs it (e.g. non-zero-PTS relocation) fetches the bytes itself.\n */\nimport { parseVttTimestampMap, type TimestampMap } from './parse-vtt-timestamp-map';\n\n/**\n * Header-level metadata for a text segment, surfaced alongside its cues. Each field is present only when the segment\n * declared it.\n */\nexport interface TextSegmentMetadata {\n  timestampMap?: TimestampMap;\n}\n\n/**\n * Fetch a VTT segment and scrape only its header metadata (no cue parsing).\n *\n * The native `<track>` parser (`media/dom/text`'s `resolveVttSegment`) discards `X-TIMESTAMP-MAP`, so reading it\n * requires the raw bytes. This is a separate, caller-controlled fetch — the caller decides _when_ metadata is needed\n * (e.g. once per source) rather than paying for it on every segment.\n */\nexport async function resolveVttSegmentMetadata(url: string): Promise<TextSegmentMetadata> {\n  const text = await fetch(url).then((response) => response.text());\n\n  return { timestampMap: parseVttTimestampMap(text) };\n}\n"],"mappings":";;;;;;;;;;;;;;AAsBA,eAAsB,0BAA0B,KAA2C;CACzF,MAAM,OAAO,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,aAAa,SAAS,KAAK,CAAC;CAEhE,OAAO,EAAE,cAAc,qBAAqB,IAAI,EAAE;AACpD"}

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../../src/media/types/index.ts"],"mappings":";;;;;;;;;;;;UAgBiB;EACf;;;;;;;EAOA,WAAW;;;;;UAMI;EACf;EACA;IACE;IACA;;;;;;;UAyBa;EACf;EACA;;;;;KAUU;;;;;;;;UAaK;EACf;EACA;;;;;;;;KAaU,kBAAkB,UAAU,QAAQ,SAAS,KAAK,yCAAyC;EACrG;EACA;EACA;EACA;;;;;;;;;;;;KA6BU,QAAQ,MAClB,oBACA;EACE,MAAM;EACN;EACA;EACA;EACA;EACA,iBAAiB;EACjB,UAAU;;;;;;;;;;;;;;;EAeV;;;;;;;;;;;;;EAaA;;;;;;;;;;;;;;;;;;;;UAqBa;EACf;EACA;EACA;EACA;;;;;;;KAQU,cAAc,cAAc,cAAc;;;;KAK1C,aAAa,QACvB,SAAS,KAAK;EACZ;EAGA;EACA;EACA,YAAY;;;;;;;;EAQZ;;;;;KAMQ,aAAa,QACvB,SAAS,KAAK;EACZ;EACA;EACA;EACA;EACA;EACA;EACA;;;;;KAMQ,YAAY;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;KAgBU,gBAAgB;EAC1B;EACA;EACA,WAAW;;;;;;;;;;UAWI;EACf;EACA;EACA;;;;;;KAmBU,6BAA6B,kBAAkB;;;;KAK/C,gBAAgB,aAAa,aAAa;;;;;;;KAoB1C,eAAe,UAAU,QAAQ,SAAS;EACpD,MAAM;EACN,SAAS,kBAAkB,KAAK;;;;;;;;KA8BtB,eAAe,UAAU,QAAQ,SAAS;EACpD,MAAM;EACN,eAAe,eAAe;;;;;KAMpB,oBAAoB,eAAe;;;;KAKnC,oBAAoB,eAAe;;;;KAKnC,mBAAmB,eAAe;;;;;KAMlC,eAAe,oBAAoB,oBAAoB;;;;;;;;;;;;;;KAmBvD,UAAU,MAAM,oBAAoB;EAAa;;;;;;;;;;;;;;UA4B5C;EACf;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;EAmBA;;;;;;;;;;;;;EAaA;;;;;;;;;;;;EAYA;;;iBAOc,yBAAyB,KAAK,KAAK,mBAAmB;;;;;;KAa1D;;;;;;;;KAwCA,eAAe,MACzB,oBACA,QAAQ;EACN,eAAe;;;;;;EAMf,aAAa;;;;;;;;;;;KAYL,4BAA4B,oBAAoB,QAAQ,KAAK,oBAAoB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../../src/media/types/index.ts"],"mappings":";;;;;;;;;;UAciB;EACf;;;;;;EAMA,WAAW;;;UAII;EACf;EACA;IACE;IACA;;;;UAqBa;EACf;EACA;;;KAQU;;;;;;UAWK;EACf;EACA;;;;;;;KAYU,kBAAkB,UAAU,QAAQ,SAAS,KAAK,yCAAyC;EACrG;EACA;EACA;EACA;;;;;;;;;;KA2BU,QAAQ,MAClB,oBACA;EACE,MAAM;EACN;EACA;EACA;EACA;EACA,iBAAiB;EACjB,UAAU;;;;;;;;;;;EAWV;;;;;;;;;;EAUA;;;;;;;;;;;;;;;;UAiBa;EACf;EACA;EACA;EACA;;;;;;;KAQU,cAAc,cAAc,cAAc;;KAG1C,aAAa,QACvB,SAAS,KAAK;EACZ;EAGA;EACA;EACA,YAAY;;;;;;EAMZ;;;KAIQ,aAAa,QACvB,SAAS,KAAK;EACZ;EACA;EACA;EACA;EACA;EACA;EACA;;;KAIQ,YAAY;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;KAYU,gBAAgB;EAC1B;EACA;EACA,WAAW;;;;;;;;;UAUI;EACf;EACA;EACA;;;;;;KAkBU,6BAA6B,kBAAkB;;KAG/C,gBAAgB,aAAa,aAAa;;;;;;KAiB1C,eAAe,UAAU,QAAQ,SAAS;EACpD,MAAM;EACN,SAAS,kBAAkB,KAAK;;;;;;;KAoBtB,eAAe,UAAU,QAAQ,SAAS;EACpD,MAAM;EACN,eAAe,eAAe;;;KAIpB,oBAAoB,eAAe;;KAGnC,oBAAoB,eAAe;;KAGnC,mBAAmB,eAAe;;KAGlC,eAAe,oBAAoB,oBAAoB;;;;;;;;;;KAevD,UAAU,MAAM,oBAAoB;EAAa;;;;;;;;;;;;;UAyB5C;EACf;EACA;EACA;EACA;;;;;;;;;;;;;;EAcA;;;;;;;;;;EAUA;;;;;;;;;EASA;;;iBAOc,yBAAyB,KAAK,KAAK,mBAAmB;;;;;KAY1D;;;;;;;;KAoCA,eAAe,MACzB,oBACA,QAAQ;EACN,eAAe;;;;;EAKf,aAAa;;;;;;;;;;KAWL,4BAA4B,oBAAoB,QAAQ,KAAK,oBAAoB"}