node-av 6.2.0-beta.9 → 6.2.0

package/dist/api/muxer.d.ts

@@ -8,6 +8,20 @@ import type { BitStreamFilterAPI } from './bitstream-filter.js';
 import type { Demuxer, RTPDemuxer } from './demuxer.js';
 import type { IOOutputCallbacks } from './io-stream.js';
 import type { ContextOptions } from './utilities/context-options.js';
+/**
+ * Observer for the packets a Muxer accepts for writing.
+ *
+ * @internal
+ */
+export interface MuxerPacketObserver {
+    /** A packet with payload was accepted; throwing fails the write like a muxing error. */
+    onPacket(streamIndex: number): void;
+    /**
+     * An accepted packet of this stream will not reach the output (dropped, or rejected by libavformat).
+     * A libavformat error for an earlier, buffered packet is reported against the packet submitted with it.
+     */
+    onPacketRejected(streamIndex: number): void;
+}
 /**
  * Options for Muxer creation.
  */
@@ -61,10 +75,57 @@ export interface MuxerOptions<F extends MuxerFormat | (string & {}) = MuxerForma
      *
      * When enabled, the muxer will terminate on the first write error.
      * When disabled, errors are logged but processing continues.
+     * Timestamp discontinuities the muxer refuses to write (see
+     * {@link MuxerOptions.dtsBackwardThreshold} and
+     * {@link MuxerOptions.dtsForwardThreshold}) are thrown either way.
      *
      * @default true
      */
     exitOnError?: boolean;
+    /**
+     * Backward DTS jump in seconds above which writing a packet fails.
+     *
+     * Audio and video DTS must not decrease, so a packet behind the stream's last
+     * written DTS is clamped forward. After a large backward jump (a live source
+     * restarting its clock) every following packet is clamped to one tick past the
+     * previous one until the source catches up again, collapsing the timeline for
+     * as long as the jump. With a threshold set, such a packet is rejected with an
+     * error instead, so the owner can restart on a fresh timeline. Smaller jumps
+     * are still clamped. `0` disables the check.
+     *
+     * Independent of this option, MP4/MOV-family outputs always reject a DTS step
+     * or packet duration that their 32-bit sample durations cannot store (INT_MAX
+     * ticks or more), where movenc would otherwise collapse the step to one tick
+     * or abort the process. Without an edit list (fragmented output without
+     * `delay_moov`) they also reject the first packet of a stream that starts
+     * more than `max_interleave_delta` (10 s) after the others and ends before
+     * the output's start, which movenc cannot store either.
+     *
+     * @default 0
+     */
+    dtsBackwardThreshold?: number;
+    /**
+     * Forward DTS jump in seconds, beyond the real time that passed, above which
+     * writing a packet fails.
+     *
+     * For a source read in real time, timestamps advance with the clock: a gap
+     * in the stream comes with a matching wait for the packet after it. A packet
+     * whose DTS runs further ahead than the time that passed is a
+     * discontinuity (a live source restarting its clock behind a restreamer),
+     * and writing it would leave a sample spanning the jump. With a threshold
+     * set, such a packet is rejected with an error before it reaches the
+     * output, so the owner can restart on a fresh timeline. Real time is
+     * measured per audio/video stream from when its packets are passed to
+     * writePacket(), and a packet is compared with the stream's last 128 to 256
+     * packets, so frames a parser or encoder held back during a gap do not make
+     * the end of the gap look like a jump. A stream's first packet is not
+     * checked, and a packet without DTS is measured by its PTS. Use it only for
+     * sources read in real time: a file read faster than real time has its gaps
+     * without the wait. `0` disables the check.
+     *
+     * @default 0
+     */
+    dtsForwardThreshold?: number;
     /**
      * Maximum number of packets to buffer per stream in the sync queue.
      *
@@ -278,6 +339,7 @@ export declare class Muxer implements AsyncDisposable, Disposable {
     private options;
     private _streams;
     private ioContext?;
+    private customIO;
     private headerWritten;
     private headerWritePromise?;
     private trailerWritten;
@@ -289,9 +351,19 @@ export declare class Muxer implements AsyncDisposable, Disposable {
     private writeWorkerPromise?;
     private writeWorkerError?;
     private signal?;
+    private movSampleLimit;
+    private tsNonStrict;
+    private movZeroStart;
+    private interleaveDeltaUs;
+    private trailerDiscarded;
+    private forwardThresholdMs;
+    private clock;
+    private packetObserver?;
     /**
      * @param options - Media output options
      *
+     * @throws {RangeError} If dtsBackwardThreshold or dtsForwardThreshold is not a finite number >= 0
+     *
      * @internal
      */
     private constructor();
@@ -312,6 +384,8 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      *
      * @throws {Error} If format required for custom I/O
      *
+     * @throws {RangeError} If dtsBackwardThreshold or dtsForwardThreshold is not a finite number >= 0
+     *
      * @throws {FFmpegError} If allocation or opening fails
      *
      * @example
