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

package/dist/dev/media/mp4/box.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"box.js","names":[],"sources":["../../../../src/media/mp4/box.ts"],"sourcesContent":["/**\n * Minimal ISO-BMFF (MP4/CMAF) box walker.\n *\n * Just enough to locate boxes by nested path — the framework needs a couple of\n * leaf fields (`mdhd` timescale, `tfdt` baseMediaDecodeTime) to derive a\n * segment's decode-time origin, not a full demuxer. DOM-free: operates on an\n * `ArrayBuffer` / `Uint8Array` via `DataView`.\n *\n * Box layout: `[u32 size][u32 type][payload]`. `size === 1` means a `u64\n * largesize` follows the type (payload after it); `size === 0` means the box\n * runs to the end of its container.\n */\n\n/** A located box: its 4-char type and byte offsets within the buffer. */\nexport interface Box {\n  type: string;\n  /** Offset of the box's first byte (its size field). */\n  start: number;\n  /** Offset of the box's payload — after `size` + `type` (+ `largesize`). */\n  dataStart: number;\n  /** Offset one past the box's last byte. */\n  end: number;\n}\n\nexport function toDataView(data: ArrayBuffer | Uint8Array): DataView {\n  return data instanceof Uint8Array ? new DataView(data.buffer, data.byteOffset, data.byteLength) : new DataView(data);\n}\n\n/** Read a 4-character box type / FourCC at `offset`. */\nexport function readFourCC(view: DataView, offset: number): string {\n  return String.fromCharCode(\n    view.getUint8(offset),\n    view.getUint8(offset + 1),\n    view.getUint8(offset + 2),\n    view.getUint8(offset + 3)\n  );\n}\n\n/** Iterate the boxes directly contained in `[start, end)`. */\nexport function* iterateBoxes(view: DataView, start = 0, end = view.byteLength): Generator<Box> {\n  let offset = start;\n  while (offset + 8 <= end) {\n    let size = view.getUint32(offset);\n    const type = readFourCC(view, offset + 4);\n    let dataStart = offset + 8;\n    if (size === 1) {\n      size = Number(view.getBigUint64(offset + 8));\n      dataStart = offset + 16;\n    } else if (size === 0) {\n      size = end - offset;\n    }\n    // A size smaller than its own header is malformed — stop rather than loop.\n    if (size < dataStart - offset) return;\n    yield { type, start: offset, dataStart, end: offset + size };\n    offset += size;\n  }\n}\n\n/** Iterate the direct child boxes of a given `type` within `[start, end)`. */\nexport function* iterateBoxesOfType(view: DataView, type: string, start = 0, end = view.byteLength): Generator<Box> {\n  for (const box of iterateBoxes(view, start, end)) {\n    if (box.type === type) yield box;\n  }\n}\n\n/**\n * Depth-first descent to the first box matching a nested path, e.g.\n * `['moov', 'trak', 'mdia', 'mdhd']`. Returns `undefined` if any level is\n * absent.\n */\nexport function findBox(view: DataView, path: readonly string[], start = 0, end = view.byteLength): Box | undefined {\n  const [head, ...rest] = path;\n  for (const box of iterateBoxes(view, start, end)) {\n    if (box.type !== head) continue;\n    if (rest.length === 0) return box;\n    const found = findBox(view, rest, box.dataStart, box.end);\n    if (found) return found;\n  }\n  return undefined;\n}\n\n/**\n * Read the version byte of a FullBox — the `version(1) + flags(3)` header at the\n * start of the payload of `mdhd` / `tkhd` / `tfdt` / `hdlr` / `elst` / etc.\n */\nexport function readFullBoxVersion(view: DataView, dataStart: number): number {\n  return view.getUint8(dataStart);\n}\n"],"mappings":";AAwBA,SAAgB,WAAW,MAA0C;CACnE,OAAO,gBAAgB,aAAa,IAAI,SAAS,KAAK,QAAQ,KAAK,YAAY,KAAK,UAAU,IAAI,IAAI,SAAS,IAAI;AACrH;;AAGA,SAAgB,WAAW,MAAgB,QAAwB;CACjE,OAAO,OAAO,aACZ,KAAK,SAAS,MAAM,GACpB,KAAK,SAAS,SAAS,CAAC,GACxB,KAAK,SAAS,SAAS,CAAC,GACxB,KAAK,SAAS,SAAS,CAAC,CAC1B;AACF;;AAGA,UAAiB,aAAa,MAAgB,QAAQ,GAAG,MAAM,KAAK,YAA4B;CAC9F,IAAI,SAAS;CACb,OAAO,SAAS,KAAK,KAAK;EACxB,IAAI,OAAO,KAAK,UAAU,MAAM;EAChC,MAAM,OAAO,WAAW,MAAM,SAAS,CAAC;EACxC,IAAI,YAAY,SAAS;EACzB,IAAI,SAAS,GAAG;GACd,OAAO,OAAO,KAAK,aAAa,SAAS,CAAC,CAAC;GAC3C,YAAY,SAAS;EACvB,OAAO,IAAI,SAAS,GAClB,OAAO,MAAM;EAGf,IAAI,OAAO,YAAY,QAAQ;EAC/B,MAAM;GAAE;GAAM,OAAO;GAAQ;GAAW,KAAK,SAAS;EAAK;EAC3D,UAAU;CACZ;AACF;;AAGA,UAAiB,mBAAmB,MAAgB,MAAc,QAAQ,GAAG,MAAM,KAAK,YAA4B;CAClH,KAAK,MAAM,OAAO,aAAa,MAAM,OAAO,GAAG,GAC7C,IAAI,IAAI,SAAS,MAAM,MAAM;AAEjC;;;;;;AAOA,SAAgB,QAAQ,MAAgB,MAAyB,QAAQ,GAAG,MAAM,KAAK,YAA6B;CAClH,MAAM,CAAC,MAAM,GAAG,QAAQ;CACxB,KAAK,MAAM,OAAO,aAAa,MAAM,OAAO,GAAG,GAAG;EAChD,IAAI,IAAI,SAAS,MAAM;EACvB,IAAI,KAAK,WAAW,GAAG,OAAO;EAC9B,MAAM,QAAQ,QAAQ,MAAM,MAAM,IAAI,WAAW,IAAI,GAAG;EACxD,IAAI,OAAO,OAAO;CACpB;AAEF;;;;;AAMA,SAAgB,mBAAmB,MAAgB,WAA2B;CAC5E,OAAO,KAAK,SAAS,SAAS;AAChC"}

