node-av 6.2.0-beta.3 → 6.2.0-beta.31

package/dist/api/muxer.js

@@ -2,7 +2,7 @@ import { mkdirSync } from 'fs';
 import { mkdir } from 'fs/promises';
 import { Writable } from 'node:stream';
 import { dirname, resolve } from 'path';
-import { AV_CODEC_FLAG_GLOBAL_HEADER, AV_DISPOSITION_ATTACHED_PIC, AV_DISPOSITION_DEFAULT, AV_NOPTS_VALUE, AV_TIME_BASE_Q, AVERROR_EAGAIN, AVERROR_EOF, AVFMT_FLAG_CUSTOM_IO, AVFMT_GLOBALHEADER, AVFMT_NOFILE, AVFMT_TS_NONSTRICT, AVIO_FLAG_WRITE, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, } from '../constants/constants.js';
+import { AV_CODEC_FLAG_GLOBAL_HEADER, AV_DISPOSITION_ATTACHED_PIC, AV_DISPOSITION_DEFAULT, AV_NOPTS_VALUE, AV_OPT_TYPE_BOOL, AV_OPT_TYPE_INT, AV_TIME_BASE_Q, AVERROR_EAGAIN, AVERROR_EOF, AVFMT_AVOID_NEG_TS_MAKE_ZERO, AVFMT_FLAG_CUSTOM_IO, AVFMT_GLOBALHEADER, AVFMT_NOFILE, AVFMT_TS_NONSTRICT, AVIO_FLAG_WRITE, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, } from '../constants/constants.js';
 import { Dictionary } from '../lib/dictionary.js';
 import { FFmpegError } from '../lib/error.js';
 import { FormatContext } from '../lib/format-context.js';
@@ -16,6 +16,35 @@ import { Encoder } from './encoder.js';
 import { IOStream } from './io-stream.js';
 import { AsyncQueue } from './utilities/async-queue.js';
 import { applyContextOptions } from './utilities/context-options.js';
+/**
+ * Output formats implemented by libavformat/movenc.c, whose sample durations are 32-bit.
+ *
+ * @internal
+ */
+const MOV_FAMILY_FORMATS = new Set(['mov', 'mp4', '3gp', '3g2', 'psp', 'ipod', 'ismv', 'f4v', 'avif']);
+/**
+ * Smallest DTS step or packet duration (stream time base ticks) rejected for movenc outputs.
+ *
+ * movenc aborts the process via av_assert0(next_dts <= INT_MAX) in get_cluster_duration()
+ * when it writes a sample table. A step of exactly INT_MAX still trips it once movenc nudges
+ * a later DTS by one tick, so the limit itself is already rejected.
+ *
+ * @internal
+ */
+const MOV_SAMPLE_DURATION_LIMIT = 0x7fffffffn;
+/**
+ * Packets per bucket of the window of recent packets the dtsForwardThreshold check compares a packet with.
+ *
+ * Two buckets cover a stream's last 128 to 256 packets. After a gap in a live
+ * source, a parser or encoder first releases the frames it held back before
+ * the gap: those frames absorb the wait, and the first frame after the gap,
+ * though on time, steps forward by the whole gap against them. Against the
+ * frames before the gap it does not, and parsers and encoders hold back far
+ * fewer frames than the window spans.
+ *
+ * @internal
+ */
+const FORWARD_WINDOW_BUCKET = 128;
 /**
  * High-level muxer for writing and muxing media files.
  *
@@ -69,6 +98,7 @@ export class Muxer {
     options;
     _streams = new Map();
     ioContext;
+    customIO = false; // ioContext is callback-backed (Writable/IOOutputCallbacks) - freed, never closed
     headerWritten = false;
     headerWritePromise;
     trailerWritten = false;
@@ -78,13 +108,32 @@ export class Muxer {
     containerMetadataCopied = false; // Track if container metadata has been copied
     writeQueue; // Optional async queue for serialized writes
     writeWorkerPromise; // Background worker promise
+    writeWorkerError; // First error from the write worker - poisons subsequent writes and close()
     signal;
+    movSampleLimit = false; // Output is a movenc format with 32-bit sample durations (set before the header write)
+    tsNonStrict = false; // Output allows equal consecutive DTS (AVFMT_TS_NONSTRICT, set before the header write)
+    movZeroStart = false; // movenc puts each track's first sample at the output's start (no edit list, set after the header write)
+    interleaveDeltaUs = 0n; // libavformat's max_interleave_delta in µs (set after the header write)
+    trailerDiscarded = false; // close() skips the trailer, see discardOnClose()
+    forwardThresholdMs = 0; // dtsForwardThreshold in ms, 0 = off
+    clock = () => performance.now(); // Monotonic ms clock for packet arrival times
+    packetObserver; // Follows the accepted packets (FMP4Stream's maxPacketAge)
     /**
      * @param options - Media output options
      *
+     * @throws {RangeError} If dtsBackwardThreshold or dtsForwardThreshold is not a finite number >= 0
+     *
      * @internal
      */
     constructor(options) {
+        for (const [name, threshold] of [
+            ['dtsBackwardThreshold', options?.dtsBackwardThreshold],
+            ['dtsForwardThreshold', options?.dtsForwardThreshold],
+        ]) {
+            if (threshold !== undefined && (!Number.isFinite(threshold) || threshold < 0)) {
+                throw new RangeError(`${name} must be a finite number of seconds >= 0, got ${threshold}`);
+            }
+        }
         this.options = {
             copyInitialNonkeyframes: false,
             exitOnError: true,
@@ -92,6 +141,7 @@ export class Muxer {
             useAsyncWrite: true,
             ...options,
         };
+        this.forwardThresholdMs = (options?.dtsForwardThreshold ?? 0) * 1000;
         this.formatContext = new FormatContext();
     }
     static async open(target, options) {
@@ -143,6 +193,7 @@ export class Muxer {
                     }
                 }
                 output.ioContext = IOStream.createOutput(target, options);
+                output.customIO = true;
                 output.formatContext.pb = output.ioContext;
                 output.formatContext.setFlags(AVFMT_FLAG_CUSTOM_IO);
             }
@@ -161,6 +212,7 @@ export class Muxer {
                     }
                 }
                 output.ioContext = IOStream.createOutput(target, options);
+                output.customIO = true;
                 output.formatContext.pb = output.ioContext;
                 output.formatContext.setFlags(AVFMT_FLAG_CUSTOM_IO);
             }
