@blockcast/mmt-container 0.1.0-main.0399efef1f07

package/src/iso-bmff-timing.ts

@@ -0,0 +1,813 @@
+/**
+ * Strict ISO-BMFF timing extraction for the timed-MFU browser path.
+ *
+ * This intentionally implements only the current single-track MMT profile:
+ * one media track in FT=0, and one matching traf/trun in each FT=1.  It does
+ * not infer timing from packet arrival, MMTP send timestamps, or cadence.
+ */
+
+const U64_MAX = 0xffff_ffff_ffff_ffffn
+const I64_MIN = -0x8000_0000_0000_0000n
+const I64_MAX = 0x7fff_ffff_ffff_ffffn
+const MICROSECONDS_PER_SECOND = 1_000_000n
+
+const TFHD_BASE_DATA_OFFSET_PRESENT = 0x000001
+const TFHD_SAMPLE_DESCRIPTION_INDEX_PRESENT = 0x000002
+const TFHD_DEFAULT_SAMPLE_DURATION_PRESENT = 0x000008
+const TFHD_DEFAULT_SAMPLE_SIZE_PRESENT = 0x000010
+const TFHD_DEFAULT_SAMPLE_FLAGS_PRESENT = 0x000020
+const TFHD_DURATION_IS_EMPTY = 0x010000
+const TFHD_DEFAULT_BASE_IS_MOOF = 0x020000
+const TFHD_KNOWN_FLAGS =
+  TFHD_BASE_DATA_OFFSET_PRESENT |
+  TFHD_SAMPLE_DESCRIPTION_INDEX_PRESENT |
+  TFHD_DEFAULT_SAMPLE_DURATION_PRESENT |
+  TFHD_DEFAULT_SAMPLE_SIZE_PRESENT |
+  TFHD_DEFAULT_SAMPLE_FLAGS_PRESENT |
+  TFHD_DURATION_IS_EMPTY |
+  TFHD_DEFAULT_BASE_IS_MOOF
+
+const TRUN_DATA_OFFSET_PRESENT = 0x000001
+const TRUN_FIRST_SAMPLE_FLAGS_PRESENT = 0x000004
+const TRUN_SAMPLE_DURATION_PRESENT = 0x000100
+const TRUN_SAMPLE_SIZE_PRESENT = 0x000200
+const TRUN_SAMPLE_FLAGS_PRESENT = 0x000400
+const TRUN_SAMPLE_CTS_OFFSET_PRESENT = 0x000800
+const TRUN_KNOWN_FLAGS =
+  TRUN_DATA_OFFSET_PRESENT |
+  TRUN_FIRST_SAMPLE_FLAGS_PRESENT |
+  TRUN_SAMPLE_DURATION_PRESENT |
+  TRUN_SAMPLE_SIZE_PRESENT |
+  TRUN_SAMPLE_FLAGS_PRESENT |
+  TRUN_SAMPLE_CTS_OFFSET_PRESENT
+
+export interface IsoBmffTrackTiming {
+  trackId: number
+  timescale: number
+  defaultSampleDuration?: number
+  defaultSampleSize?: number
+}
+
+export interface IsoBmffSampleTiming {
+  /** Exact decode time in mdhd timescale units. */
+  decodeTime: bigint
+  /** Exact presentation time in mdhd timescale units, including signed CTS. */
+  presentationTime: bigint
+  /** Exact authored duration in mdhd timescale units. */
+  duration: number
+  timescale: number
+  /** Exact elementary-stream sample size declared by trun/tfhd/trex. */
+  size: number
+  /** Byte position of the sample relative to the beginning of the moof. */
+  bytePosition: bigint
+}
+
+export interface IsoBmffMovieFragmentTiming {
+  movieFragmentSequenceNumber: number
+  samples: readonly IsoBmffSampleTiming[]
+}
+
+export type IsoBmffMovieFragmentRejection = 'invalid' | 'budget'
+
+interface IsoBox {
+  type: string
+  start: number
+  bodyStart: number
+  end: number
+}
+
+interface FullBox {
+  version: number
+  flags: number
+  bodyStart: number
+}
+
+interface ParsedTrack {
+  trackId: number
+  handlerType: string
+  timescale: number
+  hasEdits: boolean
+}
+
+interface ParsedTfhd {
+  trackId: number
+  defaultSampleDuration?: number
+  defaultSampleSize?: number
+}
+
+interface MdatLayout {
+  dataStart: bigint
+  declaredEnd: bigint
+}
+
+function view(data: Uint8Array): DataView {
+  return new DataView(data.buffer, data.byteOffset, data.byteLength)
+}
+
+function boxType(data: Uint8Array, offset: number): string {
+  return String.fromCharCode(
+    data[offset]!,
+    data[offset + 1]!,
+    data[offset + 2]!,
+    data[offset + 3]!,
+  )
+}
+
+function readU64(data: Uint8Array, offset: number): bigint | null {
+  if (offset < 0 || offset + 8 > data.length) return null
+  const dataView = view(data)
+  return (BigInt(dataView.getUint32(offset, false)) << 32n) |
+    BigInt(dataView.getUint32(offset + 4, false))
+}
+
+function parseBox(data: Uint8Array, start: number, limit: number): IsoBox | null {
+  if (start < 0 || limit > data.length || start + 8 > limit) return null
+  const dataView = view(data)
+  const shortSize = dataView.getUint32(start, false)
+  let headerSize = 8
+  let size: number
+  if (shortSize === 0) {
+    size = limit - start
+  } else if (shortSize === 1) {
+    if (start + 16 > limit) return null
+    const extendedSize = readU64(data, start + 8)
+    if (extendedSize === null || extendedSize > BigInt(Number.MAX_SAFE_INTEGER)) return null
+    headerSize = 16
+    size = Number(extendedSize)
+  } else {
+    size = shortSize
+  }
+  if (size < headerSize || start + size > limit) return null
+  return {
+    type: boxType(data, start + 4),
+    start,
+    bodyStart: start + headerSize,
+    end: start + size,
+  }
+}
+
+function parseBoxes(data: Uint8Array, start: number, end: number): IsoBox[] | null {
+  if (start < 0 || end < start || end > data.length) return null
+  const boxes: IsoBox[] = []
+  let offset = start
+  while (offset < end) {
+    const box = parseBox(data, offset, end)
+    if (!box || box.end <= offset) return null
+    boxes.push(box)
+    offset = box.end
+  }
+  return offset === end ? boxes : null
+}
+
+function children(data: Uint8Array, parent: IsoBox): IsoBox[] | null {
+  return parseBoxes(data, parent.bodyStart, parent.end)
+}
+
+function exactlyOne(boxes: readonly IsoBox[], type: string): IsoBox | null {
+  const matches = boxes.filter(box => box.type === type)
+  return matches.length === 1 ? matches[0]! : null
+}
+
+function parseFullBox(data: Uint8Array, box: IsoBox): FullBox | null {
+  if (box.bodyStart + 4 > box.end) return null
+  const versionAndFlags = view(data).getUint32(box.bodyStart, false)
+  return {
+    version: versionAndFlags >>> 24,
+    flags: versionAndFlags & 0x00ff_ffff,
+    bodyStart: box.bodyStart + 4,
+  }
+}
+
+function parseTkhdTrackId(data: Uint8Array, box: IsoBox): number | null {
+  const full = parseFullBox(data, box)
+  if (!full || full.flags & ~0x00000f) return null
+  const bodyLength = box.end - full.bodyStart
+  const trackIdOffset = full.version === 0
+    ? full.bodyStart + 8
+    : full.version === 1
+      ? full.bodyStart + 16
+      : -1
+  const expectedBodyLength = full.version === 0 ? 80 : full.version === 1 ? 92 : -1
+  if (trackIdOffset < 0 || bodyLength !== expectedBodyLength) return null
+  return view(data).getUint32(trackIdOffset, false)
+}
+
+function parseMdhdTimescale(data: Uint8Array, box: IsoBox): number | null {
+  const full = parseFullBox(data, box)
+  if (!full || full.flags !== 0) return null
+  const bodyLength = box.end - full.bodyStart
+  const timescaleOffset = full.version === 0
+    ? full.bodyStart + 8
+    : full.version === 1
+      ? full.bodyStart + 16
+      : -1
+  const expectedBodyLength = full.version === 0 ? 20 : full.version === 1 ? 32 : -1
+  if (timescaleOffset < 0 || bodyLength !== expectedBodyLength) return null
+  return view(data).getUint32(timescaleOffset, false)
+}
+
+function parseHandlerType(data: Uint8Array, box: IsoBox): string | null {
+  const full = parseFullBox(data, box)
+  if (!full || full.version !== 0 || full.flags !== 0 || full.bodyStart + 20 > box.end) {
+    return null
+  }
+  return boxType(data, full.bodyStart + 4)
+}
+
+function editListHasEntries(data: Uint8Array, box: IsoBox): boolean | null {
+  const full = parseFullBox(data, box)
+  if (!full || full.flags !== 0 || (full.version !== 0 && full.version !== 1)) return null
+  if (full.bodyStart + 4 > box.end) return null
+  const entryCount = view(data).getUint32(full.bodyStart, false)
+  const entrySize = full.version === 0 ? 12 : 20
+  const expectedEnd = full.bodyStart + 4 + entryCount * entrySize
+  if (!Number.isSafeInteger(expectedEnd) || expectedEnd !== box.end) return null
+  return entryCount !== 0
+}
+
+function parseTrack(data: Uint8Array, trak: IsoBox): ParsedTrack | null {
+  const trakChildren = children(data, trak)
+  if (!trakChildren) return null
+  const tkhd = exactlyOne(trakChildren, 'tkhd')
+  const mdia = exactlyOne(trakChildren, 'mdia')
+  if (!tkhd || !mdia) return null
+  const trackId = parseTkhdTrackId(data, tkhd)
+  if (trackId === null || trackId === 0) return null
+
+  const mdiaChildren = children(data, mdia)
+  if (!mdiaChildren) return null
+  const mdhd = exactlyOne(mdiaChildren, 'mdhd')
+  const hdlr = exactlyOne(mdiaChildren, 'hdlr')
+  if (!mdhd || !hdlr) return null
+  const timescale = parseMdhdTimescale(data, mdhd)
+  const handlerType = parseHandlerType(data, hdlr)
+  if (timescale === null || timescale === 0 || handlerType === null) return null
+
+  const edtsBoxes = trakChildren.filter(box => box.type === 'edts')
+  if (edtsBoxes.length > 1) return null
+  let hasEdits = false
+  if (edtsBoxes.length === 1) {
+    const edtsChildren = children(data, edtsBoxes[0]!)
+    if (!edtsChildren) return null
+    const editLists = edtsChildren.filter(box => box.type === 'elst')
+    if (editLists.length > 1) return null
+    if (editLists.length === 1) {
+      const result = editListHasEntries(data, editLists[0]!)
+      if (result === null) return null
+      hasEdits = result
+    }
+  }
+
+  return { trackId, handlerType, timescale, hasEdits }
+}
+
+function parseTrex(data: Uint8Array, box: IsoBox): IsoBmffTrackTiming | null {
+  const full = parseFullBox(data, box)
+  if (!full || full.version !== 0 || full.flags !== 0 || box.end - full.bodyStart !== 20) {
+    return null
+  }
+  const dataView = view(data)
+  const trackId = dataView.getUint32(full.bodyStart, false)
+  const defaultSampleDuration = dataView.getUint32(full.bodyStart + 8, false)
+  const defaultSampleSize = dataView.getUint32(full.bodyStart + 12, false)
+  return {
+    trackId,
+    timescale: 0,
+    ...(defaultSampleDuration === 0 ? {} : { defaultSampleDuration }),
+    ...(defaultSampleSize === 0 ? {} : { defaultSampleSize }),
+  }
+}
+
+export function parseIsoBmffInitializationTiming(
+  data: Uint8Array,
+): IsoBmffTrackTiming | null {
+  const topLevel = parseBoxes(data, 0, data.length)
+  if (!topLevel) return null
+  const ftyp = exactlyOne(topLevel, 'ftyp')
+  const moov = exactlyOne(topLevel, 'moov')
+  if (!ftyp || !moov || ftyp.start > moov.start) return null
+  if (topLevel.some(box => box.type === 'moof' || box.type === 'mdat')) return null
+
+  const moovChildren = children(data, moov)
+  if (!moovChildren) return null
+  const parsedTracks: ParsedTrack[] = []
+  for (const trak of moovChildren.filter(box => box.type === 'trak')) {
+    const parsed = parseTrack(data, trak)
+    if (!parsed) return null
+    parsedTracks.push(parsed)
+  }
+  const mediaTracks = parsedTracks.filter(
+    track => track.handlerType === 'vide' || track.handlerType === 'soun',
+  )
+  if (mediaTracks.length !== 1) return null
+  const mediaTrack = mediaTracks[0]!
+  if (mediaTrack.hasEdits) return null
+
+  const mvex = exactlyOne(moovChildren, 'mvex')
+  if (!mvex) return null
+  const mvexChildren = children(data, mvex)
+  if (!mvexChildren) return null
+  const trexEntries: IsoBmffTrackTiming[] = []
+  for (const trexBox of mvexChildren.filter(box => box.type === 'trex')) {
+    const trex = parseTrex(data, trexBox)
+    if (!trex) return null
+    trexEntries.push(trex)
+  }
+  const matchingTrex = trexEntries.filter(trex => trex.trackId === mediaTrack.trackId)
+  if (matchingTrex.length !== 1) return null
+  const trex = matchingTrex[0]!
+  return {
+    trackId: mediaTrack.trackId,
+    timescale: mediaTrack.timescale,
+    ...(trex.defaultSampleDuration === undefined
+      ? {}
+      : { defaultSampleDuration: trex.defaultSampleDuration }),
+    ...(trex.defaultSampleSize === undefined
+      ? {}
+      : { defaultSampleSize: trex.defaultSampleSize }),
+  }
+}
+
+function parseMfhdSequence(data: Uint8Array, box: IsoBox): number | null {
+  const full = parseFullBox(data, box)
+  if (!full || full.version !== 0 || full.flags !== 0 || box.end - full.bodyStart !== 4) {
+    return null
+  }
+  return view(data).getUint32(full.bodyStart, false)
+}
+
+function parseTfhd(data: Uint8Array, box: IsoBox): ParsedTfhd | null {
+  const full = parseFullBox(data, box)
+  if (!full || full.version !== 0 || (full.flags & ~TFHD_KNOWN_FLAGS) !== 0) return null
+  if ((full.flags & TFHD_BASE_DATA_OFFSET_PRESENT) !== 0 ||
+      (full.flags & TFHD_DEFAULT_BASE_IS_MOOF) === 0 ||
+      (full.flags & TFHD_DURATION_IS_EMPTY) !== 0) {
+    return null
+  }
+  const dataView = view(data)
+  let offset = full.bodyStart
+  if (offset + 4 > box.end) return null
+  const trackId = dataView.getUint32(offset, false)
+  offset += 4
+  if ((full.flags & TFHD_SAMPLE_DESCRIPTION_INDEX_PRESENT) !== 0) {
+    if (offset + 4 > box.end) return null
+    offset += 4
+  }
+  let defaultSampleDuration: number | undefined
+  if ((full.flags & TFHD_DEFAULT_SAMPLE_DURATION_PRESENT) !== 0) {
+    if (offset + 4 > box.end) return null
+    defaultSampleDuration = dataView.getUint32(offset, false)
+    offset += 4
+  }
+  let defaultSampleSize: number | undefined
+  if ((full.flags & TFHD_DEFAULT_SAMPLE_SIZE_PRESENT) !== 0) {
+    if (offset + 4 > box.end) return null
+    defaultSampleSize = dataView.getUint32(offset, false)
+    offset += 4
+  }
+  if ((full.flags & TFHD_DEFAULT_SAMPLE_FLAGS_PRESENT) !== 0) {
+    if (offset + 4 > box.end) return null
+    offset += 4
+  }
+  if (offset !== box.end) return null
+  return {
+    trackId,
+    ...(defaultSampleDuration === undefined ? {} : { defaultSampleDuration }),
+    ...(defaultSampleSize === undefined ? {} : { defaultSampleSize }),
+  }
+}
+
+function parseTfdt(data: Uint8Array, box: IsoBox): bigint | null {
+  const full = parseFullBox(data, box)
+  if (!full || full.flags !== 0) return null
+  if (full.version === 0 && box.end - full.bodyStart === 4) {
+    return BigInt(view(data).getUint32(full.bodyStart, false))
+  }
+  if (full.version === 1 && box.end - full.bodyStart === 8) {
+    return readU64(data, full.bodyStart)
+  }
+  return null
+}
+
+function parseMdatLayout(data: Uint8Array, offset: number): MdatLayout | null {
+  if (offset < 0 || offset + 8 > data.length || boxType(data, offset + 4) !== 'mdat') return null
+  const dataView = view(data)
+  const shortSize = dataView.getUint32(offset, false)
+  let headerSize = 8
+  let declaredSize: bigint
+  if (shortSize === 0) {
+    return null
+  } else if (shortSize === 1) {
+    const extended = readU64(data, offset + 8)
+    if (extended === null) return null
+    headerSize = 16
+    declaredSize = extended
+  } else {
+    declaredSize = BigInt(shortSize)
+  }
+  if (declaredSize < BigInt(headerSize) || declaredSize < BigInt(data.length - offset)) {
+    return null
+  }
+  const declaredEnd = BigInt(offset) + declaredSize
+  if (declaredEnd > U64_MAX) return null
+  return { dataStart: BigInt(offset + headerSize), declaredEnd }
+}
+
+function resolvedDefault(
+  entryValue: number | undefined,
+  tfhdValue: number | undefined,
+  trexValue: number | undefined,
+): number | null {
+  const value = entryValue ?? tfhdValue ?? trexValue
+  return value === undefined || value === 0 ? null : value
+}
+
+function parseTrunSamples(
+  data: Uint8Array,
+  box: IsoBox,
+  moofStart: number,
+  baseDecodeTime: bigint,
+  tfhd: ParsedTfhd,
+  track: IsoBmffTrackTiming,
+  mdat: MdatLayout,
+  maxSamples: number,
+): IsoBmffSampleTiming[] | null {
+  const full = parseFullBox(data, box)
+  if (!full || (full.version !== 0 && full.version !== 1) ||
+      (full.flags & ~TRUN_KNOWN_FLAGS) !== 0 ||
+      (full.flags & TRUN_DATA_OFFSET_PRESENT) === 0 ||
+      ((full.flags & TRUN_FIRST_SAMPLE_FLAGS_PRESENT) !== 0 &&
+        (full.flags & TRUN_SAMPLE_FLAGS_PRESENT) !== 0)) {
+    return null
+  }
+  const dataView = view(data)
+  let offset = full.bodyStart
+  if (offset + 8 > box.end) return null
+  const sampleCount = dataView.getUint32(offset, false)
+  offset += 4
+  if (sampleCount === 0 || sampleCount > maxSamples) return null
+  const relativeDataOffset = dataView.getInt32(offset, false)
+  offset += 4
+  if (relativeDataOffset < 0) return null
+  const dataOffset = BigInt(relativeDataOffset)
+  const absoluteDataOffset = BigInt(moofStart) + dataOffset
+  if (absoluteDataOffset > BigInt(data.length) || absoluteDataOffset < mdat.dataStart) return null
+  if ((full.flags & TRUN_FIRST_SAMPLE_FLAGS_PRESENT) !== 0) {
+    if (offset + 4 > box.end) return null
+    offset += 4
+  }
+
+  let decodeTime = baseDecodeTime
+  let bytePosition = dataOffset
+  const samples: IsoBmffSampleTiming[] = []
+  for (let index = 0; index < sampleCount; index++) {
+    let entryDuration: number | undefined
+    if ((full.flags & TRUN_SAMPLE_DURATION_PRESENT) !== 0) {
+      if (offset + 4 > box.end) return null
+      entryDuration = dataView.getUint32(offset, false)
+      offset += 4
+    }
+    let entrySize: number | undefined
+    if ((full.flags & TRUN_SAMPLE_SIZE_PRESENT) !== 0) {
+      if (offset + 4 > box.end) return null
+      entrySize = dataView.getUint32(offset, false)
+      offset += 4
+    }
+    if ((full.flags & TRUN_SAMPLE_FLAGS_PRESENT) !== 0) {
+      if (offset + 4 > box.end) return null
+      offset += 4
+    }
+    let compositionOffset = 0
+    if ((full.flags & TRUN_SAMPLE_CTS_OFFSET_PRESENT) !== 0) {
+      if (offset + 4 > box.end) return null
+      compositionOffset = full.version === 1
+        ? dataView.getInt32(offset, false)
+        : dataView.getUint32(offset, false)
+      offset += 4
+    }
+    if (offset > box.end) return null
+
+    const duration = resolvedDefault(
+      entryDuration,
+      tfhd.defaultSampleDuration,
+      track.defaultSampleDuration,
+    )
+    const size = resolvedDefault(entrySize, tfhd.defaultSampleSize, track.defaultSampleSize)
+    if (duration === null || size === null) return null
+    const sampleEnd = bytePosition + BigInt(size)
+    const absoluteSampleEnd = BigInt(moofStart) + sampleEnd
+    if (absoluteSampleEnd > mdat.declaredEnd || absoluteSampleEnd > U64_MAX) return null
+    const presentationTime = decodeTime + BigInt(compositionOffset)
+    if (presentationTime < I64_MIN || presentationTime > I64_MAX) return null
+    samples.push({
+      decodeTime,
+      presentationTime,
+      duration,
+      timescale: track.timescale,
+      size,
+      bytePosition,
+    })
+    decodeTime += BigInt(duration)
+    if (decodeTime > U64_MAX) return null
+    bytePosition = sampleEnd
+  }
+  return offset === box.end ? samples : null
+}
+
+export function parseIsoBmffMovieFragmentTiming(
+  data: Uint8Array,
+  track: IsoBmffTrackTiming,
+  maxSamples: number,
+): IsoBmffMovieFragmentTiming | null {
+  if (!Number.isInteger(maxSamples) || maxSamples <= 0) return null
+  const first = parseBox(data, 0, data.length)
+  if (!first) return null
+  const moof = first.type === 'styp'
+    ? parseBox(data, first.end, data.length)
+    : first
+  if (!moof || moof.type !== 'moof' || moof.end >= data.length) return null
+  const moofChildren = children(data, moof)
+  if (!moofChildren) return null
+  const mfhd = exactlyOne(moofChildren, 'mfhd')
+  const traf = exactlyOne(moofChildren, 'traf')
+  if (!mfhd || !traf) return null
+  const movieFragmentSequenceNumber = parseMfhdSequence(data, mfhd)
+  if (movieFragmentSequenceNumber === null || movieFragmentSequenceNumber === 0) return null
+
+  const trafChildren = children(data, traf)
+  if (!trafChildren) return null
+  const tfhdBox = exactlyOne(trafChildren, 'tfhd')
+  const tfdtBox = exactlyOne(trafChildren, 'tfdt')
+  const trunBox = exactlyOne(trafChildren, 'trun')
+  if (!tfhdBox || !tfdtBox || !trunBox) return null
+  const tfhd = parseTfhd(data, tfhdBox)
+  const baseDecodeTime = parseTfdt(data, tfdtBox)
+  if (!tfhd || tfhd.trackId !== track.trackId || baseDecodeTime === null) return null
+  const mdat = parseMdatLayout(data, moof.end)
+  if (!mdat) return null
+  const samples = parseTrunSamples(
+    data,
+    trunBox,
+    moof.start,
+    baseDecodeTime,
+    tfhd,
+    track,
+    mdat,
+    maxSamples,
+  )
+  if (!samples) return null
+  return { movieFragmentSequenceNumber, samples }
+}
+
+function sameTrack(a: IsoBmffTrackTiming, b: IsoBmffTrackTiming): boolean {
+  return a.trackId === b.trackId &&
+    a.timescale === b.timescale &&
+    a.defaultSampleDuration === b.defaultSampleDuration &&
+    a.defaultSampleSize === b.defaultSampleSize
+}
+
+function sameSample(a: IsoBmffSampleTiming, b: IsoBmffSampleTiming): boolean {
+  return a.decodeTime === b.decodeTime &&
+    a.presentationTime === b.presentationTime &&
+    a.duration === b.duration &&
+    a.timescale === b.timescale &&
+    a.size === b.size &&
+    a.bytePosition === b.bytePosition
+}
+
+type PendingMovieFragment = Array<IsoBmffSampleTiming | null>
+
+/** Bounded per-track FT=0/FT=1 timing state. */
+export class IsoBmffTimingResolver {
+  #track: IsoBmffTrackTiming | null = null
+  #fragments = new Map<string, PendingMovieFragment>()
+  #pendingSamples = 0
+  #evictedSamples = 0
+  #lastMovieFragmentRejection: IsoBmffMovieFragmentRejection | null = null
+
+  constructor(readonly maxPendingSamples: number) {
+    if (!Number.isInteger(maxPendingSamples) || maxPendingSamples <= 0) {
+      throw new Error('[IsoBmffTimingResolver] maxPendingSamples must be a positive integer')
+    }
+  }
+
+  get pendingSampleCount(): number {
+    return this.#pendingSamples
+  }
+
+  /**
+   * Slots reclaimed by window displacement rather than by delivery or
+   * abandonment. Deliberately separate from the combiner's own release count:
+   * "nobody ever saw this sample" and "the combiner gave up on it" are
+   * different failures with different owners, and one number cannot say which.
+   */
+  get evictedSampleCount(): number {
+    return this.#evictedSamples
+  }
+
+  /** Typed reason for the most recent rejected movie fragment. */
+  get lastMovieFragmentRejection(): IsoBmffMovieFragmentRejection | null {
+    return this.#lastMovieFragmentRejection
+  }
+
+  addInitialization(data: Uint8Array): boolean {
+    const timing = parseIsoBmffInitializationTiming(data)
+    if (!timing) return false
+    if (this.#track) return sameTrack(this.#track, timing)
+    this.#track = timing
+    return true
+  }
+
+  addMovieFragment(
+    mpuSequenceNumber: number,
+    data: Uint8Array,
+    additionalSampleLimit = this.maxPendingSamples,
+  ): boolean {
+    this.#lastMovieFragmentRejection = null
+    if (!Number.isInteger(additionalSampleLimit) || additionalSampleLimit < 0) {
+      this.#lastMovieFragmentRejection = 'invalid'
+      return false
+    }
+    if (!this.#track || !isU32(mpuSequenceNumber)) {
+      this.#lastMovieFragmentRejection = 'invalid'
+      return false
+    }
+    const parsed = parseIsoBmffMovieFragmentTiming(
+      data,
+      this.#track,
+      this.maxPendingSamples,
+    )
+    if (!parsed) {
+      this.#lastMovieFragmentRejection = 'invalid'
+      return false
+    }
+    const key = fragmentKey(mpuSequenceNumber, parsed.movieFragmentSequenceNumber)
+    const existing = this.#fragments.get(key)
+    if (existing) {
+      return existing.length === parsed.samples.length && existing.every(
+        (sample, index) => sample !== null && sameSample(sample, parsed.samples[index]!),
+      )
+    }
+    // Sliding window, not a one-way ratchet. `consumeSample` and
+    // `releaseSample` between them cover every sample some component observed
+    // -- but a sample whose data units never arrive at all is observed by
+    // nobody, so neither path ever runs and its slot is held until `reset()`.
+    // Under sustained loss those orphans accumulate until the budget is full
+    // of samples that can never arrive, at which point every later moof is
+    // refused and media stops permanently with no error.
+    //
+    // Displacement is the signal no component can raise: once the budget is
+    // full and a newer fragment is in hand, the oldest pending fragment's
+    // samples are older than the whole window and cannot still be in flight.
+    // Reclaiming them keeps the timing that is arriving now and discards the
+    // timing that is not; refusing the new fragment does exactly the reverse,
+    // which is what wedged the stream. Evicted timing is not silent loss --
+    // a late data unit then finds no entry and is dropped against a named
+    // reason, which is attributable, bounded, and recoverable.
+    let freed = 0
+    while (
+      this.#fragments.size > 0 &&
+      (this.#pendingSamples + parsed.samples.length > this.maxPendingSamples ||
+        parsed.samples.length - freed > additionalSampleLimit)
+    ) {
+      freed += this.#evictOldestFragment()
+    }
+    // Net new charge against the caller's pool is what it must afford: `freed`
+    // slots were already counted there and are handed back by this call.
+    if (parsed.samples.length - freed > additionalSampleLimit) {
+      this.#lastMovieFragmentRejection = 'budget'
+      return false
+    }
+    if (this.#pendingSamples + parsed.samples.length > this.maxPendingSamples) {
+      this.#lastMovieFragmentRejection = 'budget'
+      return false
+    }
+    this.#fragments.set(key, [...parsed.samples])
+    this.#pendingSamples += parsed.samples.length
+    return true
+  }
+
+  sampleTiming(
+    mpuSequenceNumber: number,
+    movieFragmentSequenceNumber: number,
+    sampleNumber: number,
+  ): IsoBmffSampleTiming | null {
+    if (!isU32(mpuSequenceNumber) || !isU32(movieFragmentSequenceNumber) ||
+        movieFragmentSequenceNumber === 0 || !isU32(sampleNumber) || sampleNumber === 0) {
+      return null
+    }
+    const samples = this.#fragments.get(
+      fragmentKey(mpuSequenceNumber, movieFragmentSequenceNumber),
+    )
+    return samples?.[sampleNumber - 1] ?? null
+  }
+
+  consumeSample(
+    mpuSequenceNumber: number,
+    movieFragmentSequenceNumber: number,
+    sampleNumber: number,
+    expected: IsoBmffSampleTiming,
+  ): boolean {
+    const samples = this.#fragments.get(
+      fragmentKey(mpuSequenceNumber, movieFragmentSequenceNumber),
+    )
+    const sample = samples?.[sampleNumber - 1]
+    if (!sample || !sameSample(sample, expected)) return false
+    return this.#clearSlot(mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber)
+  }
+
+  /**
+   * Free the budget slot of a sample that will never be delivered.
+   *
+   * `consumeSample` is the delivery path and is the only decrement on a
+   * healthy stream. A sample whose data units never complete is never
+   * delivered; window displacement in `addMovieFragment` eventually reclaims
+   * it, but only after it has aged out of the whole window. This path frees
+   * the slot as soon as the combiner knows the sample is gone, so the budget
+   * tracks what is actually in flight rather than what has merely aged.
+   *
+   * The caller is whoever abandoned the sample, so the release is driven by
+   * the abandonment itself rather than by a timer, an LRU, or an age bound --
+   * the slot is freed exactly when its sample provably cannot arrive, which
+   * is a protocol event the combiner already detects and counts.
+   *
+   * Deliberately takes no `expected` timing: the caller is discarding, not
+   * matching, and requiring it would make the release fail exactly when the
+   * timing entry is the thing being reclaimed. Returns false when the slot
+   * was already freed, so a double release cannot drive the count negative.
+   */
+  releaseSample(
+    mpuSequenceNumber: number,
+    movieFragmentSequenceNumber: number,
+    sampleNumber: number,
+  ): boolean {
+    return this.#clearSlot(mpuSequenceNumber, movieFragmentSequenceNumber, sampleNumber)
+  }
+
+  /**
+   * Drop the oldest pending fragment whole and return the slots it held.
+   *
+   * Oldest is insertion order, which for a moof stream is arrival order, so
+   * this is the least-recently-declared timing -- the entries least likely to
+   * still have data units in flight.
+   */
+  #evictOldestFragment(): number {
+    const oldest = this.#fragments.keys().next().value
+    if (oldest === undefined) return 0
+    const samples = this.#fragments.get(oldest)!
+    let live = 0
+    for (const sample of samples) if (sample !== null) live++
+    this.#fragments.delete(oldest)
+    this.#pendingSamples -= live
+    this.#evictedSamples += live
+    return live
+  }
+
+  /** Null one slot, decrement the budget, and drop the fragment when empty. */
+  #clearSlot(
+    mpuSequenceNumber: number,
+    movieFragmentSequenceNumber: number,
+    sampleNumber: number,
+  ): boolean {
+    if (!isU32(mpuSequenceNumber) || !isU32(movieFragmentSequenceNumber) ||
+        movieFragmentSequenceNumber === 0 || !isU32(sampleNumber) || sampleNumber === 0) {
+      return false
+    }
+    const key = fragmentKey(mpuSequenceNumber, movieFragmentSequenceNumber)
+    const samples = this.#fragments.get(key)
+    const index = sampleNumber - 1
+    if (!samples || !samples[index]) return false
+    samples[index] = null
+    this.#pendingSamples--
+    if (samples.every(value => value === null)) this.#fragments.delete(key)
+    return true
+  }
+
+  reset(): void {
+    this.#track = null
+    this.#fragments.clear()
+    this.#pendingSamples = 0
+  }
+}
+
+function fragmentKey(mpuSequenceNumber: number, movieFragmentSequenceNumber: number): string {
+  return `${mpuSequenceNumber}:${movieFragmentSequenceNumber}`
+}
+
+function isU32(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff
+}
+
+/** Convert exact media ticks to microseconds without first narrowing the ticks. */
+export function mediaTicksToMicroseconds(ticks: bigint, timescale: number): number | null {
+  if (!Number.isInteger(timescale) || timescale <= 0) return null
+  const numerator = ticks * MICROSECONDS_PER_SECOND
+  const scale = BigInt(timescale)
+  const whole = numerator / scale
+  const remainder = numerator % scale
+  if (whole < BigInt(Number.MIN_SAFE_INTEGER) || whole > BigInt(Number.MAX_SAFE_INTEGER)) {
+    return null
+  }
+  const result = Number(whole) + Number(remainder) / timescale
+  return Number.isFinite(result) ? result : null
+}