@@ -386,6 +460,8 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      *
      * @throws {Error} If format required for custom I/O
      *
+     * @throws {RangeError} If dtsBackwardThreshold or dtsForwardThreshold is not a finite number >= 0
+     *
      * @throws {FFmpegError} If allocation or opening fails
      *
      * @example
@@ -698,6 +774,9 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      *
      * @throws {Error} If stream invalid or encoder not initialized
      *
+     * @throws {Error} On a timestamp discontinuity the output cannot take (see {@link MuxerOptions.dtsBackwardThreshold}).
+     * With the background write queue (more than one stream) it surfaces from a later writePacket() or close().
+     *
      * @throws {FFmpegError} If write fails
      *
      * @example
@@ -754,6 +833,8 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      *
      * @throws {Error} If stream invalid or encoder not initialized
      *
+     * @throws {Error} On a timestamp discontinuity the output cannot take (see {@link MuxerOptions.dtsBackwardThreshold})
+     *
      * @throws {FFmpegError} If write fails
      *
      * @example
@@ -835,6 +916,54 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      * @internal
      */
     getFormatContext(): FormatContext;
+    /**
+     * Follow the packets this muxer accepts for writing.
+     *
+     * The observer hears about every packet with payload once it is accepted
+     * (before it waits in the pre-mux queue or reaches libavformat) and about
+     * every such packet that is dropped later, so together with the output it
+     * knows what the muxer holds. close() detaches it.
+     *
+     * @param observer - Observer, or undefined to detach
+     *
+     * @internal
+     */
+    setPacketObserver(observer: MuxerPacketObserver | undefined): void;
+    /**
+     * Replace the clock that stamps packet arrival times for the dtsForwardThreshold check.
+     *
+     * Lets tests drive real time deterministically. Set it before the first packet.
+     *
+     * @param clock - Monotonic time in ms
+     *
+     * @internal
+     */
+    setClock(clock: () => number): void;
+    /**
+     * Make close() skip the trailer.
+     *
+     * For owners that drop whatever the muxer still emits, such as FMP4Stream
+     * after a failed session: the trailer would only push libavformat's backlog
+     * into the void, and movenc asserts on some track states a failed session
+     * can leave behind. The backlog is freed with the format context instead.
+     *
+     * @internal
+     */
+    discardOnClose(): void;
+    /**
+     * Announce a packet the muxer has accepted to the packet observer.
+     *
+     * @param pkt - The muxer's clone of the packet
+     *
+     * @param streamIndex - Output stream index
+     *
+     * @returns True when the observer now tracks the packet
+     *
+     * @throws {Error} If the observer fails the write (the clone is freed)
+     *
+     * @internal
+     */
+    private announcePacket;
     /**
      * Apply shared pre-header setup for writePacket and writePacketSync.
      *
@@ -845,6 +974,16 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      * @internal
      */
     private prepareHeaderWrite;
+    /**
+     * Read the muxing setup libavformat settles while writing the header.
+     *
+     * movenc decides on edit lists only then: without one (fragmented output
+     * without delay_moov) it shifts the output to start at 0 and puts each
+     * track's first sample there, which {@link checkMovLateStart} guards.
+     *
+     * @internal
+     */
+    private readHeaderSetup;
     /**
      * Setup sync queues based on stream configuration.
      *
@@ -858,6 +997,14 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      * @internal
      */
     private setupSyncQueues;
+    /**
+     * Whether any stream still holds packets (or an EOF marker) in its pre-mux queue.
+     *
+     * @returns True if a pre-mux queue is not empty
+     *
+     * @internal
+     */
+    private hasPreMuxPackets;
     /**
      * Flush all PreMuxQueues in DTS-sorted order.
      *
@@ -891,6 +1038,8 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      *
      * @param streamIndex - Stream index
      *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
      * @internal
      */
     private write;
@@ -904,6 +1053,8 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      *
      * @param streamIndex - Stream index
      *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
      * @internal
      */
     private writeInternal;
@@ -924,6 +1075,8 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      *
      * @param streamIndex - Stream index
      *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
      * @internal
      */
     private writeSync;
@@ -953,11 +1106,12 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      * Apply the configured `startTime` offset to an encoded packet, per stream.
      *
      * `startTime` exists to strip a device's boot-relative timestamp base (e.g. the
-     * mach uptime avfoundation reports). But audio encoders re-stamp their output to
-     * a ~0 baseline, so subtracting a large device startTime from them would push the
-     * timestamps hugely negative and produce a broken/overflowed edit list that strict
-     * players (QuickTime) reject. The effective offset is therefore decided once on the
-     * stream's first packet and clamped to what the stream actually carries —
+     * mach uptime avfoundation reports). But not every stream of an output carries
+     * that base (e.g. zero-based audio next to device video), so subtracting a large
+     * device startTime from such a stream would push its timestamps hugely negative and
+     * produce a broken/overflowed edit list that strict players (QuickTime) reject. The
+     * effective offset is therefore decided once on the stream's first packet and
+     * clamped to what the stream actually carries —
      * `min(startTime, max(0, firstPts))`: boot-relative streams normalize to zero,
      * already-zero-based streams are left untouched.
      *
