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

package/src/mmtp-to-cmaf.ts

@@ -0,0 +1,1024 @@
+/**
+ * MMTP → CMAF converter per draft-ramadan-moq-mmt §5.3.
+ *
+ * Converts reassembled MFU frames (raw codec samples from MMTP) into
+ * fMP4 segments (moof+mdat) suitable for MSE SourceBuffer.appendBuffer().
+ *
+ * MPU metadata (fragment_type=0) packets from FFmpeg are complete
+ * ftyp+moov init segments and can be used directly as MSE init data.
+ *
+ * MFU data (fragment_type=2) contains raw AVCC samples that must be
+ * wrapped in moof+mdat boxes for MSE consumption.
+ *
+ * ISO 14496-12 (ISOBMFF) box construction is inline — no dependencies.
+ */
+
+// ── ISOBMFF box helpers ──
+
+function box(type: string, ...children: Uint8Array[]): Uint8Array {
+  let size = 8
+  for (const c of children) size += c.length
+  const buf = new Uint8Array(size)
+  new DataView(buf.buffer).setUint32(0, size)
+  buf[4] = type.charCodeAt(0)
+  buf[5] = type.charCodeAt(1)
+  buf[6] = type.charCodeAt(2)
+  buf[7] = type.charCodeAt(3)
+  let pos = 8
+  for (const c of children) {
+    buf.set(c, pos)
+    pos += c.length
+  }
+  return buf
+}
+
+function fullBox(type: string, version: number, flags: number, ...children: Uint8Array[]): Uint8Array {
+  let size = 12
+  for (const c of children) size += c.length
+  const buf = new Uint8Array(size)
+  const dv = new DataView(buf.buffer)
+  dv.setUint32(0, size)
+  buf[4] = type.charCodeAt(0)
+  buf[5] = type.charCodeAt(1)
+  buf[6] = type.charCodeAt(2)
+  buf[7] = type.charCodeAt(3)
+  dv.setUint32(8, (version << 24) | (flags & 0xffffff))
+  let pos = 12
+  for (const c of children) {
+    buf.set(c, pos)
+    pos += c.length
+  }
+  return buf
+}
+
+function u32(v: number): Uint8Array {
+  const b = new Uint8Array(4)
+  new DataView(b.buffer).setUint32(0, v)
+  return b
+}
+
+// ── Sample flags per ISO 14496-12 §8.8.3.1 ──
+const KEYFRAME_FLAGS = 0x02000000
+const DELTA_FLAGS = 0x01010000
+
+// ── Track geometry field ranges per ISO 14496-12 ──
+// tkhd/trex/tfhd track_ID and the mdhd/mvhd timescales are all unsigned 32-bit
+// fields, written below with DataView.setUint32. That call takes the value
+// modulo 2^32 without complaint, so an out-of-range configuration does not
+// fail — it silently emits different geometry than the caller asked for
+// (trackId 2^32 becomes track 0, which no fragment can ever reference).
+const UINT32_MAX = 0xffffffff
+// mvhd next_track_ID is emitted as track_ID + 1 by both buildVideoInitSegment
+// and buildAudioInitSegment (ISO 14496-12 §8.2.2.3, "a non-zero integer"). At
+// track_ID = UINT32_MAX that sum wraps to 0, which is both invalid and
+// indistinguishable from an unset field, so the largest usable track_ID is one
+// below the field maximum. (Cited by symbol, not line: this repo's docs gate
+// exists because line anchors rot silently — see rustfmt.yml's citation check.)
+const MAX_TRACK_ID = UINT32_MAX - 1
+const INT32_MIN = -0x80000000
+const INT32_MAX = 0x7fffffff
+
+/**
+ * Fail closed on a track_ID the fMP4 writers below cannot serialize faithfully.
+ *
+ * Called from both low-level encoders (encodeDataSegment,
+ * encodeMultiSampleSegment) so every fragment path is covered by construction
+ * rather than by enumerating callers. The class wrappers and init builders call
+ * it earlier as well — partly for a clearer label, partly because the encoders
+ * receive an already-incremented sequence number, so their throw would gap the
+ * sequence on a call that emitted nothing.
+ */
+function assertTrackId(trackId: number, label: string): void {
+  if (!Number.isInteger(trackId) || trackId <= 0 || trackId > MAX_TRACK_ID) {
+    throw new RangeError(`${label} must be an integer in 1..${MAX_TRACK_ID}, got ${trackId}`)
+  }
+}
+
+/** Fail closed on a timescale the mdhd/mvhd uint32 fields cannot hold. */
+function assertTimescale(timescale: number, label: string): void {
+  if (!Number.isInteger(timescale) || timescale <= 0 || timescale > UINT32_MAX) {
+    throw new RangeError(`${label} must be an integer in 1..${UINT32_MAX}, got ${timescale}`)
+  }
+}
+
+/** Fail closed on a signed trun sample_composition_time_offset. */
+function assertCompositionTimeOffsets(
+  samples: Array<{ compositionTimeOffset?: number }>,
+): void {
+  for (let i = 0; i < samples.length; i++) {
+    const offset = samples[i]!.compositionTimeOffset
+    if (offset !== undefined &&
+        (!Number.isInteger(offset) || offset < INT32_MIN || offset > INT32_MAX)) {
+      throw new RangeError(
+        `sample ${i} compositionTimeOffset must be an integer in ${INT32_MIN}..${INT32_MAX}, got ${offset}`,
+      )
+    }
+  }
+}
+
+/**
+ * Wrap multiple samples in a single moof+mdat fMP4 segment.
+ *
+ * Builds a trun with N sample entries (duration + size + flags each).
+ * Used by CmafBlockAssembler to emit one segment per FEC source block.
+ *
+ * @param samples - Array of samples with data, duration (timescale units), keyframe flag,
+ *   and an optional signed composition-time offset (same timescale units)
+ * @param baseDecodeTime - Decode time of the first sample in timescale units
+ * @param sequence - moof sequence number
+ * @param trackId - ISO track ID (default 1)
+ * @returns moof+mdat bytes ready for SourceBuffer.appendBuffer()
+ */
+export function encodeMultiSampleSegment(
+  samples: Array<{
+    data: Uint8Array
+    duration: number
+    keyframe: boolean
+    compositionTimeOffset?: number
+  }>,
+  baseDecodeTime: number,
+  sequence: number,
+  trackId = 1,
+): Uint8Array {
+  if (samples.length === 0) return new Uint8Array(0)
+  assertTrackId(trackId, 'trackId')
+  assertCompositionTimeOffsets(samples)
+
+  const mfhd = fullBox('mfhd', 0, 0, u32(sequence))
+  const tfhd = fullBox('tfhd', 0, 0x020000, u32(trackId))
+
+  // tfdt version=1 for 64-bit baseMediaDecodeTime
+  const tfdtBody = new Uint8Array(8)
+  const tfdtView = new DataView(tfdtBody.buffer)
+  tfdtView.setUint32(0, Math.floor(baseDecodeTime / 0x100000000))
+  tfdtView.setUint32(4, baseDecodeTime >>> 0)
+  const tfdt = fullBox('tfdt', 1, 0, tfdtBody)
+
+  // A composition-time offset is signed only in trun version 1. When one is
+  // present, every sample gets the field; omitted offsets are encoded as zero.
+  const hasCompositionTimeOffset = samples.some(sample => sample.compositionTimeOffset !== undefined)
+  const trunVersion = hasCompositionTimeOffset ? 1 : 0
+  const trunFlags = 0x000701 | (hasCompositionTimeOffset ? 0x000800 : 0)
+  // 4 bytes sample_count + 4 bytes data_offset + N * (4+4+4 [+4]) per sample
+  const sampleCount = samples.length
+  const sampleEntrySize = hasCompositionTimeOffset ? 16 : 12
+  const trunBody = new Uint8Array(8 + sampleCount * sampleEntrySize)
+  const trunView = new DataView(trunBody.buffer)
+  trunView.setUint32(0, sampleCount)
+  trunView.setUint32(4, 0) // dataOffset placeholder
+  for (let i = 0; i < sampleCount; i++) {
+    const s = samples[i]!
+    const off = 8 + i * sampleEntrySize
+    trunView.setUint32(off, s.duration >>> 0)
+    trunView.setUint32(off + 4, s.data.length)
+    trunView.setUint32(off + 8, s.keyframe ? KEYFRAME_FLAGS : DELTA_FLAGS)
+    if (hasCompositionTimeOffset) {
+      trunView.setInt32(off + 12, s.compositionTimeOffset ?? 0)
+    }
+  }
+  const trun = fullBox('trun', trunVersion, trunFlags, trunBody)
+
+  const traf = box('traf', tfhd, tfdt, trun)
+  const moof = box('moof', mfhd, traf)
+
+  // Concatenate all sample data into mdat
+  let mdatSize = 0
+  for (const s of samples) mdatSize += s.data.length
+  const mdatPayload = new Uint8Array(mdatSize)
+  let pos = 0
+  for (const s of samples) {
+    mdatPayload.set(s.data, pos)
+    pos += s.data.length
+  }
+  const mdat = box('mdat', mdatPayload)
+
+  // Fix trun.dataOffset: moof size + 8 (mdat box header)
+  const dataOffsetPos = 8 + mfhd.length + 8 + tfhd.length + tfdt.length + 12 + 4
+  new DataView(moof.buffer).setUint32(dataOffsetPos, moof.length + 8)
+
+  const result = new Uint8Array(moof.length + mdat.length)
+  result.set(moof, 0)
+  result.set(mdat, moof.length)
+  return result
+}
+
+// ── Green fill / silence generators ──
+
+/**
+ * Generate a minimal H.264 IDR slice NAL for green fill (YUV 0,128,128).
+ *
+ * Reuses SPS/PPS from the stream's avcC so the fill frame is compatible
+ * with the existing decoder configuration. Returns AVCC-framed data
+ * (4-byte length prefix per NAL) ready for moof+mdat wrapping.
+ *
+ * @param avcC - Raw avcC payload from catalog description
+ * @param width - Video width in pixels
+ * @param height - Video height in pixels
+ */
+export function generateGreenFillNAL(avcC: Uint8Array, width: number, height: number): Uint8Array {
+  // Parse SPS and PPS from avcC box payload
+  // avcC layout: version(1) + profile(1) + compat(1) + level(1) + lengthSizeMinusOne(1)
+  //              + numSPS(1) + [spsLen(2) + spsData]... + numPPS(1) + [ppsLen(2) + ppsData]...
+  if (avcC.length < 8) return new Uint8Array(0)
+
+  const lengthSize = (avcC[4]! & 0x03) + 1 // NAL length field size (usually 4)
+  let offset = 5
+  const numSPS = avcC[offset++]! & 0x1f
+  const nals: Uint8Array[] = []
+
+  // Extract SPS NAL(s)
+  for (let i = 0; i < numSPS; i++) {
+    if (offset + 2 > avcC.length) break
+    const spsLen = (avcC[offset]! << 8) | avcC[offset + 1]!
+    offset += 2
+    if (offset + spsLen > avcC.length) break
+    const sps = avcC.subarray(offset, offset + spsLen)
+    // AVCC frame: 4-byte length + NAL
+    const framed = new Uint8Array(4 + sps.length)
+    new DataView(framed.buffer).setUint32(0, sps.length)
+    framed.set(sps, 4)
+    nals.push(framed)
+    offset += spsLen
+  }
+
+  // Extract PPS NAL(s)
+  if (offset < avcC.length) {
+    const numPPS = avcC[offset++]!
+    for (let i = 0; i < numPPS; i++) {
+      if (offset + 2 > avcC.length) break
+      const ppsLen = (avcC[offset]! << 8) | avcC[offset + 1]!
+      offset += 2
+      if (offset + ppsLen > avcC.length) break
+      const pps = avcC.subarray(offset, offset + ppsLen)
+      const framed = new Uint8Array(4 + pps.length)
+      new DataView(framed.buffer).setUint32(0, pps.length)
+      framed.set(pps, 4)
+      nals.push(framed)
+      offset += ppsLen
+    }
+  }
+
+  // Build minimal IDR slice NAL (NAL type 5)
+  // Slice header: first_mb_in_slice=0, slice_type=7 (I), pic_parameter_set_id=0
+  // Exp-Golomb coded: 0(1 bit) + 0001000(slice_type=7=I-all, ue(v)) + 1(pps_id=0, ue(v))
+  // Then fill with green macroblocks.
+  //
+  // For a minimal valid IDR that decodes to green, we use:
+  //   nal_type=5 (IDR), slice_type=I, then CABAC/CAVLC all-intra-16x16
+  //   with luma DC=0, chroma DC=128. Exact encoding depends on SPS entropy mode.
+  //
+  // Simplified approach: generate a very small IDR slice that MSE will accept.
+  // The slice header + minimal macroblock data. The decoder fills with the
+  // predicted values which default to mid-gray/green.
+  const mbWidth = Math.ceil(width / 16)
+  const mbHeight = Math.ceil(height / 16)
+  const totalMBs = mbWidth * mbHeight
+
+  // Minimal IDR slice: nal_ref_idc=3, nal_type=5
+  // Slice header bits: first_mb=0 (1 bit ue), slice_type=7 (I-all, 0001000 ue),
+  //                    pps_id=0 (1 bit ue), frame_num=0 (depends on SPS log2_max)
+  // We construct a minimal bitstream that encodes an all-skip I-slice.
+  // For simplicity, build a fixed small IDR payload — the decoder will
+  // pad/error-conceal remaining MBs producing a solid fill frame.
+  const idrSlice = new Uint8Array([
+    0x65, // nal_ref_idc=3, nal_type=5 (IDR)
+    0x88, // slice header: first_mb_in_slice=0, slice_type=7 (I)
+    0x80, // pps_id=0, frame_num=0, idr_pic_id=0
+    0x40, // slice data: mb_skip_run covering remaining MBs
+    // Truncated — decoder will error-conceal remaining MBs as green/gray
+  ])
+  const idrFramed = new Uint8Array(4 + idrSlice.length)
+  new DataView(idrFramed.buffer).setUint32(0, idrSlice.length)
+  idrFramed.set(idrSlice, 4)
+  nals.push(idrFramed)
+
+  // Concatenate all NALs: SPS + PPS + IDR
+  let totalLen = 0
+  for (const n of nals) totalLen += n.length
+  const result = new Uint8Array(totalLen)
+  let p = 0
+  for (const n of nals) {
+    result.set(n, p)
+    p += n.length
+  }
+  return result
+}
+
+/**
+ * Generate a minimal silent audio frame for FEC fill.
+ *
+ * Supports AAC (mp4a) and Opus codecs. Returns raw frame data (no ADTS/OBU
+ * header) suitable for fMP4/CMAF wrapping.
+ *
+ * @param codec - Audio codec string (e.g. 'mp4a.40.2', 'opus')
+ * @param sampleRate - Audio sample rate (e.g. 48000)
+ * @param channels - Channel count (e.g. 1 or 2)
+ */
+export function generateSilenceFrame(codec: string, sampleRate: number, channels: number): Uint8Array {
+  if (codec.startsWith('opus') || codec.startsWith('Opus')) {
+    return generateSilenceOpus(channels)
+  }
+  return generateSilenceAAC(sampleRate, channels)
+}
+
+/** Minimal silent AAC-LC access unit (raw, no ADTS). */
+function generateSilenceAAC(sampleRate: number, channels: number): Uint8Array {
+  if (channels >= 2) {
+    // CPE (channel pair element) + END
+    return new Uint8Array([
+      0x21, 0x00, 0x49, 0x90, 0x02, 0x19, 0x00, 0x23, 0x80,
+    ])
+  }
+  // SCE (single channel element) + END
+  return new Uint8Array([
+    0x01, 0x00, 0x02, 0x00, 0x00, 0x00, 0x00,
+  ])
+}
+
+/** Minimal silent Opus frame.
+ *  RFC 6716 §3.1: a 1-byte frame with code 0 encodes silence for SILK/CELT. */
+function generateSilenceOpus(channels: number): Uint8Array {
+  // Opus TOC byte: config=0 (SILK NB 10ms), s=0 (mono/stereo from channel mapping), c=0 (1 frame)
+  // Frame data: single zero byte → silence
+  // For stereo, channel mapping in fMP4 init handles routing; the Opus frame itself is the same.
+  return new Uint8Array([0xF8, 0xFF, 0xFE])
+}
+
+export function normalizeAacSampleForCmaf(data: Uint8Array): Uint8Array {
+  if (data.length < 7 || data[0] !== 0xff || (data[1]! & 0xf6) !== 0xf0) {
+    return data
+  }
+  const headerLength = (data[1]! & 0x01) ? 7 : 9
+  if (data.length <= headerLength) return data
+  const frameLength = ((data[3]! & 0x03) << 11) | (data[4]! << 3) | ((data[5]! & 0xe0) >>> 5)
+  if (frameLength !== data.length || frameLength <= headerLength) return data
+  return data.subarray(headerLength)
+}
+
+/**
+ * Wrap a single raw codec sample in a moof+mdat fMP4 segment.
+ *
+ * @param data - Raw sample bytes (AVCC H.264 or raw AAC)
+ * @param timestamp - Decode time in timescale units
+ * @param duration - Sample duration in timescale units
+ * @param keyframe - true for IDR/sync sample
+ * @param sequence - moof sequence number (monotonically incrementing)
+ * @param trackId - ISO track ID (default 1)
+ * @returns moof+mdat bytes ready for SourceBuffer.appendBuffer()
+ */
+export function encodeDataSegment(
+  data: Uint8Array,
+  timestamp: number,
+  duration: number,
+  keyframe: boolean,
+  sequence: number,
+  trackId = 1,
+  compositionTimeOffset?: number,
+): Uint8Array {
+  assertTrackId(trackId, 'trackId')
+  assertCompositionTimeOffsets([{ compositionTimeOffset }])
+  if (compositionTimeOffset !== undefined) {
+    return encodeMultiSampleSegment(
+      [{ data, duration, keyframe, compositionTimeOffset }],
+      timestamp,
+      sequence,
+      trackId,
+    )
+  }
+  const sampleFlags = keyframe ? KEYFRAME_FLAGS : DELTA_FLAGS
+
+  const mfhd = fullBox('mfhd', 0, 0, u32(sequence))
+  const tfhd = fullBox('tfhd', 0, 0x020000, u32(trackId))
+
+  // tfdt version=1 for 64-bit baseMediaDecodeTime
+  const tfdtBody = new Uint8Array(8)
+  const tfdtView = new DataView(tfdtBody.buffer)
+  tfdtView.setUint32(0, Math.floor(timestamp / 0x100000000))
+  tfdtView.setUint32(4, timestamp >>> 0)
+  const tfdt = fullBox('tfdt', 1, 0, tfdtBody)
+
+  // trun: flags=0x000701 (data-offset + duration + size + flags)
+  const trunBody = new Uint8Array(20)
+  const trunView = new DataView(trunBody.buffer)
+  trunView.setUint32(0, 1) // sample_count
+  trunView.setUint32(4, 0) // dataOffset placeholder
+  trunView.setUint32(8, duration >>> 0)
+  trunView.setUint32(12, data.length)
+  trunView.setUint32(16, sampleFlags)
+  const trun = fullBox('trun', 0, 0x000701, trunBody)
+
+  const traf = box('traf', tfhd, tfdt, trun)
+  const moof = box('moof', mfhd, traf)
+  const mdat = box('mdat', data)
+
+  // Fix trun.dataOffset: moof size + 8 (mdat box header)
+  const dataOffsetPos = 8 + mfhd.length + 8 + tfhd.length + tfdt.length + 12 + 4
+  new DataView(moof.buffer).setUint32(dataOffsetPos, moof.length + 8)
+
+  const result = new Uint8Array(moof.length + mdat.length)
+  result.set(moof, 0)
+  result.set(mdat, moof.length)
+  return result
+}
+
+/**
+ * Build an ftyp+moov init segment for H.264 video MSE from an avcC box.
+ *
+ * @param avcC - Raw avcC box payload (SPS/PPS configuration)
+ * @param width - Video width in pixels
+ * @param height - Video height in pixels
+ * @param timescale - Timescale (default 1_000_000 = microseconds)
+ * @param trackId - Track ID (default 1)
+ */
+export function buildVideoInitSegment(
+  avcC: Uint8Array,
+  width: number,
+  height: number,
+  timescale = 1_000_000,
+  trackId = 1,
+): Uint8Array {
+  // Validated here as well as in setVideoTrackParams: this builder is exported
+  // from the package index, so a direct caller reaches the same uint32 tkhd /
+  // trex / mdhd / mvhd fields without passing through the class.
+  assertTrackId(trackId, 'video trackId')
+  assertTimescale(timescale, 'video timescale')
+  const ftyp = box('ftyp', new Uint8Array([
+    0x69, 0x73, 0x6f, 0x6d, 0, 0, 2, 0,
+    0x69, 0x73, 0x6f, 0x6d,
+    0x69, 0x73, 0x6f, 0x36,
+    0x6d, 0x70, 0x34, 0x31,
+  ]))
+
+  const avcCBox = box('avcC', avcC)
+  const avc1Body = new Uint8Array(78 + avcCBox.length)
+  const avc1View = new DataView(avc1Body.buffer)
+  avc1View.setUint16(6, 1)
+  avc1View.setUint16(24, width)
+  avc1View.setUint16(26, height)
+  avc1View.setUint32(28, 0x00480000)
+  avc1View.setUint32(32, 0x00480000)
+  avc1View.setUint16(40, 1)
+  avc1View.setUint16(74, 0x0018)
+  avc1View.setInt16(76, -1)
+  avc1Body.set(avcCBox, 78)
+  const avc1 = box('avc1', avc1Body)
+
+  const stsd = fullBox('stsd', 0, 0, u32(1), avc1)
+  const stbl = box('stbl', stsd,
+    fullBox('stts', 0, 0, u32(0)),
+    fullBox('stsc', 0, 0, u32(0)),
+    fullBox('stsz', 0, 0, u32(0), u32(0)),
+    fullBox('stco', 0, 0, u32(0)),
+  )
+  const dinf = box('dinf', fullBox('dref', 0, 0, u32(1), fullBox('url ', 0, 1)))
+  const minf = box('minf', fullBox('vmhd', 0, 1), dinf, stbl)
+  const hdlr = fullBox('hdlr', 0, 0, new Uint8Array([
+    0, 0, 0, 0, 0x76, 0x69, 0x64, 0x65,
+    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+    0x56, 0x69, 0x64, 0x65, 0x6f, 0,
+  ]))
+  const mdhdBody = new Uint8Array(20)
+  new DataView(mdhdBody.buffer).setUint32(8, timescale)
+  const mdhd = fullBox('mdhd', 0, 0, mdhdBody)
+  const mdia = box('mdia', mdhd, hdlr, minf)
+
+  const tkhdBody = new Uint8Array(80)
+  const tkhdView = new DataView(tkhdBody.buffer)
+  tkhdView.setUint32(8, trackId)
+  tkhdView.setUint32(36, 0x00010000)
+  tkhdView.setUint32(52, 0x00010000)
+  tkhdView.setUint32(64, 0x40000000)
+  tkhdView.setUint32(72, width << 16)
+  tkhdView.setUint32(76, height << 16)
+  const tkhd = fullBox('tkhd', 0, 3, tkhdBody)
+  const trak = box('trak', tkhd, mdia)
+
+  const mvhdBody = new Uint8Array(96)
+  const mvhdView = new DataView(mvhdBody.buffer)
+  mvhdView.setUint32(8, timescale)
+  mvhdView.setUint32(16, 0x00010000)
+  mvhdView.setUint16(20, 0x0100)
+  mvhdView.setUint32(32, 0x00010000)
+  mvhdView.setUint32(48, 0x00010000)
+  mvhdView.setUint32(60, 0x40000000)
+  mvhdView.setUint32(92, trackId + 1)
+  const mvhd = fullBox('mvhd', 0, 0, mvhdBody)
+
+  const trexBody = new Uint8Array(20)
+  new DataView(trexBody.buffer).setUint32(0, trackId)
+  new DataView(trexBody.buffer).setUint32(4, 1)
+  const mvex = box('mvex', fullBox('trex', 0, 0, trexBody))
+
+  const moov = box('moov', mvhd, trak, mvex)
+  const result = new Uint8Array(ftyp.length + moov.length)
+  result.set(ftyp, 0)
+  result.set(moov, ftyp.length)
+  return result
+}
+
+/**
+ * Build ftyp+moov init segment for AAC audio MSE.
+ */
+export function buildAudioInitSegment(
+  sampleRate: number,
+  channels: number,
+  asc?: Uint8Array,
+  timescale?: number,
+  trackId = 1,
+): Uint8Array {
+  // Validated here as well as in setAudioTimescale, for the same reason the
+  // video builder is: this function is exported from the package index, so a
+  // direct caller reaches the same uint32 tkhd / trex / mdhd / mvhd fields
+  // without passing through the class.
+  assertTrackId(trackId, 'audio trackId')
+  const ts = timescale ?? sampleRate
+  assertTimescale(ts, 'audio timescale')
+
+  if (!asc) {
+    const freqTable = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350]
+    const fi = freqTable.indexOf(sampleRate)
+    const freqIdx = fi >= 0 ? fi : 0x0f
+    if (freqIdx <= 0x0e) {
+      const v = (2 << 11) | (freqIdx << 7) | (channels << 3)
+      asc = new Uint8Array([(v >> 8) & 0xff, v & 0xff])
+    } else {
+      asc = new Uint8Array([
+        (2 << 3) | 0x07,
+        (0x08 | ((sampleRate >> 20) & 0x07)) & 0xff,
+        (sampleRate >> 12) & 0xff,
+        (sampleRate >> 4) & 0xff,
+        (((sampleRate & 0x0f) << 4) | (channels << 0)) & 0xff,
+      ])
+    }
+  }
+
+  // esds: ES_Descriptor → DecoderConfigDescriptor → AudioSpecificConfig
+  const dsi = new Uint8Array(2 + asc.length)
+  dsi[0] = 0x05; dsi[1] = asc.length; dsi.set(asc, 2)
+  const dcdBody = new Uint8Array(13 + dsi.length)
+  dcdBody[0] = 0x40; dcdBody[1] = 0x15; dcdBody.set(dsi, 13)
+  const dcd = new Uint8Array(2 + dcdBody.length)
+  dcd[0] = 0x04; dcd[1] = dcdBody.length; dcd.set(dcdBody, 2)
+  const esBody = new Uint8Array(3 + dcd.length)
+  esBody[0] = 0; esBody[1] = 0x01; esBody[2] = 0; esBody.set(dcd, 3)
+  const es = new Uint8Array(2 + esBody.length)
+  es[0] = 0x03; es[1] = esBody.length; es.set(esBody, 2)
+  const esdsBox = fullBox('esds', 0, 0, es)
+
+  const mp4aBody = new Uint8Array(28 + esdsBox.length)
+  const mp4aView = new DataView(mp4aBody.buffer)
+  mp4aView.setUint16(6, 1)
+  mp4aView.setUint16(16, channels)
+  mp4aView.setUint16(18, 16)
+  mp4aView.setUint32(24, sampleRate << 16)
+  mp4aBody.set(esdsBox, 28)
+  const mp4a = box('mp4a', mp4aBody)
+
+  const stsd = fullBox('stsd', 0, 0, u32(1), mp4a)
+  const stbl = box('stbl', stsd,
+    fullBox('stts', 0, 0, u32(0)),
+    fullBox('stsc', 0, 0, u32(0)),
+    fullBox('stsz', 0, 0, u32(0), u32(0)),
+    fullBox('stco', 0, 0, u32(0)),
+  )
+  const dinf = box('dinf', fullBox('dref', 0, 0, u32(1), fullBox('url ', 0, 1)))
+  const minf = box('minf', fullBox('smhd', 0, 0, new Uint8Array(4)), dinf, stbl)
+  const hdlr = fullBox('hdlr', 0, 0, new Uint8Array([
+    0, 0, 0, 0, 0x73, 0x6f, 0x75, 0x6e,
+    0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+    0x53, 0x6f, 0x75, 0x6e, 0x64, 0,
+  ]))
+  const mdhdBody = new Uint8Array(20)
+  new DataView(mdhdBody.buffer).setUint32(8, ts)
+  const mdhd = fullBox('mdhd', 0, 0, mdhdBody)
+  const mdia = box('mdia', mdhd, hdlr, minf)
+
+  const tkhdBody = new Uint8Array(80)
+  const tkhdView = new DataView(tkhdBody.buffer)
+  tkhdView.setUint32(8, trackId)
+  tkhdView.setUint32(36, 0x00010000)
+  tkhdView.setUint32(52, 0x00010000)
+  tkhdView.setUint32(64, 0x40000000)
+  const tkhd = fullBox('tkhd', 0, 3, tkhdBody)
+  const trak = box('trak', tkhd, mdia)
+
+  const mvhdBody = new Uint8Array(96)
+  const mvhdView = new DataView(mvhdBody.buffer)
+  mvhdView.setUint32(8, ts)
+  mvhdView.setUint32(16, 0x00010000)
+  mvhdView.setUint16(20, 0x0100)
+  mvhdView.setUint32(32, 0x00010000)
+  mvhdView.setUint32(48, 0x00010000)
+  mvhdView.setUint32(60, 0x40000000)
+  mvhdView.setUint32(92, trackId + 1)
+  const mvhd = fullBox('mvhd', 0, 0, mvhdBody)
+
+  const trexBody = new Uint8Array(20)
+  new DataView(trexBody.buffer).setUint32(0, trackId)
+  new DataView(trexBody.buffer).setUint32(4, 1)
+  const mvex = box('mvex', fullBox('trex', 0, 0, trexBody))
+
+  const moov = box('moov', mvhd, trak, mvex)
+  const ftyp = box('ftyp', new Uint8Array([
+    0x69, 0x73, 0x6f, 0x6d, 0, 0, 2, 0,
+    0x69, 0x73, 0x6f, 0x6d,
+    0x69, 0x73, 0x6f, 0x36,
+    0x6d, 0x70, 0x34, 0x31,
+  ]))
+  const result = new Uint8Array(ftyp.length + moov.length)
+  result.set(ftyp, 0)
+  result.set(moov, ftyp.length)
+  return result
+}
+
+/**
+ * MMTP → CMAF converter.
+ *
+ * Accepts reassembled MFU frames (raw codec samples) from MmtpDecoder
+ * and produces fMP4 segments for MSE SourceBuffer.
+ *
+ * Per draft-ramadan-moq-mmt §5.3:
+ *   MPU metadata (ftyp+moov) → init segment
+ *   MFU sample bytes → moof+mdat data segment
+ *
+ * Timescale is microseconds (1_000_000) matching MMTP NTP short timestamps
+ * converted via mmtpTimestampToMicros().
+ */
+export class MmtpToCmaf {
+  #videoSeq = 1
+  #audioSeq = 1
+  #videoInitSegment: Uint8Array | null = null
+  // Known only for locally-built init segments. Wire-supplied MPU metadata is
+  // intentionally opaque here, so setVideoTrackParams remains the API that
+  // lets a caller declare its track geometry before wrapping samples.
+  #videoInitTrackId: number | null = null
+  #audioInitSegment: Uint8Array | null = null
+  #lastVideoTimestamp = 0
+  // Sticky sample duration in video timescale units, updated from caller-
+  // supplied durations or adjacent-timestamp deltas. null means "nothing
+  // observed yet", in which case #videoFrameDuration derives ~30fps from the
+  // configured timescale (33333 at the 1_000_000 default, i.e. unchanged).
+  #frameDuration: number | null = null
+  // Per-track rebase: each track anchors on its OWN first sample so
+  // baseMediaDecodeTime is never negative. A shared base was wrong — if the
+  // first sample of one track arrives later than the other's first sample,
+  // the earlier track computes `timestamp - sharedBase` as a negative number,
+  // which serializes into tfdt as a huge unsigned uint64 (~2^64 - 46) and
+  // Chromium rejects the segment with CHUNK_DEMUXER_ERROR_APPEND_FAILED,
+  // closing the MediaSource and detaching all SourceBuffers.
+  // For A/V alignment, choose a COMMON anchor: set when the first sample of
+  // EITHER track arrives, but only if that sample's timestamp is <= any
+  // subsequent track's first sample. Implementation: each track rebases to
+  // the minimum timestamp seen across tracks on their respective first sample.
+  #videoBaseTs = -1
+  #audioBaseTs = -1
+
+  // Video track geometry. These pair with the video init segment's tkhd
+  // track_ID and mdhd/mvhd timescale: every moof this converter emits must
+  // reference the same track at the same rate or the browser either drops the
+  // fragment (unknown track) or plays it at the wrong rate. They are
+  // configuration rather than stream state, so — unlike the sequence numbers
+  // and time bases above — reset() deliberately preserves them, matching the
+  // fact that reset() also preserves #videoInitSegment.
+  #videoTrackId = 1
+  #videoTimescale = 1_000_000
+
+  /**
+   * Point the single-sample video wrappers at a specific track and rate.
+   *
+   * Call this when the init segment came off the wire (setInitSegmentFromMpu)
+   * rather than from buildVideoInit, so the wrappers match the publisher's
+   * tkhd/mdhd instead of assuming trackId=1 at microsecond rate. Consumers
+   * that build their init through buildVideoInit can pass the same values
+   * there instead and skip this call.
+   *
+   * The rate is settable only until the first single-sample wrap — see the
+   * throw below for why.
+   */
+  setVideoTrackParams(trackId: number, timescale: number) {
+    assertTrackId(trackId, 'video trackId')
+    assertTimescale(timescale, 'video timescale')
+    // #frameDuration, #lastVideoTimestamp and #videoBaseTs are all denominated
+    // in #videoTimescale, so moving the rate out from under them reinterprets
+    // every one at the new rate. Both consequences are silent:
+    //   - a duration latched as 33333 (1 MHz ~30fps) re-emits as 33333 ticks of
+    //     90 kHz, a 370 ms frame;
+    //   - a base captured on the old scale rebases new-scale timestamps to a
+    //     negative relTs, which tfdt serializes as a ~2^64 uint64 and Chromium
+    //     rejects with CHUNK_DEMUXER_ERROR_APPEND_FAILED, closing the
+    //     MediaSource (same failure the #videoBaseTs comment above describes).
+    // Rescaling instead of refusing would be a guess: the class cannot tell
+    // whether the caller's next timestamps continue this timeline in new units
+    // or open a fresh epoch. reset() is the exact mechanism for that
+    // discontinuity — it clears all three fields while preserving geometry —
+    // so require it rather than infer. Re-asserting the same rate is a no-op.
+    // A cached init also fixes the track ID in tkhd/trex; changing only the
+    // wrapper setting would make later tfhd IDs disagree with that init.
+    if (trackId !== this.#videoTrackId && this.#videoInitTrackId !== null) {
+      throw new Error(
+        `video track ID cannot change from ${this.#videoTrackId} to ${trackId} ` +
+          'after a video init has been cached; replace the init atomically',
+      )
+    }
+    if (timescale !== this.#videoTimescale && this.#videoBaseTs >= 0) {
+      throw new Error(
+        `video timescale cannot change from ${this.#videoTimescale} to ${timescale} ` +
+          `after video samples have been wrapped; call reset() first`,
+      )
+    }
+    this.#videoTrackId = trackId
+    this.#videoTimescale = timescale
+  }
+
+  /** Set init segment from MPU metadata packet (fragment_type=0).
+   *  These are complete ftyp+moov bytes from FFmpeg — use directly. */
+  setInitSegmentFromMpu(data: Uint8Array, isAudio: boolean) {
+    if (isAudio) {
+      this.#audioInitSegment = data
+    } else {
+      this.#videoInitSegment = data
+      this.#videoInitTrackId = null
+    }
+  }
+
+  /** Build init segment from codec config (catalog path — no MPU metadata available).
+   *  Passing timescale/trackId also configures the wrappers via
+   *  setVideoTrackParams, so init and media segments cannot disagree. */
+  buildVideoInit(avcC: Uint8Array, width: number, height: number, timescale?: number, trackId?: number) {
+    const nextTimescale = timescale ?? this.#videoTimescale
+    const nextTrackId = trackId ?? this.#videoTrackId
+    assertTrackId(nextTrackId, 'video trackId')
+    assertTimescale(nextTimescale, 'video timescale')
+    if (nextTimescale !== this.#videoTimescale && this.#videoBaseTs >= 0) {
+      throw new Error(
+        `video timescale cannot change from ${this.#videoTimescale} to ${nextTimescale} ` +
+          'after video samples have been wrapped; call reset() first',
+      )
+    }
+    // Build first, then publish both geometry and init together. This is the
+    // sanctioned path for replacing a cached init with a new track ID.
+    const init = buildVideoInitSegment(
+      avcC,
+      width,
+      height,
+      nextTimescale,
+      nextTrackId,
+    )
+    this.#videoTimescale = nextTimescale
+    this.#videoTrackId = nextTrackId
+    this.#videoInitSegment = init
+    this.#videoInitTrackId = nextTrackId
+  }
+
+  buildAudioInit(sampleRate: number, channels: number, asc?: Uint8Array, timescale?: number) {
+    const ts = timescale ?? sampleRate
+    // Build first, then publish, as the video path does: buildAudioInitSegment
+    // validates, so assigning the field first would leave a rejected timescale
+    // latched on the instance with no init segment to match it.
+    const init = buildAudioInitSegment(sampleRate, channels, asc, ts)
+    this.#audioTimescale = ts
+    this.#audioInitSegment = init
+  }
+
+  get videoInitSegment(): Uint8Array | null { return this.#videoInitSegment }
+  get audioInitSegment(): Uint8Array | null { return this.#audioInitSegment }
+
+  /** Convert a raw video sample to an fMP4 moof+mdat segment. */
+  wrapVideoSample(
+    data: Uint8Array,
+    timestamp: number,
+    keyframe: boolean,
+    duration?: number,
+    compositionTimeOffset?: number,
+  ): Uint8Array {
+    return this.wrapVideoSampleWithTiming(data, timestamp, keyframe, duration, compositionTimeOffset).segment
+  }
+
+  /**
+   * Convert a raw video sample and return the exact browser media interval
+   * encoded into tfdt/trun. Consumers that correlate SourceBuffer appends with
+   * requestVideoFrameCallback must use this rebased timestamp, not the wire or
+   * caller-owned timestamp passed above.
+   *
+   * `compositionTimeOffset` is the signed authored PTS-DTS delta, in the same
+   * #videoTimescale units as `timestamp` and `duration` — unlike wrapAudioSample,
+   * which takes microseconds and rescales, because every other quantity on this
+   * path is already denominated in #videoTimescale (see setVideoTrackParams).
+   * Passing it therefore needs no conversion here; rescaling would double-convert.
+   * Absent leaves the trun at version 0 with no offset field; a declared 0 is an
+   * authored value and still promotes to version 1. Never reconstruct it from
+   * arrival time.
+   */
+  wrapVideoSampleWithTiming(
+    data: Uint8Array,
+    timestamp: number,
+    keyframe: boolean,
+    duration?: number,
+    compositionTimeOffset?: number,
+  ): Readonly<{ segment: Uint8Array; mediaTimestamp: number; duration: number }> {
+    // Checked before #videoSeq++ and before the duration/base-timestamp latches
+    // below, for the same reason as wrapAudioSample and wrapVideoSamples: the
+    // encoder validates too, but by then the sequence number is spent and a
+    // caller that corrects the offset and retries emits a gapped mfhd.
+    assertCompositionTimeOffsets([{ compositionTimeOffset }])
+    // Prefer a caller-provided media duration when the browser append timeline
+    // is intentionally decoupled from sparse MMTP wire timestamps. Fall back to
+    // estimating from adjacent timestamps for legacy/direct callers. A delta of
+    // a full second or more is not a frame interval, so it is rejected as a
+    // discontinuity rather than latched.
+    if (duration !== undefined && Number.isFinite(duration) && duration > 0) {
+      this.#frameDuration = Math.round(duration)
+    } else if (this.#lastVideoTimestamp > 0 && timestamp > this.#lastVideoTimestamp) {
+      const delta = timestamp - this.#lastVideoTimestamp
+      if (delta > 0 && delta < this.#videoTimescale) this.#frameDuration = delta
+    }
+    this.#lastVideoTimestamp = timestamp
+    if (this.#videoBaseTs < 0) this.#videoBaseTs = timestamp
+    const relTs = timestamp - this.#videoBaseTs
+    const frameDuration = this.#videoFrameDuration
+    return Object.freeze({
+      segment: encodeDataSegment(
+        data,
+        relTs,
+        frameDuration,
+        keyframe,
+        this.#videoSeq++,
+        this.#videoTrackId,
+        compositionTimeOffset,
+      ),
+      mediaTimestamp: relTs,
+      duration: frameDuration,
+    })
+  }
+
+  /** Sticky duration if one has been observed, else ~30fps at the current rate. */
+  get #videoFrameDuration(): number {
+    return this.#frameDuration ?? Math.max(1, Math.round(this.#videoTimescale / 30))
+  }
+
+  /** Convert an append-safe video batch using the caller-owned timeline.
+   *  Durations, baseDecodeTime, and compositionTimeOffset are in the
+   *  configured video timescale. compositionTimeOffset is the signed PTS-DTS
+   *  delta; its presence selects a version-1 trun for the whole batch.
+   *  An explicit trackId is range-checked before #videoSeq++ for the same
+   *  reason as wrapAudioSamples: the encoder's own check fires too late to
+   *  keep the sequence ungapped. */
+  wrapVideoSamples(
+    samples: Array<{
+      data: Uint8Array
+      duration: number
+      keyframe: boolean
+      compositionTimeOffset?: number
+    }>,
+    baseDecodeTime: number,
+    trackId = this.#videoTrackId,
+  ): Uint8Array {
+    assertTrackId(trackId, 'video trackId')
+    assertCompositionTimeOffsets(samples)
+    return encodeMultiSampleSegment(samples, baseDecodeTime, this.#videoSeq++, trackId)
+  }
+
+  // Audio timescale from init segment (default 1M µs; real FFmpeg init uses sampleRate).
+  // Set by buildAudioInit or setAudioTimescale.
+  #audioTimescale = 1_000_000
+
+  /** Set audio timescale to match the init segment's mdhd timescale.
+   *  Call after appending the real encoder init (FT=0 ftyp+moov).
+   *  Fails closed on a value the mdhd uint32 cannot hold, as the video paths
+   *  already do. wrapAudioSample rescales the authored composition offset by
+   *  this value, so the two failure modes are both silent: a 0 multiplies
+   *  every authored offset to 0 — indistinguishable from a feed that authored
+   *  none — while a value above uint32 scales the trun to a timescale the
+   *  mdhd cannot declare, since it is emitted with setUint32 modulo 2^32. */
+  setAudioTimescale(timescale: number) {
+    assertTimescale(timescale, 'audio timescale')
+    this.#audioTimescale = timescale
+  }
+
+  // Audio sample counter for drift-free baseMediaDecodeTime.
+  // AAC frames are exactly 1024 samples at sampleRate. Using sequential
+  // counter × 1024 avoids floating-point rounding drift from timestamp conversion.
+  #audioSampleCount = 0
+
+  /** AAC access-unit length in samples. ISO/IEC 14496-3: an AAC-LC frame is
+   *  exactly 1024 samples at every sample rate — it is not rate-dependent. */
+  readonly #aacFrameSamples = 1024
+
+  /** Convert a raw audio sample to an fMP4 moof+mdat segment. */
+  wrapAudioSample(
+    data: Uint8Array,
+    timestamp: number,
+    sampleDuration = 21333,
+    compositionTimeOffset?: number,
+  ): Uint8Array {
+    assertCompositionTimeOffsets([{ compositionTimeOffset }])
+    const sampleData = normalizeAacSampleForCmaf(data)
+    if (this.#audioBaseTs < 0) this.#audioBaseTs = timestamp
+
+    // When timescale matches sampleRate (e.g. 48000), use integer sample counting
+    // for exact baseMediaDecodeTime alignment. This eliminates cumulative rounding
+    // drift from Math.round(µs * sampleRate / 1_000_000) that causes frequency
+    // wandering in FFT analysis (42% consistency → 99%+ with exact counting).
+    //
+    // samplesPerFrame is the AAC access-unit length, NOT a rescaled duration.
+    // Deriving it as Math.round(sampleDuration * timescale / 1e6) only lands on
+    // 1024 when the rate happens to be 48 kHz (21333 * 48000 / 1e6 = 1023.98),
+    // which made the default silently correct at 48 kHz and wrong everywhere
+    // else: at 44.1 kHz it yields 941, so every moof declared ~8% short frames
+    // and Chrome rejected the first packet with PIPELINE_ERROR_DECODE
+    // ("Failed to send audio packet for decoding", duration=21337µs = 941/44100).
+    const samplesPerFrame = this.#audioTimescale !== 1_000_000
+      ? this.#aacFrameSamples
+      : sampleDuration
+    const scaledTs = this.#audioTimescale !== 1_000_000
+      ? this.#audioSampleCount * samplesPerFrame
+      : (timestamp - this.#audioBaseTs)
+    this.#audioSampleCount++
+
+    // compositionTimeOffset arrives in microsecond ticks, like timestamp and
+    // sampleDuration: the block assembler scales authored PTS-DTS into its own
+    // timescale, which defaults to 1e6 whenever the caller omits `timescale`
+    // (cmaf-block-assembler.ts). The trun it lands in is at #audioTimescale, so
+    // on the sample-counting branch it needs the same rescale its two siblings
+    // above already get. Without it a 10 ms authored offset is written as
+    // 10_000 ticks of a 48 kHz track — 1e6/48000 = 20.83x, ~208 ms of A/V
+    // desync — which is the samplesPerFrame hazard documented above, one field
+    // over. Undefined stays undefined so raw feeds keep a v0 trun with no
+    // composition-offset field rather than claiming an authored zero.
+    //
+    // This 1e6 is the assembler's default timescale, not a free constant, so
+    // the two move together. Configuring the audio assembler with
+    // `timescale: sampleRate` makes its offsets already trun ticks and turns
+    // this rescale into a 20.83x *under*-count: an authored 480 arrives as 23.
+    //
+    // The two bridges currently disagree on that config, so this rescale is
+    // correct for exactly one of them at a time. moqtail omits `timescale`
+    // (apps/client-js/src/lib/player.ts, audio enableMseAssembler) and needs
+    // the rescale. hang passes `timescale: sampleRate` (js/watch/src/element.ts,
+    // audio enableMseAssembler) and must not get it. hang is safe today only
+    // because it pins a libmmt revision older than this rescale. Bumping that
+    // pin past this commit without dropping hang's `timescale` in the same
+    // change is the 20.83x under-count, so the pin bump and the hang edit are
+    // one atomic change. mmtp-to-cmaf-audio-composition-offset.test.ts pins
+    // both configs against a real CmafBlockAssembler so the pairing is checked
+    // by CI rather than by this comment.
+    const scaledCompositionTimeOffset =
+      compositionTimeOffset === undefined || this.#audioTimescale === 1_000_000
+        ? compositionTimeOffset
+        : Math.round((compositionTimeOffset * this.#audioTimescale) / 1_000_000)
+
+    return encodeDataSegment(
+      sampleData,
+      scaledTs,
+      samplesPerFrame,
+      true,
+      this.#audioSeq++,
+      1,
+      scaledCompositionTimeOffset,
+    )
+  }
+
+  /** Convert an ordered audio batch using the caller-owned timeline. */
+  wrapAudioSamples(
+    samples: Array<{
+      data: Uint8Array
+      duration: number
+      compositionTimeOffset?: number
+    }>,
+    baseDecodeTime: number,
+    trackId = 1,
+  ): Uint8Array {
+    // Checked before #audioSeq++ below: the encoder validates too, but its
+    // throw would land after the counter had already advanced, leaving the
+    // sequence gapped by a call that produced no segment.
+    assertTrackId(trackId, 'audio trackId')
+    assertCompositionTimeOffsets(samples)
+    return encodeMultiSampleSegment(
+      samples.map(sample => ({
+        data: normalizeAacSampleForCmaf(sample.data),
+        duration: sample.duration,
+        keyframe: true,
+        compositionTimeOffset: sample.compositionTimeOffset,
+      })),
+      baseDecodeTime,
+      this.#audioSeq++,
+      trackId,
+    )
+  }
+
+  /** Clear per-stream sequencing and time bases.
+   *  Cached init segments and the video track geometry survive, so a converter
+   *  reset mid-subscription keeps emitting moofs the existing init can resolve.
+   *  Clearing the timescale-denominated timing state also re-opens the video
+   *  rate for change — this is the sanctioned way to retarget mid-subscription. */
+  reset() {
+    this.#videoSeq = 1
+    this.#audioSeq = 1
+    this.#audioSampleCount = 0
+    this.#lastVideoTimestamp = 0
+    this.#frameDuration = null
+    this.#videoBaseTs = -1
+    this.#audioBaseTs = -1
+    this.#audioTimescale = 1_000_000
+  }
+}