package/dist/dev/media/mp4/timestamp-origin.js

@@ -0,0 +1,107 @@
+import { findBox, iterateBoxesOfType, readFourCC, readFullBoxVersion, toDataView } from "./box.js";
+//#region src/media/mp4/timestamp-origin.ts
+/**
+* Decode-time origin extraction from fMP4/CMAF segments.
+*
+* Non-zero-PTS sources encode media at a non-zero start time (an instant clip
+* starting at asset second 60, an Apple bipbop asset starting at 10s, …). To
+* relocate such a source onto a 0-based presentation timeline via
+* `SourceBuffer.timestampOffset`, the engine needs that start time — the
+* **decode-time origin** — read straight from the container:
+*
+* - `tfdt.baseMediaDecodeTime` (from a media segment's `moof`) — the decode
+*   time of the segment's first sample, in the track's media timescale. This is
+*   a DTS: relocating by `−(baseMediaDecodeTime / timescale)` lands the earliest
+*   DTS at exactly 0, so a negative-DTS append failure on Chromium is impossible
+*   by construction.
+* - `mdhd.timescale` (from the init segment's `moov`) — ticks per second for
+*   that track, needed to convert the raw tick count to seconds.
+*
+* ## Presumptive vs. track-selected reads
+*
+* The two variants share only the leaf field-readers (`mdhd` timescale, `tfdt`
+* baseMediaDecodeTime) and the box walker. Everything else differs, and the
+* split is deliberate so the presumptive pair is *proportionally* smaller under
+* tree-shaking:
+*
+* - **Presumptive** — {@link readFirstMediaTimescale} / {@link readFirstBaseMediaDecodeTime}
+*   read the first `mdhd` timescale and first `tfdt` baseMediaDecodeTime. There's
+*   no `track_id` (nothing to match against) and no `trak`/`traf` iteration — a
+*   direct `findBox` to the first leaf. Correct when the init/segment holds a
+*   single media track (the common CMAF case). A caption-free platform imports
+*   only this pair and tree-shakes away all the matching machinery below.
+* - **Track-selected** — {@link findMediaTrack} / {@link readBaseMediaDecodeTime}.
+*   `findMediaTrack` returns `{ trackId, timescale }` for the `trak` whose `hdlr`
+*   handler matches; `readBaseMediaDecodeTime` takes that `trackId` and reads the
+*   `traf` whose `tfhd.track_id` matches. The `track_id` is the join that ties one
+*   track's timescale to the *same* track's baseMediaDecodeTime — required when a
+*   source muxes CEA-608/708 captions (a `clcp` track shares the same `moov` and
+*   `moof`, each track with its own timescale + baseMediaDecodeTime, so a
+*   presumptive read there risks `300000 / 6000 = 50s` instead of
+*   `60000 / 6000 = 10s`). This pair adds `trak`/`traf` iteration plus the handler
+*   and `track_id` reads. We only ever ask for buffered media handlers
+*   (`vide` / `soun`); the caption track is never selected — we read the origin,
+*   not the captions (caption *rendering* is out of scope).
+*
+* Both raw values are returned un-divided to leave room for an edit-list (`elst`)
+* presentation-time correction term if a source ever carries one — the validated
+* streams do not.
+*/
+/**
+* The `track_ID` + timescale of the `trak` whose `mdhd` handler matches
+* `handlerType`, skipping a muxed `clcp` caption track. `undefined` if no
+* matching track exists.
+*/
+function findMediaTrack(initSegment, handlerType) {
+	const view = toDataView(initSegment);
+	const moov = findBox(view, ["moov"]);
+	if (!moov) return void 0;
+	for (const trak of iterateBoxesOfType(view, "trak", moov.dataStart, moov.end)) {
+		if (readTrakHandler(view, trak) !== handlerType) continue;
+		const tkhd = findBox(view, ["tkhd"], trak.dataStart, trak.end);
+		const mdhd = findBox(view, ["mdia", "mdhd"], trak.dataStart, trak.end);
+		if (!tkhd || !mdhd) return void 0;
+		return {
+			trackId: view.getUint32(tkhd.dataStart + 4 + (readFullBoxVersion(view, tkhd.dataStart) === 1 ? 16 : 8)),
+			timescale: readMdhdTimescale(view, mdhd)
+		};
+	}
+}
+/**
+* `baseMediaDecodeTime` (in the track's media timescale) from the `traf` matching
+* `trackId` (via `tfhd.track_id`) — required for muxed multi-`traf` segments.
+* `undefined` if no matching `tfdt` exists.
+*/
+function readBaseMediaDecodeTime(mediaSegment, trackId) {
+	const view = toDataView(mediaSegment);
+	const moof = findBox(view, ["moof"]);
+	if (!moof) return void 0;
+	for (const traf of iterateBoxesOfType(view, "traf", moof.dataStart, moof.end)) {
+		if (readTrafTrackId(view, traf) !== trackId) continue;
+		const tfdt = findBox(view, ["tfdt"], traf.dataStart, traf.end);
+		return tfdt ? readTfdtBaseMediaDecodeTime(view, tfdt) : void 0;
+	}
+}
+/** `mdhd.timescale`: FullBox version(1)+flags(3) + dates (v0: 4+4, v1: 8+8) + timescale. */
+function readMdhdTimescale(view, mdhd) {
+	return view.getUint32(mdhd.dataStart + 4 + (readFullBoxVersion(view, mdhd.dataStart) === 1 ? 16 : 8));
+}
+/** `tfdt.baseMediaDecodeTime`: FullBox, then the value — v0: (4), v1: (8). */
+function readTfdtBaseMediaDecodeTime(view, tfdt) {
+	const at = tfdt.dataStart + 4;
+	return readFullBoxVersion(view, tfdt.dataStart) === 1 ? Number(view.getBigUint64(at)) : view.getUint32(at);
+}
+/** `hdlr.handler_type` for a `trak`: FullBox version(1)+flags(3) + pre_defined(4) + handler_type(4). */
+function readTrakHandler(view, trak) {
+	const hdlr = findBox(view, ["mdia", "hdlr"], trak.dataStart, trak.end);
+	return hdlr ? readFourCC(view, hdlr.dataStart + 8) : void 0;
+}
+/** `tfhd.track_id` for a `traf`: FullBox version(1)+flags(3) + track_id(4). */
+function readTrafTrackId(view, traf) {
+	const tfhd = findBox(view, ["tfhd"], traf.dataStart, traf.end);
+	return tfhd ? view.getUint32(tfhd.dataStart + 4) : void 0;
+}
+//#endregion
+export { findMediaTrack, readBaseMediaDecodeTime };
+
+//# sourceMappingURL=timestamp-origin.js.map

