@blockcast/mmt-container 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@blockcast/mmt-container",
+  "version": "0.1.0",
+  "description": "MMTP/LOC container parsing for MMT over MoQ and SSM",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./mmtp": {
+      "import": "./dist/mmtp.js",
+      "types": "./dist/mmtp.d.ts"
+    },
+    "./mfu": {
+      "import": "./dist/mfu-reassembler.js",
+      "types": "./dist/mfu-reassembler.d.ts"
+    },
+    "./loc": {
+      "import": "./dist/loc.js",
+      "types": "./dist/loc.d.ts"
+    }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": ["mmt", "mmtp", "loc", "container", "streaming", "iso23008-1"],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Blockcast/libmmt.git",
+    "directory": "packages/container"
+  }
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * @mmt/container - MMTP/LOC Container Parsing
+ *
+ * Shared container parsing library for MMT over MoQ and SSM.
+ *
+ * @packageDocumentation
+ */
+
+// MMTP Parser
+export {
+  type MMTPHeader,
+  type MPUHeader,
+  type MMTPPacket,
+  MMTP_HEADER_SIZE,
+  MPU_HEADER_SIZE,
+  MFU_DU_HEADER_SIZE,
+  parseMMTPHeader,
+  unwrapMMTP,
+  parseMPUHeader,
+  extractNALUnit,
+  extractTimestamp,
+  isFecRepairPacket,
+  hasFecPayloadId,
+} from './mmtp.js'
+
+// MFU Reassembler
+export {
+  type MFUFragment,
+  type ReassembledMFU,
+  type ReassemblerStats,
+  type MFUReassemblerOptions,
+  MFUReassembler,
+  createFragment,
+  processMMTPWithReassembly,
+} from './mfu-reassembler.js'
+
+// LOC FEC Extensions
+export {
+  LOCHeaderExtensionId,
+  FEC_PAYLOAD_ID_MAX,
+  fecPack,
+  fecUnpack,
+  FecPayloadId,
+} from './loc.js'

package/src/loc.ts

