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

package/src/mmtp.ts

@@ -1,277 +0,0 @@
-/**
- * @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: packet_type(6) | reserved(2)
- * - 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
-  packetId: number
-  timestamp: bigint
-  sequenceNumber: number
-  payloadLength: number
-  fecType: 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
-  fragmentCounter: 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 = 14
-
-/**
- * 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)
-
-  // Extract FEC type from byte 0, bits 3-4
-  const fecType = (buffer[0]! >> 3) & 0x03
-
-  // Extract RAP flag from byte 0, bit 0 (R bit - Random Access Point)
-  const rapFlag = (buffer[0]! & 0x01) === 1
-
-  // Skip bytes 0-1 (flags and packet_type)
-  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
-
-  return {
-    version: 1,
-    packetId,
-    timestamp,
-    sequenceNumber,
-    payloadLength: buffer.length - offset,
-    fecType,
-    rapFlag,
-  }
-}
-
-/**
- * Unwrap MMTP packet to extract payload
- */
-export function unwrapMMTP(buffer: Uint8Array): MMTPPacket {
-  const header = parseMMTPHeader(buffer)
-  const payload = buffer.subarray(MMTP_HEADER_SIZE)
-
-  return { header, payload }
-}
-
-/**
- * Parse MPU header from payload
- * ISO/IEC 23008-1:2023 Section 9.2.3.3
- */
-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)
-
-  // MPU sequence number (4 bytes, big-endian)
-  const mpuSequenceNumber = view.getUint32(0, false)
-
-  // Fragmentation indicator (byte 5, bits 0-1)
-  const fragmentationIndicator = payload[5]! & 0x03
-
-  // Fragment counter (bytes 6-7, big-endian)
-  const fragmentCounter = view.getUint16(6, false)
-
-  return {
-    mpuSequenceNumber,
-    fragmentationIndicator,
-    fragmentCounter,
-  }
-}
-
-/**
- * Extract NAL unit payload from MMTP packet
- */
-export function extractNALUnit(mmtpPacket: Uint8Array): Uint8Array {
-  const { payload } = unwrapMMTP(mmtpPacket)
-
-  if (payload.length < MPU_HEADER_SIZE) {
-    throw new Error(`Payload too small for MPU header: ${payload.length} bytes`)
-  }
-
-  // Parse MPU header to check fragmentation indicator
-  const fragmentationIndicator = payload[5]! & 0x03
-
-  // MFU DU header is present only for FI = 0 (complete) or FI = 1 (first)
-  const hasMfuHeader = fragmentationIndicator === 0 || fragmentationIndicator === 1
-  const headerSize = MPU_HEADER_SIZE + (hasMfuHeader ? MFU_DU_HEADER_SIZE : 0)
-
-  if (payload.length < headerSize) {
-    throw new Error(`Payload too small for headers: ${payload.length} bytes (need ${headerSize})`)
-  }
-
-  return payload.subarray(headerSize)
-}
-
-/**
- * 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
-}
-
-/**
- * Check if MMTP packet has FEC payload ID (FEC_type 1 or higher)
- */
-export function hasFecPayloadId(mmtpPacket: Uint8Array): boolean {
-  if (mmtpPacket.length < 1) return false
-  const fecType = (mmtpPacket[0]! >> 3) & 0x03
-  return fecType >= 1
-}
-
-// =============================================================================
-// Inline Tests (vitest)
-// =============================================================================
-
-if (import.meta.vitest) {
-  const { describe, test, expect } = import.meta.vitest
-
-  describe('MMTP Parser', () => {
-    // Helper to create a minimal MMTP packet
-    function createTestPacket(opts: {
-      fecType?: number
-      packetId?: number
-      timestamp?: number
-      sequenceNumber?: number
-      payload?: Uint8Array
-    }): Uint8Array {
-      const fecType = opts.fecType ?? 0
-      const packetId = opts.packetId ?? 1
-      const timestamp = opts.timestamp ?? 12345
-      const sequenceNumber = opts.sequenceNumber ?? 1
-      const payload = opts.payload ?? new Uint8Array([0x00, 0x00, 0x00, 0x01])
-
-      const header = new Uint8Array(12)
-      const view = new DataView(header.buffer)
-
-      // Byte 0: V=1, C=0, FEC_type, r=0, X=0, R=0
-      header[0] = (1 << 6) | (fecType << 3)
-      // Byte 1: packet_type=0 (MPU)
-      header[1] = 0
-      view.setUint16(2, packetId, false)
-      view.setUint32(4, timestamp, false)
-      view.setUint32(8, sequenceNumber, false)
-
-      const result = new Uint8Array(header.length + payload.length)
-      result.set(header, 0)
-      result.set(payload, header.length)
-      return result
-    }
-
-    describe('parseMMTPHeader', () => {
-      test('should parse MMTP header correctly', () => {
-        const packet = createTestPacket({
-          packetId: 42,
-          timestamp: 1000000,
-          sequenceNumber: 100,
-        })
-        const header = parseMMTPHeader(packet)
-        expect(header.packetId).toBe(42)
-        expect(header.timestamp).toBe(1000000n)
-        expect(header.sequenceNumber).toBe(100)
-        expect(header.fecType).toBe(0)
-      })
-
-      test('should extract FEC type', () => {
-        const packet = createTestPacket({ fecType: 2 })
-        const header = parseMMTPHeader(packet)
-        expect(header.fecType).toBe(2)
-      })
-
-      test('should throw on too small packet', () => {
-        expect(() => parseMMTPHeader(new Uint8Array(10))).toThrow()
-      })
-    })
-
-    describe('isFecRepairPacket', () => {
-      test('should return false for source packets (FEC type 0)', () => {
-        const packet = createTestPacket({ fecType: 0 })
-        expect(isFecRepairPacket(packet)).toBe(false)
-      })
-
-      test('should return false for FEC mode 0 source (FEC type 1)', () => {
-        const packet = createTestPacket({ fecType: 1 })
-        expect(isFecRepairPacket(packet)).toBe(false)
-      })
-
-      test('should return true for repair packets (FEC type 2)', () => {
-        const packet = createTestPacket({ fecType: 2 })
-        expect(isFecRepairPacket(packet)).toBe(true)
-      })
-
-      test('should return true for repair packets (FEC type 3)', () => {
-        const packet = createTestPacket({ fecType: 3 })
-        expect(isFecRepairPacket(packet)).toBe(true)
-      })
-    })
-
-    describe('hasFecPayloadId', () => {
-      test('should return false for no FEC (type 0)', () => {
-        const packet = createTestPacket({ fecType: 0 })
-        expect(hasFecPayloadId(packet)).toBe(false)
-      })
-
-      test('should return true for FEC type 1+', () => {
-        expect(hasFecPayloadId(createTestPacket({ fecType: 1 }))).toBe(true)
-        expect(hasFecPayloadId(createTestPacket({ fecType: 2 }))).toBe(true)
-        expect(hasFecPayloadId(createTestPacket({ fecType: 3 }))).toBe(true)
-      })
-    })
-  })
-}