package/dist/dev/media/mp4/timestamp-origin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp-origin.js","names":[],"sources":["../../../../src/media/mp4/timestamp-origin.ts"],"sourcesContent":["/**\n * Decode-time origin extraction from fMP4/CMAF segments.\n *\n * Non-zero-PTS sources encode media at a non-zero start time (an instant clip\n * starting at asset second 60, an Apple bipbop asset starting at 10s, …). To\n * relocate such a source onto a 0-based presentation timeline via\n * `SourceBuffer.timestampOffset`, the engine needs that start time — the\n * **decode-time origin** — read straight from the container:\n *\n * - `tfdt.baseMediaDecodeTime` (from a media segment's `moof`) — the decode\n *   time of the segment's first sample, in the track's media timescale. This is\n *   a DTS: relocating by `−(baseMediaDecodeTime / timescale)` lands the earliest\n *   DTS at exactly 0, so a negative-DTS append failure on Chromium is impossible\n *   by construction.\n * - `mdhd.timescale` (from the init segment's `moov`) — ticks per second for\n *   that track, needed to convert the raw tick count to seconds.\n *\n * ## Presumptive vs. track-selected reads\n *\n * The two variants share only the leaf field-readers (`mdhd` timescale, `tfdt`\n * baseMediaDecodeTime) and the box walker. Everything else differs, and the\n * split is deliberate so the presumptive pair is *proportionally* smaller under\n * tree-shaking:\n *\n * - **Presumptive** — {@link readFirstMediaTimescale} / {@link readFirstBaseMediaDecodeTime}\n *   read the first `mdhd` timescale and first `tfdt` baseMediaDecodeTime. There's\n *   no `track_id` (nothing to match against) and no `trak`/`traf` iteration — a\n *   direct `findBox` to the first leaf. Correct when the init/segment holds a\n *   single media track (the common CMAF case). A caption-free platform imports\n *   only this pair and tree-shakes away all the matching machinery below.\n * - **Track-selected** — {@link findMediaTrack} / {@link readBaseMediaDecodeTime}.\n *   `findMediaTrack` returns `{ trackId, timescale }` for the `trak` whose `hdlr`\n *   handler matches; `readBaseMediaDecodeTime` takes that `trackId` and reads the\n *   `traf` whose `tfhd.track_id` matches. The `track_id` is the join that ties one\n *   track's timescale to the *same* track's baseMediaDecodeTime — required when a\n *   source muxes CEA-608/708 captions (a `clcp` track shares the same `moov` and\n *   `moof`, each track with its own timescale + baseMediaDecodeTime, so a\n *   presumptive read there risks `300000 / 6000 = 50s` instead of\n *   `60000 / 6000 = 10s`). This pair adds `trak`/`traf` iteration plus the handler\n *   and `track_id` reads. We only ever ask for buffered media handlers\n *   (`vide` / `soun`); the caption track is never selected — we read the origin,\n *   not the captions (caption *rendering* is out of scope).\n *\n * Both raw values are returned un-divided to leave room for an edit-list (`elst`)\n * presentation-time correction term if a source ever carries one — the validated\n * streams do not.\n */\nimport { type Box, findBox, iterateBoxesOfType, readFourCC, readFullBoxVersion, toDataView } from './box';\n\n/** MSE-buffered media handler types (`mdhd`/`hdlr`). Captions/subtitles excluded. */\nexport type MediaHandlerType = 'vide' | 'soun';\n\nexport interface MediaTrackInfo {\n  /** `tkhd.track_id` — used to match the corresponding `traf` in media segments. */\n  trackId: number;\n  /** `mdhd.timescale` — ticks per second for this track. */\n  timescale: number;\n}\n\n// --- presumptive: first leaf, no track_id, no iteration -----------------------\n\n/**\n * Presumptive: the `timescale` of the **first** `mdhd` in an init segment.\n * Correct only for single-media-track inits — for muxed captions use\n * {@link findMediaTrack}. `undefined` if no `mdhd` exists.\n */\nexport function readFirstMediaTimescale(initSegment: ArrayBuffer | Uint8Array): number | undefined {\n  const view = toDataView(initSegment);\n  const mdhd = findBox(view, ['moov', 'trak', 'mdia', 'mdhd']);\n  return mdhd ? readMdhdTimescale(view, mdhd) : undefined;\n}\n\n/**\n * Presumptive: `baseMediaDecodeTime` from the **first** `tfdt` of a media\n * segment. Correct only for single-`traf` segments — for muxed captions use\n * {@link readBaseMediaDecodeTime}. `undefined` if no `tfdt` exists.\n */\nexport function readFirstBaseMediaDecodeTime(mediaSegment: ArrayBuffer | Uint8Array): number | undefined {\n  const view = toDataView(mediaSegment);\n  const tfdt = findBox(view, ['moof', 'traf', 'tfdt']);\n  return tfdt ? readTfdtBaseMediaDecodeTime(view, tfdt) : undefined;\n}\n\n// --- track-selected: iterate + match by handler / track_id --------------------\n\n/**\n * The `track_ID` + timescale of the `trak` whose `mdhd` handler matches\n * `handlerType`, skipping a muxed `clcp` caption track. `undefined` if no\n * matching track exists.\n */\nexport function findMediaTrack(\n  initSegment: ArrayBuffer | Uint8Array,\n  handlerType: MediaHandlerType\n): MediaTrackInfo | undefined {\n  const view = toDataView(initSegment);\n  const moov = findBox(view, ['moov']);\n  if (!moov) return undefined;\n\n  for (const trak of iterateBoxesOfType(view, 'trak', moov.dataStart, moov.end)) {\n    if (readTrakHandler(view, trak) !== handlerType) continue;\n    const tkhd = findBox(view, ['tkhd'], trak.dataStart, trak.end);\n    const mdhd = findBox(view, ['mdia', 'mdhd'], trak.dataStart, trak.end);\n    if (!tkhd || !mdhd) return undefined;\n    // tkhd FullBox: version(1)+flags(3), creation/modification dates (v0: 4+4, v1:\n    // 8+8), then track_id.\n    const trackId = view.getUint32(tkhd.dataStart + 4 + (readFullBoxVersion(view, tkhd.dataStart) === 1 ? 16 : 8));\n    return { trackId, timescale: readMdhdTimescale(view, mdhd) };\n  }\n  return undefined;\n}\n\n/**\n * `baseMediaDecodeTime` (in the track's media timescale) from the `traf` matching\n * `trackId` (via `tfhd.track_id`) — required for muxed multi-`traf` segments.\n * `undefined` if no matching `tfdt` exists.\n */\nexport function readBaseMediaDecodeTime(mediaSegment: ArrayBuffer | Uint8Array, trackId: number): number | undefined {\n  const view = toDataView(mediaSegment);\n  const moof = findBox(view, ['moof']);\n  if (!moof) return undefined;\n\n  for (const traf of iterateBoxesOfType(view, 'traf', moof.dataStart, moof.end)) {\n    if (readTrafTrackId(view, traf) !== trackId) continue;\n    const tfdt = findBox(view, ['tfdt'], traf.dataStart, traf.end);\n    return tfdt ? readTfdtBaseMediaDecodeTime(view, tfdt) : undefined;\n  }\n  return undefined;\n}\n\n// --- shared leaf field-readers ------------------------------------------------\n\n/** `mdhd.timescale`: FullBox version(1)+flags(3) + dates (v0: 4+4, v1: 8+8) + timescale. */\nfunction readMdhdTimescale(view: DataView, mdhd: Box): number {\n  return view.getUint32(mdhd.dataStart + 4 + (readFullBoxVersion(view, mdhd.dataStart) === 1 ? 16 : 8));\n}\n\n/** `tfdt.baseMediaDecodeTime`: FullBox, then the value — v0: (4), v1: (8). */\nfunction readTfdtBaseMediaDecodeTime(view: DataView, tfdt: Box): number {\n  const at = tfdt.dataStart + 4;\n  return readFullBoxVersion(view, tfdt.dataStart) === 1 ? Number(view.getBigUint64(at)) : view.getUint32(at);\n}\n\n// --- track-selection readers (referenced only by the track-selected variants) -\n\n/** `hdlr.handler_type` for a `trak`: FullBox version(1)+flags(3) + pre_defined(4) + handler_type(4). */\nfunction readTrakHandler(view: DataView, trak: Box): string | undefined {\n  const hdlr = findBox(view, ['mdia', 'hdlr'], trak.dataStart, trak.end);\n  return hdlr ? readFourCC(view, hdlr.dataStart + 8) : undefined;\n}\n\n/** `tfhd.track_id` for a `traf`: FullBox version(1)+flags(3) + track_id(4). */\nfunction readTrafTrackId(view: DataView, traf: Box): number | undefined {\n  const tfhd = findBox(view, ['tfhd'], traf.dataStart, traf.end);\n  return tfhd ? view.getUint32(tfhd.dataStart + 4) : undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0FA,SAAgB,eACd,aACA,aAC4B;CAC5B,MAAM,OAAO,WAAW,WAAW;CACnC,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,CAAC;CACnC,IAAI,CAAC,MAAM,OAAO,KAAA;CAElB,KAAK,MAAM,QAAQ,mBAAmB,MAAM,QAAQ,KAAK,WAAW,KAAK,GAAG,GAAG;EAC7E,IAAI,gBAAgB,MAAM,IAAI,MAAM,aAAa;EACjD,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;EAC7D,MAAM,OAAO,QAAQ,MAAM,CAAC,QAAQ,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;EACrE,IAAI,CAAC,QAAQ,CAAC,MAAM,OAAO,KAAA;EAI3B,OAAO;GAAE,SADO,KAAK,UAAU,KAAK,YAAY,KAAK,mBAAmB,MAAM,KAAK,SAAS,MAAM,IAAI,KAAK,EAC5F;GAAG,WAAW,kBAAkB,MAAM,IAAI;EAAE;CAC7D;AAEF;;;;;;AAOA,SAAgB,wBAAwB,cAAwC,SAAqC;CACnH,MAAM,OAAO,WAAW,YAAY;CACpC,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,CAAC;CACnC,IAAI,CAAC,MAAM,OAAO,KAAA;CAElB,KAAK,MAAM,QAAQ,mBAAmB,MAAM,QAAQ,KAAK,WAAW,KAAK,GAAG,GAAG;EAC7E,IAAI,gBAAgB,MAAM,IAAI,MAAM,SAAS;EAC7C,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;EAC7D,OAAO,OAAO,4BAA4B,MAAM,IAAI,IAAI,KAAA;CAC1D;AAEF;;AAKA,SAAS,kBAAkB,MAAgB,MAAmB;CAC5D,OAAO,KAAK,UAAU,KAAK,YAAY,KAAK,mBAAmB,MAAM,KAAK,SAAS,MAAM,IAAI,KAAK,EAAE;AACtG;;AAGA,SAAS,4BAA4B,MAAgB,MAAmB;CACtE,MAAM,KAAK,KAAK,YAAY;CAC5B,OAAO,mBAAmB,MAAM,KAAK,SAAS,MAAM,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC,IAAI,KAAK,UAAU,EAAE;AAC3G;;AAKA,SAAS,gBAAgB,MAAgB,MAA+B;CACtE,MAAM,OAAO,QAAQ,MAAM,CAAC,QAAQ,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;CACrE,OAAO,OAAO,WAAW,MAAM,KAAK,YAAY,CAAC,IAAI,KAAA;AACvD;;AAGA,SAAS,gBAAgB,MAAgB,MAA+B;CACtE,MAAM,OAAO,QAAQ,MAAM,CAAC,MAAM,GAAG,KAAK,WAAW,KAAK,GAAG;CAC7D,OAAO,OAAO,KAAK,UAAU,KAAK,YAAY,CAAC,IAAI,KAAA;AACrD"}

