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

package/dist/mmtp-to-cmaf.d.ts

@@ -0,0 +1,187 @@
+/**
+ * MMTP → CMAF converter per draft-ramadan-moq-mmt §5.3.
+ *
+ * Converts reassembled MFU frames (raw codec samples from MMTP) into
+ * fMP4 segments (moof+mdat) suitable for MSE SourceBuffer.appendBuffer().
+ *
+ * MPU metadata (fragment_type=0) packets from FFmpeg are complete
+ * ftyp+moov init segments and can be used directly as MSE init data.
+ *
+ * MFU data (fragment_type=2) contains raw AVCC samples that must be
+ * wrapped in moof+mdat boxes for MSE consumption.
+ *
+ * ISO 14496-12 (ISOBMFF) box construction is inline — no dependencies.
+ */
+/**
+ * Wrap multiple samples in a single moof+mdat fMP4 segment.
+ *
+ * Builds a trun with N sample entries (duration + size + flags each).
+ * Used by CmafBlockAssembler to emit one segment per FEC source block.
+ *
+ * @param samples - Array of samples with data, duration (timescale units), keyframe flag,
+ *   and an optional signed composition-time offset (same timescale units)
+ * @param baseDecodeTime - Decode time of the first sample in timescale units
+ * @param sequence - moof sequence number
+ * @param trackId - ISO track ID (default 1)
+ * @returns moof+mdat bytes ready for SourceBuffer.appendBuffer()
+ */
+export declare function encodeMultiSampleSegment(samples: Array<{
+    data: Uint8Array;
+    duration: number;
+    keyframe: boolean;
+    compositionTimeOffset?: number;
+}>, baseDecodeTime: number, sequence: number, trackId?: number): Uint8Array;
+/**
+ * Generate a minimal silent audio frame for FEC fill.
+ *
+ * Supports AAC (mp4a) and Opus codecs. Returns raw frame data (no ADTS/OBU
+ * header) suitable for fMP4/CMAF wrapping.
+ *
+ * @param codec - Audio codec string (e.g. 'mp4a.40.2', 'opus')
+ * @param sampleRate - Audio sample rate (e.g. 48000)
+ * @param channels - Channel count (e.g. 1 or 2)
+ */
+export declare function generateSilenceFrame(codec: string, sampleRate: number, channels: number): Uint8Array;
+export declare function normalizeAacSampleForCmaf(data: Uint8Array): Uint8Array;
+/**
+ * Wrap a single raw codec sample in a moof+mdat fMP4 segment.
+ *
+ * @param data - Raw sample bytes (AVCC H.264 or raw AAC)
+ * @param timestamp - Decode time in timescale units
+ * @param duration - Sample duration in timescale units
+ * @param keyframe - true for IDR/sync sample
+ * @param sequence - moof sequence number (monotonically incrementing)
+ * @param trackId - ISO track ID (default 1)
+ * @returns moof+mdat bytes ready for SourceBuffer.appendBuffer()
+ */
+export declare function encodeDataSegment(data: Uint8Array, timestamp: number, duration: number, keyframe: boolean, sequence: number, trackId?: number, compositionTimeOffset?: number): Uint8Array;
+/**
+ * Build an ftyp+moov init segment for H.264 video MSE from an avcC box.
+ *
+ * @param avcC - Raw avcC box payload (SPS/PPS configuration)
+ * @param width - Video width in pixels
+ * @param height - Video height in pixels
+ * @param timescale - Timescale (default 1_000_000 = microseconds)
+ * @param trackId - Track ID (default 1)
+ */
+export declare function buildVideoInitSegment(avcC: Uint8Array, width: number, height: number, timescale?: number, trackId?: number): Uint8Array;
+/**
+ * Build an ftyp+moov init segment for H.265/HEVC video MSE.
+ *
+ * The sample entry is `hev1` or `hvc1` (ISO/IEC 14496-15 §8.4.1.1) carrying an
+ * `hvcC` HEVCDecoderConfigurationRecord (§8.3.3.1). Choose the entry from the
+ * catalog codec string's first element, never by inspecting the bitstream:
+ * `hev1` permits VPS/SPS/PPS to stay in-band in the samples (cast's
+ * `repeat-headers=1` stream), `hvc1` requires every parameter set in the
+ * `hvcC` and none in the samples.
+ *
+ * @param sampleEntry - `hev1` or `hvc1`
+ * @param hvcC - Raw hvcC record payload (e.g. from `generateHvcCFromParameterSets`)
+ * @param width - Video width in pixels
+ * @param height - Video height in pixels
+ * @param timescale - Media timescale
+ * @param trackId - ISO track ID
+ */
+export declare function buildHevcVideoInitSegment(sampleEntry: 'hev1' | 'hvc1', hvcC: Uint8Array, width: number, height: number, timescale: number, trackId: number): Uint8Array;
+/**
+ * Build ftyp+moov init segment for AAC audio MSE.
+ */
+export declare function buildAudioInitSegment(sampleRate: number, channels: number, asc?: Uint8Array, timescale?: number, trackId?: number): Uint8Array;
+/**
+ * MMTP → CMAF converter.
+ *
+ * Accepts reassembled MFU frames (raw codec samples) from MmtpDecoder
+ * and produces fMP4 segments for MSE SourceBuffer.
+ *
+ * Per draft-ramadan-moq-mmt §5.3:
+ *   MPU metadata (ftyp+moov) → init segment
+ *   MFU sample bytes → moof+mdat data segment
+ *
+ * Timescale is microseconds (1_000_000) matching MMTP NTP short timestamps
+ * converted via mmtpTimestampToMicros().
+ */
+export declare class MmtpToCmaf {
+    #private;
+    /**
+     * Point the single-sample video wrappers at a specific track and rate.
+     *
+     * Call this when the init segment came off the wire (setInitSegmentFromMpu)
+     * rather than from buildVideoInit, so the wrappers match the publisher's
+     * tkhd/mdhd instead of assuming trackId=1 at microsecond rate. Consumers
+     * that build their init through buildVideoInit can pass the same values
+     * there instead and skip this call.
+     *
+     * The rate is settable only until the first single-sample wrap — see the
+     * throw below for why.
+     */
+    setVideoTrackParams(trackId: number, timescale: number): void;
+    /** Set init segment from MPU metadata packet (fragment_type=0).
+     *  These are complete ftyp+moov bytes from FFmpeg — use directly. */
+    setInitSegmentFromMpu(data: Uint8Array, isAudio: boolean): void;
+    /** Build init segment from codec config (catalog path — no MPU metadata available).
+     *  Passing timescale/trackId also configures the wrappers via
+     *  setVideoTrackParams, so init and media segments cannot disagree. */
+    buildVideoInit(avcC: Uint8Array, width: number, height: number, timescale?: number, trackId?: number): void;
+    buildAudioInit(sampleRate: number, channels: number, asc?: Uint8Array, timescale?: number): void;
+    get videoInitSegment(): Uint8Array | null;
+    get audioInitSegment(): Uint8Array | null;
+    /** Convert a raw video sample to an fMP4 moof+mdat segment. */
+    wrapVideoSample(data: Uint8Array, timestamp: number, keyframe: boolean, duration?: number, compositionTimeOffset?: number): Uint8Array;
+    /**
+     * Convert a raw video sample and return the exact browser media interval
+     * encoded into tfdt/trun. Consumers that correlate SourceBuffer appends with
+     * requestVideoFrameCallback must use this rebased timestamp, not the wire or
+     * caller-owned timestamp passed above.
+     *
+     * `compositionTimeOffset` is the signed authored PTS-DTS delta, in the same
+     * #videoTimescale units as `timestamp` and `duration` — unlike wrapAudioSample,
+     * which takes microseconds and rescales, because every other quantity on this
+     * path is already denominated in #videoTimescale (see setVideoTrackParams).
+     * Passing it therefore needs no conversion here; rescaling would double-convert.
+     * Absent leaves the trun at version 0 with no offset field; a declared 0 is an
+     * authored value and still promotes to version 1. Never reconstruct it from
+     * arrival time.
+     */
+    wrapVideoSampleWithTiming(data: Uint8Array, timestamp: number, keyframe: boolean, duration?: number, compositionTimeOffset?: number): Readonly<{
+        segment: Uint8Array;
+        mediaTimestamp: number;
+        duration: number;
+    }>;
+    /** Convert an append-safe video batch using the caller-owned timeline.
+     *  Durations, baseDecodeTime, and compositionTimeOffset are in the
+     *  configured video timescale. compositionTimeOffset is the signed PTS-DTS
+     *  delta; its presence selects a version-1 trun for the whole batch.
+     *  An explicit trackId is range-checked before #videoSeq++ for the same
+     *  reason as wrapAudioSamples: the encoder's own check fires too late to
+     *  keep the sequence ungapped. */
+    wrapVideoSamples(samples: Array<{
+        data: Uint8Array;
+        duration: number;
+        keyframe: boolean;
+        compositionTimeOffset?: number;
+    }>, baseDecodeTime: number, trackId?: number): Uint8Array;
+    /** Set audio timescale to match the init segment's mdhd timescale.
+     *  Call after appending the real encoder init (FT=0 ftyp+moov).
+     *  Fails closed on a value the mdhd uint32 cannot hold, as the video paths
+     *  already do. wrapAudioSample rescales the authored composition offset by
+     *  this value, so the two failure modes are both silent: a 0 multiplies
+     *  every authored offset to 0 — indistinguishable from a feed that authored
+     *  none — while a value above uint32 scales the trun to a timescale the
+     *  mdhd cannot declare, since it is emitted with setUint32 modulo 2^32. */
+    setAudioTimescale(timescale: number): void;
+    /** Convert a raw audio sample to an fMP4 moof+mdat segment. */
+    wrapAudioSample(data: Uint8Array, timestamp: number, sampleDuration?: number, compositionTimeOffset?: number): Uint8Array;
+    /** Convert an ordered audio batch using the caller-owned timeline. */
+    wrapAudioSamples(samples: Array<{
+        data: Uint8Array;
+        duration: number;
+        compositionTimeOffset?: number;
+    }>, baseDecodeTime: number, trackId?: number): Uint8Array;
+    /** Clear per-stream sequencing and time bases.
+     *  Cached init segments and the video track geometry survive, so a converter
+     *  reset mid-subscription keeps emitting moofs the existing init can resolve.
+     *  Clearing the timescale-denominated timing state also re-opens the video
+     *  rate for change — this is the sanctioned way to retarget mid-subscription. */
+    reset(): void;
+}
+//# sourceMappingURL=mmtp-to-cmaf.d.ts.map

package/dist/mmtp-to-cmaf.d.ts.map

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