@blockcast/mmt-base 0.1.0

package/src/mmtp.ts

@@ -0,0 +1,746 @@
+import {
+  MMTP_EXT_TYPE_ALTA_AUTH as _LEAF_MMTP_EXT_TYPE_ALTA_AUTH,
+  MMTP_EXT_TRAILER_HEADER_SIZE as _LEAF_MMTP_EXT_TRAILER_HEADER_SIZE,
+  extractAltaTrailer as _leafExtractAltaTrailer,
+  type AltaTrailer as _LeafAltaTrailer,
+} from '@blockcast/mmt-alta-parse'
+
+/**
+ * @mmt/container - MMTP Parser
+ *
+ * MMTP (MMT Protocol) packet parser based on ISO/IEC 23008-1:2023 Section 9.2
+ *
+ * MMTP header format (12 bytes):
+ * - Byte 0: V(2) | C(1) | FEC_type(2) | r(1) | X(1) | R(1)
+ * - Byte 1: reserved(2) | packet_type(6)
+ * - Bytes 2-3: packet_id (big-endian)
+ * - Bytes 4-7: timestamp (big-endian, 32-bit)
+ * - Bytes 8-11: sequence_number (big-endian)
+ *
+ * FEC_type values:
+ * - 0: No FEC / source packet
+ * - 1: FEC mode 0 (source with FEC payload ID)
+ * - 2: FEC repair packet mode 0
+ * - 3: FEC repair packet mode 1
+ *
+ * @packageDocumentation
+ */
+
+export interface MMTPHeader {
+  version: number
+  /** Packet type: 0x00=MPU, 0x02=Signaling, 0x03=Repair */
+  packetType: number
+  packetId: number
+  timestamp: bigint
+  sequenceNumber: number
+  payloadLength: number
+  fecType: number
+  /** C flag: header carries a 32-bit packet_counter. */
+  packetCounterFlag: boolean
+  packetCounter?: number
+  /** X flag: header carries an extension header and value. */
+  extensionFlag: boolean
+  extension?: { type: number; data: Uint8Array }
+  /** Byte offset at which the MMTP payload begins. */
+  headerLength: number
+  /** Random Access Point flag - indicates keyframe (ISO 23008-1, byte 0 bit 0) */
+  rapFlag: boolean
+}
+
+export interface MPUHeader {
+  mpuSequenceNumber: number
+  fragmentationIndicator: number // FI: 0=complete, 1=first, 2=middle, 3=last
+  /** 8-bit MPU fragment_counter from byte 3. */
+  fragmentCounter: number
+  /** T flag: 1=timed media (14-byte MFU DU header), 0=non-timed (4-byte header) */
+  timedFlag: number
+  /** A flag: aggregated MPU payload. This strict profile requires A=0. */
+  aggregationFlag: boolean
+  /** MPU payload_length (bytes 0-1): bytes after the length field, including
+   *  the remaining six MPU-header bytes and all data-unit bytes. */
+  payloadLength: number
+}
+
+export interface MFUDuHeader {
+  movieFragmentSequenceNumber: number
+  sampleNumber: number
+  offset: number
+  priority: number
+  dependencyCounter: number
+}
+
+export interface MMTPPacket {
+  header: MMTPHeader
+  payload: Uint8Array
+}
+
+export const MMTP_HEADER_SIZE = 12
+export const MPU_HEADER_SIZE = 8
+export const MFU_DU_HEADER_SIZE_TIMED = 14    // T=1: timed media (video/audio samples)
+export const MFU_DU_HEADER_SIZE_NONTIMED = 4  // T=0: non-timed media (item_id only)
+
+const MPU_LENGTH_FIELD_SIZE = 2
+const MPU_HEADER_REMAINDER_SIZE = MPU_HEADER_SIZE - MPU_LENGTH_FIELD_SIZE
+const SOURCE_FEC_PAYLOAD_ID_SIZE = 4
+
+// MMTP Packet Types (ISO/IEC 23008-1:2023 Section 9.2.2)
+export const PACKET_TYPE_MPU = 0x00
+export const PACKET_TYPE_SIGNALING = 0x02
+export const PACKET_TYPE_REPAIR = 0x03
+
+// AL-FEC Signaling Message ID (ISO/IEC 23008-1:2023 Amendment 1:2025)
+export const ALFEC_MESSAGE_ID = 0x0203
+
+// FEC Code IDs
+export const FEC_CODE_XOR = 1
+export const FEC_CODE_RAPTORQ = 2
+
+/**
+ * Parse MMTP header from buffer
+ */
+export function parseMMTPHeader(buffer: Uint8Array): MMTPHeader {
+  if (buffer.length < MMTP_HEADER_SIZE) {
+    throw new Error(`MMTP packet too small: ${buffer.length} bytes`)
+  }
+
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+
+  const version = (buffer[0]! >> 6) & 0x03
+  if (version !== 0) {
+    throw new Error(`Unsupported MMTP version: ${version}`)
+  }
+
+  // Extract FEC type from byte 0, bits 3-4
+  const fecType = (buffer[0]! >> 3) & 0x03
+  const packetCounterFlag = (buffer[0]! & 0x20) !== 0
+  const extensionFlag = (buffer[0]! & 0x02) !== 0
+
+  // Extract RAP flag from byte 0, bit 0 (R bit - Random Access Point)
+  const rapFlag = (buffer[0]! & 0x01) === 1
+
+  // ISO/IEC 23008-1:2023 Figure 8 (V=0) places reserved(2) before
+  // packet_type(6), so packet_type occupies the low six bits of byte 1.
+  const packetType = buffer[1]! & 0x3F
+
+  let offset = 2
+
+  // Packet ID (2 bytes, big-endian)
+  const packetId = view.getUint16(offset, false)
+  offset += 2
+
+  // Timestamp (4 bytes, big-endian)
+  const timestamp = BigInt(view.getUint32(offset, false))
+  offset += 4
+
+  // Sequence number (4 bytes, big-endian)
+  const sequenceNumber = view.getUint32(offset, false)
+  offset += 4
+
+  let packetCounter: number | undefined
+  if (packetCounterFlag) {
+    if (offset + 4 > buffer.length) throw new Error('MMTP packet truncated in packet_counter')
+    packetCounter = view.getUint32(offset, false)
+    offset += 4
+  }
+
+  let extension: { type: number; data: Uint8Array } | undefined
+  if (extensionFlag) {
+    if (offset + 4 > buffer.length) throw new Error('MMTP packet truncated in header extension')
+    const type = view.getUint16(offset, false)
+    const length = view.getUint16(offset + 2, false)
+    offset += 4
+    if (offset + length > buffer.length) throw new Error('MMTP packet truncated in header extension value')
+    extension = { type, data: buffer.subarray(offset, offset + length) }
+    offset += length
+  }
+
+  return {
+    version,
+    packetType,
+    packetId,
+    timestamp,
+    sequenceNumber,
+    payloadLength: buffer.length - offset,
+    fecType,
+    packetCounterFlag,
+    packetCounter,
+    extensionFlag,
+    extension,
+    headerLength: offset,
+    rapFlag,
+  }
+}
+
+/**
+ * Unwrap MMTP packet to extract payload
+ */
+export function unwrapMMTP(buffer: Uint8Array): MMTPPacket {
+  const header = parseMMTPHeader(buffer)
+  const payload = buffer.subarray(header.headerLength)
+
+  return { header, payload }
+}
+
+/**
+ * Parse MPU header from payload
+ * ISO/IEC 23008-1:2023 Section 9.2.3.3
+ *
+ * MPU Header format (8 bytes) as written by FFmpeg/libmmt:
+ * - Bytes 0-1: payload_length (16 bits, big-endian)
+ * - Byte 2: FT(4) | T(1) | FI(2) | A(1)
+ * - Byte 3: fragment_counter (8 bits)
+ * - Bytes 4-7: MPU_sequence_number (32 bits, big-endian)
+ */
+export function parseMPUHeader(payload: Uint8Array): MPUHeader {
+  if (payload.length < MPU_HEADER_SIZE) {
+    throw new Error(`Payload too small for MPU header: ${payload.length} bytes`)
+  }
+
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength)
+
+  // Bytes 0-1: payload_length (16 bits, big-endian)
+  const payloadLength = view.getUint16(0, false)
+
+  // Byte 2: FT(4) | T(1) | FI(2) | A(1)
+  const flagsByte = payload[2]!
+  const timedFlag = (flagsByte >> 3) & 0x01
+  const fragmentationIndicator = (flagsByte >> 1) & 0x03
+  const aggregationFlag = (flagsByte & 0x01) !== 0
+
+  // Byte 3: fragment_counter (8 bits). The high bit is part of the counter in
+  // the current libmmt/FFmpeg writer ABI.
+  const fragmentCounter = payload[3]!
+
+  // Bytes 4-7: MPU_sequence_number (32 bits, big-endian)
+  const mpuSequenceNumber = view.getUint32(4, false)
+
+  return {
+    mpuSequenceNumber,
+    fragmentationIndicator,
+    fragmentCounter,
+    timedFlag,
+    aggregationFlag,
+    payloadLength,
+  }
+}
+
+export function parseTimedMfuDuHeader(payload: Uint8Array, offset: number): MFUDuHeader | null {
+  if (offset < 0 || offset + MFU_DU_HEADER_SIZE_TIMED > payload.length) return null
+  const view = new DataView(payload.buffer, payload.byteOffset + offset, MFU_DU_HEADER_SIZE_TIMED)
+  return {
+    movieFragmentSequenceNumber: view.getUint32(0, false),
+    sampleNumber: view.getUint32(4, false),
+    offset: view.getUint32(8, false),
+    priority: payload[offset + 12]!,
+    dependencyCounter: payload[offset + 13]!,
+  }
+}
+
+interface MfuPayloadLayout {
+  hasMfuDuHeader: boolean
+  mfuOffset: number
+  dataEnd: number
+}
+
+function resolveMfuPayloadLayout(
+  mpu: MPUHeader,
+  fragmentType: number,
+  payload: Uint8Array,
+): MfuPayloadLayout | null {
+  if (mpu.payloadLength < MPU_HEADER_REMAINDER_SIZE) return null
+
+  // ISO/IEC 23008-1 defines payload_length from immediately after its own
+  // two-byte field. It therefore includes the remaining six MPU-header bytes.
+  const declaredEnd = MPU_LENGTH_FIELD_SIZE + mpu.payloadLength
+  if (declaredEnd > payload.length) return null
+
+  const hasHeader = fragmentType === 2 && mpu.fragmentationIndicator <= 1
+  const mfuHeaderSize = mpu.timedFlag ? MFU_DU_HEADER_SIZE_TIMED : MFU_DU_HEADER_SIZE_NONTIMED
+  const mfuOffset = MPU_HEADER_SIZE + (hasHeader ? mfuHeaderSize : 0)
+  if (mfuOffset >= declaredEnd) return null
+
+  return {
+    hasMfuDuHeader: hasHeader,
+    mfuOffset,
+    dataEnd: declaredEnd,
+  }
+}
+
+function isEmptyOrExactAltaTrailer(payload: Uint8Array, start: number, end: number): boolean {
+  if (start === end) return true
+  if (start < 0 || end > payload.length || start + _LEAF_MMTP_EXT_TRAILER_HEADER_SIZE > end) {
+    return false
+  }
+
+  const view = new DataView(
+    payload.buffer,
+    payload.byteOffset + start,
+    end - start,
+  )
+  if (view.getUint16(0, false) !== _LEAF_MMTP_EXT_TYPE_ALTA_AUTH) return false
+
+  const authLength = view.getUint16(2, false)
+  return start + _LEAF_MMTP_EXT_TRAILER_HEADER_SIZE + authLength === end
+}
+
+interface DeclaredTrailerLayout {
+  hasFecId: boolean
+}
+
+function resolveDeclaredTrailers(
+  payload: Uint8Array,
+  declaredEnd: number,
+  fecType: number,
+  options?: { skipFecId?: boolean },
+): DeclaredTrailerLayout | null {
+  if (declaredEnd > payload.length) return null
+
+  if (options?.skipFecId) {
+    return isEmptyOrExactAltaTrailer(payload, declaredEnd, payload.length)
+      ? { hasFecId: false }
+      : null
+  }
+
+  if (fecType === 1) {
+    const fecStart = payload.length - SOURCE_FEC_PAYLOAD_ID_SIZE
+    if (fecStart < declaredEnd || !isEmptyOrExactAltaTrailer(payload, declaredEnd, fecStart)) {
+      return null
+    }
+    return { hasFecId: true }
+  }
+  if (fecType !== 0) return null
+
+  if (isEmptyOrExactAltaTrailer(payload, declaredEnd, payload.length)) {
+    return { hasFecId: false }
+  }
+
+  return null
+}
+
+/**
+ * Extract NAL unit payload from MMTP packet
+ */
+export function extractNALUnit(mmtpPacket: Uint8Array): Uint8Array {
+  const extraction = extractMFUPayload(mmtpPacket)
+  if (!extraction) throw new Error('Malformed MMTP MPU payload')
+  return extraction.data
+}
+
+/** Result of extracting MFU payload from an MMTP packet */
+export interface MFUExtraction {
+  /** MMTP header fields */
+  header: MMTPHeader
+  /** MPU header fields */
+  mpu: MPUHeader
+  /** Fragment type (FT field, 4 bits): 0=metadata, 2=MFU data */
+  fragmentType: number
+  /** MFU payload data (video/audio bytes, headers stripped, FEC ID excluded) */
+  data: Uint8Array
+  /** Parsed timed MFU DU header when present, otherwise null */
+  mfuDuHeader: MFUDuHeader | null
+  /** Non-timed MFU Item_ID when the 4-byte DU header is present. */
+  itemId: number | null
+  /** Source FEC Payload ID if present (`FEC_type == 1`), or null */
+  fecPayloadId: { ssId: number } | null
+}
+
+/**
+ * Extract MFU payload from a raw MMTP packet.
+ *
+ * Handles all the byte arithmetic for:
+ * - MMTP header (12 bytes)
+ * - MPU sub-header (8 bytes, payloadLength field)
+ * - MFU DU header (14 bytes timed / 4 bytes non-timed, only for FI ≤ 1)
+ * - Source FEC Payload ID (4 bytes at end, only when `FEC_type == 1`)
+ *
+ * `payloadLength` is the ISO length-after-field value: six remaining MPU-header
+ * bytes, then the MFU DU header when present, then media. ALTA and Source FEC
+ * trailers are outside that declared span and must consume the exact suffix.
+ *
+ * @param mmtpPacket Raw MMTP packet (from multicast or MoQ)
+ * @param options.skipFecId When true, do NOT subtract the 4-byte Source FEC Payload ID
+ *   from the payload boundary, even if fecType >= 1 in the MMTP header.  Use this for
+ *   FEC-recovered symbols where the FEC PID was already stripped before WASM decoding
+ *   but the fecType bits in byte 0 still reflect the original packet (FEC Type=1 per
+ *   draft-ramadan-moq-mmt-00 §3.1).
+ * @returns Extracted MFU data + metadata, or null if packet is too small
+ */
+export function extractMFUPayload(
+  mmtpPacket: Uint8Array,
+  options?: { skipFecId?: boolean },
+): MFUExtraction | null {
+  if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return null
+
+  let header: MMTPHeader
+  try {
+    header = parseMMTPHeader(mmtpPacket)
+  } catch {
+    return null
+  }
+  if (header.packetType !== PACKET_TYPE_MPU) return null
+  const payload = mmtpPacket.subarray(header.headerLength)
+  if (payload.length < MPU_HEADER_SIZE) return null
+  const mpu = parseMPUHeader(payload)
+  if (mpu.aggregationFlag) return null
+
+  // Fragment type from byte 2 upper nibble (not returned by parseMPUHeader)
+  const fragmentType = (payload[2]! >> 4) & 0x0f
+
+  const layout = resolveMfuPayloadLayout(
+    mpu,
+    fragmentType,
+    payload,
+  )
+  if (!layout) return null
+
+  const trailerLayout = resolveDeclaredTrailers(payload, layout.dataEnd, header.fecType, options)
+  if (!trailerLayout) return null
+
+  const mfuDuHeaderPresent = layout.hasMfuDuHeader
+  const mfuOffset = layout.mfuOffset
+  const dataEnd = layout.dataEnd
+
+  if (mfuOffset >= dataEnd) return null
+
+  const mfuDuHeader =
+    mfuDuHeaderPresent && mpu.timedFlag === 1
+      ? parseTimedMfuDuHeader(payload, MPU_HEADER_SIZE)
+      : null
+  const itemId =
+    mfuDuHeaderPresent && mpu.timedFlag === 0
+      ? new DataView(payload.buffer, payload.byteOffset + MPU_HEADER_SIZE, 4).getUint32(0, false)
+      : null
+
+  const data = payload.subarray(mfuOffset, dataEnd)
+
+  const fecPayloadId = trailerLayout.hasFecId
+    ? {
+        ssId: new DataView(
+          mmtpPacket.buffer,
+          mmtpPacket.byteOffset + mmtpPacket.length - SOURCE_FEC_PAYLOAD_ID_SIZE,
+          SOURCE_FEC_PAYLOAD_ID_SIZE,
+        ).getUint32(0, false),
+      }
+    : null
+
+  return { header, mpu, fragmentType, data, mfuDuHeader, itemId, fecPayloadId }
+}
+
+/**
+ * Extract timestamp from MMTP packet
+ */
+export function extractTimestamp(mmtpPacket: Uint8Array): bigint {
+  const { header } = unwrapMMTP(mmtpPacket)
+  return header.timestamp
+}
+
+/**
+ * Check if MMTP packet is an FEC repair packet
+ * FEC_type 2 and 3 are repair packets
+ */
+export function isFecRepairPacket(mmtpPacket: Uint8Array): boolean {
+  if (mmtpPacket.length < 1) return false
+  const fecType = (mmtpPacket[0]! >> 3) & 0x03
+  return fecType >= 2
+}
+
+/**
+ * Extract Source FEC Payload ID (SS_ID) from the last 4 bytes of an MMTP
+ * source packet per ISO/IEC 23008-1:2023 Section C.5.2 Figure C.10.
+ *
+ * SS_ID is a flat 32-bit monotonic counter (incremented by 1 per packet
+ * for ssbg_mode0 and ssbg_mode1).  Block membership and ESI are derived
+ * at recovery time from repair packet SS_Start and SSB_length:
+ *   SBN = floor(SS_ID / K),  ESI = SS_ID % K
+ *   SS_Start = SBN * K  (first SS_ID of the block)
+ *
+ * This matches FFmpeg moqenc_mmt.c, the drafts (draft-ramadan-moq-fec §6.2),
+ * and ATSC A/331 §8.1.2.5 which defers to ISO 23008-1 Annex C.
+ */
+export function extractFecPayloadId(mmtpPacket: Uint8Array): { ssId: number } | null {
+  if (!hasSourceFecPayloadId(mmtpPacket)) return null
+  // Flat 4-byte SS_ID: encoder writes block_id * K + symbol_id
+  const off = mmtpPacket.length - SOURCE_FEC_PAYLOAD_ID_SIZE
+  const view = new DataView(
+    mmtpPacket.buffer,
+    mmtpPacket.byteOffset + off,
+    SOURCE_FEC_PAYLOAD_ID_SIZE,
+  )
+  return { ssId: view.getUint32(0, false) }
+}
+
+/**
+ * Return true when FEC_type=1 and the exact suffix after the ISO-declared MPU
+ * payload contains a four-byte Source FEC Payload ID.
+ */
+export function hasSourceFecPayloadId(mmtpPacket: Uint8Array): boolean {
+  if (mmtpPacket.length < MMTP_HEADER_SIZE + MPU_HEADER_SIZE) return false
+
+  let header: MMTPHeader
+  try {
+    header = parseMMTPHeader(mmtpPacket)
+  } catch {
+    return false
+  }
+  if (header.packetType !== PACKET_TYPE_MPU) return false
+
+  const payload = mmtpPacket.subarray(header.headerLength)
+  if (payload.length < MPU_HEADER_SIZE) return false
+  const mpu = parseMPUHeader(payload)
+  if (mpu.payloadLength < MPU_HEADER_REMAINDER_SIZE) return false
+  const declaredEnd = MPU_LENGTH_FIELD_SIZE + mpu.payloadLength
+  return resolveDeclaredTrailers(payload, declaredEnd, header.fecType)?.hasFecId ?? false
+}
+
+/**
+ * MMTP header-extension ext_type assigned to the detached ALTA authenticator
+ * trailer (Path 2 / 08-07). Carried in an `[ext_type][ext_length][auth]`
+ * block appended after the MPU's declared payload bytes, before the 4-byte
+ * Source FEC Payload ID. MMTP X-bit stays 0 — non-ALTA MMTP receivers treat
+ * the trailer as bytes past `payload_length` and skip it (per ISO 23008-1
+ * §9.2.2 "may be discarded without impacting correct processing").
+ */
+// Re-export the ALTA trailer helper from the zero-dep leaf package. The leaf
+// owns the implementation so container and FEC consumers share one parser
+// without creating a package cycle.
+export const MMTP_EXT_TYPE_ALTA_AUTH = _LEAF_MMTP_EXT_TYPE_ALTA_AUTH
+export const MMTP_EXT_TRAILER_HEADER_SIZE = _LEAF_MMTP_EXT_TRAILER_HEADER_SIZE
+export type AltaTrailer = _LeafAltaTrailer
+export const extractAltaTrailer = _leafExtractAltaTrailer
+
+/** Size of Repair FEC Payload ID per ISO/IEC 23008-1 Section C.5.3 */
+export const REPAIR_FEC_PID_SIZE = 13
+
+/** Parse the 13-byte Repair FEC Payload ID after the complete dynamic MMTP header. */
+function readRepairFecPayloadIdFields(mmtpPacket: Uint8Array): {
+  packetId: number; ssStart: number; rsbLength: number; rsId: number; ssbLength: number; dataOffset: number
+} | null {
+  let header: MMTPHeader
+  try {
+    header = parseMMTPHeader(mmtpPacket)
+  } catch {
+    return null
+  }
+  if (header.packetType !== PACKET_TYPE_REPAIR || header.fecType !== 2) return null
+
+  const off = header.headerLength
+  if (mmtpPacket.length < off + REPAIR_FEC_PID_SIZE) return null
+  const view = new DataView(mmtpPacket.buffer, mmtpPacket.byteOffset + off, REPAIR_FEC_PID_SIZE)
+  const ssStart = view.getUint32(0, false)  // 32 bits
+  const rsbLength = (mmtpPacket[off + 4]! << 16) | (mmtpPacket[off + 5]! << 8) | mmtpPacket[off + 6]!  // 24 bits
+  const rsId = (mmtpPacket[off + 7]! << 16) | (mmtpPacket[off + 8]! << 8) | mmtpPacket[off + 9]!  // 24 bits
+  const ssbLength = (mmtpPacket[off + 10]! << 16) | (mmtpPacket[off + 11]! << 8) | mmtpPacket[off + 12]!  // 24 bits
+  return {
+    packetId: header.packetId,
+    ssStart,
+    rsbLength,
+    rsId,
+    ssbLength,
+    dataOffset: off + REPAIR_FEC_PID_SIZE,
+  }
+}
+
+/**
+ * Extract Repair FEC Payload ID from a raw-multicast MMTP repair packet.
+ * Per ISO/IEC 23008-1:2023 Section C.5.3 (ssbg_mode0, one-stage, no FFSRP_TS):
+ *   [MMTP header][SS_Start:4][RSB_length:3][RS_ID:3][SSB_length:3][repair data]
+ * OTI is delivered via AL-FEC signaling message (Table C.3), not per-packet.
+ *
+ * Byte 1 is reserved(2)|packet_type(6) for V=0, so repair type 0x03 is 0x03.
+ * Pre-migration high-bits bytes (0x0c) are rejected — no compatibility decode.
+ */
+export function extractRepairFecPayloadId(mmtpPacket: Uint8Array): {
+  ssStart: number; rsbLength: number; rsId: number; ssbLength: number
+} | null {
+  const fields = readRepairFecPayloadIdFields(mmtpPacket)
+  if (!fields) return null
+  return {
+    ssStart: fields.ssStart,
+    rsbLength: fields.rsbLength,
+    rsId: fields.rsId,
+    ssbLength: fields.ssbLength,
+  }
+}
+
+/** Parsed MoQ repair frame per ISO/IEC 23008-1 Section C.4.3 + C.5.3 */
+export interface MoqRepairFrame {
+  /** MMTP packetId (1=video, 2=audio) — for routing to correct FEC decoder */
+  packetId: number
+  /** SS_Start (32 bits): SS_ID of first source symbol in block */
+  ssStart: number
+  /** RSB_length (24 bits): number of repair symbols (P) */
+  rsbLength: number
+  /** RS_ID (24 bits): repair symbol index (0-based) */
+  rsId: number
+  /** SSB_length (24 bits): number of source symbols (K) */
+  ssbLength: number
+  /** Repair symbol data after the dynamic MMTP header and 13-byte FEC payload ID. */
+  symbolData: Uint8Array
+}
+
+/**
+ * Parse a MoQ repair frame (ISO/IEC 23008-1 Annex C format).
+ *
+ * Wire format per ISO 23008-1 §C.4.3 + §C.5.3:
+ *   MMTP Header: fixed 12 bytes plus C/X optional fields
+ *   then SS_Start (4 bytes) → block identifier
+ *   then RSB_length (3 bytes) → P
+ *   then RS_ID (3 bytes) → ESI = K + RS_ID
+ *   then SSB_length (3 bytes) → K
+ *   then Repair Symbol Data (T bytes)
+ *
+ * @param frame - Raw MoQ repair frame bytes
+ * @returns Parsed frame or null if invalid
+ */
+export function parseMoqRepairFrame(frame: Uint8Array): MoqRepairFrame | null {
+  const repairId = readRepairFecPayloadIdFields(frame)
+  if (!repairId) return null
+
+  const symbolData = frame.subarray(repairId.dataOffset)
+  if (
+    repairId.rsbLength === 0 ||
+    repairId.ssbLength === 0 ||
+    repairId.rsId >= repairId.rsbLength ||
+    symbolData.length === 0
+  ) return null
+
+  return {
+    packetId: repairId.packetId,
+    ssStart: repairId.ssStart,
+    rsbLength: repairId.rsbLength,
+    rsId: repairId.rsId,
+    ssbLength: repairId.ssbLength,
+    symbolData,
+  }
+}
+
+/**
+ * AL-FEC signaling configuration parsed from ISO/IEC 23008-1:2023 Table C.3 message.
+ */
+export interface AlFecConfig {
+  fecCodeId: number
+  fecPayloadIdMode: 0
+  repairSymbolSize: number
+  maximumK: number
+  maximumP: number
+  interleaveDepth: number
+  oti: Uint8Array
+}
+
+function canonicalRaptorQOtiK(oti: Uint8Array, repairSymbolSize: number): number | null {
+  if (oti.length !== 12 || oti[5] !== 0) return null
+  const transferLength = (oti[0]! * 0x1_0000_0000) +
+    (((oti[1]! << 24) | (oti[2]! << 16) | (oti[3]! << 8) | oti[4]!) >>> 0)
+  const symbolSize = (oti[6]! << 8) | oti[7]!
+  const sourceBlocks = oti[8]!
+  const subBlocks = (oti[9]! << 8) | oti[10]!
+  const alignment = oti[11]!
+  if (!Number.isSafeInteger(transferLength) || transferLength <= 0 ||
+      symbolSize !== repairSymbolSize || symbolSize === 0 || symbolSize % 8 !== 0 ||
+      sourceBlocks !== 1 || subBlocks !== 1 || alignment !== 8 ||
+      transferLength % symbolSize !== 0) {
+    return null
+  }
+  const k = transferLength / symbolSize
+  return Number.isInteger(k) && k >= 1 && k <= 56_403 ? k : null
+}
+
+/**
+ * Parse AL-FEC signaling message from a full MMTP signaling packet.
+ *
+ * Wire format (ISO/IEC 23008-1:2023 Table C.3, Amendment 1:2025):
+ *   [12-byte MMTP header (packet_type=0x02)]
+ *   message_id(2)        = 0x0203
+ *   version(1)
+ *   message_length(2)    = length of remaining payload
+ *   flags(1)             = fec_flag(1) | private_fec_flag(1) | reserved(6)
+ *   fec_flow_descriptor:
+ *     length(2)
+ *     num_flows(1)
+ *     per flow:
+ *       fec_flow_id(1), source_flow_id(1), num_assets(1), packet_ids(2*N),
+ *       coding_params(1), repair_symbol_size(2),
+ *       [one-stage]: repair_flow_id(2), fec_code_id(1),
+ *       [private_fec_flag]: private_header(1){flag(1)|len(7)},
+ *         current RaptorQ profile OTI(12) + interleave_depth(1)
+ *       max_k(3), max_p(3), protection_window_time(4), protection_window_size(4)
+ *
+ * @param mmtpPacket Full MMTP packet including 12-byte header
+ * @returns Parsed config or null if not an AL-FEC signaling message
+ */
+export function parseAlFecMessage(mmtpPacket: Uint8Array): AlFecConfig | null {
+  if (mmtpPacket.length < MMTP_HEADER_SIZE + 9) return null
+  let header: MMTPHeader
+  try {
+    header = parseMMTPHeader(mmtpPacket)
+  } catch {
+    return null
+  }
+  if (header.packetType !== PACKET_TYPE_SIGNALING || header.fecType !== 0) return null
+  const payload = mmtpPacket.subarray(header.headerLength)
+  if (payload.length < 9) return null
+  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength)
+  let off = 0
+
+  const messageId = view.getUint16(off, false); off += 2
+  if (messageId !== ALFEC_MESSAGE_ID) return null
+  const version = payload[off]!; off += 1
+  const messageLength = view.getUint16(off, false); off += 2
+  if (version !== 1 || messageLength === 0 || messageLength !== payload.length - off) return null
+
+  const flags = payload[off]!; off += 1
+  const fecFlag = (flags >> 7) & 1
+  const privateFecFlag = (flags >> 6) & 1
+  if (fecFlag !== 1 || privateFecFlag !== 1 || (flags & 0x3f) !== 0x3f) return null
+
+  if (off + 2 > payload.length) return null
+  const descriptorLength = view.getUint16(off, false); off += 2
+  const descriptorEnd = off + descriptorLength
+  if (descriptorLength === 0 || descriptorEnd !== payload.length) return null
+
+  const numFlows = payload[off]!; off += 1
+  if (numFlows !== 1 || off + 3 > descriptorEnd) return null
+
+  off += 2 // fec_flow_id, source_flow_id
+  const numAssets = payload[off]!; off += 1
+  if (numAssets === 0 || off + (numAssets * 2) > descriptorEnd) return null
+  off += numAssets * 2
+
+  if (off + 3 > descriptorEnd) return null
+  const codingParams = payload[off]!; off += 1
+  const fecCodingStructure = (codingParams >> 4) & 0x0f
+  const ssbgMode = (codingParams >> 2) & 0x03
+  const ffsrptsFlag = (codingParams >> 1) & 0x01
+  const fecPayloadIdMode = codingParams & 0x01
+  if (fecCodingStructure !== 1 || ssbgMode !== 0 || ffsrptsFlag !== 0 || fecPayloadIdMode !== 0) {
+    return null
+  }
+  const repairSymbolSize = view.getUint16(off, false); off += 2
+  if (repairSymbolSize === 0 || repairSymbolSize % 8 !== 0) return null
+
+  if (off + 4 > descriptorEnd) return null
+  off += 2 // Amendment 1:2025 replaces Table C.3 with a 16-bit repair_flow_id
+  const fecCodeId = payload[off]!; off += 1
+  if (fecCodeId !== FEC_CODE_RAPTORQ) return null
+  const privateHeader = payload[off]!; off += 1
+  const privateFlag = privateHeader >> 7
+  const privateFieldLength = privateHeader & 0x7f
+  if (privateFlag !== 1 || privateFieldLength !== 13 || off + 13 > descriptorEnd) return null
+  const oti = payload.slice(off, off + 12); off += 12
+  const interleaveDepth = payload[off]!; off += 1
+  const otiK = canonicalRaptorQOtiK(oti, repairSymbolSize)
+  if (otiK === null || interleaveDepth === 0) return null
+
+  if (off + 14 !== descriptorEnd) return null
+  const maximumK = (payload[off]! << 16) | (payload[off + 1]! << 8) | payload[off + 2]!
+  off += 3
+  const maximumP = (payload[off]! << 16) | (payload[off + 1]! << 8) | payload[off + 2]!
+  off += 3
+  if (maximumK !== otiK || maximumP === 0 || maximumK + maximumP - 1 > 0x00ff_ffff) {
+    return null
+  }
+  off += 8 // protection_window_time, protection_window_size
+  if (off !== descriptorEnd) return null
+
+  return { fecCodeId, fecPayloadIdMode, repairSymbolSize, maximumK, maximumP, interleaveDepth, oti }
+}