package/dist/dev/media/primitives/resolution.d.ts

@@ -0,0 +1,24 @@
+//#region src/media/primitives/resolution.d.ts
+/**
+ * Pixel dimensions, and the one projection every reader of them needs.
+ *
+ * Shared by the surfaces a rendition cap measures — a screen (`media/dom/screen`),
+ * a player element (`behaviors/dom/track-player-resolution`) — and by the caps
+ * that compare renditions against them. Lives outside the DOM layer because
+ * scaling and rounding two numbers needs no DOM, which is also what lets the
+ * DOM-free selection rules name the type they read instead of restating its shape.
+ */
+/**
+ * A surface's pixel dimensions.
+ *
+ * A width and a height rather than a `"720p"`-style tier, because a tier only
+ * describes a surface once you assume its aspect ratio — the assumption that
+ * mis-measures an anamorphic or otherwise non-16:9 rendition.
+ */
+interface Resolution {
+  readonly width: number;
+  readonly height: number;
+}
+//#endregion
+export { Resolution };
+//# sourceMappingURL=resolution.d.ts.map

package/dist/dev/media/primitives/resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.d.ts","names":[],"sources":["../../../../src/media/primitives/resolution.ts"],"mappings":";;;;;;;;;;;;;;;;;UAiBiB;WACN;WACA"}