@@ -0,0 +1,218 @@
+/**
+ * @mmt/container - LOC FEC Extensions
+ *
+ * FEC Payload ID helpers for LOC (Low Overhead Container) format
+ * Per draft-ramadan-moq-mmt Section 7.3
+ *
+ * The FEC Payload ID encodes Source Block Number (SBN) and
+ * Encoding Symbol ID (ESI) as a 48-bit value: (SBN << 24) | ESI
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * LOC Header Extension IDs
+ */
+export enum LOCHeaderExtensionId {
+  CaptureTimestamp = 2,
+  VideoFrameMarking = 4,
+  AudioLevel = 6,
+  VideoConfig = 13,
+  /** FEC Payload ID extension (draft-ramadan-moq-mmt Section 7.3) */
+  FecPayloadId = 0x10,
+}
+
+/** Maximum value for SBN and ESI (24 bits each) */
+export const FEC_PAYLOAD_ID_MAX = 0xffffff
+
+/**
+ * Pack Source Block Number (SBN) and Encoding Symbol ID (ESI) into a 48-bit value.
+ *
+ * Per draft-ramadan-moq-mmt Section 7.3, the FEC Payload ID is encoded as:
+ * `(SBN << 24) | ESI` where both SBN and ESI are 24 bits.
+ *
+ * @param sbn - Source Block Number (24 bits, 0-16777215)
+ * @param esi - Encoding Symbol ID (24 bits, 0-16777215)
+ * @returns Packed 48-bit value as bigint
+ *
+ * @example
+ * ```ts
+ * import { fecPack } from '@mmt/container/loc'
+ * const packed = fecPack(100, 5) // 419430405n
+ * ```
+ */
+export function fecPack(sbn: number, esi: number): bigint {
+  return (BigInt(sbn & 0xffffff) << 24n) | BigInt(esi & 0xffffff)
+}
+
+/**
+ * Unpack a 48-bit FEC Payload ID into Source Block Number and Encoding Symbol ID.
+ *
+ * Per draft-ramadan-moq-mmt Section 7.3, extracts:
+ * - SBN from upper 24 bits
+ * - ESI from lower 24 bits
+ *
+ * @param packed - Packed 48-bit FEC Payload ID value
+ * @returns Tuple of [sbn, esi] both as numbers
+ *
+ * @example
+ * ```ts
+ * import { fecPack, fecUnpack } from '@mmt/container/loc'
+ * const packed = fecPack(100, 5)
+ * const [sbn, esi] = fecUnpack(packed) // [100, 5]
+ * ```
+ */
+export function fecUnpack(packed: bigint): [sbn: number, esi: number] {
+  const sbn = Number((packed >> 24n) & 0xffffffn)
+  const esi = Number(packed & 0xffffffn)
+  return [sbn, esi]
+}
+
+/**
+ * FEC Payload ID for LOC extension headers
+ *
+ * Encodes Source Block Number (SBN) and Encoding Symbol ID (ESI)
+ * for FEC recovery with LOC container format.
+ *
+ * @example
+ * ```ts
+ * import { FecPayloadId } from '@mmt/container/loc'
+ *
+ * // Create from SBN/ESI
+ * const fecId = new FecPayloadId(100, 5)
+ *
+ * // Get packed value for extension header
+ * const packed = fecId.packed // 419430405n
+ *
+ * // Create from packed value
+ * const fecId2 = FecPayloadId.fromPacked(packed)
+ * ```
+ */
+export class FecPayloadId {
+  static readonly TYPE = LOCHeaderExtensionId.FecPayloadId
+
+  constructor(
+    /** Source Block Number (24 bits, 0-16777215) */
+    public readonly sbn: number,
+    /** Encoding Symbol ID (24 bits, 0-16777215) */
+    public readonly esi: number,
+  ) {
+    if (sbn < 0 || sbn > 0xffffff) {
+      throw new Error('SBN must be 0-16777215 (24 bits)')
+    }
+    if (esi < 0 || esi > 0xffffff) {
+      throw new Error('ESI must be 0-16777215 (24 bits)')
+    }
+  }
+
+  /** Get packed 48-bit value */
+  get packed(): bigint {
+    return fecPack(this.sbn, this.esi)
+  }
+
+  /** Create from packed 48-bit value */
+  static fromPacked(packed: bigint): FecPayloadId {
+    const [sbn, esi] = fecUnpack(packed)
+    return new FecPayloadId(sbn, esi)
+  }
+
+  /** Check if value is within valid 24-bit range */
+  static isValidSbn(sbn: number): boolean {
+    return sbn >= 0 && sbn <= 0xffffff
+  }
+
+  /** Check if value is within valid 24-bit range */
+  static isValidEsi(esi: number): boolean {
+    return esi >= 0 && esi <= 0xffffff
+  }
+}
+
+// =============================================================================
+// Inline Tests (vitest)
+// =============================================================================
+
+if (import.meta.vitest) {
+  const { describe, test, expect } = import.meta.vitest
+
+  describe('FEC Helpers', () => {
+    test('fecPack/fecUnpack roundtrip', () => {
+      const sbn = 12345
+      const esi = 67890
+      const packed = fecPack(sbn, esi)
+      const [unpackedSbn, unpackedEsi] = fecUnpack(packed)
+      expect(unpackedSbn).toBe(sbn)
+      expect(unpackedEsi).toBe(esi)
+    })
+
+    test('fecPack/fecUnpack max values', () => {
+      const sbn = FEC_PAYLOAD_ID_MAX
+      const esi = FEC_PAYLOAD_ID_MAX
+      const packed = fecPack(sbn, esi)
+      const [unpackedSbn, unpackedEsi] = fecUnpack(packed)
+      expect(unpackedSbn).toBe(sbn)
+      expect(unpackedEsi).toBe(esi)
+    })
+
+    test('fecPack/fecUnpack zero', () => {
+      const packed = fecPack(0, 0)
+      expect(packed).toBe(0n)
+      const [sbn, esi] = fecUnpack(0n)
+      expect(sbn).toBe(0)
+      expect(esi).toBe(0)
+    })
+
+    test('fecPack truncates overflow', () => {
+      const sbn = 0x1ffffff // 25 bits
+      const esi = 0x1ffffff // 25 bits
+      const packed = fecPack(sbn, esi)
+      const [unpackedSbn, unpackedEsi] = fecUnpack(packed)
+      expect(unpackedSbn).toBe(FEC_PAYLOAD_ID_MAX)
+      expect(unpackedEsi).toBe(FEC_PAYLOAD_ID_MAX)
+    })
+  })
+
+  describe('FecPayloadId', () => {
+    test('should create and roundtrip', () => {
+      const sbn = 12345
+      const esi = 67890
+      const fecId = new FecPayloadId(sbn, esi)
+      expect(fecId.sbn).toBe(sbn)
+      expect(fecId.esi).toBe(esi)
+
+      const fecId2 = FecPayloadId.fromPacked(fecId.packed)
+      expect(fecId2.sbn).toBe(sbn)
+      expect(fecId2.esi).toBe(esi)
+    })
+
+    test('should handle max 24-bit values', () => {
+      const sbn = 0xffffff
+      const esi = 0xffffff
+      const fecId = new FecPayloadId(sbn, esi)
+      const fecId2 = FecPayloadId.fromPacked(fecId.packed)
+      expect(fecId2.sbn).toBe(sbn)
+      expect(fecId2.esi).toBe(esi)
+    })
+
+    test('should reject invalid SBN', () => {
+      expect(() => new FecPayloadId(-1, 0)).toThrow()
+      expect(() => new FecPayloadId(0x1000000, 0)).toThrow()
+    })
+
+    test('should reject invalid ESI', () => {
+      expect(() => new FecPayloadId(0, -1)).toThrow()
+      expect(() => new FecPayloadId(0, 0x1000000)).toThrow()
+    })
+
+    test('isValidSbn/isValidEsi', () => {
+      expect(FecPayloadId.isValidSbn(0)).toBe(true)
+      expect(FecPayloadId.isValidSbn(0xffffff)).toBe(true)
+      expect(FecPayloadId.isValidSbn(-1)).toBe(false)
+      expect(FecPayloadId.isValidSbn(0x1000000)).toBe(false)
+
+      expect(FecPayloadId.isValidEsi(0)).toBe(true)
+      expect(FecPayloadId.isValidEsi(0xffffff)).toBe(true)
+      expect(FecPayloadId.isValidEsi(-1)).toBe(false)
+      expect(FecPayloadId.isValidEsi(0x1000000)).toBe(false)
+    })
+  })
+}