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

package/src/codec-utils.ts

@@ -0,0 +1,1539 @@
+/**
+ * H.264/AVC codec utilities for MMTP container format conversion.
+ *
+ * Shared between moq-lib (hang-mmt-fec) and moqtail players.
+ * Handles AVCC↔Annex-B conversion, SPS/PPS extraction, fallback avcC generation,
+ * and MMTP timestamp conversion.
+ *
+ * @packageDocumentation
+ */
+
+// ─── Public Types ────────────────────────────────────────────────
+
+/** Result of extracting a video codec configuration record from an fMP4 init segment. */
+export interface AvcCInfo {
+  codec: string
+  description: Uint8Array
+}
+
+/** Result of extracting AAC AudioSpecificConfig from an fMP4 init segment. */
+export interface AacAscInfo {
+  /** Codec string like "mp4a.40.2" (AAC-LC). Derived from AOT in ASC[0] >> 3. */
+  codec: string
+  /** AudioSpecificConfig bytes — what AudioDecoder.configure({description}) needs for raw AAC. */
+  description: Uint8Array
+}
+
+/** SPS and PPS NAL units extracted from an avcC record. */
+export interface SpsPps {
+  sps: Uint8Array
+  pps: Uint8Array
+}
+
+/** Options for fallback avcC generation. */
+export interface FallbackAvcCOptions {
+  /** Codec string like "avc1.640033". Profile/constraint/level parsed from hex triplet. */
+  codec?: string
+  /** Coded width in pixels. Used in SPS pic_width_in_mbs. */
+  width?: number
+  /** Coded height in pixels. Used in SPS pic_height_in_map_units. */
+  height?: number
+}
+
+// ─── Public Functions ────────────────────────────────────────────
+
+/**
+ * Extract the codec configuration record (avcC/hvcC/av1C/vpcC) from
+ * an fMP4 init segment (moov box).
+ * MMTP FT=0 packets contain a complete fMP4: moov > trak > mdia > minf > stbl > stsd > sample entry > codec config.
+ *
+ * Walks every trak and returns the first supported video sample entry. This
+ * handles both per-track CMSF init segments and multiplexed ftyp+moov blobs
+ * where the audio trak may appear before video.
+ */
+export function extractAvcCFromInitSegment(data: Uint8Array): AvcCInfo | undefined {
+  if (!hasIsoBmffMagic(data)) return undefined
+
+  for (const stsd of findTrackStsdBoxes(data)) {
+    const info = extractVideoConfigFromStsd(data, stsd)
+    if (info) return info
+  }
+
+  return undefined
+}
+
+function extractVideoConfigFromStsd(data: Uint8Array, stsd: { o: number; sz: number }): AvcCInfo | undefined {
+  let s = stsd.o + 16
+  const e = stsd.o + stsd.sz
+
+  // H.264: avc1 VisualSampleEntry → avcC.
+  const avc1 = findBox(data, s, e, 'avc1')
+  if (avc1 && avc1.sz >= 86) {
+    const avcC = findBox(data, avc1.o + 86, avc1.o + avc1.sz, 'avcC')
+    if (avcC && avcC.sz >= 12) {
+      const d = data.subarray(avcC.o + 8, avcC.o + avcC.sz)
+      const codec = `avc1.${hex2(d[1])}${hex2(d[2])}${hex2(d[3])}`
+      return { codec, description: d }
+    }
+  }
+  // HEVC: hvc1/hev1 VisualSampleEntry → hvcC. Same +86 child-box offset as
+  // avc1 (identical VisualSampleEntry layout). Without this branch, HEVC
+  // ftyp+moov inits yield no descriptor, so the WebCodecs path configures the
+  // VideoDecoder with no `description` and the first length-prefixed hvc1
+  // keyframe decode() throws DataError ("must fill out the description field"),
+  // which the player's MoQ pump catch swallows → video track silently 0-fps
+  // (BLO-8054).
+  const hvc1 = findBox(data, s, e, 'hvc1') ?? findBox(data, s, e, 'hev1')
+  if (hvc1 && hvc1.sz >= 86) {
+    const hvcC = findBox(data, hvc1.o + 86, hvc1.o + hvc1.sz, 'hvcC')
+    // HEVCDecoderConfigurationRecord is ≥23 bytes (+8 box header).
+    if (hvcC && hvcC.sz >= 8 + 23) {
+      const d = data.subarray(hvcC.o + 8, hvcC.o + hvcC.sz)
+      return { codec: hevcCodecStringFromHvcC(d), description: d }
+    }
+  }
+  // AV1: av01 VisualSampleEntry -> av1C. Real FFmpeg MMTP inits can carry an
+  // empty av1C box (size=8) while still providing the authoritative sample
+  // entry/codec signal. Return an empty description for that shape so callers
+  // can open their FT=0 gate without passing a zero-byte WebCodecs description.
+  const av01 = findBox(data, s, e, 'av01')
+  if (av01 && av01.sz >= 86) {
+    const av1C = findBox(data, av01.o + 86, av01.o + av01.sz, 'av1C')
+    if (av1C && av1C.sz >= 8) {
+      const d = data.subarray(av1C.o + 8, av1C.o + av1C.sz)
+      return { codec: codecStringFromAv1C(d), description: d }
+    }
+  }
+  // VP9: vp09 VisualSampleEntry -> vpcC. Some encoders omit the VP codec record
+  // payload; use the sample entry as readiness evidence and fall back to a
+  // conservative vp09 codec string in that case.
+  const vp09 = findBox(data, s, e, 'vp09')
+  if (vp09 && vp09.sz >= 86) {
+    const vpcC = findBox(data, vp09.o + 86, vp09.o + vp09.sz, 'vpcC')
+    if (vpcC && vpcC.sz >= 8) {
+      const d = data.subarray(vpcC.o + 8, vpcC.o + vpcC.sz)
+      return { codec: codecStringFromVpcC(d), description: d }
+    }
+  }
+  return undefined
+}
+
+/**
+ * Generate a minimal avcC (AVCDecoderConfigurationRecord) from codec parameters.
+ * Parses "avc1.XXYYZZ" → profile_idc=0xXX, constraint_flags=0xYY, level_idc=0xZZ.
+ * Width/height are encoded in the SPS; if not provided, they're inferred from the
+ * H.264 level's max frame size (e.g. level 4.2 → 2048x1088).
+ * Used when late MoQ subscribers miss the FT=0 init segment (moov/avcC).
+ */
+export function generateFallbackAvcC(options?: FallbackAvcCOptions | string): Uint8Array {
+  const opts: FallbackAvcCOptions = typeof options === 'string' ? { codec: options } : (options ?? {})
+
+  let profile = 0x64
+  let constraint = 0x00
+  let level = 0x2a
+
+  if (opts.codec) {
+    const match = opts.codec.match(/^avc[13]\.([0-9a-fA-F]{6})$/)
+    if (match) {
+      profile = Number.parseInt(match[1].substring(0, 2), 16)
+      constraint = Number.parseInt(match[1].substring(2, 4), 16)
+      level = Number.parseInt(match[1].substring(4, 6), 16)
+    }
+  }
+
+  const { width, height } = resolveResolution(opts.width, opts.height, level)
+  const sps = buildMinimalSps(profile, constraint, level, width, height)
+  const pps = buildMinimalPps(profile)
+
+  const avcC = new Uint8Array(5 + 1 + 2 + sps.length + 1 + 2 + pps.length)
+  let w = 0
+  avcC[w++] = 0x01
+  avcC[w++] = profile
+  avcC[w++] = constraint
+  avcC[w++] = level
+  avcC[w++] = 0xff
+  avcC[w++] = 0xe1
+  avcC[w++] = (sps.length >> 8) & 0xff
+  avcC[w++] = sps.length & 0xff
+  avcC.set(sps, w)
+  w += sps.length
+  avcC[w++] = 0x01
+  avcC[w++] = (pps.length >> 8) & 0xff
+  avcC[w++] = pps.length & 0xff
+  avcC.set(pps, w)
+  return avcC
+}
+
+/**
+ * Extract raw SPS and PPS NAL unit bytes from an avcC (AVCDecoderConfigurationRecord).
+ * Returns the first SPS and first PPS found.
+ */
+export function extractSpsPpsFromAvcC(avcC: Uint8Array): SpsPps | undefined {
+  if (avcC.length < 8) return undefined
+  const numSPS = avcC[5] & 0x1f
+  let offset = 6
+  let sps: Uint8Array | undefined
+  for (let i = 0; i < numSPS && offset + 2 <= avcC.length; i++) {
+    const spsLen = (avcC[offset] << 8) | avcC[offset + 1]
+    offset += 2
+    if (offset + spsLen <= avcC.length) {
+      if (!sps) sps = avcC.subarray(offset, offset + spsLen)
+      offset += spsLen
+    }
+  }
+  let pps: Uint8Array | undefined
+  if (offset < avcC.length) {
+    const numPPS = avcC[offset] & 0x1f
+    offset++
+    for (let i = 0; i < numPPS && offset + 2 <= avcC.length; i++) {
+      const ppsLen = (avcC[offset] << 8) | avcC[offset + 1]
+      offset += 2
+      if (offset + ppsLen <= avcC.length) {
+        if (!pps) pps = avcC.subarray(offset, offset + ppsLen)
+        offset += ppsLen
+      }
+    }
+  }
+  return sps && pps ? { sps, pps } : undefined
+}
+
+/**
+ * Convert AVCC (4-byte NAL length prefixed) to Annex-B (start code prefixed).
+ * Prepends SPS/PPS NALs before keyframes.
+ */
+export function avccToAnnexB(avccData: Uint8Array, isKeyframe: boolean, spsPps: SpsPps): Uint8Array {
+  let offset = 0
+  let totalNalSize = 0
+  let nalCount = 0
+  while (offset + 4 <= avccData.length) {
+    const nalLen =
+      (avccData[offset] << 24) |
+      (avccData[offset + 1] << 16) |
+      (avccData[offset + 2] << 8) |
+      avccData[offset + 3]
+    offset += 4
+    if (nalLen <= 0 || offset + nalLen > avccData.length) break
+    totalNalSize += nalLen
+    nalCount++
+    offset += nalLen
+  }
+  if (nalCount === 0) return avccData
+
+  let outSize = nalCount * 4 + totalNalSize
+  if (isKeyframe) {
+    outSize += 4 + spsPps.sps.length + 4 + spsPps.pps.length
+  }
+  const out = new Uint8Array(outSize)
+  let w = 0
+
+  if (isKeyframe) {
+    out[w++] = 0; out[w++] = 0; out[w++] = 0; out[w++] = 1
+    out.set(spsPps.sps, w); w += spsPps.sps.length
+    out[w++] = 0; out[w++] = 0; out[w++] = 0; out[w++] = 1
+    out.set(spsPps.pps, w); w += spsPps.pps.length
+  }
+
+  offset = 0
+  while (offset + 4 <= avccData.length) {
+    const nalLen =
+      (avccData[offset] << 24) |
+      (avccData[offset + 1] << 16) |
+      (avccData[offset + 2] << 8) |
+      avccData[offset + 3]
+    offset += 4
+    if (nalLen <= 0 || offset + nalLen > avccData.length) break
+    out[w++] = 0; out[w++] = 0; out[w++] = 0; out[w++] = 1
+    out.set(avccData.subarray(offset, offset + nalLen), w)
+    w += nalLen
+    offset += nalLen
+  }
+  return out
+}
+
+/**
+ * Build an avcC record by parsing Annex-B data to extract SPS (NAL type 7) and PPS (NAL type 8).
+ * Returns the avcC record, or null if SPS/PPS not found.
+ */
+export function extractCodecDescriptionFromAnnexB(data: Uint8Array): Uint8Array | null {
+  const nalUnits: Array<{ type: number; data: Uint8Array }> = []
+  let i = 0
+  while (i < data.length - 4) {
+    if (data[i] === 0 && data[i + 1] === 0) {
+      let nalStart = 0
+      if (data[i + 2] === 1) {
+        nalStart = i + 3
+      } else if (data[i + 2] === 0 && data[i + 3] === 1) {
+        nalStart = i + 4
+      }
+      if (nalStart > 0 && nalStart < data.length) {
+        let nalEnd = data.length
+        for (let j = nalStart; j < data.length - 3; j++) {
+          if (data[j] === 0 && data[j + 1] === 0 &&
+              (data[j + 2] === 1 || (data[j + 2] === 0 && data[j + 3] === 1))) {
+            nalEnd = j
+            break
+          }
+        }
+        const nalType = data[nalStart] & 0x1f
+        nalUnits.push({ type: nalType, data: data.slice(nalStart, nalEnd) })
+        i = nalEnd
+        continue
+      }
+    }
+    i++
+  }
+
+  const sps = nalUnits.find(n => n.type === 7)
+  const pps = nalUnits.find(n => n.type === 8)
+  if (!sps || !pps) return null
+
+  const avcCLength = 6 + 2 + sps.data.length + 1 + 2 + pps.data.length
+  const avcC = new Uint8Array(avcCLength)
+  let offset = 0
+  avcC[offset++] = 1
+  avcC[offset++] = sps.data[1]
+  avcC[offset++] = sps.data[2]
+  avcC[offset++] = sps.data[3]
+  avcC[offset++] = 0xff
+  avcC[offset++] = 0xe1
+  avcC[offset++] = (sps.data.length >> 8) & 0xff
+  avcC[offset++] = sps.data.length & 0xff
+  avcC.set(sps.data, offset); offset += sps.data.length
+  avcC[offset++] = 1
+  avcC[offset++] = (pps.data.length >> 8) & 0xff
+  avcC[offset++] = pps.data.length & 0xff
+  avcC.set(pps.data, offset)
+  return avcC
+}
+
+/**
+ * Derive codec string from avcC record (e.g. "avc1.640033").
+ */
+export function codecStringFromAvcC(avcC: Uint8Array): string {
+  if (avcC.length < 4) return 'avc1.640033'
+  return `avc1.${hex2(avcC[1])}${hex2(avcC[2])}${hex2(avcC[3])}`
+}
+
+/** VPS/SPS/PPS NAL units extracted from an HEVC keyframe (raw NAL bytes, no start code/length prefix). */
+export interface HevcParameterSets {
+  vps?: Uint8Array
+  sps?: Uint8Array
+  pps?: Uint8Array
+}
+
+/** True for HEVC/H.265 codec strings (hev1.* / hvc1.*). */
+export function isHevcCodec(codec: string): boolean {
+  return codec.startsWith('hev1') || codec.startsWith('hvc1')
+}
+
+/** HEVC NAL unit type from the first NAL header byte: (byte >> 1) & 0x3f. */
+function hevcNalType(nal: Uint8Array): number {
+  return (nal[0] >> 1) & 0x3f
+}
+
+/**
+ * Remove H.26x emulation-prevention bytes (0x03 after 0x00 0x00) from an RBSP so
+ * fixed-position fields (e.g. HEVC profile_tier_level) can be read by byte offset.
+ */
+export function removeEmulationPrevention(rbsp: Uint8Array): Uint8Array {
+  const out: number[] = []
+  let zeros = 0
+  for (let i = 0; i < rbsp.length; i++) {
+    const b = rbsp[i]
+    if (zeros >= 2 && b === 0x03 && i + 1 < rbsp.length && rbsp[i + 1] <= 0x03) {
+      zeros = 0
+      continue
+    }
+    out.push(b)
+    zeros = b === 0 ? zeros + 1 : 0
+  }
+  return Uint8Array.from(out)
+}
+
+/**
+ * Split an AVCC/hvcC bitstream (length-prefixed NAL units) into raw NAL byte slices.
+ * `lengthSize` is the NAL length prefix width (4 for FFmpeg LOC / fMP4 sample data).
+ */
+export function splitAvccNalUnits(data: Uint8Array, lengthSize = 4): Uint8Array[] {
+  const nals: Uint8Array[] = []
+  let i = 0
+  while (i + lengthSize <= data.length) {
+    let len = 0
+    for (let k = 0; k < lengthSize; k++) len = (len << 8) | data[i + k]
+    i += lengthSize
+    if (len <= 0 || i + len > data.length) break
+    nals.push(data.subarray(i, i + len))
+    i += len
+  }
+  return nals
+}
+
+/**
+ * True when `data` is exactly one or more length-prefixed NAL units.
+ *
+ * This is intentionally stricter than "starts with a plausible length": a
+ * H.264 AVCC access unit may begin with bytes `00 00 00 01` when the first
+ * NAL is a one-byte AUD. That byte pattern is also an Annex-B start code, so
+ * callers must prove the whole buffer is complete AVCC before falling back to
+ * Annex-B detection/conversion.
+ */
+export function isCompleteAvccSample(data: Uint8Array, lengthSize = 4): boolean {
+  let i = 0
+  let count = 0
+  while (i + lengthSize <= data.length) {
+    let len = 0
+    for (let k = 0; k < lengthSize; k++) len = (len << 8) | data[i + k]
+    i += lengthSize
+    if (len <= 0 || i + len > data.length) return false
+    i += len
+    count++
+  }
+  return count > 0 && i === data.length
+}
+
+export type H264SampleFormat = 'avcc' | 'annexb' | 'raw-nal' | 'unknown'
+export type H264NalUnitFormat = H264SampleFormat | 'partial-avcc'
+
+export interface H264AvccSample {
+  data: Uint8Array
+  format: H264SampleFormat
+}
+
+export interface H264NalUnitSample {
+  nals: Uint8Array[]
+  format: H264NalUnitFormat
+}
+
+/**
+ * Normalize a H.264 access unit/sample to length-prefixed AVCC for fMP4 mdat
+ * payloads. Already-AVCC samples are returned as-is. Annex-B and single raw
+ * NAL samples are converted one-way to AVCC at the MSE/fMP4 boundary.
+ */
+export function normalizeH264SampleToAvcc(data: Uint8Array): H264AvccSample {
+  if (isCompleteAvccSample(data)) return { data, format: 'avcc' }
+  if (isAnnexB(data)) return { data: annexBToAvcc(data), format: 'annexb' }
+  if (isLikelyRawH264NalUnit(data)) return { data: rawH264NalToAvcc(data), format: 'raw-nal' }
+  return { data, format: 'unknown' }
+}
+
+/**
+ * Split a H.264 access unit/sample into NAL units without changing its framing.
+ * Use this for routing, keyframe gates, and diagnostics. Conversion to AVCC is
+ * reserved for `normalizeH264SampleToAvcc` at the fMP4/MSE boundary.
+ */
+export function splitH264SampleNalUnits(
+  data: Uint8Array,
+  options: H264KeyframeDetectionOptions = {},
+): H264NalUnitSample {
+  if (isCompleteAvccSample(data)) return { nals: splitAvccNalUnits(data), format: 'avcc' }
+  if (isAnnexB(data)) return { nals: splitAnnexBNalUnits(data), format: 'annexb' }
+  if (options.allowPartialAvcc === true) {
+    const partial = splitPartialAvccNalUnits(data)
+    if (partial.length > 0) return { nals: partial, format: 'partial-avcc' }
+  }
+  if (isLikelyRawH264NalUnit(data)) return { nals: [data], format: 'raw-nal' }
+  const nals = splitAvccNalUnits(data)
+  return { nals, format: nals.length > 0 ? 'avcc' : 'unknown' }
+}
+
+/**
+ * Extract HEVC VPS (type 32) / SPS (33) / PPS (34) NAL units from a keyframe access
+ * unit. Accepts either Annex-B (start-code delimited) or AVCC/hvcC (length-prefixed)
+ * framing — FFmpeg LOC delivers the latter.
+ */
+export function extractHevcParameterSets(keyframe: Uint8Array): HevcParameterSets {
+  const nals = isAnnexB(keyframe) ? splitAnnexBNalUnits(keyframe) : splitAvccNalUnits(keyframe)
+  const out: HevcParameterSets = {}
+  for (const nal of nals) {
+    if (nal.length === 0) continue
+    const t = hevcNalType(nal)
+    if (t === 32 && !out.vps) out.vps = nal
+    else if (t === 33 && !out.sps) out.sps = nal
+    else if (t === 34 && !out.pps) out.pps = nal
+  }
+  return out
+}
+
+/**
+ * Build a minimal hvcC (HEVCDecoderConfigurationRecord, ISO 14496-15 §8.3.3.1) from
+ * VPS/SPS/PPS NAL units. The general profile_tier_level (12 bytes) is copied from the
+ * SPS (de-emulated); remaining fields use the common 4:2:0 / 8-bit / 4-byte-NAL-length
+ * defaults. Suitable as the `description` for a WebCodecs hvc1 VideoDecoderConfig.
+ *
+ * WebCodecs REQUIRES a description for length-prefixed HEVC — unlike H.264, Chrome will
+ * not self-configure HEVC from the bitstream (BLO-7764).
+ */
+export function generateHvcCFromParameterSets(sets: HevcParameterSets): Uint8Array | null {
+  const { vps, sps, pps } = sets
+  if (!sps || !pps) return null
+  const spsRbsp = removeEmulationPrevention(sps)
+  // general profile_tier_level is 12 bytes at RBSP offset 3:
+  // 2-byte NAL header + 1 byte (sps_video_parameter_set_id u(4), sps_max_sub_layers_minus1
+  // u(3), sps_temporal_id_nesting_flag u(1)), then general_profile_space..general_level_idc.
+  const ptl = spsRbsp.subarray(3, 15)
+  const arrays = [
+    { type: 32, nal: vps },
+    { type: 33, nal: sps },
+    { type: 34, nal: pps },
+  ].filter((a): a is { type: number; nal: Uint8Array } => a.nal !== undefined)
+
+  let size = 23
+  for (const a of arrays) size += 5 + a.nal.length
+  const h = new Uint8Array(size)
+  let o = 0
+  h[o++] = 1                                    // configurationVersion
+  for (let i = 0; i < 12; i++) h[o++] = ptl[i] ?? 0   // general profile_tier_level
+  h[o++] = 0xf0; h[o++] = 0x00                  // reserved(1111) + min_spatial_segmentation_idc(0)
+  h[o++] = 0xfc                                 // reserved(111111) + parallelismType(0)
+  h[o++] = 0xfd                                 // reserved(111111) + chromaFormat(1 = 4:2:0)
+  h[o++] = 0xf8                                 // reserved(11111) + bitDepthLumaMinus8(0)
+  h[o++] = 0xf8                                 // reserved(11111) + bitDepthChromaMinus8(0)
+  h[o++] = 0x00; h[o++] = 0x00                  // avgFrameRate(0 = unspecified)
+  h[o++] = 0x0b                                 // CFR(0) numTempLayers(1) nested(0) lengthSizeMinusOne(3)
+  h[o++] = arrays.length                        // numOfArrays
+  for (const a of arrays) {
+    h[o++] = a.type & 0x3f                       // array_completeness(0) + NAL_unit_type
+    h[o++] = 0; h[o++] = 1                        // numNalus = 1
+    h[o++] = (a.nal.length >> 8) & 0xff
+    h[o++] = a.nal.length & 0xff
+    h.set(a.nal, o); o += a.nal.length
+  }
+  return h.subarray(0, o)
+}
+
+/**
+ * Build an hvcC `description` for a WebCodecs HEVC VideoDecoderConfig directly from a
+ * keyframe access unit (Annex-B or length-prefixed). Returns null if VPS/SPS/PPS aren't
+ * present in-band. HEVC analogue of {@link extractCodecDescriptionFromAnnexB}.
+ */
+export function extractHevcCodecDescription(keyframe: Uint8Array): Uint8Array | null {
+  return generateHvcCFromParameterSets(extractHevcParameterSets(keyframe))
+}
+
+/**
+ * Strip non-VCL NAL units (VPS/SPS/PPS/SEI/AUD, type >= 32) from an HEVC access unit,
+ * returning only the VCL NAL units (type <= 31) as a 4-byte length-prefixed buffer.
+ *
+ * Required when decoding `hvc1` with an explicit hvcC `description`: WebCodecs rejects a
+ * sample whose data still carries in-band parameter sets ("Unable to determine size of
+ * bitstream buffer"). Accepts Annex-B or length-prefixed input. Returns the input
+ * unchanged if it already contains only VCL NALs (cheap no-op for delta frames).
+ */
+export function hevcVclOnly(data: Uint8Array): Uint8Array {
+  const nals = isAnnexB(data) ? splitAnnexBNalUnits(data) : splitAvccNalUnits(data)
+  const vcl = nals.filter((n) => n.length > 0 && hevcNalType(n) <= 31)
+  if (vcl.length === nals.length && !isAnnexB(data)) return data
+  let size = 0
+  for (const n of vcl) size += 4 + n.length
+  const out = new Uint8Array(size)
+  let o = 0
+  for (const n of vcl) {
+    out[o++] = (n.length >> 24) & 0xff
+    out[o++] = (n.length >> 16) & 0xff
+    out[o++] = (n.length >> 8) & 0xff
+    out[o++] = n.length & 0xff
+    out.set(n, o); o += n.length
+  }
+  return out
+}
+
+/**
+ * Check if data starts with an Annex-B start code (00 00 01 or 00 00 00 01).
+ */
+export function isAnnexB(data: Uint8Array): boolean {
+  if (data.length >= 4 && data[0] === 0 && data[1] === 0 &&
+      (data[2] === 1 || (data[2] === 0 && data[3] === 1))) {
+    return true
+  }
+  return false
+}
+
+/**
+ * Find the byte offset of the first Annex-B start code in data.
+ * Returns -1 if no start code found.
+ */
+export function findAnnexBStartCode(data: Uint8Array): number {
+  for (let i = 0; i < data.length - 3; i++) {
+    if (data[i] === 0 && data[i + 1] === 0) {
+      if (data[i + 2] === 1) return i
+      if (data[i + 2] === 0 && data[i + 3] === 1) return i
+    }
+  }
+  return -1
+}
+
+/**
+ * Split Annex-B bitstream into NAL units.
+ * Returns array of NAL unit byte slices (without start codes).
+ */
+export function splitAnnexBNalUnits(data: Uint8Array): Uint8Array[] {
+  const nalUnits: Uint8Array[] = []
+  let i = 0
+  while (i < data.length - 3) {
+    if (data[i] === 0 && data[i + 1] === 0) {
+      let scLen = 0
+      if (data[i + 2] === 1) scLen = 3
+      else if (data[i + 2] === 0 && i + 3 < data.length && data[i + 3] === 1) scLen = 4
+      if (scLen > 0) {
+        const nalStart = i + scLen
+        let nalEnd = data.length
+        for (let j = nalStart + 1; j < data.length - 2; j++) {
+          if (data[j] === 0 && data[j + 1] === 0 &&
+              (data[j + 2] === 1 || (data[j + 2] === 0 && j + 3 < data.length && data[j + 3] === 1))) {
+            nalEnd = j
+            break
+          }
+        }
+        if (nalEnd > nalStart) nalUnits.push(data.subarray(nalStart, nalEnd))
+        i = nalEnd
+        continue
+      }
+    }
+    i++
+  }
+  return nalUnits
+}
+
+/**
+ * Convert Annex-B (start-code delimited) to AVCC (4-byte length prefixed).
+ * Optionally prepends SPS/PPS NALs for keyframes.
+ */
+export function annexBToAvcc(data: Uint8Array, spsPps?: SpsPps): Uint8Array {
+  const nalUnits = splitAnnexBNalUnits(data)
+  if (nalUnits.length === 0) return data
+
+  let extraSize = 0
+  if (spsPps) {
+    extraSize = 4 + spsPps.sps.length + 4 + spsPps.pps.length
+  }
+  const frameSize = nalUnits.reduce((sum, nal) => sum + 4 + nal.length, 0)
+  const output = new Uint8Array(extraSize + frameSize)
+  let w = 0
+
+  if (spsPps) {
+    w = writeNalLength(output, w, spsPps.sps.length)
+    output.set(spsPps.sps, w); w += spsPps.sps.length
+    w = writeNalLength(output, w, spsPps.pps.length)
+    output.set(spsPps.pps, w); w += spsPps.pps.length
+  }
+
+  for (const nal of nalUnits) {
+    w = writeNalLength(output, w, nal.length)
+    output.set(nal, w); w += nal.length
+  }
+  return output
+}
+
+export interface H264KeyframeDetectionOptions {
+  /**
+   * Allow classifying a length-prefixed NAL when the declared NAL length runs
+   * beyond this buffer. MMTP routing can see only the first packet fragment of
+   * a sample, where the NAL header is present but the full NAL is not.
+   */
+  allowPartialAvcc?: boolean
+}
+
+/**
+ * Classify H.264 keyframe status by scanning NAL units. Returns undefined when
+ * the payload is not H.264-classifiable. Handles Annex-B and AVCC formats.
+ */
+export function classifyH264Keyframe(
+  data: Uint8Array,
+  options: H264KeyframeDetectionOptions = {},
+): boolean | undefined {
+  const nals = h264NalUnitsForKeyframeDetection(data, options)
+  if (nals.length === 0) return undefined
+  let sawIntraSlice = false
+  let sawNonIntraVcl = false
+  let sawNal = false
+  for (const nal of nals) {
+    sawNal = true
+    const nalType = nal[0] !== undefined ? nal[0] & 0x1f : -1
+    if (nalType === 5 || nalType === 7) return true
+    if (nalType === 1) {
+      if (isH264IntraSlice(nal)) sawIntraSlice = true
+      else sawNonIntraVcl = true
+    }
+  }
+  if (sawIntraSlice && !sawNonIntraVcl) return true
+  return sawNal ? false : undefined
+}
+
+/**
+ * Detect H.264 keyframe by scanning for IDR/SPS or intra non-IDR slices.
+ * Handles both Annex-B and AVCC formats.
+ */
+export function detectH264Keyframe(
+  data: Uint8Array,
+  options: H264KeyframeDetectionOptions = {},
+): boolean {
+  return classifyH264Keyframe(data, options) === true
+}
+
+/**
+ * Convert MMTP timestamp (NTP short format) to monotonic microseconds.
+ * Per ISO 23008-1 §9.2.2 / RFC 5905: upper 16 bits = seconds (lower 16
+ * of NTP seconds), lower 16 bits = fractional seconds.
+ * Returns a monotonically increasing µs value within an ~18-hour window.
+ */
+export function mmtpTimestampToMicros(rawTs: bigint | number): number {
+  const ts = Number(rawTs) >>> 0  // ensure unsigned 32-bit
+  if (ts === 0) return 0
+  const seconds = ts >>> 16
+  const frac = ts & 0xFFFF
+  return seconds * 1_000_000 + Math.floor(frac * 1_000_000 / 65536)
+}
+
+/** Validate the CMSF/MMTP catalog initData contract: complete top-level ftyp+moov. */
+export function isFmp4InitSegment(data: Uint8Array): boolean {
+  let offset = 0
+  let sawFtyp = false
+  let sawMoov = false
+
+  while (offset + 8 <= data.byteLength) {
+    const view = new DataView(data.buffer, data.byteOffset + offset, data.byteLength - offset)
+    let size = view.getUint32(0, false)
+    const type = String.fromCharCode(data[offset + 4]!, data[offset + 5]!, data[offset + 6]!, data[offset + 7]!)
+    let headerSize = 8
+
+    if (size === 1) {
+      if (offset + 16 > data.byteLength) return false
+      const largeSize = view.getBigUint64(8, false)
+      if (largeSize > BigInt(Number.MAX_SAFE_INTEGER)) return false
+      size = Number(largeSize)
+      headerSize = 16
+    } else if (size === 0) {
+      size = data.byteLength - offset
+    }
+
+    if (size < headerSize || offset + size > data.byteLength) return false
+    if (type === 'ftyp') sawFtyp = true
+    if (type === 'moov') {
+      if (!sawFtyp) return false
+      sawMoov = true
+    }
+    offset += size
+  }
+
+  return offset === data.byteLength && sawFtyp && sawMoov
+}
+
+// ─── Internal Helpers ────────────────────────────────────────────
+
+function hasIsoBmffMagic(data: Uint8Array): boolean {
+  for (let i = 0; i + 8 <= data.length && i < 32; i += 4) {
+    const tag = String.fromCharCode(data[i + 4], data[i + 5], data[i + 6], data[i + 7])
+    if (tag === 'ftyp' || tag === 'moov') return true
+  }
+  return false
+}
+
+function findTrackStsdBoxes(data: Uint8Array): Array<{ o: number; sz: number }> {
+  const moov = findBox(data, 0, data.length, 'moov')
+  if (!moov) return []
+
+  const out: Array<{ o: number; sz: number }> = []
+  for (const trak of findBoxes(data, moov.o + 8, moov.o + moov.sz, 'trak')) {
+    const stsd = findNestedBox(data, trak.o + 8, trak.o + trak.sz, ['mdia', 'minf', 'stbl', 'stsd'])
+    if (stsd) out.push(stsd)
+  }
+  return out
+}
+
+function findNestedBox(
+  buf: Uint8Array,
+  start: number,
+  end: number,
+  path: string[],
+): { o: number; sz: number } | undefined {
+  let s = start
+  let e = end
+  let current: { o: number; sz: number } | undefined
+  for (const type of path) {
+    current = findBox(buf, s, e, type)
+    if (!current) return undefined
+    s = current.o + 8
+    e = current.o + current.sz
+  }
+  return current
+}
+
+function findBox(buf: Uint8Array, start: number, end: number, type: string): { o: number; sz: number } | undefined {
+  return findBoxes(buf, start, end, type)[0]
+}
+
+function findBoxes(buf: Uint8Array, start: number, end: number, type: string): Array<{ o: number; sz: number }> {
+  const boxes: Array<{ o: number; sz: number }> = []
+  let o = start
+  while (o + 8 <= end) {
+    let sz = (buf[o] << 24) | (buf[o + 1] << 16) | (buf[o + 2] << 8) | buf[o + 3]
+    const t = String.fromCharCode(buf[o + 4], buf[o + 5], buf[o + 6], buf[o + 7])
+    if (sz === 0) sz = end - o
+    if (sz < 8 || o + sz > end) break
+    if (t === type) boxes.push({ o, sz })
+    o += sz
+  }
+  return boxes
+}
+
+function writeNalLength(buf: Uint8Array, offset: number, len: number): number {
+  buf[offset] = (len >> 24) & 0xff
+  buf[offset + 1] = (len >> 16) & 0xff
+  buf[offset + 2] = (len >> 8) & 0xff
+  buf[offset + 3] = len & 0xff
+  return offset + 4
+}
+
+function h264NalUnitsForKeyframeDetection(
+  data: Uint8Array,
+  options: H264KeyframeDetectionOptions,
+): Uint8Array[] {
+  return splitH264SampleNalUnits(data, options).nals
+}
+
+function splitPartialAvccNalUnits(data: Uint8Array, lengthSize = 4): Uint8Array[] {
+  const nals: Uint8Array[] = []
+  let i = 0
+  while (i + lengthSize < data.length) {
+    let len = 0
+    for (let k = 0; k < lengthSize; k++) len = (len << 8) | data[i + k]
+    i += lengthSize
+    if (len <= 0 || i >= data.length) break
+    const end = Math.min(i + len, data.length)
+    nals.push(data.subarray(i, end))
+    if (end < i + len) break
+    i = end
+  }
+  return nals
+}
+
+function isLikelyRawH264NalUnit(data: Uint8Array): boolean {
+  if (data.length === 0) return false
+  const header = data[0]!
+  if ((header & 0x80) !== 0) return false
+  const nalType = header & 0x1f
+  return nalType > 0 && nalType < 24
+}
+
+function rawH264NalToAvcc(data: Uint8Array): Uint8Array {
+  const out = new Uint8Array(4 + data.length)
+  new DataView(out.buffer, out.byteOffset, out.byteLength).setUint32(0, data.length)
+  out.set(data, 4)
+  return out
+}
+
+function isH264IntraSlice(nal: Uint8Array): boolean {
+  const sliceType = readH264SliceType(nal)
+  return sliceType === 2 || sliceType === 4 || sliceType === 7 || sliceType === 9
+}
+
+function readH264SliceType(nal: Uint8Array): number | null {
+  if (nal.length < 2 || (nal[0]! & 0x1f) !== 1) return null
+  const rbsp = removeEmulationPrevention(nal.subarray(1))
+  const state = { bitOffset: 0 }
+  if (readUnsignedExpGolomb(rbsp, state) === null) return null
+  return readUnsignedExpGolomb(rbsp, state)
+}
+
+function readUnsignedExpGolomb(data: Uint8Array, state: { bitOffset: number }): number | null {
+  let leadingZeroBits = 0
+  while (true) {
+    const bit = readBit(data, state)
+    if (bit === null) return null
+    if (bit === 1) break
+    leadingZeroBits++
+    if (leadingZeroBits > 30) return null
+  }
+
+  let suffix = 0
+  for (let i = 0; i < leadingZeroBits; i++) {
+    const bit = readBit(data, state)
+    if (bit === null) return null
+    suffix = (suffix << 1) | bit
+  }
+  return (1 << leadingZeroBits) - 1 + suffix
+}
+
+function readBit(data: Uint8Array, state: { bitOffset: number }): 0 | 1 | null {
+  if (state.bitOffset >= data.length * 8) return null
+  const byte = data[state.bitOffset >> 3]!
+  const bit = (byte >> (7 - (state.bitOffset & 7))) & 1
+  state.bitOffset++
+  return bit as 0 | 1
+}
+
+function hex2(n: number): string {
+  return n.toString(16).padStart(2, '0')
+}
+
+function pad2(n: number): string {
+  return String(n).padStart(2, '0')
+}
+
+function codecStringFromAv1C(av1C: Uint8Array): string {
+  if (av1C.length < 4) return 'av01.0.01M.08'
+  const profile = (av1C[1]! >>> 5) & 0x07
+  const level = av1C[1]! & 0x1f
+  const tier = (av1C[2]! & 0x80) !== 0 ? 'H' : 'M'
+  let bitDepth = 8
+  if ((av1C[2]! & 0x40) !== 0) {
+    bitDepth = (av1C[2]! & 0x20) !== 0 ? 12 : 10
+  }
+  return `av01.${profile}.${pad2(level)}${tier}.${pad2(bitDepth)}`
+}
+
+function codecStringFromVpcC(vpcC: Uint8Array): string {
+  if (vpcC.length < 3) return 'vp09.00.10.08'
+  // ISO/IEC 14496-15 defines vpcC as a FullBox. Some tooling hands callers
+  // the VPCodecConfigurationRecord after the 4-byte FullBox header; tolerate
+  // both shapes because WebCodecs callers only need a stable RFC 6381 fallback.
+  const offset = vpcC.length >= 7 && vpcC[0] <= 1 ? 4 : 0
+  if (offset + 2 >= vpcC.length) return 'vp09.00.10.08'
+  const profile = vpcC[offset]!
+  const level = vpcC[offset + 1]!
+  const bitDepth = (vpcC[offset + 2]! >>> 4) || 8
+  return `vp09.${pad2(profile)}.${pad2(level)}.${pad2(bitDepth)}`
+}
+
+/**
+ * Derive an RFC 6381 HEVC codec string (e.g. "hvc1.1.6.L93.90") from the
+ * payload of an hvcC box (the HEVCDecoderConfigurationRecord, ISO 14496-15 §8.3.3.1).
+ * Only the general_* fields in the fixed 23-byte header are needed:
+ *   byte 1: general_profile_space(2) | general_tier_flag(1) | general_profile_idc(5)
+ *   bytes 2-5:  general_profile_compatibility_flags (32 bits)
+ *   bytes 6-11: general_constraint_indicator_flags (48 bits)
+ *   byte 12:    general_level_idc
+ */
+function hevcCodecStringFromHvcC(c: Uint8Array): string {
+  const profileSpace = (c[1] >> 6) & 0x3
+  const tierFlag = (c[1] >> 5) & 0x1
+  const profileIdc = c[1] & 0x1f
+  // Compatibility flags are emitted reversed bit-order as hex, leading zeros trimmed.
+  const compat = ((c[2] << 24) | (c[3] << 16) | (c[4] << 8) | c[5]) >>> 0
+  let rev = 0
+  let v = compat
+  for (let i = 0; i < 32; i++) {
+    rev = ((rev << 1) | (v & 1)) >>> 0
+    v >>>= 1
+  }
+  const compatStr = rev.toString(16)
+  // Constraint flags: dot-separated hex bytes, trailing zero bytes trimmed.
+  const constraint = c.subarray(6, 12)
+  let lastNonZero = -1
+  for (let i = 0; i < constraint.length; i++) if (constraint[i] !== 0) lastNonZero = i
+  const constraintParts: string[] = []
+  for (let i = 0; i <= lastNonZero; i++) constraintParts.push(constraint[i].toString(16))
+  const space = profileSpace === 0 ? '' : String.fromCharCode(64 + profileSpace) // 1→'A', 2→'B', 3→'C'
+  const tier = tierFlag === 0 ? 'L' : 'H'
+  let s = `hvc1.${space}${profileIdc}.${compatStr}.${tier}${c[12]}`
+  if (constraintParts.length > 0) s += '.' + constraintParts.join('.')
+  return s
+}
+
+/** Exp-Golomb bitstream writer for SPS/PPS generation. */
+class BitWriter {
+  buf: number[] = []
+  byte = 0
+  bit = 7
+
+  u(val: number, bits: number) {
+    for (let i = bits - 1; i >= 0; i--) {
+      this.byte |= ((val >> i) & 1) << this.bit
+      if (--this.bit < 0) {
+        this.buf.push(this.byte)
+        this.byte = 0
+        this.bit = 7
+      }
+    }
+  }
+
+  ue(val: number) {
+    const v = val + 1
+    const bits = Math.floor(Math.log2(v)) + 1
+    this.u(0, bits - 1)
+    this.u(v, bits)
+  }
+
+  se(val: number) {
+    this.ue(val <= 0 ? -val * 2 : val * 2 - 1)
+  }
+
+  finish(): Uint8Array {
+    if (this.bit < 7) {
+      this.byte |= 1 << this.bit
+      this.buf.push(this.byte)
+    }
+    return new Uint8Array(this.buf)
+  }
+}
+
+function resolveResolution(
+  explicitW: number | undefined,
+  explicitH: number | undefined,
+  level: number,
+): { width: number; height: number } {
+  if (explicitW && explicitH) return { width: explicitW, height: explicitH }
+
+  const levelResolutions: Record<number, [number, number]> = {
+    10: [176, 144], 11: [352, 288], 12: [352, 288], 13: [352, 288],
+    20: [352, 288], 21: [720, 576], 22: [720, 576],
+    30: [1280, 720], 31: [1280, 720], 32: [1280, 1024],
+    40: [1920, 1088], 41: [1920, 1088], 42: [2048, 1088],
+    50: [4096, 2160], 51: [4096, 2160], 52: [4096, 2160],
+  }
+
+  const [w, h] = levelResolutions[level] ?? [1920, 1088]
+  return { width: explicitW ?? w, height: explicitH ?? h }
+}
+
+function buildMinimalSps(
+  profile: number, constraint: number, level: number,
+  width: number, height: number,
+): Uint8Array {
+  const widthInMbs = Math.ceil(width / 16)
+  const heightInMapUnits = Math.ceil(height / 16)
+
+  const w = new BitWriter()
+  w.u(0, 1); w.u(3, 2); w.u(7, 5) // NAL header: SPS
+  w.u(profile, 8); w.u(constraint, 8); w.u(level, 8)
+  w.ue(0) // seq_parameter_set_id
+
+  if (profile === 100 || profile === 110 || profile === 122 || profile === 244 || profile === 44) {
+    w.ue(1); w.ue(0); w.ue(0) // chroma + bit depth
+    w.u(0, 1); w.u(0, 1) // transform bypass + scaling matrix
+  }
+
+  w.ue(0) // log2_max_frame_num_minus4
+  w.ue(2) // pic_order_cnt_type=2
+  w.ue(1) // max_num_ref_frames
+  w.u(0, 1) // gaps_in_frame_num
+  w.ue(widthInMbs - 1)
+  w.ue(heightInMapUnits - 1)
+  w.u(1, 1) // frame_mbs_only
+  w.u(1, 1) // direct_8x8_inference
+
+  const cropRight = widthInMbs * 16 - width
+  const cropBottom = heightInMapUnits * 16 - height
+  if (cropRight > 0 || cropBottom > 0) {
+    w.u(1, 1)
+    w.ue(0); w.ue(cropRight / 2); w.ue(0); w.ue(cropBottom / 2)
+  } else {
+    w.u(0, 1)
+  }
+
+  w.u(0, 1) // vui_parameters_present
+  return w.finish()
+}
+
+function buildMinimalPps(profile: number): Uint8Array {
+  const isHighProfile = profile === 100 || profile === 110 || profile === 122 || profile === 244 || profile === 44
+  const w = new BitWriter()
+  w.u(0, 1); w.u(3, 2); w.u(8, 5) // NAL header: PPS
+
+  w.ue(0); w.ue(0) // pps_id, sps_id
+  w.u(isHighProfile ? 1 : 0, 1) // entropy_coding_mode
+  w.u(0, 1) // bottom_field_pic_order
+  w.ue(0); w.ue(0); w.ue(0) // slice groups, ref_idx defaults
+  w.u(0, 1); w.u(0, 2) // weighted_pred
+  w.se(0); w.se(0); w.se(0) // qp offsets
+  w.u(1, 1); w.u(0, 1); w.u(0, 1) // deblock, constrained_intra, redundant_pic_cnt
+
+  if (isHighProfile) {
+    w.u(1, 1); w.u(0, 1); w.se(0) // transform_8x8, scaling_matrix, chroma_qp_offset
+  }
+
+  return w.finish()
+}
+
+// ─── AAC / ADTS Utilities ──────────────────────────────────────
+
+/** ISO 14496-3 sampling frequency index lookup. */
+const ADTS_SAMPLE_RATES = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350] as const
+
+/**
+ * Prepend a 7-byte ADTS header to a raw AAC access unit.
+ *
+ * WebCodecs AudioDecoder configured WITHOUT an AudioSpecificConfig `description`
+ * expects ADTS-framed AAC.  MMTP carries raw AAC (no ADTS sync), so this wrapper
+ * must be applied before calling `AudioDecoder.decode()`.
+ */
+export function wrapAdtsFrame(raw: Uint8Array, sampleRate: number, channels: number): Uint8Array {
+  const sri = ADTS_SAMPLE_RATES.indexOf(sampleRate as typeof ADTS_SAMPLE_RATES[number])
+  const idx = sri >= 0 ? sri : 3  // default 48 kHz
+  const len = 7 + raw.length
+  const out = new Uint8Array(len)
+  out[0] = 0xFF
+  out[1] = 0xF1                                         // MPEG-4, Layer 0, no CRC
+  out[2] = (1 << 6) | (idx << 2) | (channels >> 2)     // profile=AAC-LC(1), freq, ch high
+  out[3] = ((channels & 3) << 6) | ((len >> 11) & 3)
+  out[4] = (len >> 3) & 0xFF
+  out[5] = ((len & 7) << 5) | 0x1F
+  out[6] = 0xFC
+  out.set(raw, 7)
+  return out
+}
+
+/**
+ * Extract AAC AudioSpecificConfig (ASC) from an fMP4 init segment.
+ *
+ * Walks moov > trak > mdia > minf > stbl > stsd > mp4a > esds, then descends
+ * the MPEG-4 descriptor chain (ES_Descriptor 0x03 > DecoderConfigDescriptor
+ * 0x04 > DecoderSpecificInfo 0x05) to return the ASC payload.
+ *
+ * Sibling of extractAvcCFromInitSegment, used by the same BLO-4830 / CMSF §3.1
+ * path: when the catalog initData is the full ftyp+moov, WebCodecs' AudioDecoder
+ * needs the raw ASC (~2 bytes for AAC-LC) as `description`, NOT the whole
+ * segment. Without this extraction the configure() succeeds but every decode()
+ * silently produces zero output (no error fires), exactly the symptom that
+ * shows up as "Audio continuity FAILED: energy unstable CV=1.00" in the
+ * 7-point E2E test (CV=1.00 is the meanEnergy=0 sentinel from audio-fft.mjs).
+ *
+ * Returns undefined when:
+ *  - data has no ftyp/moov magic in the first 32 bytes
+ *  - no mp4a sample entry exists in any trak's stbl
+ *  - the esds descriptor chain doesn't yield a DecoderSpecificInfo
+ *  - the ASC payload is shorter than 2 bytes (AOT + sampling-freq nibble)
+ *
+ * Walks every trak and returns the first AAC sample entry. This mirrors
+ * extractAvcCFromInitSegment so multiplexed ftyp+moov init blobs work
+ * regardless of track order.
+ */
+export function extractAacAscFromInitSegment(data: Uint8Array): AacAscInfo | undefined {
+  if (!hasIsoBmffMagic(data)) return undefined
+
+  for (const stsd of findTrackStsdBoxes(data)) {
+    const info = extractAacAscFromStsd(data, stsd)
+    if (info) return info
+  }
+
+  return undefined
+}
+
+function extractAacAscFromStsd(data: Uint8Array, stsd: { o: number; sz: number }): AacAscInfo | undefined {
+  // stsd: 8 box header + 4 version+flags + 4 entry_count = 16 bytes before entries.
+  const s = stsd.o + 16
+  const e = stsd.o + stsd.sz
+  // mp4a AudioSampleEntry minimum length: 8 box header + 28 fixed fields = 36 bytes
+  // before any child boxes (esds lives here).
+  const mp4a = findBox(data, s, e, 'mp4a')
+  if (!mp4a || mp4a.sz < 36) return undefined
+  const esds = findBox(data, mp4a.o + 36, mp4a.o + mp4a.sz, 'esds')
+  // esds = 8 box header + 4 full-box version+flags = 12 bytes minimum before descriptors.
+  if (!esds || esds.sz < 12) return undefined
+  const esdsPayload = data.subarray(esds.o + 8, esds.o + esds.sz)
+  const asc = extractAudioSpecificConfig(esdsPayload)
+  if (!asc || asc.length < 2) return undefined
+  // AudioObjectType = top 5 bits of ASC[0]. AAC-LC = 2, HE-AAC = 5, etc.
+  const aot = asc[0] >> 3
+  return { codec: `mp4a.40.${aot}`, description: asc }
+}
+
+/**
+ * Walk an esds descriptor chain to find DecoderSpecificInfo (tag 0x05).
+ * Step over fixed-size headers of container descriptors (0x03, 0x04) so the
+ * scan continues into their children rather than skipping their full payload.
+ *
+ * Assumes the ES_Descriptor flags byte is zero (no streamDependence, URL, OCR
+ * ES_ID fields). FFmpeg's mov/mp4 muxer emits exactly that for all standard
+ * AAC tracks; the assumption is the same one extractAvcCFromInitSegment makes
+ * about the avc1 sample entry's reserved fields.
+ *
+ * Input is the esds box payload AFTER the 8-byte box header; the first 4 bytes
+ * (full-box version+flags) are skipped here.
+ */
+function extractAudioSpecificConfig(esds: Uint8Array): Uint8Array | undefined {
+  let offset = 4  // skip esds version+flags
+  while (offset < esds.length) {
+    const tag = esds[offset++]
+    let size = 0
+    for (let i = 0; i < 4 && offset < esds.length; i++) {
+      const b = esds[offset++]
+      size = (size << 7) | (b & 0x7f)
+      if ((b & 0x80) === 0) break
+    }
+    if (tag === 0x05) {
+      if (offset + size > esds.length) return undefined
+      return esds.subarray(offset, offset + size)
+    }
+    if (tag === 0x03) {
+      offset += 3   // ES_ID (2) + flags (1)
+    } else if (tag === 0x04) {
+      offset += 13  // OTI (1) + streamType (1) + bufferSizeDB (3) + maxBitrate (4) + avgBitrate (4)
+    } else {
+      offset += size
+    }
+  }
+  return undefined
+}
+
+// =============================================================================
+// Inline Tests (vitest)
+// =============================================================================
+
+if (import.meta.vitest) {
+  const { describe, test, expect } = import.meta.vitest
+
+  describe('codec-utils', () => {
+    describe('isAnnexB', () => {
+      test('4-byte start code', () => {
+        expect(isAnnexB(new Uint8Array([0, 0, 0, 1, 0x65]))).toBe(true)
+      })
+      test('3-byte start code', () => {
+        expect(isAnnexB(new Uint8Array([0, 0, 1, 0x65]))).toBe(true)
+      })
+      test('rejects AVCC', () => {
+        expect(isAnnexB(new Uint8Array([0, 0, 0, 10, 0x65]))).toBe(false)
+      })
+    })
+
+    describe('findAnnexBStartCode', () => {
+      test('at offset 0', () => {
+        expect(findAnnexBStartCode(new Uint8Array([0, 0, 0, 1, 0x65]))).toBe(0)
+      })
+      test('at offset 5', () => {
+        expect(findAnnexBStartCode(new Uint8Array([0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0, 0, 1, 0x65]))).toBe(5)
+      })
+      test('returns -1 when none', () => {
+        expect(findAnnexBStartCode(new Uint8Array([0xAA, 0xBB, 0xCC]))).toBe(-1)
+      })
+    })
+
+    describe('splitAnnexBNalUnits', () => {
+      test('splits two NALs', () => {
+        const data = new Uint8Array([0, 0, 0, 1, 0x65, 0xAA, 0xBB, 0, 0, 0, 1, 0x41, 0xCC])
+        const nals = splitAnnexBNalUnits(data)
+        expect(nals.length).toBe(2)
+        expect(nals[0]).toEqual(new Uint8Array([0x65, 0xAA, 0xBB]))
+        expect(nals[1]).toEqual(new Uint8Array([0x41, 0xCC]))
+      })
+      test('handles 3-byte start codes', () => {
+        const nals = splitAnnexBNalUnits(new Uint8Array([0, 0, 1, 0x67, 0x42, 0, 0, 1, 0x68, 0x01]))
+        expect(nals.length).toBe(2)
+      })
+    })
+
+    describe('annexBToAvcc', () => {
+      test('converts single NAL', () => {
+        const annexB = new Uint8Array([0, 0, 0, 1, 0x41, 0xAA, 0xBB])
+        const avcc = annexBToAvcc(annexB)
+        expect(avcc[3]).toBe(3) // NAL length
+        expect(avcc[4]).toBe(0x41)
+      })
+      test('prepends SPS/PPS', () => {
+        const annexB = new Uint8Array([0, 0, 0, 1, 0x65, 0x01])
+        const avcc = annexBToAvcc(annexB, { sps: new Uint8Array([0x67, 0x42]), pps: new Uint8Array([0x68, 0x01]) })
+        expect(avcc[3]).toBe(2) // SPS length
+        expect(avcc[4]).toBe(0x67)
+      })
+    })
+
+    describe('detectH264Keyframe', () => {
+      test('IDR in Annex-B', () => {
+        expect(detectH264Keyframe(new Uint8Array([0, 0, 0, 1, 0x65]))).toBe(true)
+      })
+      test('SPS in Annex-B', () => {
+        expect(detectH264Keyframe(new Uint8Array([0, 0, 0, 1, 0x67]))).toBe(true)
+      })
+      test('IDR in AVCC', () => {
+        expect(detectH264Keyframe(new Uint8Array([0, 0, 0, 5, 0x65, 1, 2, 3, 4]))).toBe(true)
+      })
+      test('IDR after AVCC AUD', () => {
+        expect(detectH264Keyframe(new Uint8Array([
+          0, 0, 0, 1, 0x09,
+          0, 0, 0, 2, 0x65, 0xaa,
+        ]))).toBe(true)
+      })
+      test('non-IDR AVC I-slice in AVCC', () => {
+        expect(detectH264Keyframe(new Uint8Array([
+          0, 0, 0, 2, 0x41, 0x88,
+        ]))).toBe(true)
+      })
+      test('raw H.264 IDR NAL', () => {
+        expect(detectH264Keyframe(new Uint8Array([0x65, 0x88, 0x84]))).toBe(true)
+      })
+      test('raw H.264 non-IDR I-slice NAL', () => {
+        expect(detectH264Keyframe(new Uint8Array([0x41, 0x88]))).toBe(true)
+      })
+      test('classifies partial length-prefixed IDR only when requested', () => {
+        const partial = new Uint8Array([0, 0, 0x20, 0, 0x65])
+        expect(classifyH264Keyframe(partial)).toBeUndefined()
+        expect(classifyH264Keyframe(partial, { allowPartialAvcc: true })).toBe(true)
+      })
+      test('rejects P-frame', () => {
+        expect(detectH264Keyframe(new Uint8Array([0, 0, 0, 1, 0x41]))).toBe(false)
+      })
+      test('rejects AVCC sample with only non-IDR slices', () => {
+        expect(detectH264Keyframe(new Uint8Array([
+          0, 0, 0, 2, 0x41, 0xc0,
+          0, 0, 0, 2, 0x41, 0xc0,
+        ]))).toBe(false)
+      })
+    })
+
+    describe('avccToAnnexB', () => {
+      test('converts with SPS/PPS on keyframe', () => {
+        const avcc = new Uint8Array([0, 0, 0, 3, 0x65, 0xAA, 0xBB])
+        const spsPps: SpsPps = { sps: new Uint8Array([0x67, 0x42]), pps: new Uint8Array([0x68, 0x01]) }
+        const annexB = avccToAnnexB(avcc, true, spsPps)
+        expect(annexB[3]).toBe(1) // start code
+        expect(annexB[4]).toBe(0x67) // SPS
+      })
+    })
+
+    describe('codecStringFromAvcC', () => {
+      test('derives avc1.64002a', () => {
+        expect(codecStringFromAvcC(new Uint8Array([1, 100, 0, 42]))).toBe('avc1.64002a')
+      })
+    })
+
+    describe('extractAacAscFromInitSegment', () => {
+      // Build a minimal valid ftyp+moov containing one mp4a sample entry whose
+      // esds carries the supplied AudioSpecificConfig. The walker only needs
+      // the box hierarchy moov > trak > mdia > minf > stbl > stsd > mp4a > esds;
+      // mvhd/tkhd/mdhd/hdlr/smhd/dinf/stts/stsc/stsz/stco are spec-required for
+      // a truly valid init but the extractor never reads them, so we omit them
+      // to keep the fixture tight (~150 bytes vs ~500). FFmpeg's real output
+      // includes them; the production path passes through `findBox` exactly
+      // the same way.
+      function buildMinimalAacInit(asc: Uint8Array): Uint8Array {
+        const box = (type: string, payload: Uint8Array): Uint8Array => {
+          const sz = 8 + payload.length
+          const out = new Uint8Array(sz)
+          out[0] = (sz >>> 24) & 0xff
+          out[1] = (sz >>> 16) & 0xff
+          out[2] = (sz >>> 8) & 0xff
+          out[3] = sz & 0xff
+          out[4] = type.charCodeAt(0); out[5] = type.charCodeAt(1)
+          out[6] = type.charCodeAt(2); out[7] = type.charCodeAt(3)
+          out.set(payload, 8)
+          return out
+        }
+        const concat = (...arrs: Uint8Array[]): Uint8Array => {
+          const total = arrs.reduce((n, a) => n + a.length, 0)
+          const out = new Uint8Array(total)
+          let off = 0
+          for (const a of arrs) { out.set(a, off); off += a.length }
+          return out
+        }
+        // ftyp: major_brand=iso5, minor=0x200, compat=iso5,iso6
+        const ftyp = box('ftyp', new Uint8Array([
+          0x69, 0x73, 0x6f, 0x35,        // 'iso5'
+          0x00, 0x00, 0x02, 0x00,        // minor 0x200
+          0x69, 0x73, 0x6f, 0x35,        // 'iso5'
+          0x69, 0x73, 0x6f, 0x36,        // 'iso6'
+        ]))
+
+        // ESDescriptor (0x03) > DecoderConfigDescriptor (0x04) > DecoderSpecificInfo (0x05) > ASC.
+        // Use 1-byte BER sizes (all payloads < 128).
+        const dsi = new Uint8Array(2 + asc.length)
+        dsi[0] = 0x05; dsi[1] = asc.length
+        dsi.set(asc, 2)
+        // DCD = 13 fixed bytes + DSI: OTI=0x40 (AAC), streamType=0x05<<2|0x01 (audio, upStream=0)
+        const dcd = new Uint8Array(2 + 13 + dsi.length)
+        dcd[0] = 0x04; dcd[1] = 13 + dsi.length
+        dcd[2] = 0x40             // objectTypeIndication: Audio ISO/IEC 14496-3
+        dcd[3] = (0x05 << 2) | 1  // streamType=AudioStream(5), upStream=0, reserved=1
+        // bufferSizeDB(3) + maxBitrate(4) + avgBitrate(4) all zero is fine for the walker.
+        dcd.set(dsi, 15)
+        // ESDescriptor: ES_ID=0, flags=0, then DCD
+        const esd = new Uint8Array(2 + 3 + dcd.length)
+        esd[0] = 0x03; esd[1] = 3 + dcd.length
+        // ES_ID(2) + flags(1) all zero
+        esd.set(dcd, 5)
+        // esds box = full-box (4-byte version+flags) + ES_Descriptor chain
+        const esdsPayload = new Uint8Array(4 + esd.length)
+        esdsPayload.set(esd, 4)
+        const esds = box('esds', esdsPayload)
+
+        // mp4a sample entry: 6 reserved + 2 dref_idx + 8 reserved + 2 channels + 2 samplesize +
+        //                    2 pre_defined + 2 reserved + 4 samplerate(48000<<16) = 28 bytes,
+        //                    then esds child.
+        const mp4aFixed = new Uint8Array(28)
+        mp4aFixed[7] = 0x01                 // data_reference_index = 1
+        mp4aFixed[16] = 0x00; mp4aFixed[17] = 0x01  // channelcount = 1
+        mp4aFixed[18] = 0x00; mp4aFixed[19] = 0x10  // samplesize = 16
+        // samplerate at offset 24-27 (top 16 bits = sampleRate). 48000 = 0xBB80.
+        mp4aFixed[24] = 0xBB; mp4aFixed[25] = 0x80
+        const mp4a = box('mp4a', concat(mp4aFixed, esds))
+
+        // stsd: 4 ver+flags + 4 entry_count(=1) + entries
+        const stsdPayload = new Uint8Array(8 + mp4a.length)
+        stsdPayload[7] = 0x01  // entry_count = 1
+        stsdPayload.set(mp4a, 8)
+        const stsd = box('stsd', stsdPayload)
+
+        const stbl = box('stbl', stsd)
+        const minf = box('minf', stbl)
+        const mdia = box('mdia', minf)
+        const trak = box('trak', mdia)
+        const moov = box('moov', trak)
+
+        return concat(ftyp, moov)
+      }
+
+      test('extracts AAC-LC mono 48k ASC and derives codec', () => {
+        // AOT=2 (00010), samplingFrequencyIndex=3 (0011, 48000Hz), channelConfig=1 (0001),
+        // GA: frameLengthFlag=0, dependsOnCoreCoder=0, extensionFlag=0 → 0x11 0x88.
+        const asc = new Uint8Array([0x11, 0x88])
+        const init = buildMinimalAacInit(asc)
+        const result = extractAacAscFromInitSegment(init)
+        expect(result).toBeDefined()
+        expect(result!.codec).toBe('mp4a.40.2')
+        expect(Array.from(result!.description)).toEqual([0x11, 0x88])
+      })
+
+      test('derives AOT 5 (HE-AAC) from ASC[0] >> 3', () => {
+        // AOT=5 (00101), rest don't matter for codec derivation.
+        const asc = new Uint8Array([0x29, 0x88])  // 00101 001 1000 1000
+        const init = buildMinimalAacInit(asc)
+        expect(extractAacAscFromInitSegment(init)?.codec).toBe('mp4a.40.5')
+      })
+
+      test('rejects data without ftyp/moov magic', () => {
+        expect(extractAacAscFromInitSegment(new Uint8Array(64))).toBeUndefined()
+      })
+
+      test('rejects ftyp+moov with no audio (no mp4a sample entry)', () => {
+        // ftyp + moov with empty trak chain — no stsd, let alone mp4a.
+        const ftyp = new Uint8Array([
+          0, 0, 0, 24, 0x66, 0x74, 0x79, 0x70,
+          0x69, 0x73, 0x6f, 0x35, 0, 0, 2, 0,
+          0x69, 0x73, 0x6f, 0x35, 0x69, 0x73, 0x6f, 0x36,
+        ])
+        const moov = new Uint8Array([0, 0, 0, 8, 0x6d, 0x6f, 0x6f, 0x76])  // empty moov
+        const cat = new Uint8Array(ftyp.length + moov.length)
+        cat.set(ftyp); cat.set(moov, ftyp.length)
+        expect(extractAacAscFromInitSegment(cat)).toBeUndefined()
+      })
+    })
+
+    describe('hevc', () => {
+      // Minimal HEVC NAL units: header byte0 = (type << 1). VPS=32(0x40), SPS=33(0x42), PPS=34(0x44).
+      const vps = new Uint8Array([0x40, 0x01, 0x0c, 0x01, 0xff, 0xff])
+      const sps = new Uint8Array([0x42, 0x01, 0x01, 0x01, 0x60, 0x00, 0x00, 0x00, 0x90, 0x00, 0x00, 0x00, 0x00, 0x00, 0x3c, 0xa0, 0x05, 0x02])
+      const pps = new Uint8Array([0x44, 0x01, 0xc1, 0x72, 0xb4, 0x62])
+      const idr = new Uint8Array([0x26, 0x01, 0xaf, 0x06])  // type 19 (IDR_W_RADL)
+      const lp = (...nals: Uint8Array[]) => {
+        const parts: number[] = []
+        for (const n of nals) { parts.push((n.length >> 24) & 0xff, (n.length >> 16) & 0xff, (n.length >> 8) & 0xff, n.length & 0xff, ...n) }
+        return Uint8Array.from(parts)
+      }
+
+      test('isHevcCodec', () => {
+        expect(isHevcCodec('hev1.1.6.L93.B0')).toBe(true)
+        expect(isHevcCodec('hvc1.1.6.L93.B0')).toBe(true)
+        expect(isHevcCodec('avc1.640033')).toBe(false)
+      })
+
+      test('removeEmulationPrevention strips 0x03', () => {
+        expect(Array.from(removeEmulationPrevention(new Uint8Array([0, 0, 0x03, 1])))).toEqual([0, 0, 1])
+        expect(Array.from(removeEmulationPrevention(new Uint8Array([0xaa, 0xbb])))).toEqual([0xaa, 0xbb])
+      })
+
+      test('splitAvccNalUnits splits length-prefixed NALs', () => {
+        const nals = splitAvccNalUnits(lp(vps, sps))
+        expect(nals.length).toBe(2)
+        expect(nals[0]).toEqual(vps)
+        expect(nals[1]).toEqual(sps)
+      })
+
+      test('isCompleteAvccSample accepts complete length-prefixed NAL samples', () => {
+        expect(isCompleteAvccSample(lp(new Uint8Array([0x09]), idr))).toBe(true)
+      })
+
+      test('isCompleteAvccSample rejects Annex-B start-code samples', () => {
+        expect(isCompleteAvccSample(new Uint8Array([0, 0, 0, 1, 0x65, 0xaa]))).toBe(false)
+      })
+
+      test('isCompleteAvccSample rejects truncated length-prefixed samples', () => {
+        expect(isCompleteAvccSample(new Uint8Array([0, 0, 0, 4, 0x65, 0xaa]))).toBe(false)
+      })
+
+      test('normalizeH264SampleToAvcc leaves complete AVCC samples unchanged', () => {
+        const avcc = lp(new Uint8Array([0x09]), idr)
+        const normalized = normalizeH264SampleToAvcc(avcc)
+        expect(normalized.format).toBe('avcc')
+        expect(normalized.data).toBe(avcc)
+      })
+
+      test('normalizeH264SampleToAvcc converts a single raw H.264 NAL to AVCC', () => {
+        const raw = new Uint8Array([0x65, 0x88, 0x84])
+        const normalized = normalizeH264SampleToAvcc(raw)
+        expect(normalized.format).toBe('raw-nal')
+        expect(normalized.data).toEqual(new Uint8Array([0, 0, 0, 3, 0x65, 0x88, 0x84]))
+      })
+
+      test('splitH264SampleNalUnits exposes Annex-B NALs without AVCC conversion', () => {
+        const annexB = new Uint8Array([0, 0, 0, 1, 0x65, 0x88, 0x84])
+        const sample = splitH264SampleNalUnits(annexB)
+        expect(sample.format).toBe('annexb')
+        expect(sample.nals).toHaveLength(1)
+        expect(sample.nals[0]).toEqual(new Uint8Array([0x65, 0x88, 0x84]))
+      })
+
+      test('splitH264SampleNalUnits exposes single raw H.264 NALs without wrapping', () => {
+        const raw = new Uint8Array([0x65, 0x88, 0x84])
+        const sample = splitH264SampleNalUnits(raw)
+        expect(sample.format).toBe('raw-nal')
+        expect(sample.nals).toEqual([raw])
+      })
+
+      test('splitH264SampleNalUnits can expose partial AVCC NAL headers', () => {
+        const partial = new Uint8Array([0, 0, 0, 5, 0x65, 0x88])
+        const sample = splitH264SampleNalUnits(partial, { allowPartialAvcc: true })
+        expect(sample.format).toBe('partial-avcc')
+        expect(sample.nals).toHaveLength(1)
+        expect(sample.nals[0]).toEqual(new Uint8Array([0x65, 0x88]))
+      })
+
+      test('extractHevcParameterSets finds VPS/SPS/PPS (length-prefixed)', () => {
+        const sets = extractHevcParameterSets(lp(vps, sps, pps, idr))
+        expect(sets.vps).toEqual(vps)
+        expect(sets.sps).toEqual(sps)
+        expect(sets.pps).toEqual(pps)
+      })
+
+      test('extractHevcParameterSets finds VPS/SPS/PPS (Annex-B)', () => {
+        const sc = new Uint8Array([0, 0, 0, 1])
+        const annexb = Uint8Array.from([...sc, ...vps, ...sc, ...sps, ...sc, ...pps, ...sc, ...idr])
+        const sets = extractHevcParameterSets(annexb)
+        expect(sets.vps).toEqual(vps)
+        expect(sets.sps).toEqual(sps)
+        expect(sets.pps).toEqual(pps)
+      })
+
+      test('generateHvcCFromParameterSets builds a valid hvcC', () => {
+        const hvcc = generateHvcCFromParameterSets({ vps, sps, pps })!
+        expect(hvcc).not.toBeNull()
+        expect(hvcc[0]).toBe(1)                       // configurationVersion
+        expect(hvcc[1]).toBe(sps[3])                  // general profile_tier_level byte 0 copied from SPS[3]
+        expect(hvcc[22]).toBe(3)                      // numOfArrays (VPS+SPS+PPS)
+        // first array entry: NAL_unit_type 32 (VPS), numNalus 1
+        expect(hvcc[23] & 0x3f).toBe(32)
+        expect((hvcc[24] << 8) | hvcc[25]).toBe(1)
+      })
+
+      test('generateHvcCFromParameterSets returns null without SPS/PPS', () => {
+        expect(generateHvcCFromParameterSets({ vps })).toBeNull()
+      })
+
+      test('extractHevcCodecDescription end-to-end from keyframe', () => {
+        const desc = extractHevcCodecDescription(lp(vps, sps, pps, idr))
+        expect(desc).not.toBeNull()
+        expect(desc![0]).toBe(1)
+      })
+
+      test('hevcVclOnly strips parameter-set NALs, keeps VCL', () => {
+        const stripped = hevcVclOnly(lp(vps, sps, pps, idr))
+        const nals = splitAvccNalUnits(stripped)
+        expect(nals.length).toBe(1)        // only the IDR VCL NAL remains
+        expect(nals[0]).toEqual(idr)
+      })
+
+      test('hevcVclOnly is a no-op for VCL-only length-prefixed input', () => {
+        const vclOnly = lp(idr)
+        expect(hevcVclOnly(vclOnly)).toBe(vclOnly)
+      })
+    })
+  })
+}