@@ -975,8 +1129,14 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      * Performs timestamp corrections:
      * 1. Rescales timestamps to output timebase (av_rescale_delta for audio streamcopy)
      * 2. Sets pkt.timeBase to output stream timebase
-     * 3. Fixes invalid DTS > PTS relationships
-     * 4. Enforces monotonic DTS (never decreasing)
+     * 3. Rejects backward jumps beyond dtsBackwardThreshold
+     * 4. Fixes invalid DTS > PTS relationships
+     * 5. Enforces monotonic DTS (never decreasing), shrinking a clamped packet's duration to the clamped step
+     * 6. Rejects forward jumps that run ahead of real time beyond dtsForwardThreshold
+     * 7. Rejects DTS steps/durations a movenc output cannot store, and a late stream's first packet before its start
+     *
+     * The stream's last muxed DTS only advances when the packet is accepted and
+     * carries a DTS.
      *
      * @param pkt - Packet to fix
      *
@@ -984,9 +1144,118 @@ export declare class Muxer implements AsyncDisposable, Disposable {
      *
      * @param streamIndex - Stream index
      *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @throws {Error} On a rejected timestamp discontinuity
+     *
      * @internal
      */
     private muxFixupTs;
+    /**
+     * Reject a packet whose DTS lies further behind the stream's last muxed DTS
+     * than the configured dtsBackwardThreshold.
+     *
+     * Expects the DTS already rescaled to the output stream time base. No-op when
+     * the threshold is unset or 0.
+     *
+     * @param dts - Packet DTS in the output time base
+     *
+     * @param lastMuxDts - The stream's last muxed DTS
+     *
+     * @param timeBase - Output stream time base
+     *
+     * @param streamIndex - Stream index
+     *
+     * @throws {Error} If the backward jump exceeds the threshold
+     *
+     * @internal
+     */
+    private checkBackwardDts;
+    /**
+     * Reject a packet whose DTS runs further ahead of real time than the
+     * configured dtsForwardThreshold.
+     *
+     * Tracks per stream how real time and media time move apart (the offset) and
+     * compares the packet's offset with the lowest one of the stream's recent
+     * packets, see FORWARD_WINDOW_BUCKET. A gap in a live source leaves the
+     * offset level, since the wait comes with it; a jump lowers it by the size
+     * of the jump. The stream's first packet only sets the starting point.
+     *
+     * @param ts - Final packet DTS (PTS without DTS) in the output time base
+     *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @param streamInfo - Stream description
+     *
+     * @param streamIndex - Stream index
+     *
+     * @returns The packet's offset, for {@link recordForwardDts} once the packet is accepted
+     *
+     * @throws {Error} If the DTS runs ahead of real time by more than the threshold
+     *
+     * @internal
+     */
+    private checkForwardDts;
+    /**
+     * Make an accepted packet the reference of the stream's next forward check.
+     *
+     * @param state - The stream's forward check state
+     *
+     * @param ts - The packet's DTS (PTS without DTS) in the output time base
+     *
+     * @param offset - The packet's offset from {@link checkForwardDts}
+     *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
+     * @internal
+     */
+    private recordForwardDts;
+    /**
+     * Reject a packet whose DTS step or duration a movenc output cannot store.
+     *
+     * Runs after the monotonic clamp, on the DTS movenc will see. Steps are
+     * measured against the stream's last muxed DTS.
+     *
+     * @param dts - Final packet DTS, or its PTS for a packet without DTS
+     *
+     * @param duration - Final packet duration
+     *
+     * @param lastMuxDts - The stream's last muxed DTS
+     *
+     * @param timeBase - Output stream time base
+     *
+     * @param streamIndex - Stream index
+     *
+     * @throws {Error} If the step or duration reaches INT_MAX ticks
+     *
+     * @internal
+     */
+    private checkMovSampleDuration;
+    /**
+     * Reject a stream's first packet that ends before the output's start.
+     *
+     * Without an edit list movenc puts each track's first sample at the output's
+     * start, so a first packet that ends before it becomes a sample of negative
+     * duration, and movenc aborts the process (av_assert0 in
+     * get_cluster_duration) at the next fragment or the trailer unless a second
+     * sample reaches it first. libavformat sets that start from the lowest DTS
+     * it holds when it writes its first packet. It holds every packet until each
+     * stream has sent one or its queue spans max_interleave_delta, so only a
+     * stream that starts that much later than the others can land before it.
+     *
+     * @param ts - Packet DTS (PTS without DTS) in the output time base
+     *
+     * @param duration - Packet duration
+     *
+     * @param timeBase - Output stream time base
+     *
+     * @param streamIndex - Stream index
+     *
+     * @throws {Error} If the packet ends before a start libavformat may already have set
+     *
+     * @internal
+     */
+    private checkMovLateStart;
     /**
      * Copy container metadata from input to output.
      *