package/dist/dev/media/primitives/resolution.js

@@ -0,0 +1,29 @@
+//#region src/media/primitives/resolution.ts
+/**
+* Apply `scale` to a size and normalize it to whole pixels, or `undefined` where
+* that leaves nothing to describe.
+*
+* Rounded because pixels are whole and a fractional scale doesn't divide a
+* surface evenly. A non-positive or non-finite axis yields `undefined` rather
+* than a zero-area reading: an element that isn't being rendered reports `0 × 0`
+* and a nonsense dimension reports `NaN`, and the caps consuming this read
+* absence as "unknown, don't cap" while an area of zero would read as a cap of
+* zero — pinning every source to its smallest rendition.
+*
+* @param size - Dimensions to project, in the units `scale` converts from
+* @param scale - Multiplier for both axes, e.g. `devicePixelRatio`; defaults to 1
+* @returns The scaled, whole-pixel resolution, or `undefined` when either axis
+* doesn't survive it
+*/
+function scaleResolution(size, scale = 1) {
+	const width = Math.round(size.width * scale);
+	const height = Math.round(size.height * scale);
+	return width > 0 && height > 0 ? {
+		width,
+		height
+	} : void 0;
+}
+//#endregion
+export { scaleResolution };
+
+//# sourceMappingURL=resolution.js.map

