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

package/node_modules/@blockcast/mmt-base/dist/mmtp.d.ts

@@ -0,0 +1,275 @@
+import { 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;
+    /** 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 declare const MMTP_HEADER_SIZE = 12;
+export declare const MPU_HEADER_SIZE = 8;
+export declare const MFU_DU_HEADER_SIZE_TIMED = 14;
+export declare const MFU_DU_HEADER_SIZE_NONTIMED = 4;
+export declare const PACKET_TYPE_MPU = 0;
+export declare const PACKET_TYPE_SIGNALING = 2;
+export declare const PACKET_TYPE_REPAIR = 3;
+export declare const ALFEC_MESSAGE_ID = 515;
+export declare const FEC_CODE_XOR = 1;
+export declare const FEC_CODE_RAPTORQ = 2;
+/**
+ * Parse MMTP header from buffer
+ */
+export declare function parseMMTPHeader(buffer: Uint8Array): MMTPHeader;
+/**
+ * Unwrap MMTP packet to extract payload
+ */
+export declare function unwrapMMTP(buffer: Uint8Array): MMTPPacket;
+/**
+ * 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 declare function parseMPUHeader(payload: Uint8Array): MPUHeader;
+export declare function parseTimedMfuDuHeader(payload: Uint8Array, offset: number): MFUDuHeader | null;
+/**
+ * Why `extractMFUPayload` refused a packet.
+ *
+ * These identifiers are part of the public contract: callers surface them in
+ * diagnostics, so renaming one is a breaking change.
+ */
+export type MFURejectionGate = 'packet-shorter-than-mmtp-plus-mpu-header' | 'mmtp-header-unparseable' | 'not-an-mpu-packet' | 'payload-shorter-than-mpu-header' | 'aggregation-flag-set' | 'mpu-payload-length-below-header-remainder' | 'mpu-declared-end-exceeds-payload' | 'mfu-offset-at-or-past-declared-end' | 'source-fec-payload-id-width-mismatch' | 'declared-trailers-unresolved';
+export interface MFURejection {
+    gate: MFURejectionGate;
+    /** Human-readable detail, including the byte arithmetic that decided it. */
+    detail: string;
+}
+/**
+ * Extract NAL unit payload from MMTP packet
+ */
+export declare function extractNALUnit(mmtpPacket: Uint8Array): Uint8Array;
+/** 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;
+}
+/**
+ * Report why `extractMFUPayload` would refuse this packet, or null if it would
+ * accept it.
+ *
+ * `extractMFUPayload` returns bare `null` on ten distinct conditions, which
+ * makes a producer/consumer framing disagreement indistinguishable from a
+ * publisher that never started — both render as silence. Use this wherever
+ * that distinction matters: diagnostics, contract tests, and operator-facing
+ * logs.
+ */
+export declare function explainMFURejection(mmtpPacket: Uint8Array, options?: {
+    skipFecId?: boolean;
+}): MFURejection | null;
+export declare function extractMFUPayload(mmtpPacket: Uint8Array, options?: {
+    skipFecId?: boolean;
+}): MFUExtraction | null;
+/**
+ * Extract timestamp from MMTP packet
+ */
+export declare function extractTimestamp(mmtpPacket: Uint8Array): bigint;
+/**
+ * Check if MMTP packet is an FEC repair packet
+ * FEC_type 2 and 3 are repair packets
+ */
+export declare function isFecRepairPacket(mmtpPacket: Uint8Array): boolean;
+/**
+ * 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 declare function extractFecPayloadId(mmtpPacket: Uint8Array): {
+    ssId: number;
+} | null;
+/**
+ * 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 declare function hasSourceFecPayloadId(mmtpPacket: Uint8Array): boolean;
+/**
+ * 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").
+ */
+export declare const MMTP_EXT_TYPE_ALTA_AUTH = 61601;
+export declare const MMTP_EXT_TRAILER_HEADER_SIZE = 4;
+export type AltaTrailer = _LeafAltaTrailer;
+export declare const extractAltaTrailer: typeof _leafExtractAltaTrailer;
+/** Size of Repair FEC Payload ID per ISO/IEC 23008-1 Section C.5.3 */
+export declare const REPAIR_FEC_PID_SIZE = 13;
+/**
+ * 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 declare function extractRepairFecPayloadId(mmtpPacket: Uint8Array): {
+    ssStart: number;
+    rsbLength: number;
+    rsId: number;
+    ssbLength: number;
+} | null;
+/** 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 declare function parseMoqRepairFrame(frame: Uint8Array): MoqRepairFrame | null;
+/**
+ * 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;
+}
+/**
+ * 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 declare function parseAlFecMessage(mmtpPacket: Uint8Array): AlFecConfig | null;
+//# sourceMappingURL=mmtp.d.ts.map

package/node_modules/@blockcast/mmt-base/dist/mmtp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmtp.d.ts","sourceRoot":"","sources":["../src/mmtp.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,kBAAkB,IAAI,uBAAuB,EAC7C,KAAK,WAAW,IAAI,gBAAgB,EACrC,MAAM,2BAA2B,CAAA;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,sDAAsD;IACtD,iBAAiB,EAAE,OAAO,CAAA;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAE,CAAA;IAC9C,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAA;IACpB,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,iBAAiB,EAAE,MAAM,CAAA;IACzB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAA;IACvB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,eAAe,EAAE,OAAO,CAAA;IACxB;sEACkE;IAClE,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,2BAA2B,EAAE,MAAM,CAAA;IACnC,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,iBAAiB,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAA;IAClB,OAAO,EAAE,UAAU,CAAA;CACpB;AAED,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAClC,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAC1C,eAAO,MAAM,2BAA2B,IAAI,CAAA;AAO5C,eAAO,MAAM,eAAe,IAAO,CAAA;AACnC,eAAO,MAAM,qBAAqB,IAAO,CAAA;AACzC,eAAO,MAAM,kBAAkB,IAAO,CAAA;AAGtC,eAAO,MAAM,gBAAgB,MAAS,CAAA;AAGtC,eAAO,MAAM,YAAY,IAAI,CAAA;AAC7B,eAAO,MAAM,gBAAgB,IAAI,CAAA;AAEjC;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAuE9D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAKzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CA+B7D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAU7F;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACxB,0CAA0C,GAC1C,yBAAyB,GACzB,mBAAmB,GACnB,iCAAiC,GACjC,sBAAsB,GACtB,2CAA2C,GAC3C,kCAAkC,GAClC,oCAAoC,GACpC,sCAAsC,GACtC,8BAA8B,CAAA;AAElC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAA;IACtB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAA;CACf;AA4GD;;GAEG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAIjE;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,yBAAyB;IACzB,MAAM,EAAE,UAAU,CAAA;IAClB,wBAAwB;IACxB,GAAG,EAAE,SAAS,CAAA;IACd,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAA;IACpB,8EAA8E;IAC9E,IAAI,EAAE,UAAU,CAAA;IAChB,8DAA8D;IAC9D,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;IAC/B,kEAAkE;IAClE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,kEAAkE;IAClE,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CACtC;AAqID;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,YAAY,GAAG,IAAI,CAGrB;AAED,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAChC,aAAa,GAAG,IAAI,CA+BtB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAG/D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAIjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAUnF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAiBrE;AAED;;;;;;;GAOG;AAIH,eAAO,MAAM,uBAAuB,QAAgC,CAAA;AACpE,eAAO,MAAM,4BAA4B,IAAqC,CAAA;AAC9E,MAAM,MAAM,WAAW,GAAG,gBAAgB,CAAA;AAC1C,eAAO,MAAM,kBAAkB,gCAA0B,CAAA;AAEzD,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,KAAK,CAAA;AA+BrC;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,UAAU,GAAG;IACjE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CACpE,GAAG,IAAI,CASP;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAoB5E;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,CAAC,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,GAAG,EAAE,UAAU,CAAA;CAChB;AAoBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI,CA2E5E"}