@blockcast/mmt-container 0.1.0-main.0399efef1f07

package/dist/cmaf-block-assembler.d.ts

@@ -0,0 +1,217 @@
+/**
+ * FEC-block-aware CMAF segment assembler for MSE multicast.
+ *
+ * Buffers reassembled frames per FEC source block (SBN). On block completion
+ * (K source symbols received clean, or FEC recovery), sorts frames by ESI
+ * and builds a single multi-sample moof+mdat CMAF segment. On block timeout,
+ * generates fill frames (green video / silence audio) for missing ESI slots.
+ *
+ * One assembler instance per track (video or audio). MulticastManager owns
+ * these instances and calls them directly with SBN/ESI from the FEC pipeline.
+ */
+import { type AuthoredTiming } from './authored-timing.js';
+import type { MmtpDeliveryProvenance } from './mfu-reassembler.js';
+interface BlockFrame {
+    data: Uint8Array;
+    timestamp: number;
+    keyframe: boolean;
+    /** True only for locally generated concealment frames. */
+    synthetic?: boolean;
+    /** Raw MMTP short-NTP header timestamp; never used for CMAF timing. */
+    mmtpTimestamp?: bigint;
+    /** Exact ISO-BMFF timing retained from the parser for FEC/source ordering. */
+    authoredTiming?: AuthoredTiming;
+    /** MMTP packet_sequence_number identifying the delivered access unit. */
+    packetSequenceNumber?: number;
+    /** Every authoritative MMTP source-packet sequence that formed this sample. */
+    packetSequenceNumbers?: number[];
+    /** Subset of packetSequenceNumbers reconstructed by FEC. */
+    repairedPacketSequenceNumbers?: number[];
+    /** Native MMTP MPU group coordinate retained across source/FEC ordering. */
+    mpuSequenceNumber?: number;
+    /** Timed-MFU sample identity; absent when the MFU header is untimed. */
+    movieFragmentSequenceNumber?: number;
+    sampleNumber?: number;
+    catalogTrackName?: string;
+    /**
+     * Whole-frame delivery verdict folded across every contributing fragment.
+     * Absent means no caller declared one; it is never an implied 'multicast'.
+     */
+    deliveryProvenance?: MmtpDeliveryProvenance;
+}
+export interface CmafBlockSample {
+    data: Uint8Array;
+    timestamp: number;
+    duration: number;
+    keyframe: boolean;
+    /**
+     * True only for locally generated concealment samples. These samples carry
+     * codec bytes and a media timestamp, but no authored MMTP identity; object
+     * consumers must not validate them as source MFUs.
+     */
+    synthetic?: boolean;
+    /**
+     * Raw MMTP short-NTP header timestamp retained for timing telemetry.
+     * This is intentionally separate from the authored media timestamp above.
+     */
+    mmtpTimestamp?: bigint;
+    /** Signed PTS-DTS offset in the configured CMAF timescale. */
+    compositionTimeOffset?: number;
+    /** Exact ISO-BMFF timing in the media track's native timescale. */
+    authoredTiming?: AuthoredTiming;
+    /** MMTP packet_sequence_number identifying the delivered access unit. */
+    packetSequenceNumber?: number;
+    /** Every authoritative MMTP source-packet sequence that formed this sample. */
+    packetSequenceNumbers?: number[];
+    /** Subset of packetSequenceNumbers reconstructed by FEC. */
+    repairedPacketSequenceNumbers?: number[];
+    /** Native MMTP MPU group coordinate retained for exact replay selection. */
+    mpuSequenceNumber?: number;
+    /**
+     * Timed-MFU sample identity `(movie_fragment_sequence_number,
+     * sample_number)` from the MFU data-unit header, carried alongside
+     * `mpuSequenceNumber` so a consumer can address the sample by its native
+     * MMTP coordinates. Absent when the MFU header is untimed.
+     */
+    movieFragmentSequenceNumber?: number;
+    sampleNumber?: number;
+    /** Immutable catalog identity supplied by the owning ingress subscription. */
+    catalogTrackName?: string;
+    /**
+     * Whole-frame delivery verdict, carried so MSE `onSample` consumers can see
+     * the same evidence the non-MSE frame path gets. Without it the MSE branch
+     * silently loses a computed 'mixed' or 'multicast' finding.
+     */
+    deliveryProvenance?: MmtpDeliveryProvenance;
+}
+export type CmafSampleOrderPolicy = {
+    mode: 'arrival';
+} | {
+    /** Release samples according to media progression, without a wall clock. */
+    mode: 'media-window';
+    /** Delivery window in the same units as CmafBlockSample.timestamp. */
+    deliveryWindow: number;
+    /** Optional modulo period for wrapped input timestamps, in timestamp units. */
+    timestampWrapPeriod?: number;
+};
+export interface CmafSampleOrderStats {
+    staleSamples: number;
+    duplicateSamples: number;
+    preRapDeadlineDrops: number;
+    noRapFlushDrops: number;
+    forcedReleases: number;
+    /**
+     * Samples refused because they carried `authoredTiming` while this track's
+     * `admitAuthoredTiming` was false. Non-zero means the contract rollback
+     * switch is engaged AND the producer is still sending authored batches —
+     * a rollback is meant to be paired with that producer reverting to raw.
+     */
+    unadmittedAuthoredSamples: number;
+}
+export interface BlockAssemblerConfig {
+    /** Number of source symbols per FEC block */
+    k: number;
+    /** Timescale for CMAF segments (default 1_000_000 = microseconds) */
+    timescale?: number;
+    /** ISO track ID (default 1) */
+    trackId?: number;
+    /** Track type — determines fill frame generation and init segment format */
+    trackType: 'video' | 'audio';
+    /** Video/audio codec string (e.g. 'avc1.64002a', 'mp4a.40.2'). */
+    codec?: string;
+    /** Raw avcC payload from catalog description — for init + green fill */
+    avcC?: Uint8Array;
+    /** Video width in pixels */
+    width?: number;
+    /** Video height in pixels */
+    height?: number;
+    /** Audio codec string (e.g. 'mp4a.40.2', 'opus') — for silence fill generation */
+    audioCodec?: string;
+    /** Audio sample rate (e.g. 48000) */
+    sampleRate?: number;
+    /** Audio channel count (e.g. 1 or 2) */
+    channels?: number;
+    /** Raw AudioSpecificConfig from catalog */
+    asc?: Uint8Array;
+    /** Frames per second — fallback for duration estimation */
+    fps?: number;
+    /** Explicit sample ordering policy. Datagram/FEC callers use media-window. */
+    sampleOrder?: CmafSampleOrderPolicy;
+    /**
+     * Bounded sample reorder depth for callback mode.
+     *
+     * Default 0 preserves immediate emission. When set on video tracks with
+     * onSample enabled, samples are sorted by timestamp and the oldest sample is
+     * emitted only after this many newer samples are available.
+     * @deprecated Use sampleOrder with an explicit policy.
+     */
+    sampleReorderWindow?: number;
+    /**
+     * Authored-timing admission for this track (default `true` — admitted).
+     *
+     * This is the rollback switch named by the authored-audio-CTS contract's
+     * removal gate (BLO-30397). An assembler is constructed per track/per
+     * packetId (`mmtp-router.ts` `enableMseAssembler`), so a producer feeding its
+     * own stream is de-admitted by configuring its assembler alone.
+     *
+     * Set `false` and a sample carrying `authoredTiming` is **rejected**, not
+     * zeroed: the contract forbids rolling back "by zeroing already-authored
+     * offsets", because a zeroed offset is byte-indistinguishable from a feed
+     * that authored nothing (BLO-30401 measured both as 0 A/V skew). Raw samples
+     * — those with no `authoredTiming` at all — are unaffected and keep emitting
+     * a v0 trun with no composition-offset field.
+     */
+    admitAuthoredTiming?: boolean;
+}
+export declare class CmafBlockAssembler {
+    #private;
+    /** Callback: emits a complete moof+mdat CMAF segment */
+    onSegment: ((segment: Uint8Array) => void) | null;
+    /** Callback: emits a gated/deduped raw sample for callers that already own the MSE timeline. */
+    onSample: ((sample: CmafBlockSample) => void) | null;
+    /** Callback: emits an init segment (ftyp+moov) */
+    onInitSegment: ((init: Uint8Array) => void) | null;
+    /** Mark video as already synchronized by an external decoder path.
+     *  Used by MoQ→multicast MSE continuity when MoQ has already appended a
+     *  keyframe to the same SourceBuffer timeline before multicast takeover. */
+    markVideoSynced(): void;
+    constructor(config: BlockAssemblerConfig);
+    private _videoConfig;
+    private _audioConfig;
+    get sampleOrderStats(): Readonly<CmafSampleOrderStats>;
+    /** Emit a single frame immediately as a one-sample moof+mdat segment.
+     *
+     *  BLO-3035 layer 4 (4b): the prior SBN-grouped buffering scheme stranded
+     *  frames whenever a multi-packet frame spanned FEC block boundaries —
+     *  intermediate SBNs had packets-but-no-frames and got `completeBlock`
+     *  events that landed on empty `#blocks` (→ `pendingFlush` leak), while
+     *  the SBN where the multi-packet frame finally completed received the
+     *  `addFrame` but its `trackBlock` count never reached K (→ `pendingBlocks`
+     *  leak). Result: ~50% of received frames never reached MSE.
+     *
+     *  This path now mirrors `addBypassFrame` — emit on arrival, no buffering.
+     *  FEC recovery (`addRecoveredBlock`) keeps its SBN-watermark dedup against
+     *  the same SBN being re-emitted from two paths. Out-of-order regression
+     *  is guarded by the per-frame `lastEmittedTs` check (also enforced in
+     *  `#emitPerSample`). The `sbn`/`esi` parameters are kept for the call-site
+     *  signature but no longer affect routing. */
+    addFrame(sbn: number, esi: number, data: Uint8Array, timestamp: number, keyframe: boolean, catalogTrackName?: string, mpuSequenceNumber?: number, packetSequenceNumber?: number, packetSequenceNumbers?: number[], repairedPacketSequenceNumbers?: number[], authoredTiming?: AuthoredTiming, deliveryProvenance?: MmtpDeliveryProvenance, mmtpTimestamp?: bigint, movieFragmentSequenceNumber?: number, sampleNumber?: number): void;
+    /** Mark a block as complete (all K source symbols received or FEC recovery succeeded).
+     *  If all frames are already buffered, flushes immediately. Otherwise sets pending-flush. */
+    completeBlock(sbn: number): void;
+    /** Handle block timeout — emit whatever frames we have + fill for missing slots. */
+    failBlock(sbn: number): void;
+    /** Add all frames from a FEC-recovered block at once and emit immediately. */
+    addRecoveredBlock(sbn: number, frames: BlockFrame[]): void;
+    /** Emit a single frame immediately as a one-sample segment (for oversized packets bypassing FEC). */
+    addBypassFrame(data: Uint8Array, timestamp: number, keyframe: boolean, catalogTrackName?: string, mpuSequenceNumber?: number, packetSequenceNumber?: number, packetSequenceNumbers?: number[], repairedPacketSequenceNumbers?: number[], authoredTiming?: AuthoredTiming, deliveryProvenance?: MmtpDeliveryProvenance, mmtpTimestamp?: bigint, movieFragmentSequenceNumber?: number, sampleNumber?: number): void;
+    /** Build and emit init segment from catalog config. */
+    emitInit(): void;
+    /** Drain all ordered samples at end-of-stream or before reconfiguration. */
+    flush(): void;
+    /** Drop all queued state and begin a fresh timestamp epoch. */
+    reset(): void;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=cmaf-block-assembler.d.ts.map

package/dist/cmaf-block-assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cmaf-block-assembler.d.ts","sourceRoot":"","sources":["../src/cmaf-block-assembler.ts"],"names":[],"mappings":"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"}