package/dist/dev/media/primitives/resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.js","names":[],"sources":["../../../../src/media/primitives/resolution.ts"],"sourcesContent":["/**\n * Pixel dimensions, and the one projection every reader of them needs.\n *\n * Shared by the surfaces a rendition cap measures — a screen (`media/dom/screen`),\n * a player element (`behaviors/dom/track-player-resolution`) — and by the caps\n * that compare renditions against them. Lives outside the DOM layer because\n * scaling and rounding two numbers needs no DOM, which is also what lets the\n * DOM-free selection rules name the type they read instead of restating its shape.\n */\n\n/**\n * A surface's pixel dimensions.\n *\n * A width and a height rather than a `\"720p\"`-style tier, because a tier only\n * describes a surface once you assume its aspect ratio — the assumption that\n * mis-measures an anamorphic or otherwise non-16:9 rendition.\n */\nexport interface Resolution {\n  readonly width: number;\n  readonly height: number;\n}\n\n/**\n * Apply `scale` to a size and normalize it to whole pixels, or `undefined` where\n * that leaves nothing to describe.\n *\n * Rounded because pixels are whole and a fractional scale doesn't divide a\n * surface evenly. A non-positive or non-finite axis yields `undefined` rather\n * than a zero-area reading: an element that isn't being rendered reports `0 × 0`\n * and a nonsense dimension reports `NaN`, and the caps consuming this read\n * absence as \"unknown, don't cap\" while an area of zero would read as a cap of\n * zero — pinning every source to its smallest rendition.\n *\n * @param size - Dimensions to project, in the units `scale` converts from\n * @param scale - Multiplier for both axes, e.g. `devicePixelRatio`; defaults to 1\n * @returns The scaled, whole-pixel resolution, or `undefined` when either axis\n * doesn't survive it\n */\nexport function scaleResolution(size: Resolution, scale = 1): Resolution | undefined {\n  const width = Math.round(size.width * scale);\n  const height = Math.round(size.height * scale);\n\n  return width > 0 && height > 0 ? { width, height } : undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAsCA,SAAgB,gBAAgB,MAAkB,QAAQ,GAA2B;CACnF,MAAM,QAAQ,KAAK,MAAM,KAAK,QAAQ,KAAK;CAC3C,MAAM,SAAS,KAAK,MAAM,KAAK,SAAS,KAAK;CAE7C,OAAO,QAAQ,KAAK,SAAS,IAAI;EAAE;EAAO;CAAO,IAAI,KAAA;AACvD"}

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

@@ -0,0 +1,107 @@
+//#region src/media/primitives/select-tracks.ts
+/**
+* Test whether a track matches a partial-track description: every present,
+* defined field of `filter` equals the track's. Absent or `undefined` filter
+* fields don't constrain. Used to narrow candidates by a user selection
+* (`{ id }`, `{ language }`, `{ height }`, …).
+*
+* @param track - The track to test
+* @param filter - Partial-track description; only present, defined fields constrain
+* @returns `true` when the track matches every constraining field
+*/
+function matchesPartialTrack(track, filter) {
+	for (const key in filter) {
+		const filterValue = filter[key];
+		if (filterValue !== void 0 && track[key] !== filterValue) return false;
+	}
+	return true;
+}
+/** Missing dimensions are treated as area `0`, so a track without them ranks last. */
+function pixelArea(track) {
+	return (track.width ?? 0) * (track.height ?? 0);
+}
+/**
+* Narrow to the tracks at or below `maxPixelArea`, and nothing else: no ordering,
+* no fallback. Survivors keep their incoming order, and an empty result is a real
+* answer — "none of these fit".
+*
+* Deliberately only the filter, because as a selection rule this composes under
+* `applyRules`, which already owns both halves a caller might expect here: an empty
+* result is skipped, so a preference can never narrow the candidate set to nothing;
+* and ordering the survivors is a separate rule's job
+* ({@link byDescendingResolution}, bandwidth ABR). Doing either here would duplicate
+* the composer and give one rule two responsibilities.
+*/
+function tracksUnderPixelArea(tracks, maxPixelArea = Number.POSITIVE_INFINITY) {
+	return tracks.filter((track) => pixelArea(track) <= maxPixelArea);
+}
+/**
+* The smallest track area that still covers `minPixelArea`, or `undefined` when
+* no track reaches it.
+*
+* The cap a surface-size rule wants when it should round *up* to the ladder: a
+* surface between two tiers is covered by the upper one, and capping at the
+* surface's own area instead would serve a picture smaller than the surface and
+* upscale it.
+*
+* Tracks declaring no dimensions compare as area `0` and so never cover anything,
+* which keeps them out of the cap rather than pinning it to zero.
+*/
+function smallestCoveringPixelArea(tracks, minPixelArea) {
+	const covering = tracks.map(pixelArea).filter((area) => area >= minPixelArea);
+	return covering.length ? Math.min(...covering) : void 0;
+}
+/**
+* Compare two tracks by resolution, largest first, with bandwidth as the tiebreak
+* for renditions of identical dimensions. Missing dimensions are treated as area
+* `0`, so a track without them sorts last.
+*
+* A comparator rather than a "highest track" function: the selection-rule chain
+* takes the head of the list it produces, so ranking never has to collapse to a
+* single track. `preferHighestResolution` is `sort` over this and nothing more.
+*/
+function byDescendingResolution(a, b) {
+	return pixelArea(b) - pixelArea(a) || (b.bandwidth ?? 0) - (a.bandwidth ?? 0);
+}
+/**
+* Default audio policy over a candidate list: the three-tier pick a selection-rule
+* chain applies once it has narrowed the candidates.
+*
+* Priority: `preferredAudioLanguage` match → `DEFAULT=YES` → first track.
+*/
+function pickAudioTrackFromTracks(tracks, config) {
+	if (config?.preferredAudioLanguage) {
+		const languageMatch = tracks.find((track) => track.language === config.preferredAudioLanguage);
+		if (languageMatch) return languageMatch.id;
+	}
+	const defaultTrack = tracks.find((track) => track.default === true);
+	if (defaultTrack) return defaultTrack.id;
+	return tracks[0]?.id;
+}
+/**
+* Default text-track policy over a candidate list: the opt-in three-tier pick
+* `switchTextTrack`'s terminal applies once it has narrowed the renditions to the
+* constrained, CDN-scoped set.
+*
+* Priority: `preferredSubtitleLanguage` match → `DEFAULT=YES + AUTOSELECT=YES`
+* (only when `enableDefaultTrack`) → `undefined` (opt-in). FORCED tracks are
+* excluded unless `includeForcedTracks` (Apple-spec: a regular track must carry
+* forced content when both exist, so a forced-only track is redundant).
+*/
+function pickTextTrackFromTracks(tracks, config) {
+	const availableTracks = config?.includeForcedTracks ? tracks : tracks.filter((track) => !track.forced);
+	if (availableTracks.length === 0) return void 0;
+	const { preferredSubtitleLanguage, enableDefaultTrack = false } = config ?? {};
+	if (preferredSubtitleLanguage) {
+		const languageMatch = availableTracks.find((track) => track.language === preferredSubtitleLanguage);
+		if (languageMatch) return languageMatch.id;
+	}
+	if (enableDefaultTrack) {
+		const defaultTrack = availableTracks.find((track) => track.default === true);
+		if (defaultTrack) return defaultTrack.id;
+	}
+}
+//#endregion
+export { byDescendingResolution, matchesPartialTrack, pickAudioTrackFromTracks, pickTextTrackFromTracks, smallestCoveringPixelArea, tracksUnderPixelArea };
+
+//# sourceMappingURL=select-tracks.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,42 @@
+//#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.
+*
+* 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));
+	return timestampMapLine ? parseTimestampMapBody(timestampMapLine.slice(16)) : void 0;
+}
+const TimeStampMapParserMap = {
+	LOCAL: parseWebVttTimestamp,
+	MPEGTS: (v) => +v
+};
+function parseTimestampMapBody(body) {
+	return Object.fromEntries(body.split(",").map((kvStr) => {
+		const [k, v] = kvStr.split(/:(.*)/).map((kOrV) => kOrV.trim());
+		return [k?.toLowerCase(), TimeStampMapParserMap[k](v)];
+	}));
+}
+/** Seconds-per-unit for the `[HH:]MM:SS.mmm` parts, right-aligned so a missing HH just drops the leading weight. */
+const VTT_TIMESTAMP_WEIGHTS = [
+	3600,
+	60,
+	1,
+	.001
+];
+function parseWebVttTimestamp(value) {
+	const parts = value.split(/[:.]/);
+	return parts.reduce((acc, val, i) => acc + +val * (VTT_TIMESTAMP_WEIGHTS[i + 4 - parts.length] ?? 0), 0);
+}
+//#endregion
+export { parseVttTimestampMap };
+
+//# sourceMappingURL=parse-vtt-timestamp-map.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,23 @@
+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.
+*/
+/**
+* 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.
+*/
+async function resolveVttSegmentMetadata(url) {
+	return { timestampMap: parseVttTimestampMap(await fetch(url).then((response) => response.text())) };
+}
+//#endregion
+export { resolveVttSegmentMetadata };
+
+//# sourceMappingURL=resolve-vtt-metadata.js.map

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

@@ -0,0 +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"}