@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/cmaf-block-assembler.ts

@@ -0,0 +1,1058 @@
+/**
+ * FEC-block-aware CMAF segment assembler for MSE multicast.
+ *
+ * Buffers reassembled frames per FEC source block (SBN). On block completion
+ * (K source symbols received clean, or FEC recovery), sorts frames by ESI
+ * and builds a single multi-sample moof+mdat CMAF segment. On block timeout,
+ * generates fill frames (green video / silence audio) for missing ESI slots.
+ *
+ * One assembler instance per track (video or audio). MulticastManager owns
+ * these instances and calls them directly with SBN/ESI from the FEC pipeline.
+ */
+
+import {
+  encodeDataSegment,
+  buildVideoInitSegment,
+  buildAudioInitSegment,
+  generateGreenFillNAL,
+  normalizeAacSampleForCmaf,
+} from './mmtp-to-cmaf.js'
+import {
+  classifyH264Keyframe,
+  detectH264Keyframe,
+  splitH264SampleNalUnits,
+} from './codec-utils.js'
+import {
+  scaleAuthoredTicks,
+  scaleAuthoredTiming,
+  type AuthoredTiming,
+} from './authored-timing.js'
+import type { MmtpDeliveryProvenance } from './mfu-reassembler.js'
+
+const INT32_MIN = -0x80000000
+const INT32_MAX = 0x7fffffff
+
+interface BlockFrame {
+  data: Uint8Array
+  timestamp: number
+  keyframe: boolean
+  /** Exact ISO-BMFF timing retained from the parser for FEC/source ordering. */
+  authoredTiming?: AuthoredTiming
+  /** MMTP packet_sequence_number identifying the delivered access unit. */
+  packetSequenceNumber?: number
+  /** Every authoritative MMTP source-packet sequence that formed this sample. */
+  packetSequenceNumbers?: number[]
+  /** Subset of packetSequenceNumbers reconstructed by FEC. */
+  repairedPacketSequenceNumbers?: number[]
+  /** Native MMTP MPU group coordinate retained across source/FEC ordering. */
+  mpuSequenceNumber?: number
+  catalogTrackName?: string
+  /**
+   * Whole-frame delivery verdict folded across every contributing fragment.
+   * Absent means no caller declared one; it is never an implied 'multicast'.
+   */
+  deliveryProvenance?: MmtpDeliveryProvenance
+}
+
+export interface CmafBlockSample {
+  data: Uint8Array
+  timestamp: number
+  duration: number
+  keyframe: boolean
+  /** Signed PTS-DTS offset in the configured CMAF timescale. */
+  compositionTimeOffset?: number
+  /** Exact ISO-BMFF timing in the media track's native timescale. */
+  authoredTiming?: AuthoredTiming
+  /** MMTP packet_sequence_number identifying the delivered access unit. */
+  packetSequenceNumber?: number
+  /** Every authoritative MMTP source-packet sequence that formed this sample. */
+  packetSequenceNumbers?: number[]
+  /** Subset of packetSequenceNumbers reconstructed by FEC. */
+  repairedPacketSequenceNumbers?: number[]
+  /** Native MMTP MPU group coordinate retained for exact replay selection. */
+  mpuSequenceNumber?: number
+  /** Immutable catalog identity supplied by the owning ingress subscription. */
+  catalogTrackName?: string
+  /**
+   * Whole-frame delivery verdict, carried so MSE `onSample` consumers can see
+   * the same evidence the non-MSE frame path gets. Without it the MSE branch
+   * silently loses a computed 'mixed' or 'multicast' finding.
+   */
+  deliveryProvenance?: MmtpDeliveryProvenance
+}
+
+export type CmafSampleOrderPolicy =
+  | { mode: 'arrival' }
+  | {
+    /** Release samples according to media progression, without a wall clock. */
+    mode: 'media-window'
+    /** Delivery window in the same units as CmafBlockSample.timestamp. */
+    deliveryWindow: number
+    /** Optional modulo period for wrapped input timestamps, in timestamp units. */
+    timestampWrapPeriod?: number
+  }
+
+export interface CmafSampleOrderStats {
+  staleSamples: number
+  duplicateSamples: number
+  preRapDeadlineDrops: number
+  noRapFlushDrops: number
+  forcedReleases: number
+}
+
+export interface BlockAssemblerConfig {
+  /** Number of source symbols per FEC block */
+  k: number
+  /** Timescale for CMAF segments (default 1_000_000 = microseconds) */
+  timescale?: number
+  /** ISO track ID (default 1) */
+  trackId?: number
+  /** Track type — determines fill frame generation and init segment format */
+  trackType: 'video' | 'audio'
+  /** Video/audio codec string (e.g. 'avc1.64002a', 'mp4a.40.2'). */
+  codec?: string
+  // Video config (required when trackType='video')
+  /** Raw avcC payload from catalog description — for init + green fill */
+  avcC?: Uint8Array
+  /** Video width in pixels */
+  width?: number
+  /** Video height in pixels */
+  height?: number
+  // Audio config (required when trackType='audio')
+  /** Audio codec string (e.g. 'mp4a.40.2', 'opus') — for silence fill generation */
+  audioCodec?: string
+  /** Audio sample rate (e.g. 48000) */
+  sampleRate?: number
+  /** Audio channel count (e.g. 1 or 2) */
+  channels?: number
+  /** Raw AudioSpecificConfig from catalog */
+  asc?: Uint8Array
+  // Shared
+  /** Frames per second — fallback for duration estimation */
+  fps?: number
+  /** Explicit sample ordering policy. Datagram/FEC callers use media-window. */
+  sampleOrder?: CmafSampleOrderPolicy
+  /**
+   * Bounded sample reorder depth for callback mode.
+   *
+   * Default 0 preserves immediate emission. When set on video tracks with
+   * onSample enabled, samples are sorted by timestamp and the oldest sample is
+   * emitted only after this many newer samples are available.
+   * @deprecated Use sampleOrder with an explicit policy.
+   */
+  sampleReorderWindow?: number
+}
+
+interface OrderedSample extends CmafBlockSample {
+  advancesHorizon: boolean
+}
+
+export class CmafBlockAssembler {
+  #config: Required<Pick<BlockAssemblerConfig, 'k' | 'timescale' | 'trackId' | 'trackType'>>
+  #blocks = new Map<number, Map<number, BlockFrame>>()
+  #pendingFlush = new Set<number>()
+  #pendingRecovered = new Map<number, BlockFrame>()
+  #sequence = 1
+  #baseTs = -1
+  #fillFrame: Uint8Array
+  #lastDecodableAudioFrame: Uint8Array | null = null
+  #frameDuration: number
+  #lastEmittedTs = -1
+  #lastSourceTs = -1
+  #sampleReorderWindow = 0
+  #sampleOrder: CmafSampleOrderPolicy = { mode: 'arrival' }
+  #sampleOrderCapacity = 0
+  #sampleReorderQueue: OrderedSample[] = []
+  #recoveredHorizonTs = -1
+  #sampleOrderStats: CmafSampleOrderStats = {
+    staleSamples: 0,
+    duplicateSamples: 0,
+    preRapDeadlineDrops: 0,
+    noRapFlushDrops: 0,
+    forcedReleases: 0,
+  }
+  #validateH264Keyframes = false
+  #keyframeRejectDumpCount = 0
+
+  /** Callback: emits a complete moof+mdat CMAF segment */
+  onSegment: ((segment: Uint8Array) => void) | null = null
+  /** Callback: emits a gated/deduped raw sample for callers that already own the MSE timeline. */
+  onSample: ((sample: CmafBlockSample) => void) | null = null
+  /** Callback: emits an init segment (ftyp+moov) */
+  onInitSegment: ((init: Uint8Array) => void) | null = null
+
+  // Video keyframe gate (BLO-3035 layer 3): Chrome's CHUNK_DEMUXER rejects a
+  // moof+mdat whose first sample is non-sync with no prior reference frames
+  // ("CHUNK_DEMUXER_ERROR_APPEND_FAILED: Failed to prepare video sample for
+  // decode") and detaches the SourceBuffer for the rest of the session.
+  // Mid-stream join almost guarantees the first FEC blocks are mid-GOP — all
+  // delta frames. Gate emission until the first block containing an IDR;
+  // within that block, splice samples to start at the IDR index. Audio passes
+  // unconditionally — valid for the codecs supported here (AAC, Opus) where
+  // every frame is independently decodable. SBR-only AAC, USAC, or HE-AAC v2
+  // with PCE re-entry would need a similar gate.
+  #armedVideo = false
+
+  // Legacy SBN emission watermark for the old block-buffered path. Direct
+  // source emission is now timestamp-ordered instead; recovered frames are
+  // queued by media timestamp so they can fill gaps without racing ahead of
+  // source frames.
+  #lastEmittedSbn = -1
+
+  /** Attempt to claim emission for `sbn`. Returns true if `sbn` is past
+   *  the watermark (and advances it); false if this sbn has already been
+   *  claimed or is older (caller should drop). */
+  #claimSbnEmission(sbn: number): boolean {
+    if (sbn <= this.#lastEmittedSbn) return false
+    this.#lastEmittedSbn = sbn
+    return true
+  }
+
+  /** Truncate `frames` to start at the first keyframe for video tracks before
+   *  the first emission. Returns the (possibly spliced) frames, or null to
+   *  drop the block entirely. Audio + already-armed video: identity. */
+  #applyVideoKeyframeGate<T extends { data: Uint8Array; keyframe: boolean }>(frames: T[]): T[] | null {
+    const keyedFrames = this.#normalizeVideoKeyframes(frames)
+    if (this.#config.trackType !== 'video' || this.#armedVideo) return keyedFrames
+    const firstKfIdx = keyedFrames.findIndex(f => f.keyframe)
+    if (firstKfIdx < 0) return null
+    return firstKfIdx === 0 ? keyedFrames : keyedFrames.slice(firstKfIdx)
+  }
+
+  #normalizeVideoKeyframes<T extends { data: Uint8Array; keyframe: boolean }>(frames: T[]): T[] {
+    if (this.#config.trackType !== 'video' || !this.#validateH264Keyframes) return frames
+    return frames.map((frame) => this.#withEffectiveVideoKeyframe(frame))
+  }
+
+  #withEffectiveVideoKeyframe<T extends { data: Uint8Array; keyframe: boolean }>(frame: T): T {
+    if (this.#config.trackType !== 'video' || !this.#validateH264Keyframes) return frame
+    const keyframe = detectH264Keyframe(frame.data)
+    if (!keyframe) this.#dumpRejectedVideoKeyframe(frame.data, frame.keyframe)
+    return keyframe === frame.keyframe ? frame : { ...frame, keyframe }
+  }
+
+  #dumpRejectedVideoKeyframe(data: Uint8Array, metadataKeyframe: boolean): void {
+    if (this.#keyframeRejectDumpCount >= 12) return
+    this.#keyframeRejectDumpCount++
+    const sample = splitH264SampleNalUnits(data)
+    const nalTypes = describeH264NalTypes(sample.nals)
+    const classify = classifyH264Keyframe(data)
+    const hex = Array.from(data.subarray(0, Math.min(48, data.length)))
+      .map(b => (b as number).toString(16).padStart(2, '0'))
+      .join(' ')
+    console.log(
+      `[L4-KF-GATE] reject#${this.#keyframeRejectDumpCount} len=${data.length} ` +
+      `metadataKf=${metadataKeyframe} classify=${classify} format=${sample.format} ` +
+      `nalTypes=[${nalTypes.join(',')}] first48=[${hex}]`,
+    )
+  }
+
+  /** Mark video as already synchronized by an external decoder path.
+   *  Used by MoQ→multicast MSE continuity when MoQ has already appended a
+   *  keyframe to the same SourceBuffer timeline before multicast takeover. */
+  markVideoSynced(): void {
+    if (this.#config.trackType === 'video') this.#armedVideo = true
+  }
+
+  /** Emit each frame as its own single-sample moof+mdat segment. Matches the
+   *  case-20 path (`MmtpToCmaf.wrapVideoSample` → `encodeDataSegment`) byte-
+   *  for-byte per frame. Working hypothesis (pending Chromium-source
+   *  validation against `media/filters/chunk_demuxer.cc`):
+   *  `encodeMultiSampleSegment` blobs are accepted by ChunkDemuxer in this
+   *  pipeline but only the first sample renders for live, possibly because
+   *  the pipeline expects per-frame moof boundaries. Track in BLO-3035.
+   *
+   *  Stale-tfdt defense-in-depth: drops any frame whose timestamp is older
+   *  than `#lastEmittedTs`. The SBN watermark already prevents out-of-order
+   *  FEC-block emissions, but `addBypassFrame` (oversized MFU / no-FEC path)
+   *  doesn't touch the watermark — a bypass frame at t=T followed by a FEC
+   *  block whose frames precede T would otherwise inject earlier tfdt and
+   *  detach the SourceBuffer. */
+  #ordersSamples(): boolean {
+    return this.#sampleOrder.mode === 'media-window' || this.#sampleReorderWindow > 0
+  }
+
+  #unwrapTimestamp(timestamp: number): number {
+    const wrapPeriod = this.#sampleOrder.mode === 'media-window'
+      ? this.#sampleOrder.timestampWrapPeriod
+      : undefined
+    if (!wrapPeriod) return timestamp
+    const reference = this.#lastSourceTs >= 0
+      ? this.#lastSourceTs
+      : this.#recoveredHorizonTs >= 0
+        ? this.#recoveredHorizonTs
+        : this.#lastEmittedTs
+    if (reference < 0) return timestamp
+    return timestamp + Math.round((reference - timestamp) / wrapPeriod) * wrapPeriod
+  }
+
+  #emitSample(
+    data: Uint8Array,
+    timestamp: number,
+    duration: number,
+    keyframe: boolean,
+    advancesHorizon: boolean,
+    catalogTrackName: string | undefined,
+    mpuSequenceNumber: number | undefined,
+    packetSequenceNumber: number | undefined,
+    packetSequenceNumbers: number[] | undefined,
+    repairedPacketSequenceNumbers: number[] | undefined,
+    authoredTiming: AuthoredTiming | undefined,
+    // Required, not optional: an omitted optional argument is silently
+    // undefined, which is exactly how this field went missing from the
+    // recovered path in the first place. Callers with nothing to declare pass
+    // `undefined` on purpose.
+    deliveryProvenance: MmtpDeliveryProvenance | undefined,
+  ): void {
+    const scaledTiming = authoredTiming === undefined
+      ? null
+      : scaleAuthoredTiming(authoredTiming, this.#config.timescale)
+    if (authoredTiming !== undefined && scaledTiming === null) return
+    const authoredTimestamp = scaledTiming?.timestamp ?? timestamp
+    const authoredDuration = scaledTiming?.duration ?? duration
+    let compositionTimeOffset: number | undefined
+    if (authoredTiming !== undefined) {
+      const scaledOffset = scaleAuthoredTicks(
+        authoredTiming.presentationTime - authoredTiming.decodeTime,
+        authoredTiming.mediaTimescale,
+        this.#config.timescale,
+      )
+      if (scaledOffset === null) return
+      // trun stores composition offsets as integer target-timescale ticks.
+      // Preserve the nearest representable tick, then enforce the signed
+      // int32 serialization range on the rounded value.
+      const roundedOffset = Math.round(scaledOffset)
+      if (
+        !Number.isSafeInteger(roundedOffset) ||
+        roundedOffset < INT32_MIN ||
+        roundedOffset > INT32_MAX
+      ) return
+      compositionTimeOffset = roundedOffset
+    }
+    const unwrappedTimestamp = this.#unwrapTimestamp(authoredTimestamp)
+    if (unwrappedTimestamp <= this.#lastEmittedTs) {
+      this.#sampleOrderStats.staleSamples++
+      return
+    }
+
+    const sample = this.#withEffectiveVideoKeyframe({
+      data,
+      timestamp: unwrappedTimestamp,
+      duration: authoredDuration,
+      keyframe,
+      ...(compositionTimeOffset === undefined ? {} : { compositionTimeOffset }),
+      advancesHorizon,
+      ...(authoredTiming === undefined ? {} : { authoredTiming }),
+      ...(packetSequenceNumber === undefined ? {} : { packetSequenceNumber }),
+      ...(packetSequenceNumbers === undefined ? {} : { packetSequenceNumbers }),
+      ...(repairedPacketSequenceNumbers === undefined
+        ? {}
+        : { repairedPacketSequenceNumbers }),
+      ...(mpuSequenceNumber === undefined ? {} : { mpuSequenceNumber }),
+      ...(catalogTrackName === undefined ? {} : { catalogTrackName }),
+      ...(deliveryProvenance === undefined ? {} : { deliveryProvenance }),
+    })
+    if (advancesHorizon && unwrappedTimestamp > this.#lastSourceTs) {
+      this.#lastSourceTs = unwrappedTimestamp
+    } else if (!advancesHorizon && unwrappedTimestamp > this.#recoveredHorizonTs) {
+      this.#recoveredHorizonTs = unwrappedTimestamp
+    }
+
+    if (this.#ordersSamples()) {
+      this.#queueSample(sample)
+      return
+    }
+    this.#emitArrivalOrdered(sample)
+  }
+
+  #emitArrivalOrdered(sample: OrderedSample): void {
+    if (this.#config.trackType === 'video' && !this.#armedVideo && !sample.keyframe) {
+      this.#sampleOrderStats.preRapDeadlineDrops++
+      return
+    }
+    this.#emitSampleNow(sample)
+  }
+
+  #queueSample(sample: OrderedSample): void {
+    if (this.#sampleReorderQueue.some(s => s.timestamp === sample.timestamp)) {
+      this.#sampleOrderStats.duplicateSamples++
+      return
+    }
+    this.#sampleReorderQueue.push(sample)
+    this.#sampleReorderQueue.sort((a, b) => a.timestamp - b.timestamp)
+    this.#drainSampleReorder(false)
+    this.#enforceSampleOrderCapacity()
+  }
+
+  #releaseHorizon(): number {
+    return this.#lastSourceTs >= 0 ? this.#lastSourceTs : this.#recoveredHorizonTs
+  }
+
+  #sampleIsReleasable(sample: OrderedSample, flushAll: boolean): boolean {
+    if (flushAll) return true
+    if (this.#sampleOrder.mode === 'media-window') {
+      const horizon = this.#releaseHorizon()
+      return horizon >= 0 && sample.timestamp < horizon - this.#sampleOrder.deliveryWindow
+    }
+    return this.#sampleReorderQueue.length > this.#sampleReorderWindow
+  }
+
+  #dropPreRapSamples(flushAll: boolean): boolean {
+    if (this.#config.trackType !== 'video' || this.#armedVideo) return false
+
+    const firstRap = this.#sampleReorderQueue.findIndex(
+      sample => sample.keyframe && this.#sampleIsReleasable(sample, flushAll),
+    )
+    if (firstRap >= 0) {
+      if (firstRap > 0) {
+        this.#sampleOrderStats.preRapDeadlineDrops += firstRap
+        this.#sampleReorderQueue.splice(0, firstRap)
+      }
+      return false
+    }
+
+    let dropped = 0
+    while (
+      this.#sampleReorderQueue[0] &&
+      this.#sampleIsReleasable(this.#sampleReorderQueue[0]!, flushAll)
+    ) {
+      this.#sampleReorderQueue.shift()
+      dropped++
+    }
+    if (flushAll) this.#sampleOrderStats.noRapFlushDrops += dropped
+    else this.#sampleOrderStats.preRapDeadlineDrops += dropped
+    return dropped > 0
+  }
+
+  #drainSampleReorder(flushAll: boolean): void {
+    while (this.#sampleReorderQueue.length > 0) {
+      if (this.#dropPreRapSamples(flushAll) && this.#sampleReorderQueue.length === 0) return
+      const sample = this.#sampleReorderQueue[0]
+      if (!sample || !this.#sampleIsReleasable(sample, flushAll)) return
+      this.#sampleReorderQueue.shift()
+      this.#emitQueuedSample(sample)
+    }
+  }
+
+  #emitQueuedSample(sample: OrderedSample): void {
+    const next = this.#sampleReorderQueue.find(s => s.timestamp > sample.timestamp)
+    const duration = sample.authoredTiming
+      ? sample.duration
+      : next ? next.timestamp - sample.timestamp : sample.duration
+    this.#emitSampleNow({
+      ...sample,
+      duration: duration > 0
+        ? duration
+        : sample.authoredTiming ? sample.duration : this.#frameDuration,
+    })
+  }
+
+  #enforceSampleOrderCapacity(): void {
+    if (this.#sampleOrder.mode !== 'media-window') return
+    while (this.#sampleReorderQueue.length > this.#sampleOrderCapacity) {
+      const sample = this.#sampleReorderQueue.shift()
+      if (!sample) return
+      this.#sampleOrderStats.forcedReleases++
+      console.warn(
+        `[CmafBlockAssembler] ${this.#config.trackType} media-window queue exceeded ` +
+        `${this.#sampleOrderCapacity} samples; force-releasing timestamp=${sample.timestamp}`,
+      )
+      if (this.#config.trackType === 'video' && !this.#armedVideo && !sample.keyframe) {
+        this.#sampleOrderStats.preRapDeadlineDrops++
+        continue
+      }
+      this.#emitQueuedSample(sample)
+    }
+  }
+
+  #emitSampleNow(sample: CmafBlockSample): void {
+    if (sample.timestamp <= this.#lastEmittedTs) {
+      this.#sampleOrderStats.staleSamples++
+      return
+    }
+    this.#emitAudioGapFillNowBefore(sample.timestamp)
+    this.#writeSampleNow(sample, true)
+  }
+
+  #writeSampleNow(sample: CmafBlockSample, rememberAudio: boolean): void {
+    const { timestamp, duration, keyframe } = sample
+    this.#lastEmittedTs = timestamp
+    if (this.#config.trackType === 'video' && keyframe) this.#armedVideo = true
+    const data = this.#normalizeSampleData(sample.data)
+    if (this.#config.trackType === 'audio' && rememberAudio && data.length > 0) {
+      // Keep decoder-proven codec data for concealment only after the FEC
+      // delivery deadline has passed without the missing audio sample.
+      this.#lastDecodableAudioFrame = data.slice()
+    }
+    if (this.onSample) {
+      this.onSample(data === sample.data ? sample : { ...sample, data })
+    } else {
+      const baseTime = this.#rebase(timestamp)
+      const segment = encodeDataSegment(
+        data,
+        baseTime,
+        duration,
+        keyframe,
+        this.#sequence++,
+        this.#config.trackId,
+        sample.compositionTimeOffset,
+      )
+      this.onSegment?.(segment)
+    }
+  }
+
+  #emitAudioGapFillNowBefore(timestamp: number): void {
+    if (
+      this.#config.trackType !== 'audio' ||
+      this.#lastEmittedTs < 0 ||
+      this.#lastDecodableAudioFrame === null
+    ) return
+
+    const gap = timestamp - this.#lastEmittedTs
+    if (gap <= this.#frameDuration * 1.5) return
+
+    const missingFrames = Math.max(0, Math.round(gap / this.#frameDuration) - 1)
+    for (let i = 0; i < missingFrames; i++) {
+      const fillTs = this.#lastEmittedTs + this.#frameDuration
+      this.#writeSampleNow({
+        data: this.#lastDecodableAudioFrame.slice(),
+        timestamp: fillTs,
+        duration: this.#frameDuration,
+        keyframe: true,
+      }, false)
+    }
+  }
+
+  #emitPerSample(
+    frames: BlockFrame[],
+    audioDurationOverride?: number,
+    advancesHorizon = false,
+  ): void {
+    for (let i = 0; i < frames.length; i++) {
+      const f = frames[i]!
+      // Per-frame duration from delta to next frame, or fallback.
+      let duration: number
+      if (this.#config.trackType === 'audio') {
+        duration = audioDurationOverride ?? this.#frameDuration
+      } else if (i < frames.length - 1) {
+        duration = frames[i + 1]!.timestamp - f.timestamp
+      } else if (i > 0) {
+        duration = f.timestamp - frames[i - 1]!.timestamp
+      } else {
+        duration = audioDurationOverride ?? this.#frameDuration
+      }
+      if (duration <= 0) duration = audioDurationOverride ?? this.#frameDuration
+      this.#emitSample(
+        f.data,
+        f.timestamp,
+        duration,
+        f.keyframe,
+        advancesHorizon,
+        f.catalogTrackName,
+        f.mpuSequenceNumber,
+        f.packetSequenceNumber,
+        f.packetSequenceNumbers,
+        f.repairedPacketSequenceNumbers,
+        f.authoredTiming,
+        f.deliveryProvenance,
+      )
+    }
+  }
+
+  // [BLO-3035-LAYER4-DIAG] Byte-dump for the first 6 video emits + 1Hz
+  // aggregate counters that survive the whole run. The counters tell us
+  // whether "emits=low" (assembler emits too few segments) or
+  // "addFrame=low" (parser delivers too few frames) — which routes the
+  // root-cause hunt to assembler vs router vs publisher.
+  #dumpCount = 0
+  #emitCount = 0
+  #sampleCount = 0
+  #keyframeCount = 0
+  #addFrameCount = 0
+  #recoveredBlockCount = 0
+  #completeBlockCount = 0
+  #failBlockCount = 0
+  #aggregateTimer: ReturnType<typeof setInterval> | null = null
+  #startAggregateTimer(): void {
+    if (this.#aggregateTimer) return
+    this.#aggregateTimer = setInterval(() => {
+      console.log(
+        `[L4-AGG-${this.#config.trackType}] emits=${this.#emitCount} samples=${this.#sampleCount} ` +
+        `kf=${this.#keyframeCount} addFrame=${this.#addFrameCount} ` +
+        `recovered=${this.#recoveredBlockCount} complete=${this.#completeBlockCount} ` +
+        `fail=${this.#failBlockCount} pendingBlocks=${this.#blocks.size} ` +
+        `pendingFlushes=${this.#pendingFlush.size} armedVideo=${this.#armedVideo}`,
+      )
+      this.#emitCount = 0
+      this.#sampleCount = 0
+      this.#keyframeCount = 0
+      this.#addFrameCount = 0
+      this.#recoveredBlockCount = 0
+      this.#completeBlockCount = 0
+      this.#failBlockCount = 0
+    }, 1000)
+  }
+  #dumpEmit(path: string, samples: Array<{ data: Uint8Array; keyframe: boolean; timestamp?: number }>, sbn?: number): void {
+    this.#emitCount++
+    this.#sampleCount += samples.length
+    this.#keyframeCount += samples.filter(s => s.keyframe).length
+    // Always log video keyframes (no cap) — needed to see bytes of every IDR
+    // including the t=5s one that Chrome's decoder rejected (BLO-3035 L4).
+    const anyKf = this.#config.trackType === 'video' && samples.some(s => s.keyframe)
+    if (this.#config.trackType !== 'video' || (this.#dumpCount >= 6 && !anyKf)) return
+    this.#dumpCount++
+    const s0 = samples[0]
+    if (!s0) return
+    const d = s0.data
+    const hex = Array.from(d.subarray(0, Math.min(48, d.length)))
+      .map(b => (b as number).toString(16).padStart(2, '0'))
+      .join(' ')
+    // djb2 hash of full s0 buffer — used to compare clean vs FEC-recovered emit bytes.
+    let h = 5381
+    for (let i = 0; i < d.length; i++) h = (h * 33 + (d[i] as number)) | 0
+    const hash = (h >>> 0).toString(16).padStart(8, '0')
+    const ts0 = s0.timestamp ?? -1
+    const tsN = samples[samples.length - 1]?.timestamp ?? -1
+    console.log(
+      `[L4-DIAG] EMIT#${this.#dumpCount} path=${path}${sbn !== undefined ? ` sbn=${sbn}` : ''} ` +
+      `samples=${samples.length} s0.kf=${s0.keyframe} s0.len=${d.length} ` +
+      `ts0=${ts0} tsN=${tsN} dur=${tsN - ts0} hash=${hash} first48=[${hex}]`,
+    )
+  }
+
+  constructor(config: BlockAssemblerConfig) {
+    this.#config = {
+      k: config.k,
+      timescale: config.timescale ?? 1_000_000,
+      trackId: config.trackId ?? 1,
+      trackType: config.trackType,
+    }
+
+    // Compute default frame duration from fps (updated from timestamp deltas at runtime)
+    if (config.fps && config.fps > 0) {
+      this.#frameDuration = Math.round(this.#config.timescale / config.fps)
+    } else if (config.trackType === 'audio' && config.sampleRate) {
+      this.#frameDuration = Math.round(this.#config.timescale * 1024 / config.sampleRate)
+    } else {
+      // No fps info — will be refined from actual timestamp deltas
+      this.#frameDuration = 33333
+    }
+
+    // Build fill frame based on track type (requires codec config from catalog)
+    if (config.trackType === 'video' && config.avcC && config.width && config.height) {
+      this.#fillFrame = generateGreenFillNAL(config.avcC, config.width, config.height)
+    } else {
+      this.#fillFrame = new Uint8Array(0)
+    }
+
+    const sampleReorderWindow = config.sampleReorderWindow ?? 0
+    if (!Number.isFinite(sampleReorderWindow) || sampleReorderWindow < 0) {
+      throw new Error('[CmafBlockAssembler] sampleReorderWindow must be finite and non-negative')
+    }
+    if (config.sampleOrder && sampleReorderWindow > 0) {
+      throw new Error('[CmafBlockAssembler] configure sampleOrder or sampleReorderWindow, not both')
+    }
+    this.#sampleReorderWindow = Math.floor(sampleReorderWindow)
+    this.#sampleOrder = config.sampleOrder ?? { mode: 'arrival' }
+    if (this.#sampleOrder.mode === 'media-window') {
+      const { deliveryWindow, timestampWrapPeriod } = this.#sampleOrder
+      if (!Number.isSafeInteger(deliveryWindow) || deliveryWindow <= 0) {
+        throw new Error(
+          '[CmafBlockAssembler] media-window deliveryWindow must be a positive safe integer',
+        )
+      }
+      if (
+        timestampWrapPeriod !== undefined &&
+        (!Number.isSafeInteger(timestampWrapPeriod) || timestampWrapPeriod <= deliveryWindow * 2)
+      ) {
+        throw new Error(
+          '[CmafBlockAssembler] timestampWrapPeriod must be a safe integer larger than two delivery windows',
+        )
+      }
+      const samplesPerSecond = config.trackType === 'audio' && config.sampleRate
+        ? config.sampleRate / 1024
+        : config.fps
+      if (!samplesPerSecond || !Number.isFinite(samplesPerSecond) || samplesPerSecond <= 0) {
+        throw new Error(
+          '[CmafBlockAssembler] media-window ordering requires catalog-derived media cadence',
+        )
+      }
+      this.#sampleOrderCapacity =
+        Math.ceil(deliveryWindow * samplesPerSecond / this.#config.timescale) + 1
+    }
+    this.#validateH264Keyframes =
+      config.trackType === 'video' &&
+      (!!config.avcC || !config.codec || isH264Codec(config.codec))
+    if (config.trackType === 'video') {
+      console.log(
+        `[L4-KF-CONFIG] validate=${this.#validateH264Keyframes} ` +
+        `codec=${config.codec ?? ''} avcC=${config.avcC?.length ?? 0}`,
+      )
+    }
+
+    // Store config for init segment generation
+    this._videoConfig = config.trackType === 'video' && config.avcC
+      ? { avcC: config.avcC, width: config.width ?? 0, height: config.height ?? 0 }
+      : null
+    this._audioConfig = config.trackType === 'audio' && config.sampleRate && config.channels
+      ? { sampleRate: config.sampleRate, channels: config.channels, asc: config.asc }
+      : null
+  }
+
+  private _videoConfig: { avcC?: Uint8Array; width: number; height: number } | null
+  private _audioConfig: { sampleRate: number; channels: number; asc?: Uint8Array } | null
+
+  get sampleOrderStats(): Readonly<CmafSampleOrderStats> {
+    return { ...this.#sampleOrderStats }
+  }
+
+  /** Emit a single frame immediately as a one-sample moof+mdat segment.
+   *
+   *  BLO-3035 layer 4 (4b): the prior SBN-grouped buffering scheme stranded
+   *  frames whenever a multi-packet frame spanned FEC block boundaries —
+   *  intermediate SBNs had packets-but-no-frames and got `completeBlock`
+   *  events that landed on empty `#blocks` (→ `pendingFlush` leak), while
+   *  the SBN where the multi-packet frame finally completed received the
+   *  `addFrame` but its `trackBlock` count never reached K (→ `pendingBlocks`
+   *  leak). Result: ~50% of received frames never reached MSE.
+   *
+   *  This path now mirrors `addBypassFrame` — emit on arrival, no buffering.
+   *  FEC recovery (`addRecoveredBlock`) keeps its SBN-watermark dedup against
+   *  the same SBN being re-emitted from two paths. Out-of-order regression
+   *  is guarded by the per-frame `lastEmittedTs` check (also enforced in
+   *  `#emitPerSample`). The `sbn`/`esi` parameters are kept for the call-site
+   *  signature but no longer affect routing. */
+  addFrame(
+    sbn: number,
+    esi: number,
+    data: Uint8Array,
+    timestamp: number,
+    keyframe: boolean,
+    catalogTrackName?: string,
+    mpuSequenceNumber?: number,
+    packetSequenceNumber?: number,
+    packetSequenceNumbers?: number[],
+    repairedPacketSequenceNumbers?: number[],
+    authoredTiming?: AuthoredTiming,
+    deliveryProvenance?: MmtpDeliveryProvenance,
+  ): void {
+    void sbn; void esi
+    this.#addFrameCount++
+    this.#startAggregateTimer()
+
+    if (!this.#ordersSamples()) this.#drainRecoveredUpTo(timestamp)
+
+    // Per-frame duration: default to catalog-derived `#frameDuration`. For
+    // variable-rate content Chrome refines duration from the next sample's
+    // DTS at append time, so a fallback here is safe.
+    this.#emitSample(
+      data,
+      timestamp,
+      this.#frameDuration,
+      keyframe,
+      true,
+      catalogTrackName,
+      mpuSequenceNumber,
+      packetSequenceNumber,
+      packetSequenceNumbers,
+      repairedPacketSequenceNumbers,
+      authoredTiming,
+      deliveryProvenance,
+    )
+
+    // Stats — #dumpEmit increments emit/sample/keyframe counters internally.
+    this.#dumpEmit('addFrame-direct', [{ data, timestamp, keyframe }])
+  }
+
+  /** Mark a block as complete (all K source symbols received or FEC recovery succeeded).
+   *  If all frames are already buffered, flushes immediately. Otherwise sets pending-flush. */
+  completeBlock(sbn: number): void {
+    void sbn
+    this.#completeBlockCount++
+    this.#startAggregateTimer()
+    // Source samples are emitted directly from addFrame(). A clean FEC block
+    // completion is still useful for stats, but it must not enqueue stale
+    // pending flushes from the retired block-buffered path.
+  }
+
+  /** Handle block timeout — emit whatever frames we have + fill for missing slots. */
+  failBlock(sbn: number): void {
+    this.#failBlockCount++
+    this.#startAggregateTimer()
+    this.#pendingFlush.delete(sbn)
+    const block = this.#blocks.get(sbn)
+    if (!block || block.size === 0) {
+      this.#blocks.delete(sbn)
+      return
+    }
+    this.#flushBlockWithFill(sbn)
+  }
+
+  /** Add all frames from a FEC-recovered block at once and emit immediately. */
+  addRecoveredBlock(sbn: number, frames: BlockFrame[]): void {
+    void sbn
+    this.#recoveredBlockCount++
+    this.#startAggregateTimer()
+    // Build samples directly — recovered frames are already sorted
+    this.#pendingFlush.delete(sbn)
+    this.#blocks.delete(sbn)
+
+    if (frames.length === 0) return
+    const normalized = this.#normalizeVideoKeyframes(frames)
+    this.#dumpEmit('addRecoveredBlock', normalized, sbn)
+    if (this.#ordersSamples()) {
+      this.#emitPerSample(normalized, undefined, false)
+      return
+    }
+
+    // Arrival mode preserves the legacy protection against future recovered
+    // samples advancing past source media. Explicit media-window mode routes
+    // both paths through one queue instead.
+    if (this.#lastSourceTs >= 0) {
+      this.#enqueueRecovered(normalized)
+      this.#drainRecoveredUpTo(this.#lastSourceTs)
+    } else {
+      const gated = this.#applyVideoKeyframeGate(normalized)
+      if (gated) this.#emitPerSample(gated, undefined, false)
+    }
+  }
+
+  /** Emit a single frame immediately as a one-sample segment (for oversized packets bypassing FEC). */
+  addBypassFrame(
+    data: Uint8Array,
+    timestamp: number,
+    keyframe: boolean,
+    catalogTrackName?: string,
+    mpuSequenceNumber?: number,
+    packetSequenceNumber?: number,
+    packetSequenceNumbers?: number[],
+    repairedPacketSequenceNumbers?: number[],
+    authoredTiming?: AuthoredTiming,
+    deliveryProvenance?: MmtpDeliveryProvenance,
+  ): void {
+    if (!this.#ordersSamples()) this.#drainRecoveredUpTo(timestamp)
+    this.#emitSample(
+      data,
+      timestamp,
+      this.#frameDuration,
+      keyframe,
+      true,
+      catalogTrackName,
+      mpuSequenceNumber,
+      packetSequenceNumber,
+      packetSequenceNumbers,
+      repairedPacketSequenceNumbers,
+      authoredTiming,
+      deliveryProvenance,
+    )
+  }
+
+  /** Build and emit init segment from catalog config. */
+  emitInit(): void {
+    let init: Uint8Array | null = null
+    if (this._videoConfig?.avcC) {
+      init = buildVideoInitSegment(
+        this._videoConfig.avcC,
+        this._videoConfig.width,
+        this._videoConfig.height,
+        this.#config.timescale,
+        this.#config.trackId,
+      )
+    } else if (this._audioConfig) {
+      init = buildAudioInitSegment(
+        this._audioConfig.sampleRate,
+        this._audioConfig.channels,
+        this._audioConfig.asc,
+        this.#config.timescale,
+        this.#config.trackId,
+      )
+    }
+    if (init) this.onInitSegment?.(init)
+  }
+
+  /** Drain all ordered samples at end-of-stream or before reconfiguration. */
+  flush(): void {
+    if (this.#ordersSamples()) {
+      this.#drainSampleReorder(true)
+      return
+    }
+    if (this.#pendingRecovered.size === 0) return
+    const frames = [...this.#pendingRecovered.values()].sort((a, b) => a.timestamp - b.timestamp)
+    this.#pendingRecovered.clear()
+    const gated = this.#applyVideoKeyframeGate(frames)
+    if (gated) this.#emitPerSample(gated, undefined, false)
+    else if (this.#config.trackType === 'video') {
+      this.#sampleOrderStats.noRapFlushDrops += frames.length
+    }
+  }
+
+  /** Drop all queued state and begin a fresh timestamp epoch. */
+  reset(): void {
+    this.#blocks.clear()
+    this.#pendingFlush.clear()
+    this.#pendingRecovered.clear()
+    this.#sequence = 1
+    this.#baseTs = -1
+    this.#lastEmittedTs = -1
+    this.#lastSourceTs = -1
+    this.#recoveredHorizonTs = -1
+    this.#lastDecodableAudioFrame = null
+    this.#armedVideo = false
+    this.#lastEmittedSbn = -1
+    this.#sampleReorderQueue = []
+  }
+
+  dispose(): void {
+    this.reset()
+    this.onSegment = null
+    this.onSample = null
+    this.onInitSegment = null
+    if (this.#aggregateTimer) {
+      clearInterval(this.#aggregateTimer)
+      this.#aggregateTimer = null
+    }
+  }
+
+  // ── Private ──
+
+  /** Rebase an absolute timestamp to relative media time (starting near 0). */
+  #rebase(timestamp: number): number {
+    if (this.#baseTs < 0) this.#baseTs = timestamp
+    return timestamp - this.#baseTs
+  }
+
+  #normalizeSampleData(data: Uint8Array): Uint8Array {
+    return this.#config.trackType === 'audio' ? normalizeAacSampleForCmaf(data) : data
+  }
+
+  #enqueueRecovered(frames: BlockFrame[]): void {
+    for (const frame of frames) {
+      if (this.#lastEmittedTs >= 0 && frame.timestamp <= this.#lastEmittedTs) {
+        this.#sampleOrderStats.staleSamples++
+        continue
+      }
+      if (this.#pendingRecovered.has(frame.timestamp)) {
+        this.#sampleOrderStats.duplicateSamples++
+        continue
+      }
+      this.#pendingRecovered.set(frame.timestamp, frame)
+    }
+  }
+
+  #drainRecoveredUpTo(horizonTs: number): void {
+    if (this.#pendingRecovered.size === 0) return
+    const ready = [...this.#pendingRecovered.values()]
+      .filter(frame => frame.timestamp <= horizonTs)
+      .sort((a, b) => a.timestamp - b.timestamp)
+
+    for (const frame of ready) {
+      this.#pendingRecovered.delete(frame.timestamp)
+      this.#emitSample(
+        frame.data,
+        frame.timestamp,
+        this.#frameDuration,
+        frame.keyframe,
+        false,
+        frame.catalogTrackName,
+        frame.mpuSequenceNumber,
+        frame.packetSequenceNumber,
+        frame.packetSequenceNumbers,
+        frame.repairedPacketSequenceNumbers,
+        frame.authoredTiming,
+        frame.deliveryProvenance,
+      )
+      this.#dumpEmit('recovered-drain', [frame])
+    }
+  }
+
+  /** Flush a block's buffered frames as a multi-sample CMAF segment. */
+  #flushBlock(sbn: number): void {
+    const block = this.#blocks.get(sbn)
+    if (!block || block.size === 0) {
+      this.#blocks.delete(sbn)
+      return
+    }
+
+    // Sort by ESI to restore original frame order
+    const entries = [...block.entries()].sort((a, b) => a[0] - b[0])
+    const sortedFrames = entries.map(([, f]) => f)
+    this.#blocks.delete(sbn)
+
+    if (!this.#claimSbnEmission(sbn)) return
+    const frames = this.#applyVideoKeyframeGate(sortedFrames)
+    if (!frames) return
+
+    this.#dumpEmit('flushBlock', frames, sbn)
+    this.#emitPerSample(frames)
+  }
+
+  /** Flush a block with fill frames for missing ESI slots (FEC timeout path). */
+  #flushBlockWithFill(sbn: number): void {
+    const block = this.#blocks.get(sbn)
+    if (!block) return
+
+    const k = this.#config.k
+    const isVideo = this.#config.trackType === 'video'
+    const firstAudioFrame = !isVideo
+      ? [...block.values()].sort((a, b) => a.timestamp - b.timestamp)[0]?.data
+      : undefined
+    const audioConcealmentFrame = this.#lastDecodableAudioFrame ?? firstAudioFrame
+
+    // Build full K-slot array: real frames + fill for missing
+    const allFrames: BlockFrame[] = []
+    let lastRealTs = -1
+    let firstRealTs = -1
+
+    // Find min/max timestamps from received frames to interpolate missing ones
+    for (const [, f] of block) {
+      if (firstRealTs < 0 || f.timestamp < firstRealTs) firstRealTs = f.timestamp
+      if (f.timestamp > lastRealTs) lastRealTs = f.timestamp
+    }
+    const estimatedBlockDuration = block.size > 1
+      ? (lastRealTs - firstRealTs) / (block.size - 1) * k
+      : this.#frameDuration * k
+
+    for (let esi = 0; esi < k; esi++) {
+      const real = block.get(esi)
+      if (real) {
+        allFrames.push(real)
+      } else {
+        // Interpolate timestamp for missing slot
+        const interpolatedTs = firstRealTs >= 0
+          ? firstRealTs + Math.round(esi * estimatedBlockDuration / k)
+          : (this.#lastEmittedTs >= 0
+            ? this.#lastEmittedTs + this.#frameDuration * (esi + 1)
+            : 0)
+        allFrames.push({
+          // A synthesized AAC access unit is not portable across every
+          // AudioSpecificConfig. Repeat known-good encoded audio instead;
+          // if this is the first block, use its earliest received sample.
+          data: isVideo
+            ? this.#fillFrame
+            : (audioConcealmentFrame?.slice() ?? new Uint8Array(0)),
+          timestamp: interpolatedTs,
+          // Video: first fill is keyframe (IDR). Audio: all fill marked keyframe.
+          keyframe: isVideo ? !block.has(0) && esi === 0 : true,
+        })
+      }
+    }
+
+    this.#blocks.delete(sbn)
+    if (!this.#claimSbnEmission(sbn)) return
+    const gatedFrames = this.#applyVideoKeyframeGate(allFrames)
+    if (!gatedFrames) return
+
+    this.#emitPerSample(gatedFrames)
+  }
+}
+
+function isH264Codec(codec?: string): boolean {
+  const c = codec?.toLowerCase()
+  return c?.startsWith('avc1') === true || c?.startsWith('avc3') === true
+}
+
+function describeH264NalTypes(nals: Uint8Array[]): number[] {
+  return nals.slice(0, 16).map((nal) => (
+    nal[0] !== undefined ? nal[0] & 0x1f : -1
+  ))
+}