@blockcast/mmt-container 0.1.0 → 0.3.0-main.ef68de90edb3

package/src/conceal-timeline.ts

@@ -0,0 +1,293 @@
+/**
+ * Sink-side concealment helpers for the keyframe-protected FEC policy.
+ *
+ * Concealment is hold-last-good-frame. No bitstream is ever synthesised:
+ * a generated "fill" picture is codec-specific, resets the reference chain
+ * (an IDR) or is not a picture at all, and every later delta would decode
+ * against it until the next RAP. Instead the sink keeps presenting the last
+ * good frame, sized exactly from authored timestamps, until media resumes.
+ *
+ * - {@link videoConcealModeForCodec} says whether a video decoder can be fed
+ *   straight through a delta gap (H.264 conceals missing references itself)
+ *   or must hold until the next RAP.
+ * - {@link HoldLastTimeline} gives MSE sinks gapless per-sample durations.
+ * - {@link AudioGapConcealer} sizes audio concealment exactly: repeat the last
+ *   good access unit (MSE) or insert PCM silence (WebCodecs).
+ */
+
+import type { FrameGapDecision } from './block-policy.js'
+
+// ─── Video conceal mode ─────────────────────────────────────────────
+
+/**
+ * `feed-through`: keep feeding deltas after a delta-only gap; the decoder
+ * conceals missing references and the canvas keeps the last frame.
+ * `hold-to-rap`: drop non-RAP frames until the next RAP (no queue flush, no
+ * A/V sync reset).
+ */
+export type VideoConcealMode = 'feed-through' | 'hold-to-rap'
+
+/**
+ * AVC decoders conceal a missing reference and resynchronise on their own;
+ * HEVC, AV1 and VP9 decoders error or freeze on a broken reference chain.
+ * Any codec not known to conceal is held to the next RAP (fail-closed).
+ */
+export function videoConcealModeForCodec(codec: string): VideoConcealMode {
+  const lower = codec.toLowerCase()
+  if (lower.startsWith('avc1') || lower.startsWith('avc3')) return 'feed-through'
+  return 'hold-to-rap'
+}
+
+// ─── HoldLastTimeline ───────────────────────────────────────────────
+
+/** One video sample in its media timescale. */
+export interface TimelineSample<T> {
+  readonly payload: T
+  readonly dts: bigint
+  readonly pts: bigint
+  /** Authored duration in media ticks. */
+  readonly duration: number
+  /** Codec-aware RAP. */
+  readonly keyframe: boolean
+  readonly mpu?: number
+  /** Decision attached by libmmt to the first frame released after a gap. */
+  readonly gapBefore?: FrameGapDecision
+}
+
+/** A sample ready to append, with an explicit per-sample duration. */
+export interface TimelineEmit<T> {
+  readonly payload: T
+  readonly dts: bigint
+  readonly pts: bigint
+  readonly duration: number
+  readonly keyframe: boolean
+}
+
+export interface HoldLastTimelineOptions {
+  readonly concealMode: VideoConcealMode
+}
+
+export interface HoldLastTimelineStats {
+  /** Non-RAP frames dropped while waiting for a RAP. */
+  droppedFrames: number
+  /** Held frames whose duration was extended over a gap. */
+  extendedHolds: number
+}
+
+const U32_MAX = 0xffff_ffffn
+
+/**
+ * Holds one video sample back so its duration can run to the next emitted
+ * sample's dts. That costs exactly one frame of MSE latency (1000/framerate
+ * ms, from the catalog) and buys a gapless hold-last without synthesising a
+ * bitstream: a gap simply lengthens the last good frame.
+ *
+ * On a stall, or on any conceal under `hold-to-rap` except a RAP arriving
+ * right after the gap, frames are dropped until the next RAP and the held
+ * frame stays held until that RAP arrives, then runs exactly to its dts. The
+ * element waits on the held frame for the length of the outage, but the
+ * buffer never gets a hole, however many RAPs the outage took. Once the
+ * stream shows composition offsets (dts ≠ pts), samples pass straight
+ * through with their authored durations and MSE starves until the RAP is
+ * appended — the one documented case where the element also waits on audio.
+ */
+export class HoldLastTimeline<T> {
+  readonly #concealMode: VideoConcealMode
+  #held: TimelineSample<T> | null = null
+  #dropping = false
+  #compositionOffsets = false
+  readonly #stats: HoldLastTimelineStats = { droppedFrames: 0, extendedHolds: 0 }
+
+  constructor(options: HoldLastTimelineOptions) {
+    this.#concealMode = options.concealMode
+  }
+
+  get stats(): Readonly<HoldLastTimelineStats> {
+    return { ...this.#stats }
+  }
+
+  push(sample: TimelineSample<T>): TimelineEmit<T>[] {
+    if (sample.dts !== sample.pts) this.#compositionOffsets = true
+
+    if (this.#dropping) {
+      if (!sample.keyframe) {
+        this.#stats.droppedFrames++
+        return []
+      }
+      this.#dropping = false
+      return this.#accept(sample)
+    }
+
+    if (this.#dropsUntilRap(sample)) {
+      this.#dropping = true
+      this.#stats.droppedFrames++
+      // The held frame stays held: the RAP's #accept sizes it exactly.
+      return this.#compositionOffsets ? this.#releaseHeld() : []
+    }
+
+    return this.#accept(sample)
+  }
+
+  /** Release the held sample with its authored duration (end of stream). */
+  flush(): TimelineEmit<T>[] {
+    return this.#releaseHeld()
+  }
+
+  /** Drop all state for a new epoch. */
+  reset(): void {
+    this.#held = null
+    this.#dropping = false
+    this.#compositionOffsets = false
+  }
+
+  #accept(sample: TimelineSample<T>): TimelineEmit<T>[] {
+    if (this.#compositionOffsets) {
+      const out = this.#releaseHeld()
+      out.push(this.#emit(sample, sample.duration))
+      return out
+    }
+    const out: TimelineEmit<T>[] = []
+    const held = this.#held
+    if (held) out.push(this.#emit(held, this.#durationTo(held, sample.dts)))
+    this.#held = sample
+    return out
+  }
+
+  #dropsUntilRap(sample: TimelineSample<T>): boolean {
+    const gap = sample.gapBefore
+    if (!gap || gap.trackKind !== 'video' || sample.keyframe) return false
+    if (gap.action === 'stall') return true
+    return this.#concealMode === 'hold-to-rap' && gap.reason !== 'rap-next'
+  }
+
+  #durationTo(held: TimelineSample<T>, target: bigint): number {
+    if (target <= held.dts) return held.duration
+    const span = target - held.dts
+    if (span > U32_MAX) return held.duration
+    const duration = Number(span)
+    if (duration !== held.duration) this.#stats.extendedHolds++
+    return duration
+  }
+
+  #releaseHeld(): TimelineEmit<T>[] {
+    const held = this.#held
+    this.#held = null
+    return held ? [this.#emit(held, held.duration)] : []
+  }
+
+  #emit(sample: TimelineSample<T>, duration: number): TimelineEmit<T> {
+    return {
+      payload: sample.payload,
+      dts: sample.dts,
+      pts: sample.pts,
+      duration,
+      keyframe: sample.keyframe,
+    }
+  }
+}
+
+// ─── AudioGapConcealer ──────────────────────────────────────────────
+
+/**
+ * One audio access unit on its track's authored clock: the ISO-BMFF media
+ * timescale the `audio-gap` decision was computed in (`decideGap`, from
+ * `AuthoredTiming`). An AAC AU is exactly 1024 ticks there. Never pass values
+ * rescaled to another timescale: 1024 samples at 48 kHz is 21333.33... µs,
+ * which no integer tick count can hold.
+ */
+export interface AudioAccessUnit<T> {
+  readonly payload: T
+  /** Authored presentation time in media ticks (`AuthoredTiming.presentationTime`). */
+  readonly pts: bigint
+  /** Authored duration in media ticks (`AuthoredTiming.durationTicks`): a positive safe integer. */
+  readonly duration: number
+}
+
+export interface AudioGapConcealerStats {
+  /**
+   * Access units `note()` refused because their duration was not a positive
+   * safe integer: not media ticks, so the AU cannot size a gap. The concealer
+   * then holds no good AU and the next gap re-anchors. Non-zero means a caller
+   * noted a rescaled value (e.g. microseconds) instead of authored ticks.
+   */
+  rejectedUnits: number
+}
+
+export type AudioGapPlan<T> =
+  | { readonly kind: 'none' }
+  | {
+      readonly kind: 'conceal'
+      /**
+       * MSE: the last good AU repeated into each missing slot. Empty when no
+       * good AU has been seen yet; an AAC access unit is not portable across
+       * AudioSpecificConfigs, so none is ever synthesised.
+       */
+      readonly repeat: AudioAccessUnit<T>[]
+      /** WebCodecs: exactly this much PCM silence, in media ticks. */
+      readonly silenceTicks: bigint
+    }
+  | {
+      /** The gap is not a whole number of AUs: re-anchor at `pts`. */
+      readonly kind: 're-anchor'
+      readonly pts: bigint
+    }
+
+/**
+ * Sizes an audio gap from the libmmt gap decision. Audio never touches video
+ * state: every plan is local to the audio sink.
+ */
+export class AudioGapConcealer<T> {
+  #last: AudioAccessUnit<T> | null = null
+  readonly #stats: AudioGapConcealerStats = { rejectedUnits: 0 }
+
+  get stats(): Readonly<AudioGapConcealerStats> {
+    return { ...this.#stats }
+  }
+
+  /**
+   * Record a good access unit as it is emitted. An AU whose duration is not
+   * whole media ticks is refused and counted (`stats.rejectedUnits`), and the
+   * concealer forgets its previous AU: that one no longer precedes the gap, so
+   * sizing from it would misplace every slot. Refusing here keeps `plan()`
+   * total, so a bad AU never throws out of the packet path.
+   */
+  note(au: AudioAccessUnit<T>): void {
+    if (!Number.isSafeInteger(au.duration) || au.duration <= 0) {
+      this.#stats.rejectedUnits++
+      this.#last = null
+      return
+    }
+    this.#last = au
+  }
+
+  plan(decision: FrameGapDecision | undefined, next: { readonly pts: bigint }): AudioGapPlan<T> {
+    if (!decision || decision.trackKind !== 'audio') return { kind: 'none' }
+    const missing = decision.missingFrames
+    if (
+      decision.reason !== 'audio-gap' ||
+      missing === null ||
+      !Number.isSafeInteger(missing) ||
+      missing <= 0
+    ) {
+      return { kind: 're-anchor', pts: next.pts }
+    }
+    const last = this.#last
+    // Exact sizing needs the preceding AU's duration; a sink that has not
+    // emitted one yet has nothing to hold and simply starts at the next AU.
+    if (last === null) return { kind: 're-anchor', pts: next.pts }
+    const duration = BigInt(last.duration)
+    const repeat: AudioAccessUnit<T>[] = []
+    for (let slot = 1; slot <= missing; slot++) {
+      repeat.push({
+        payload: last.payload,
+        pts: last.pts + BigInt(slot) * duration,
+        duration: last.duration,
+      })
+    }
+    return { kind: 'conceal', repeat, silenceTicks: BigInt(missing) * duration }
+  }
+
+  reset(): void {
+    this.#last = null
+  }
+}

package/src/delivery-gap.ts

@@ -0,0 +1,147 @@
+/**
+ * Receiver-measured multicast delivery gap (BLO-35597).
+ *
+ * The FEC layer gives a block's multicast symbols a late-symbol wait before it
+ * declares the block over: the catalog block span plus an allowance for the
+ * path's arrival jitter. The catalog can only signal a tolerance it knows in
+ * advance (`fec.reorderToleranceMs`); the path the receiver actually sits on
+ * is measured here, in-band, from the arrival times of the multicast
+ * datagrams themselves.
+ *
+ * Which statistic, and why not RFC 3550 interarrival jitter
+ * ---------------------------------------------------------
+ * The wait is an inactivity bound: a block fails when no symbol reaches it for
+ * the wait. What it has to outlast is therefore the longest silence the
+ * delivery path produces, not the path's average variation.
+ *
+ * RFC 3550 §6.4.1 `J` is a mean absolute transit-time difference smoothed with
+ * gain 1/16. It is the right number for sizing a playout buffer against steady
+ * jitter, and the wrong one for a bimodal path. On the path this was measured
+ * on (iPhone Safari over Wi-Fi, prod AMT, 2026-09-28, 36,657 datagrams in 57 s)
+ * arrivals were either back-to-back (p90 inter-arrival 2 ms) or stalled for
+ * one 802.11 power-save beacon interval (102.4 ms; 135 stalls of 50-110 ms,
+ * recurring every ~511 ms at the median). Applied to that trace, `J` has a p99
+ * of 6 ms: a wait of span + J expires inside every stall, and the stall's
+ * symbols then arrive at a block that has already been failed.
+ *
+ * So the estimator is the largest delivery gap observed over a trailing
+ * window: the time between consecutive multicast datagram arrivals, measured
+ * on the page thread where the FEC deadlines themselves run (a main-thread or
+ * bridge-batching delay is as real to those timers as a radio stall). It is
+ * receiver-wide rather than per stream because the stall is a property of the
+ * link every stream shares; a quiet stream learns the gap from a busy one.
+ *
+ * Only a gap that ended in delivery counts. A silence is closed by the first
+ * packet after it; if that packet is the in-sequence successor (MMTP
+ * packet_sequence_number + 1) of the last one its packet_id delivered, nothing
+ * of that flow was lost across the silence: its packets were held and then
+ * delivered, which is exactly the lateness a longer wait turns from a failed
+ * block into a completed one. If the sequence jumped, the silence was (at
+ * least partly) loss -- a tunnel outage, a publisher pause -- and waiting
+ * longer would not have delivered anything, so the gap is not taken as
+ * jitter.
+ *
+ * The trailing window is supplied by the caller from the catalog. It must be
+ * long enough to contain one recurrence of the stall it has to remember, and
+ * nothing here can know that recurrence in advance. The window is also the
+ * largest gap reported: a silence longer than the catalog horizon is outside
+ * what the estimator models (a backgrounded tab, a long GC), and every bound
+ * derived from the wait (block lifetime, terminal retention, the release
+ * gate's hold ceiling) must stay a catalog quantity rather than a measurement.
+ * `undefined` means no catalog horizon is known: nothing bounds the gap, so
+ * none is reported and the catalog tolerance alone applies.
+ */
+export class DeliveryGapEstimator {
+  /** Most recent arrival, or undefined before the first one since reset. */
+  #lastArrivalMs: number | undefined
+  /** Last MMTP packet_sequence_number seen per packet_id. */
+  #lastSequence = new Map<number, number>()
+  /**
+   * Monotonic deque of (arrivalMs, gapMs): gaps strictly decrease from head to
+   * tail, so the head is the window maximum. Amortized O(1) per arrival.
+   */
+  #times: number[] = []
+  #gaps: number[] = []
+  #head = 0
+  #windowMs: number | undefined
+
+  /**
+   * @param windowMs trailing window in ms, which also caps the reported gap,
+   *   or undefined when the catalog gives none (no gap is reported).
+   */
+  setWindowMs(windowMs: number | undefined): void {
+    if (windowMs !== undefined && !(Number.isFinite(windowMs) && windowMs > 0)) {
+      throw new Error(
+        `[DeliveryGap] window must be a finite positive ms value or undefined (got ${windowMs})`,
+      )
+    }
+    this.#windowMs = windowMs
+  }
+
+  get windowMs(): number | undefined {
+    return this.#windowMs
+  }
+
+  /**
+   * Record one multicast datagram arrival at receiver time `nowMs`, carrying
+   * MMTP `packetSequenceNumber` (32-bit, per packet_id) on `packetId`.
+   */
+  noteArrival(nowMs: number, packetId: number, packetSequenceNumber: number): void {
+    const last = this.#lastArrivalMs
+    const previousSequence = this.#lastSequence.get(packetId)
+    this.#lastArrivalMs = nowMs
+    this.#lastSequence.set(packetId, packetSequenceNumber)
+    if (last === undefined || previousSequence === undefined) return
+    if (this.#windowMs === undefined) return
+    // MMTP packet_sequence_number is a 32-bit counter that wraps.
+    if (((previousSequence + 1) >>> 0) !== (packetSequenceNumber >>> 0)) return
+    const gap = nowMs - last
+    this.#evict(nowMs)
+    // A gap no larger than the current tail can never become the maximum
+    // while the tail is still in the window, except as the newest entry.
+    while (this.#gaps.length > this.#head && this.#gaps[this.#gaps.length - 1] <= gap) {
+      this.#gaps.pop()
+      this.#times.pop()
+    }
+    this.#gaps.push(gap)
+    this.#times.push(nowMs)
+    this.#compact()
+  }
+
+  /**
+   * Largest gap observed within the window ending at `nowMs`, at most the
+   * window itself; 0 if none or when no window is set.
+   */
+  peakGapMs(nowMs: number): number {
+    const windowMs = this.#windowMs
+    if (windowMs === undefined) return 0
+    this.#evict(nowMs)
+    return this.#gaps.length > this.#head ? Math.min(this.#gaps[this.#head], windowMs) : 0
+  }
+
+  /** Forget everything: a new delivery path starts with no measurement. */
+  reset(): void {
+    this.#lastArrivalMs = undefined
+    this.#lastSequence.clear()
+    this.#times = []
+    this.#gaps = []
+    this.#head = 0
+  }
+
+  #evict(nowMs: number): void {
+    const windowMs = this.#windowMs
+    if (windowMs === undefined) return
+    while (this.#times.length > this.#head && this.#times[this.#head] < nowMs - windowMs) {
+      this.#head++
+    }
+  }
+
+  #compact(): void {
+    // Drop consumed head slots once they outnumber live ones.
+    if (this.#head > 0 && this.#head * 2 >= this.#times.length) {
+      this.#times = this.#times.slice(this.#head)
+      this.#gaps = this.#gaps.slice(this.#head)
+      this.#head = 0
+    }
+  }
+}