@@ -174,10 +226,10 @@ export class Muxer {
             // Cleanup on error
             if (output.ioContext) {
                 try {
-                    const isCustomIO = output.formatContext.hasFlags(AVFMT_FLAG_CUSTOM_IO);
-                    if (isCustomIO) {
-                        // Clear the pb reference first
-                        output.formatContext.pb = null;
+                    // Clear the pb reference first - freeContext() below closes a pb that
+                    // is still set, which would double-free the context released here
+                    output.formatContext.pb = null;
+                    if (output.customIO) {
                         // For custom IO with callbacks, free the context
                         output.ioContext.freeContext();
                     }
@@ -250,6 +302,7 @@ export class Muxer {
                     }
                 }
                 output.ioContext = IOStream.createOutput(target, options);
+                output.customIO = true;
                 output.formatContext.pb = output.ioContext;
                 output.formatContext.setFlags(AVFMT_FLAG_CUSTOM_IO);
             }
@@ -268,6 +321,7 @@ export class Muxer {
                     }
                 }
                 output.ioContext = IOStream.createOutput(target, options);
+                output.customIO = true;
                 output.formatContext.pb = output.ioContext;
                 output.formatContext.setFlags(AVFMT_FLAG_CUSTOM_IO);
             }
@@ -281,10 +335,10 @@ export class Muxer {
             // Cleanup on error
             if (output.ioContext) {
                 try {
-                    const isCustomIO = output.formatContext.hasFlags(AVFMT_FLAG_CUSTOM_IO);
-                    if (isCustomIO) {
-                        // Clear the pb reference first
-                        output.formatContext.pb = null;
+                    // Clear the pb reference first - freeContext() below closes a pb that
+                    // is still set, which would double-free the context released here
+                    output.formatContext.pb = null;
+                    if (output.customIO) {
                         // For custom IO with callbacks, free the context
                         output.ioContext.freeContext();
                     }
@@ -480,6 +534,8 @@ export class Muxer {
                 isStreamCopy: true,
                 sqIdxMux: -1, // Will be set if sync queue is needed
                 preMuxQueue: [],
+                preMuxArrivals: [],
+                sqArrivals: [],
                 preMuxQueueDataSize: 0,
                 eofReceived: false,
                 lastMuxDts: AV_NOPTS_VALUE,
@@ -501,6 +557,8 @@ export class Muxer {
                 isStreamCopy: false,
                 sqIdxMux: -1, // Will be set if sync queue is needed
                 preMuxQueue: [],
+                preMuxArrivals: [],
+                sqArrivals: [],
                 preMuxQueueDataSize: 0,
                 eofReceived: false,
                 lastMuxDts: AV_NOPTS_VALUE,
@@ -658,6 +716,9 @@ export class Muxer {
      *
      * @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
@@ -685,6 +746,10 @@ export class Muxer {
      */
     async writePacket(packet, streamIndex) {
         this.signal?.throwIfAborted();
+        // A previous background write failed - surface it instead of buffering more packets
+        if (this.writeWorkerError) {
+            throw this.writeWorkerError;
+        }
         if (this.isClosed) {
             throw new Error('Muxer is closed');
         }
@@ -777,6 +842,7 @@ export class Muxer {
             if (uninitialized || this.headerWritePromise) {
                 // Buffer NULL as EOF marker (no size contribution)
                 streamInfo.preMuxQueue.push(null);
+                streamInfo.preMuxArrivals.push(0);
                 return;
             }
             // PHASE 2: After muxer started - send EOF to SyncQueue and flush
@@ -809,7 +875,7 @@ export class Muxer {
                             throw new Error('Failed to clone packet from sync queue');
                         }
                         pkt.streamIndex = recvRet;
-                        await this.write(pkt, recvStreamInfo, recvRet);
+                        await this.write(pkt, recvStreamInfo, recvRet, recvStreamInfo.sqArrivals.shift() ?? 0);
                     }
                 }
             }
@@ -820,6 +886,10 @@ export class Muxer {
         if (!clonedPacket) {
             throw new Error('Failed to clone packet for writing');
         }
+        // The forward check compares DTS steps with the time between packets as
+        // they reach the muxer. Taken here and carried through the pre-mux, sync
+        // and write queues, so time a packet spends queued does not count.
+        const arrival = this.forwardThresholdMs > 0 ? this.clock() : 0;
         // Apply streamcopy filtering BEFORE buffering
         // This ensures rejected packets never enter the queue/buffer
         if (streamInfo.isStreamCopy) {
@@ -833,6 +903,9 @@ export class Muxer {
             // For encoded (non-streamcopy) streams, strip the device's startTime base.
             this.applyStartTimeOffset(clonedPacket, streamInfo);
         }
+        // Announced on acceptance, so the observer also counts what waits in the
+        // pre-mux queue for the header.
+        const observed = this.announcePacket(clonedPacket, streamIndex);
         // Check if any streams are still uninitialized or header is being written
         const uninitialized = Array.from(this._streams.values()).some((s) => !s.initialized);
         // PHASE 1: Before header write - ALWAYS buffer in PreMuxQueue
@@ -850,12 +923,16 @@ export class Muxer {
             // Check if we would exceed packet limit (only if threshold reached)
             if (currentPackets >= effectiveMaxPackets) {
                 clonedPacket.free(); // Free the clone since we can't buffer it
+                if (observed) {
+                    this.packetObserver?.onPacketRejected(streamIndex);
+                }
                 throw new Error(
                 // eslint-disable-next-line @stylistic/max-len
                 `Too many packets buffered for output stream ${streamIndex} (packets: ${currentPackets}, bytes: ${currentBytes}, threshold: ${dataThreshold}, max: ${maxPackets})`);
             }
             // Buffer in PreMuxQueue (per-stream FIFO)
             streamInfo.preMuxQueue.push(clonedPacket);
+            streamInfo.preMuxArrivals.push(arrival);
             streamInfo.preMuxQueueDataSize += packetSize;
             return; // Don't proceed to header write yet
         }
@@ -863,16 +940,20 @@ export class Muxer {
         if (!this.headerWritten) {
             this.headerWritePromise ??= (async () => {
                 this.startWriteWorker();
-                this.setupSyncQueues();
-                this.updateDefaultDisposition();
-                this.copyContainerMetadata();
-                this.options.configure?.(this.formatContext);
+                this.prepareHeaderWrite();
                 const ret = await this.formatContext.writeHeader();
                 FFmpegError.throwIfError(ret, 'Failed to write header');
                 this.headerWritten = true;
+                this.readHeaderSetup();
                 // PHASE 2: Flush PreMuxQueue in DTS-sorted order (once after header write)
                 // Packets go: PreMuxQueue → SyncQueue (if present) → Muxer
-                await this.flushPreMuxQueues();
+                // Concurrent writers keep queueing while headerWritePromise is set, also
+                // after a flush found the queues empty. Drain until they are empty and
+                // clear the promise in that same tick, or such packets are never written.
+                do {
+                    await this.flushPreMuxQueues();
+                } while (this.hasPreMuxPackets());
+                this.headerWritePromise = undefined;
             })();
             await this.headerWritePromise;
             if (this.headerWritten) {
@@ -888,6 +969,9 @@ export class Muxer {
             const ret = this.syncQueue.send(streamInfo.sqIdxMux, clonedPacket);
             // Handle errors from sq_send
             if (ret < 0) {
+                if (observed) {
+                    this.packetObserver?.onPacketRejected(streamIndex);
+                }
                 if (ret === AVERROR_EOF) {
                     // Stream finished - this is normal, just return
                     return;
@@ -897,6 +981,8 @@ export class Muxer {
                 }
                 return;
             }
+            // The sync queue keeps each stream's packets in order and drops none.
+            streamInfo.sqArrivals.push(arrival);
             // Receive synchronized packets from queue and write to muxer
             while (!this.isClosed) {
                 const recvRet = this.syncQueue.receive(-1, this.sqPacket);
@@ -917,14 +1003,14 @@ export class Muxer {
                     }
                     pkt.streamIndex = recvRet;
                     // Write packet (muxer takes ownership)
-                    await this.write(pkt, recvStreamInfo, recvRet);
+                    await this.write(pkt, recvStreamInfo, recvRet, recvStreamInfo.sqArrivals.shift() ?? 0);
                 }
             }
         }
         else {
             // No sync queue needed - write directly
             clonedPacket.streamIndex = streamIndex;
-            await this.write(clonedPacket, streamInfo, streamIndex);
+            await this.write(clonedPacket, streamInfo, streamIndex, arrival);
         }
     }
     /**
@@ -957,6 +1043,8 @@ export class Muxer {
      *
      * @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
@@ -1084,6 +1172,7 @@ export class Muxer {
             if (uninitialized || this.headerWritePromise) {
                 // Buffer NULL as EOF marker (no size contribution)
                 streamInfo.preMuxQueue.push(null);
+                streamInfo.preMuxArrivals.push(0);
                 return;
             }
             // PHASE 2: After muxer started - send EOF to SyncQueue and flush
@@ -1116,7 +1205,7 @@ export class Muxer {
                             throw new Error('Failed to clone packet from sync queue');
                         }
                         pkt.streamIndex = recvRet;
-                        this.writeSync(pkt, recvStreamInfo, recvRet);
+                        this.writeSync(pkt, recvStreamInfo, recvRet, recvStreamInfo.sqArrivals.shift() ?? 0);
                     }
                 }
             }
@@ -1127,6 +1216,7 @@ export class Muxer {
         if (!clonedPacket) {
             throw new Error('Failed to clone packet for writing');
         }
+        const arrival = this.forwardThresholdMs > 0 ? this.clock() : 0;
         // Apply streamcopy filtering BEFORE buffering
         // This ensures rejected packets never enter the queue/buffer
         if (streamInfo.isStreamCopy) {
@@ -1140,6 +1230,9 @@ export class Muxer {
             // For encoded (non-streamcopy) streams, strip the device's startTime base.
             this.applyStartTimeOffset(clonedPacket, streamInfo);
         }
+        // Announced on acceptance, so the observer also counts what waits in the
+        // pre-mux queue for the header.
+        const observed = this.announcePacket(clonedPacket, streamIndex);
         // Check if any streams are still uninitialized
         const uninitialized = Array.from(this._streams.values()).some((s) => !s.initialized);
         // PHASE 1: Before header write - ALWAYS buffer in PreMuxQueue
@@ -1157,25 +1250,26 @@ export class Muxer {
             // Check if we would exceed packet limit (only if threshold reached)
             if (currentPackets >= effectiveMaxPackets) {
                 clonedPacket.free(); // Free the clone since we can't buffer it
+                if (observed) {
+                    this.packetObserver?.onPacketRejected(streamIndex);
+                }
                 throw new Error(
                 // eslint-disable-next-line @stylistic/max-len
                 `Too many packets buffered for output stream ${streamIndex} (packets: ${currentPackets}, bytes: ${currentBytes}, threshold: ${dataThreshold}, max: ${maxPackets})`);
             }
             // Buffer in PreMuxQueue (per-stream FIFO)
             streamInfo.preMuxQueue.push(clonedPacket);
+            streamInfo.preMuxArrivals.push(arrival);
             streamInfo.preMuxQueueDataSize += packetSize;
             return; // Don't proceed to header write yet
         }
         // Automatically write header if not written yet
         if (!this.headerWritten) {
-            this.setupSyncQueues();
-            this.updateDefaultDisposition();
-            this.copyContainerMetadata();
-            applyContextOptions(this.formatContext, this.options.context);
-            this.options.configure?.(this.formatContext);
+            this.prepareHeaderWrite();
             const ret = this.formatContext.writeHeaderSync();
             FFmpegError.throwIfError(ret, 'Failed to write header');
             this.headerWritten = true;
+            this.readHeaderSetup();
             // PHASE 2: Flush PreMuxQueue in DTS-sorted order (once after header write)
             // Packets go: PreMuxQueue → SyncQueue (if present) → Muxer
             this.flushPreMuxQueuesSync();
@@ -1189,6 +1283,9 @@ export class Muxer {
             const ret = this.syncQueue.send(streamInfo.sqIdxMux, clonedPacket);
             // Handle errors from sq_send
             if (ret < 0) {
+                if (observed) {
+                    this.packetObserver?.onPacketRejected(streamIndex);
+                }
                 if (ret === AVERROR_EOF) {
                     // Stream finished - this is normal, just return
                     return;
@@ -1198,6 +1295,7 @@ export class Muxer {
                 }
                 return;
             }
+            streamInfo.sqArrivals.push(arrival);
             // Receive synchronized packets from queue and write to muxer
             while (!this.isClosed) {
                 const recvRet = this.syncQueue.receive(-1, this.sqPacket);
@@ -1218,14 +1316,14 @@ export class Muxer {
                     }
                     pkt.streamIndex = recvRet;
                     // Write packet (muxer takes ownership)
-                    this.writeSync(pkt, recvStreamInfo, recvRet);
+                    this.writeSync(pkt, recvStreamInfo, recvRet, recvStreamInfo.sqArrivals.shift() ?? 0);
                 }
             }
         }
         else {
             // No sync queue needed - write directly
             clonedPacket.streamIndex = streamIndex;
-            this.writeSync(clonedPacket, streamInfo, streamIndex);
+            this.writeSync(clonedPacket, streamInfo, streamIndex, arrival);
         }
     }
     /**
@@ -1246,6 +1344,8 @@ export class Muxer {
      * }
      * ```
      *
+     * @throws {Error} If a background write failed and was not yet observed by the caller (resources are still released; a second close() is a no-op)
+     *
      * @see {@link Symbol.asyncDispose} For automatic cleanup
      */
     async close() {
@@ -1253,10 +1353,34 @@ export class Muxer {
             return;
         }
         this.isClosed = true;
-        // Close write queue and wait for worker to finish
+        // Detached first, so the final flush can never fail on the observer.
+        this.packetObserver = undefined;
+        // A header write launched by a concurrent writePacket() must settle before
+        // teardown: nulling pb / freeing the format context under a running
+        // avformat_write_header() crashes on the worker thread. This happens when a
+        // pipeline is stopped mid-startup - the reader task rejects the shared
+        // completion while the writer task is still inside its first writePacket().
+        if (this.headerWritePromise) {
+            try {
+                await this.headerWritePromise;
+            }
+            catch {
+                // Ignore errors - teardown proceeds either way
+            }
+        }
+        // Close write queue and wait for worker to finish.
+        // The worker catches its own errors, but guard the await anyway so a
+        // failed worker can never abort cleanup - resources below must always
+        // be freed even after a write failure.
         if (this.writeQueue) {
             this.writeQueue.close();
-            await this.writeWorkerPromise;
+            try {
+                await this.writeWorkerPromise;
+            }
+            catch (error) {
+                this.writeWorkerError ??= error instanceof Error ? error : new Error(String(error));
+            }
+            this.writeQueue.clear(); // Free any job packet the worker never consumed
         }
         // Free PreMuxQueue packets
         for (const streamInfo of this._streams.values()) {
@@ -1265,6 +1389,7 @@ export class Muxer {
                 pkt?.free();
             }
             streamInfo.preMuxQueue = [];
+            streamInfo.preMuxArrivals = [];
         }
         // Free sync queue resources
         if (this.sqPacket) {
@@ -1277,7 +1402,7 @@ export class Muxer {
         }
         // Try to write trailer if header was written but trailer wasn't
         try {
-            if (this.headerWritten && !this.trailerWritten) {
+            if (this.headerWritten && !this.trailerWritten && !this.trailerDiscarded) {
                 await this.formatContext.writeTrailer();
                 this.trailerWritten = true;
             }
@@ -1289,11 +1414,11 @@ export class Muxer {
         if (this.ioContext) {
             this.formatContext.pb = null;
         }
-        // Determine if this is custom IO before freeing format context
-        const isCustomIO = this.formatContext.hasFlags(AVFMT_FLAG_CUSTOM_IO);
-        // For file-based IO, close the file handle via closep
+        // For file-based IO, close the file handle via closep - freeContext() alone
+        // would release the AVIOContext but leak the underlying protocol handle,
+        // leaving the file locked (EBUSY on Windows) until the process exits.
         // For custom IO, the context will be freed below
-        if (this.ioContext && !isCustomIO) {
+        if (this.ioContext && !this.customIO) {
             try {
                 await this.ioContext.closep();
             }
@@ -1311,7 +1436,7 @@ export class Muxer {
             }
         }
         // Now free custom IO context if present
-        if (this.ioContext && isCustomIO) {
+        if (this.ioContext && this.customIO) {
             try {
                 this.ioContext.freeContext();
             }
@@ -1319,6 +1444,11 @@ export class Muxer {
                 // Ignore errors
             }
         }
+        // Surface a background write failure the caller may not have observed yet.
+        // Thrown only after all resources are freed - a second close() is a no-op.
+        if (this.writeWorkerError) {
+            throw this.writeWorkerError;
+        }
     }
     /**
      * Close muxer and free resources synchronously.
@@ -1346,6 +1476,7 @@ export class Muxer {
             return;
         }
         this.isClosed = true;
+        this.packetObserver = undefined;
         // Free PreMuxQueue packets
         for (const streamInfo of this._streams.values()) {
             // Free any packets in PreMuxQueue
@@ -1353,6 +1484,7 @@ export class Muxer {
                 pkt?.free();
             }
             streamInfo.preMuxQueue = [];
+            streamInfo.preMuxArrivals = [];
         }
         // Free sync queue resources
         if (this.sqPacket) {
@@ -1365,7 +1497,7 @@ export class Muxer {
         }
         // Try to write trailer if header was written but trailer wasn't
         try {
-            if (this.headerWritten && !this.trailerWritten) {
+            if (this.headerWritten && !this.trailerWritten && !this.trailerDiscarded) {
                 this.formatContext.writeTrailerSync();
                 this.trailerWritten = true;
             }
@@ -1377,11 +1509,9 @@ export class Muxer {
         if (this.ioContext) {
             this.formatContext.pb = null;
         }
-        // Determine if this is custom IO before freeing format context
-        const isCustomIO = this.formatContext.hasFlags(AVFMT_FLAG_CUSTOM_IO);
         // For file-based IO, close the file handle via closep
         // For custom IO, the context will be freed below
-        if (this.ioContext && !isCustomIO) {
+        if (this.ioContext && !this.customIO) {
             try {
                 this.ioContext.closepSync();
             }
@@ -1399,7 +1529,7 @@ export class Muxer {
             }
         }
         // Now free custom IO context if present
-        if (this.ioContext && isCustomIO) {
+        if (this.ioContext && this.customIO) {
             try {
                 this.ioContext.freeContext();
             }
@@ -1420,6 +1550,109 @@ export class Muxer {
     getFormatContext() {
         return this.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) {
+        this.packetObserver = observer;
+    }
+    /**
+     * 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) {
+        this.clock = clock;
+    }
+    /**
+     * 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() {
+        this.trailerDiscarded = true;
+    }
+    /**
+     * 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
+     */
+    announcePacket(pkt, streamIndex) {
+        // movenc drops packets without payload instead of storing a sample.
+        if (this.packetObserver === undefined || pkt.size <= 0) {
+            return false;
+        }
+        try {
+            this.packetObserver.onPacket(streamIndex);
+        }
+        catch (error) {
+            pkt.free();
+            throw error;
+        }
+        return true;
+    }
+    /**
+     * Apply shared pre-header setup for writePacket and writePacketSync.
+     *
+     * Configures sync queues, dispositions and container metadata, then applies
+     * user-provided context options and the configure callback. Must run
+     * immediately before writing the header so both variants stay in sync.
+     *
+     * @internal
+     */
+    prepareHeaderWrite() {
+        this.setupSyncQueues();
+        this.updateDefaultDisposition();
+        this.copyContainerMetadata();
+        applyContextOptions(this.formatContext, this.options.context);
+        this.options.configure?.(this.formatContext);
+        const oformat = this.formatContext.oformat;
+        this.movSampleLimit = MOV_FAMILY_FORMATS.has(oformat?.name ?? '');
+        this.tsNonStrict = oformat?.hasFlags(AVFMT_TS_NONSTRICT) ?? false;
+    }
+    /**
+     * 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
+     */
+    readHeaderSetup() {
+        if (!this.movSampleLimit) {
+            return;
+        }
+        const ctx = this.formatContext;
+        this.movZeroStart = ctx.getOption('use_editlist', AV_OPT_TYPE_BOOL) === false && ctx.getOption('avoid_negative_ts', AV_OPT_TYPE_INT) === AVFMT_AVOID_NEG_TS_MAKE_ZERO;
+        this.interleaveDeltaUs = ctx.maxInterleaveDelta;
+    }
     /**
      * Setup sync queues based on stream configuration.
      *
@@ -1464,6 +1697,21 @@ export class Muxer {
             }
         }
     }
+    /**
+     * 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
+     */
+    hasPreMuxPackets() {
+        for (const streamInfo of this._streams.values()) {
+            if (streamInfo.preMuxQueue.length > 0) {
+                return true;
+            }
+        }
+        return false;
+    }
     /**
      * Flush all PreMuxQueues in DTS-sorted order.
      *
@@ -1509,6 +1757,7 @@ export class Muxer {
             }
             // 3. Take packet from stream with earliest DTS (or NULL for EOF)
             const pkt = minStreamInfo.preMuxQueue.shift();
+            const arrival = minStreamInfo.preMuxArrivals.shift() ?? 0;
             // 4. Handle NULL packet (EOF marker)
             // FFmpeg: if (pkt) { send packet } else { tq_send_finish() }
             if (!pkt) {
@@ -1533,8 +1782,15 @@ export class Muxer {
                 // NOTE: Do NOT set pkt.timeBase here!
                 // Packet must keep its source timebase so muxFixupTs can rescale correctly
                 // pkt.timeBase = minStreamInfo.stream.timeBase;  // ❌ WRONG!
+                const size = pkt.size;
                 const ret = this.syncQueue.send(minStreamInfo.sqIdxMux, pkt);
-                if (ret < 0 && ret !== AVERROR_EOF) {
+                if (ret < 0 && size > 0) {
+                    this.packetObserver?.onPacketRejected(minStreamIndex);
+                }
+                if (ret >= 0) {
+                    minStreamInfo.sqArrivals.push(arrival);
+                }
+                else if (ret !== AVERROR_EOF) {
                     if (this.options.exitOnError) {
                         FFmpegError.throwIfError(ret, 'Failed to send packet to sync queue during PreMuxQueue flush');
                     }
@@ -1542,7 +1798,7 @@ export class Muxer {
             }
             else {
                 // Write directly to muxer
-                await this.write(pkt, minStreamInfo, minStreamIndex);
+                await this.write(pkt, minStreamInfo, minStreamIndex, arrival);
             }
         }
         // If using SyncQueue, receive and write all interleaved packets
@@ -1565,7 +1821,7 @@ export class Muxer {
                     }
                     pkt.streamIndex = recvRet;
                     // Write packet (muxer takes ownership)
-                    await this.write(pkt, recvStreamInfo, recvRet);
+                    await this.write(pkt, recvStreamInfo, recvRet, recvStreamInfo.sqArrivals.shift() ?? 0);
                 }
             }
         }
@@ -1613,6 +1869,7 @@ export class Muxer {
                 break;
             // 3. Take packet from stream with earliest DTS (or NULL for EOF)
             const pkt = minStreamInfo.preMuxQueue.shift();
+            const arrival = minStreamInfo.preMuxArrivals.shift() ?? 0;
             // 4. Handle NULL packet (EOF marker)
             // FFmpeg: if (pkt) { send packet } else { tq_send_finish() }
             if (!pkt) {
@@ -1637,8 +1894,15 @@ export class Muxer {
                 // NOTE: Do NOT set pkt.timeBase here!
                 // Packet must keep its source timebase so muxFixupTs can rescale correctly
                 // pkt.timeBase = minStreamInfo.stream.timeBase;  // ❌ WRONG!
+                const size = pkt.size;
                 const ret = this.syncQueue.send(minStreamInfo.sqIdxMux, pkt);
-                if (ret < 0 && ret !== AVERROR_EOF) {
+                if (ret < 0 && size > 0) {
+                    this.packetObserver?.onPacketRejected(minStreamIndex);
+                }
+                if (ret >= 0) {
+                    minStreamInfo.sqArrivals.push(arrival);
+                }
+                else if (ret !== AVERROR_EOF) {
                     if (this.options.exitOnError) {
                         FFmpegError.throwIfError(ret, 'Failed to send packet to sync queue during PreMuxQueue flush');
                     }
@@ -1646,7 +1910,7 @@ export class Muxer {
             }
             else {
                 // Write directly to muxer
-                this.writeSync(pkt, minStreamInfo, minStreamIndex);
+                this.writeSync(pkt, minStreamInfo, minStreamIndex, arrival);
             }
         }
         // If using SyncQueue, receive and write all interleaved packets
@@ -1669,7 +1933,7 @@ export class Muxer {
                     }
                     pkt.streamIndex = recvRet;
                     // Write packet (muxer takes ownership)
-                    this.writeSync(pkt, recvStreamInfo, recvRet);
+                    this.writeSync(pkt, recvStreamInfo, recvRet, recvStreamInfo.sqArrivals.shift() ?? 0);
                 }
             }
         }
@@ -1683,16 +1947,26 @@ export class Muxer {
      *
      * @param streamIndex - Stream index
      *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
      * @internal
      */
-    async write(pkt, streamInfo, streamIndex) {
+    async write(pkt, streamInfo, streamIndex, arrival) {
         if (this.writeQueue) {
-            // Use async queue for serialized writes
-            await this.writeQueue.send({ pkt, streamInfo, streamIndex });
+            // Use async queue for serialized writes.
+            // If the worker died with a write error, the queue is poisoned and send()
+            // rethrows that error - free the clone since it never reaches the worker.
+            try {
+                await this.writeQueue.send({ pkt, streamInfo, streamIndex, arrival });
+            }
+            catch (error) {
+                pkt.free();
+                throw error;
+            }
         }
         else {
             // Direct write without serialization
-            await this.writeInternal(pkt, streamInfo, streamIndex);
+            await this.writeInternal(pkt, streamInfo, streamIndex, arrival);
         }
     }
     /**
@@ -1705,20 +1979,37 @@ export class Muxer {
      *
      * @param streamIndex - Stream index
      *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
      * @internal
      */
-    async writeInternal(pkt, streamInfo, streamIndex) {
-        // Fix timestamps (rescale, DTS>PTS fix, monotonic DTS enforcement)
-        this.muxFixupTs(pkt, streamInfo, streamIndex);
-        // Write the packet (muxer takes ownership and will unref it)
-        // NOTE: Caller must clone packet if they need to keep it (e.g., for SyncQueue)
-        const ret = await this.formatContext.interleavedWriteFrame(pkt);
-        // Handle write errors
-        if (ret < 0 && ret !== AVERROR_EOF) {
-            if (this.options.exitOnError) {
-                FFmpegError.throwIfError(ret, 'Failed to write packet');
+    async writeInternal(pkt, streamInfo, streamIndex, arrival) {
+        // Read before the write moves the payload out (see announcePacket()).
+        const observed = this.packetObserver !== undefined && pkt.size > 0;
+        let accepted = false;
+        try {
+            // Fix timestamps (rescale, DTS>PTS fix, monotonic DTS enforcement)
+            this.muxFixupTs(pkt, streamInfo, streamIndex, arrival);
+            // Write the packet (muxer takes ownership and will unref it)
+            // NOTE: Caller must clone packet if they need to keep it (e.g., for SyncQueue)
+            const ret = await this.formatContext.interleavedWriteFrame(pkt);
+            accepted = ret >= 0;
+            // Handle write errors
+            if (ret < 0 && ret !== AVERROR_EOF) {
+                if (this.options.exitOnError) {
+                    FFmpegError.throwIfError(ret, 'Failed to write packet');
+                }
             }
         }
+        finally {
+            if (observed && !accepted) {
+                this.packetObserver?.onPacketRejected(streamIndex);
+            }
+            // Every packet reaching here is a clone this class made, and the write
+            // has consumed its contents. Release the struct now instead of leaving a
+            // GC-sized backlog of them behind - this is the last owner.
+            pkt.free();
+        }
     }
     /**
      * Start background worker for async write queue.
@@ -1730,13 +2021,25 @@ export class Muxer {
         if (!this.options.useAsyncWrite || this._streams.size <= 1) {
             return;
         }
-        this.writeQueue ??= new AsyncQueue(1); // size=1 for strict serialization
+        this.writeQueue ??= new AsyncQueue(1, (job) => job.pkt.free()); // size=1 for strict serialization
         this.writeWorkerPromise ??= (async () => {
-            while (true) {
-                const job = await this.writeQueue.receive();
-                if (!job)
-                    break; // Queue closed
-                await this.writeInternal(job.pkt, job.streamInfo, job.streamIndex);
+            try {
+                while (true) {
+                    const job = await this.writeQueue.receive();
+                    if (!job)
+                        break; // Queue closed
+                    await this.writeInternal(job.pkt, job.streamInfo, job.streamIndex, job.arrival);
+                }
+            }
+            catch (error) {
+                // A write failure kills the worker. Without propagation the next send()
+                // would block forever on a queue nobody drains (pipeline deadlock), so
+                // store the error and poison the queue: pending and future send() calls
+                // throw it instead of hanging. close() surfaces it after cleanup.
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.writeWorkerError = err;
+                this.writeQueue?.closeWithError(err);
+                this.writeQueue?.clear(); // Free any job packet still buffered
             }
         })();
     }
@@ -1750,15 +2053,29 @@ export class Muxer {
      *
      * @param streamIndex - Stream index
      *
+     * @param arrival - When the packet reached the muxer (ms on the arrival clock)
+     *
      * @internal
      */
-    writeSync(pkt, streamInfo, streamIndex) {
-        // Fix timestamps (rescale, DTS>PTS fix, monotonic DTS enforcement)
-        this.muxFixupTs(pkt, streamInfo, streamIndex);
-        // Write the packet (muxer takes ownership and will unref it)
-        // NOTE: Caller must clone packet if they need to keep it (e.g., for SyncQueue)
-        const ret = this.formatContext.interleavedWriteFrameSync(pkt);
-        FFmpegError.throwIfError(ret, 'Failed to write packet');
+    writeSync(pkt, streamInfo, streamIndex, arrival) {
+        const observed = this.packetObserver !== undefined && pkt.size > 0;
+        let accepted = false;
+        try {
+            // Fix timestamps (rescale, DTS>PTS fix, monotonic DTS enforcement)
+            this.muxFixupTs(pkt, streamInfo, streamIndex, arrival);
+            // Write the packet (muxer takes ownership and will unref it)
+            // NOTE: Caller must clone packet if they need to keep it (e.g., for SyncQueue)
+            const ret = this.formatContext.interleavedWriteFrameSync(pkt);
+            accepted = ret >= 0;
+            FFmpegError.throwIfError(ret, 'Failed to write packet');
+        }
+        finally {
+            if (observed && !accepted) {
+                this.packetObserver?.onPacketRejected(streamIndex);
+            }
+            // See writeInternal(): this is the last owner of the clone.
+            pkt.free();
+        }
     }
     /**
      * Streamcopy packet filtering and timestamp offset.
@@ -1786,11 +2103,12 @@ export class Muxer {
      * 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.
      *
@@ -1884,8 +2202,14 @@ export class Muxer {
      * 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
      *
@@ -1893,69 +2217,332 @@ export class Muxer {
      *
      * @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
      */
-    muxFixupTs(pkt, streamInfo, streamIndex) {
-        const outputStream = this.formatContext.streams[streamIndex];
-        if (!outputStream)
-            return;
-        const codecType = streamInfo.outputStream.codecpar.codecType;
-        const dstTb = outputStream.timeBase;
-        // const srcTb = streamInfo.sourceTimeBase!;
+    muxFixupTs(pkt, streamInfo, streamIndex, arrival) {
+        const outputStream = streamInfo.outputStream;
+        // Both are final once the header is written, which happens before the
+        // first packet gets here.
+        const dstTb = (streamInfo.muxTimeBase ??= outputStream.timeBase);
+        const codecType = (streamInfo.muxCodecType ??= outputStream.codecpar.codecType);
+        const lastMuxDts = streamInfo.lastMuxDts;
+        // Every timestamp getter is a native call returning a new BigInt, so each
+        // value is read once, corrected in locals, and only changes are written back.
+        let dts = pkt.dts;
+        let pts = pkt.pts;
         // Check if timestamps are valid before rescaling
         // FFmpeg's av_rescale_q/av_rescale_delta don't accept AV_NOPTS_VALUE
-        if (pkt.dts === AV_NOPTS_VALUE && pkt.pts === AV_NOPTS_VALUE) {
+        if (dts === AV_NOPTS_VALUE && pts === AV_NOPTS_VALUE) {
             // Set packet timebase anyway for muxer
             pkt.timeBase = dstTb;
             return;
         }
         // 1. Rescale timestamps to the stream timebase
+        const srcTb = streamInfo.sourceTimeBase;
         if (codecType === AVMEDIA_TYPE_AUDIO && streamInfo.isStreamCopy) {
-            let duration = avGetAudioFrameDuration2(streamInfo.outputStream.codecpar, pkt.size);
+            const codecpar = outputStream.codecpar;
+            let duration = avGetAudioFrameDuration2(codecpar, pkt.size);
             if (!duration) {
-                duration = streamInfo.outputStream.codecpar.frameSize;
+                duration = codecpar.frameSize;
             }
-            const srcTb = streamInfo.sourceTimeBase;
-            const sampleRate = streamInfo.outputStream.codecpar.sampleRate;
-            const fsTb = { num: 1, den: sampleRate };
-            pkt.dts = avRescaleDelta(srcTb, pkt.dts, fsTb, duration, streamInfo.tsRescaleDeltaLast, dstTb);
-            pkt.pts = pkt.dts;
+            const fsTb = { num: 1, den: codecpar.sampleRate };
+            dts = avRescaleDelta(srcTb, dts, fsTb, duration, streamInfo.tsRescaleDeltaLast, dstTb);
+            pts = dts;
+            pkt.dts = dts;
+            pkt.pts = pts;
             pkt.duration = avRescaleQ(pkt.duration, srcTb, dstTb);
         }
         else {
             // For video or encoded audio, use regular rescaling
-            const srcTb = streamInfo.sourceTimeBase;
             pkt.rescaleTs(srcTb, dstTb);
+            dts = pkt.dts;
+            pts = pkt.pts;
         }
         // 2. Set packet timeBase
         // av_interleaved_write_frame uses this for sorting!
         pkt.timeBase = dstTb;
-        // 3. Fix DTS > PTS (invalid relationship)
+        const isAudioVideo = codecType === AVMEDIA_TYPE_AUDIO || codecType === AVMEDIA_TYPE_VIDEO;
+        // 3. Reject a large backward jump while it is still visible - the corrections
+        // below would turn it into a run of one-tick steps
+        if (isAudioVideo) {
+            this.checkBackwardDts(dts, lastMuxDts, dstTb, streamIndex);
+        }
+        // 4. Fix DTS > PTS (invalid relationship)
         // FFmpeg formula: median of (pts, dts, last_mux_dts+1)
-        if (pkt.dts !== AV_NOPTS_VALUE && pkt.pts !== AV_NOPTS_VALUE && pkt.dts > pkt.pts) {
-            const last = streamInfo.lastMuxDts !== AV_NOPTS_VALUE ? streamInfo.lastMuxDts + 1n : 0n;
-            const min = pkt.pts < pkt.dts ? (pkt.pts < last ? pkt.pts : last) : pkt.dts < last ? pkt.dts : last;
-            const max = pkt.pts > pkt.dts ? (pkt.pts > last ? pkt.pts : last) : pkt.dts > last ? pkt.dts : last;
-            const median = pkt.pts + pkt.dts + last - min - max;
+        if (dts !== AV_NOPTS_VALUE && pts !== AV_NOPTS_VALUE && dts > pts) {
+            const last = lastMuxDts !== AV_NOPTS_VALUE ? lastMuxDts + 1n : 0n;
+            const min = pts < dts ? (pts < last ? pts : last) : dts < last ? dts : last;
+            const max = pts > dts ? (pts > last ? pts : last) : dts > last ? dts : last;
+            const median = pts + dts + last - min - max;
+            pts = median;
+            dts = median;
             pkt.pts = median;
             pkt.dts = median;
         }
-        // 4. Enforce monotonic DTS
-        if ((codecType === AVMEDIA_TYPE_AUDIO || codecType === AVMEDIA_TYPE_VIDEO) && pkt.dts !== AV_NOPTS_VALUE && streamInfo.lastMuxDts !== AV_NOPTS_VALUE) {
+        // 5. Enforce monotonic DTS
+        let clampedDuration;
+        if (isAudioVideo && dts !== AV_NOPTS_VALUE && lastMuxDts !== AV_NOPTS_VALUE) {
             // FFmpeg: max = last_mux_dts + !(oformat->flags & AVFMT_TS_NONSTRICT)
             // AVFMT_TS_NONSTRICT allows non-strict monotonic timestamps (equal DTS is OK)
-            const tsNonStrict = this.formatContext.oformat?.hasFlags(AVFMT_TS_NONSTRICT) ?? false;
-            const max = streamInfo.lastMuxDts + (tsNonStrict ? 0n : 1n);
-            if (pkt.dts < max) {
+            const max = lastMuxDts + (this.tsNonStrict ? 0n : 1n);
+            if (dts < max) {
                 // Adjust PTS if it would create invalid relationship
-                if (pkt.pts !== AV_NOPTS_VALUE && pkt.pts >= pkt.dts) {
-                    pkt.pts = pkt.pts > max ? pkt.pts : max;
+                if (pts !== AV_NOPTS_VALUE && pts >= dts && pts < max) {
+                    pts = max;
+                    pkt.pts = max;
                 }
+                dts = max;
                 pkt.dts = max;
+                // The clamped packet must not keep its source duration: after a fragment
+                // flush movenc continues the track at the previous DTS plus its duration,
+                // which then lies ahead of the clamped timeline. movenc corrects that by
+                // moving later DTS itself and can end with a negative sample duration
+                // (av_assert0 in get_cluster_duration). A duration of 0 does not help -
+                // mux.c guesses a new one - so use the clamped step.
+                if (max > lastMuxDts) {
+                    clampedDuration = max - lastMuxDts;
+                    pkt.duration = clampedDuration;
+                }
+            }
+        }
+        // mux.c derives a missing DTS from the PTS and never above it (its PTS-0
+        // fallback aside, which only steps one frame), so the PTS stands in for the
+        // DTS of such a packet in the checks below.
+        const ts = dts !== AV_NOPTS_VALUE ? dts : pts;
+        // 6. Reject a forward jump on the DTS libavformat would see, before the
+        // packet enters it: once in, movenc takes the jump as the duration of the
+        // stream's previous sample.
+        let forwardOffset = NaN;
+        if (isAudioVideo && this.forwardThresholdMs > 0) {
+            forwardOffset = this.checkForwardDts(ts, arrival, streamInfo, streamIndex);
+        }
+        // 7. Reject what movenc cannot store before it reaches its abort
+        if (this.movSampleLimit) {
+            const duration = clampedDuration ?? pkt.duration;
+            this.checkMovSampleDuration(ts, duration, lastMuxDts, dstTb, streamIndex);
+            if (this.movZeroStart && streamInfo.firstMuxTs === undefined) {
+                this.checkMovLateStart(ts, duration, dstTb, streamIndex);
+            }
+        }
+        // 8. Update last mux DTS for next packet. mux.c fills a missing DTS itself
+        // and rejects it unless it lies past the previous one, so the last known
+        // DTS stays a valid reference: the clamp and the guards remain armed for
+        // the next packet instead of letting it through unchecked.
+        if (dts !== AV_NOPTS_VALUE) {
+            streamInfo.lastMuxDts = dts;
+        }
+        streamInfo.firstMuxTs ??= ts;
+        if (streamInfo.forward && !Number.isNaN(forwardOffset)) {
+            this.recordForwardDts(streamInfo.forward, ts, forwardOffset, arrival);
+        }
+    }
+    /**
+     * 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
+     */
+    checkBackwardDts(dts, lastMuxDts, timeBase, streamIndex) {
+        const threshold = this.options.dtsBackwardThreshold;
+        if (!threshold || dts === AV_NOPTS_VALUE || lastMuxDts === AV_NOPTS_VALUE || dts >= lastMuxDts) {
+            return;
+        }
+        const regression = lastMuxDts - dts;
+        const thresholdUs = BigInt(Math.round(threshold * 1_000_000));
+        if (avCompareTs(regression, timeBase, thresholdUs, AV_TIME_BASE_Q) <= 0) {
+            return;
+        }
+        const seconds = ((Number(regression) * timeBase.num) / timeBase.den).toFixed(3);
+        throw new Error(`Timestamp discontinuity on output stream ${streamIndex}: DTS jumped back ${seconds}s, more than dtsBackwardThreshold (${threshold}s)`);
+    }
+    /**
+     * 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
+     */
+    checkForwardDts(ts, arrival, streamInfo, streamIndex) {
+        const tb = streamInfo.muxTimeBase;
+        const state = (streamInfo.forward ??= {
+            msPerTick: (1000 * tb.num) / tb.den,
+            lastTs: AV_NOPTS_VALUE,
+            lastArrival: NaN,
+            offset: 0,
+            windowMin: Infinity,
+            windowPrevMin: Infinity,
+            windowCount: 0,
+        });
+        if (Number.isNaN(state.lastArrival)) {
+            return 0;
+        }
+        const stepMs = Number(ts - state.lastTs) * state.msPerTick;
+        const elapsedMs = arrival - state.lastArrival;
+        const offset = state.offset + elapsedMs - stepMs;
+        const reference = state.windowMin < state.windowPrevMin ? state.windowMin : state.windowPrevMin;
+        if (reference - offset <= this.forwardThresholdMs) {
+            return offset;
+        }
+        const jump = `DTS jumped forward ${(stepMs / 1000).toFixed(3)}s while ${(elapsedMs / 1000).toFixed(3)}s passed`;
+        throw new Error(`Timestamp discontinuity on output stream ${streamIndex}: ${jump}, more than dtsForwardThreshold (${this.options.dtsForwardThreshold}s)`);
+    }
+    /**
+     * 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
+     */
+    recordForwardDts(state, ts, offset, arrival) {
+        state.lastTs = ts;
+        state.offset = offset;
+        state.lastArrival = arrival;
+        if (offset < state.windowMin) {
+            state.windowMin = offset;
+        }
+        // Two buckets keep the window between one and two buckets long in O(1).
+        if (++state.windowCount >= FORWARD_WINDOW_BUCKET) {
+            state.windowPrevMin = state.windowMin;
+            state.windowMin = Infinity;
+            state.windowCount = 0;
+        }
+    }
+    /**
+     * 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
+     */
+    checkMovSampleDuration(dts, duration, lastMuxDts, timeBase, streamIndex) {
+        const step = dts !== AV_NOPTS_VALUE && lastMuxDts !== AV_NOPTS_VALUE ? dts - lastMuxDts : 0n;
+        const ticks = step >= MOV_SAMPLE_DURATION_LIMIT ? step : duration >= MOV_SAMPLE_DURATION_LIMIT ? duration : undefined;
+        if (ticks === undefined) {
+            return;
+        }
+        const what = ticks === step ? 'DTS jumped forward' : 'packet duration is';
+        const seconds = ((Number(ticks) * timeBase.num) / timeBase.den).toFixed(3);
+        const format = this.formatContext.oformat?.name ?? 'mov';
+        const detail = `${what} ${ticks} ticks (${seconds}s at time base ${timeBase.num}/${timeBase.den})`;
+        throw new Error(`Timestamp discontinuity on output stream ${streamIndex}: ${detail}, but ${format} sample durations must stay below ${MOV_SAMPLE_DURATION_LIMIT} ticks`);
+    }
+    /**
+     * 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
+     */
+    checkMovLateStart(ts, duration, timeBase, streamIndex) {
+        if (this.interleaveDeltaUs <= 0n) {
+            return;
+        }
+        // The other streams' earliest and latest timestamp so far, in µs
+        let start;
+        let startUs = 0n;
+        let latestUs = 0n;
+        for (const [index, other] of this._streams) {
+            const first = other.firstMuxTs;
+            const otherTb = other.muxTimeBase;
+            if (first === undefined || !otherTb) {
+                continue;
+            }
+            const firstUs = avRescaleQ(first, otherTb, AV_TIME_BASE_Q);
+            const lastUs = other.lastMuxDts !== AV_NOPTS_VALUE ? avRescaleQ(other.lastMuxDts, otherTb, AV_TIME_BASE_Q) : firstUs;
+            if (!start) {
+                latestUs = lastUs;
             }
+            else if (lastUs > latestUs) {
+                latestUs = lastUs;
+            }
+            if (!start || firstUs < startUs) {
+                start = { ts: first, timeBase: otherTb, index };
+                startUs = firstUs;
+            }
+        }
+        // Until its queue spans max_interleave_delta, libavformat has written nothing
+        // and will start the output at this packet if it is the lowest.
+        if (!start || latestUs - startUs <= this.interleaveDeltaUs) {
+            return;
+        }
+        const end = ts + (duration > 0n ? duration : 0n);
+        if (avCompareTs(end, timeBase, start.ts, start.timeBase) >= 0) {
+            return;
         }
-        // 5. Update last mux DTS for next packet
-        streamInfo.lastMuxDts = pkt.dts;
+        const seconds = (Number(startUs - avRescaleQ(end, timeBase, AV_TIME_BASE_Q)) / 1_000_000).toFixed(3);
+        const format = this.formatContext.oformat?.name ?? 'mov';
+        const detail = `its first packet ends ${seconds}s before the start of output stream ${start.index}`;
+        throw new Error(`Timestamp discontinuity on output stream ${streamIndex}: ${detail}, which ${format} without an edit list cannot store`);
     }
     /**
      * Copy container metadata from input to output.