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

package/dist/api/demuxer.js

@@ -55,7 +55,7 @@ import { closeSync, openSync, readSync } from 'fs';
 import { open } from 'fs/promises';
 import { Readable } from 'node:stream';
 import { resolve } from 'path';
-import { AV_NOPTS_VALUE, AV_PIX_FMT_NONE, AV_ROUND_NEAR_INF, AV_ROUND_PASS_MINMAX, AV_TIME_BASE, AV_TIME_BASE_Q, AVFLAG_NONE, AVFMT_FLAG_CUSTOM_IO, AVFMT_FLAG_NONBLOCK, AVFMT_TS_DISCONT, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, AVSEEK_CUR, AVSEEK_END, AVSEEK_SET, } from '../constants/constants.js';
+import { AV_NOPTS_VALUE, AV_PIX_FMT_NONE, AV_ROUND_NEAR_INF, AV_ROUND_PASS_MINMAX, AV_TIME_BASE, AV_TIME_BASE_Q, AVERROR_EOF, AVERROR_EXIT, AVFLAG_NONE, AVFMT_FLAG_CUSTOM_IO, AVFMT_FLAG_NONBLOCK, AVFMT_TS_DISCONT, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, AVSEEK_CUR, AVSEEK_END, AVSEEK_SET, } from '../constants/constants.js';
 import { Dictionary } from '../lib/dictionary.js';
 import { AVERROR_EAGAIN, FFmpegError } from '../lib/error.js';
 import { FormatContext } from '../lib/format-context.js';
@@ -67,6 +67,9 @@ import { avGetPixFmtName, avGetSampleFmtName, avRescaleQ, avRescaleQRnd, dtsPred
 import { DELTA_THRESHOLD, DTS_ERROR_THRESHOLD, IO_BUFFER_SIZE, MAX_INPUT_QUEUE_SIZE } from './constants.js';
 import { IOStream } from './io-stream.js';
 import { StreamingUtils } from './utilities/streaming.js';
+// Scratch buffer for Atomics.wait() - gives packetsSync a blocking sleep for
+// EAGAIN retries (mirrors FFmpeg CLI's av_usleep()) without spinning the CPU.
+const SYNC_SLEEP_SIGNAL = new Int32Array(new SharedArrayBuffer(4));
 /**
  * High-level demuxer for reading and demuxing media files.
  *
@@ -110,6 +113,7 @@ export class Demuxer {
     formatContext;
     _streams = [];
     ioContext;
+    externalIO = false; // ioContext was supplied by the caller - may own a protocol handle from open2()
     isClosed = false;
     options;
     // Timestamp processing state (per-stream)
@@ -122,9 +126,11 @@ export class Demuxer {
     demuxThread = null;
     packetQueues = new Map(); // streamIndex or 'all' -> queue
     packetQueueConsumers = new Map(); // active consumer count per queue key
-    queueResolvers = new Map(); // Promise resolvers for waiting consumers
+    queueResolvers = new Map(); // Promise resolvers for waiting consumers (multiple per key)
+    drainResolver = null; // Promise resolver for the demux thread parked on a full queue
     demuxThreadActive = false;
     demuxEof = false;
+    lastError = null; // read error that ended the demux loop (null = clean EOF)
     signal;
     signalCleanup;
     /**
@@ -134,11 +140,14 @@ export class Demuxer {
      *
      * @param ioContext - Optional IO context for custom I/O (e.g., from Buffer)
      *
+     * @param externalIO - Whether ioContext was supplied by the caller instead of built here
+     *
      * @internal
      */
-    constructor(formatContext, options, ioContext) {
+    constructor(formatContext, options, ioContext, externalIO = false) {
         this.formatContext = formatContext;
         this.ioContext = ioContext;
+        this.externalIO = externalIO;
         this._streams = formatContext.streams ?? [];
         this.options = options;
     }
@@ -339,8 +348,17 @@ export class Demuxer {
         // Original implementation for non-raw data
         const formatContext = new FormatContext();
         let ioContext;
+        let externalIO = false; // caller-supplied context - released via dispose, not freeContext
         let optionsDict = null;
         let inputFormat = null;
+        // Abort during the open phase: avformat_open_input()/find_stream_info()
+        // block for seconds on an unresponsive network source, so the signal must
+        // fire the native interrupt callback to unblock them.
+        const onOpenAbort = () => formatContext.interrupt();
+        if (options.signal) {
+            options.signal.throwIfAborted();
+            options.signal.addEventListener('abort', onOpenAbort, { once: true });
+        }
         try {
             // Create options dictionary if options are provided
             if (options.options) {
@@ -381,6 +399,7 @@ export class Demuxer {
                 }
                 formatContext.allocContext();
                 ioContext = input;
+                externalIO = true;
                 formatContext.pb = ioContext;
                 formatContext.setFlags(AVFMT_FLAG_CUSTOM_IO);
                 const ret = await formatContext.openInput('', inputFormat, optionsDict);
@@ -454,20 +473,43 @@ export class Demuxer {
                 copyTs: options.copyTs ?? false,
                 options: options.options ?? {},
             };
-            const demuxer = new Demuxer(formatContext, fullOptions, ioContext);
+            const demuxer = new Demuxer(formatContext, fullOptions, ioContext, externalIO);
             if (options.signal) {
-                options.signal.throwIfAborted();
-                demuxer.signal = options.signal;
+                const signal = options.signal;
+                signal.removeEventListener('abort', onOpenAbort);
+                demuxer.signal = signal;
+                // An abort that raced the successful open must not hand out a usable
+                // demuxer - tear it down and surface the abort instead.
+                if (signal.aborted) {
+                    await demuxer.close();
+                    signal.throwIfAborted();
+                }
+                // Keep abort -> interrupt wired for the demuxer's lifetime so a
+                // blocked av_read_frame() unwinds too; close() removes the listener.
+                const onAbort = () => {
+                    demuxer.demuxThreadActive = false;
+                    demuxer.interrupt();
+                };
+                signal.addEventListener('abort', onAbort, { once: true });
+                demuxer.signalCleanup = () => signal.removeEventListener('abort', onAbort);
             }
             return demuxer;
         }
         catch (error) {
+            options.signal?.removeEventListener('abort', onOpenAbort);
             // Clean up only on error
             if (ioContext) {
                 // Clear the pb reference first
                 formatContext.pb = null;
-                // Free the IOContext (for both custom I/O and buffer-based I/O)
-                ioContext.freeContext();
+                // Release the IOContext (for both custom I/O and buffer-based I/O).
+                // A caller-supplied context may own a protocol handle from open2(),
+                // which only dispose closes - see close().
+                if (externalIO) {
+                    await ioContext[Symbol.asyncDispose]();
+                }
+                else {
+                    ioContext.freeContext();
+                }
             }
             // Clean up FormatContext
             await formatContext.closeInput();
@@ -513,6 +555,7 @@ export class Demuxer {
         // Original implementation for non-raw data
         const formatContext = new FormatContext();
         let ioContext;
+        let externalIO = false; // caller-supplied context - released via dispose, not freeContext
         let optionsDict = null;
         let inputFormat = null;
         try {
@@ -555,6 +598,7 @@ export class Demuxer {
                 }
                 formatContext.allocContext();
                 ioContext = input;
+                externalIO = true;
                 formatContext.pb = ioContext;
                 formatContext.setFlags(AVFMT_FLAG_CUSTOM_IO);
                 const ret = formatContext.openInputSync('', inputFormat, optionsDict);
@@ -616,7 +660,7 @@ export class Demuxer {
                 copyTs: options.copyTs ?? false,
                 options: options.options ?? {},
             };
-            const demuxer = new Demuxer(formatContext, fullOptions, ioContext);
+            const demuxer = new Demuxer(formatContext, fullOptions, ioContext, externalIO);
             if (options.signal) {
                 options.signal.throwIfAborted();
                 demuxer.signal = options.signal;
@@ -628,8 +672,13 @@ export class Demuxer {
             if (ioContext) {
                 // Clear the pb reference first
                 formatContext.pb = null;
-                // Free the IOContext (for both custom I/O and buffer-based I/O)
-                ioContext.freeContext();
+                // Release the IOContext (see open() for why dispose)
+                if (externalIO) {
+                    ioContext[Symbol.dispose]();
+                }
+                else {
+                    ioContext.freeContext();
+                }
             }
             // Clean up FormatContext
             formatContext.closeInputSync();
@@ -1197,6 +1246,9 @@ export class Demuxer {
      *
      * @yields {Packet} Demuxed packets (must be freed by caller)
      *
+     * @throws {FFmpegError} If reading fails with an error other than EOF (e.g. I/O failure
+     * or a dropped network source) - only a real end-of-file ends the stream cleanly
+     *
      * @throws {Error} If packet cloning fails
      *
      * @example
@@ -1253,42 +1305,64 @@ export class Demuxer {
         this.packetQueueConsumers.set(queueKey, (this.packetQueueConsumers.get(queueKey) ?? 0) + 1);
         // Always start demux thread (handles single and multiple generators)
         this.startDemuxThread();
-        let aborted = false;
         try {
             let hasSeenKeyframe = !this.options.startWithKeyframe;
             // Read from queue (demux thread is handling av_read_frame)
             const queue = this.packetQueues.get(queueKey);
             while (!this.isClosed) {
                 if (this.signal?.aborted) {
-                    aborted = true;
                     break;
                 }
                 // Try to get packet from queue
                 let packet = queue.shift();
+                if (packet) {
+                    this.wakeDemuxThread();
+                }
                 // If queue is empty, wait for next packet
                 if (!packet) {
-                    // Check for EOF first
+                    // Queue drained - check for end of stream. Buffered packets always
+                    // drain before EOF/error is honored, so successfully read data is
+                    // never dropped.
                     if (this.demuxEof) {
+                        // The read loop ended with a real error (not EOF): propagate it
+                        // instead of ending the stream silently - a dead live source must
+                        // be distinguishable from a finished file.
+                        if (this.lastError) {
+                            throw this.lastError;
+                        }
                         break; // End of stream
                     }
-                    // Create promise and register resolver
+                    // Create promise and register resolver. Multiple consumers may wait
+                    // on the same queue key concurrently, so resolvers are collected per
+                    // key - a single slot would be overwritten by the second consumer,
+                    // parking the first one forever (whole-demuxer deadlock).
                     const { promise, resolve } = Promise.withResolvers();
-                    this.queueResolvers.set(queueKey, resolve);
+                    const resolvers = this.queueResolvers.get(queueKey);
+                    if (resolvers) {
+                        resolvers.push(resolve);
+                    }
+                    else {
+                        this.queueResolvers.set(queueKey, [resolve]);
+                    }
                     // Wait for demux thread to add packet
                     await promise;
                     // Check for abort after wakeup
                     if (this.signal?.aborted) {
-                        aborted = true;
-                        break;
-                    }
-                    // Check again after wakeup
-                    if (this.demuxEof) {
                         break;
                     }
                     packet = queue.shift();
                     if (!packet) {
+                        // Woken without a packet for us - either EOF/error or another
+                        // consumer grabbed it. Loop back and re-evaluate.
+                        if (this.demuxEof) {
+                            if (this.lastError) {
+                                throw this.lastError;
+                            }
+                            break;
+                        }
                         continue;
                     }
+                    this.wakeDemuxThread();
                 }
                 // Apply keyframe filtering if needed
                 if (!hasSeenKeyframe) {
@@ -1323,6 +1397,8 @@ export class Demuxer {
                         p.free();
                     }
                 }
+                // The demux thread may be waiting on this queue, so wake it to check the remaining ones.
+                this.wakeDemuxThread();
             }
             else {
                 this.packetQueueConsumers.set(queueKey, remaining);
@@ -1331,13 +1407,13 @@ export class Demuxer {
             if (this.activeGenerators === 0) {
                 await this.stopDemuxThread();
             }
-            if (!aborted) {
-                yield null; // Signal EOF
-            }
         }
-        // Throw after generator cleanup — only reachable when aborted
-        // (when not aborted, yield null in finally already terminated the generator)
+        // Only reached when the loop ended naturally (EOF, abort, close). A consumer
+        // break resumes inside the finally above and completes the generator there -
+        // yielding from the finally would suspend forever inside iterator.return(),
+        // violating the iterator protocol.
         this.signal?.throwIfAborted();
+        yield null; // Signal EOF
     }
     /**
      * Read packets from media as generator synchronously.
@@ -1353,6 +1429,9 @@ export class Demuxer {
      *
      * @yields {Packet} Demuxed packets (must be freed by caller)
      *
+     * @throws {FFmpegError} If reading fails with an error other than EOF (e.g. I/O failure
+     * or a dropped network source) - only a real end-of-file ends the stream cleanly
+     *
      * @throws {Error} If packet cloning fails
      *
      * @example
@@ -1385,6 +1464,16 @@ export class Demuxer {
             while (!this.isClosed) {
                 const ret = this.formatContext.readFrameSync(packet);
                 if (ret < 0) {
+                    // No data available yet (live device capture) - blocking retry
+                    if (ret === AVERROR_EAGAIN) {
+                        Atomics.wait(SYNC_SLEEP_SIGNAL, 0, 0, 10);
+                        continue;
+                    }
+                    // Real read errors propagate; end-of-file and a deliberate
+                    // interrupt() (AVERROR_EXIT) end cleanly
+                    if (!FFmpegError.is(ret, AVERROR_EOF) && !FFmpegError.is(ret, AVERROR_EXIT)) {
+                        throw new FFmpegError(ret);
+                    }
                     break;
                 }
                 // Get stream for timestamp processing
@@ -1531,13 +1620,26 @@ export class Demuxer {
         const ts = BigInt(Math.floor(timestamp * 1000000));
         return this.formatContext.seekFrameSync(streamIndex, ts, flags);
     }
+    /**
+     * Wake the demux thread if it is parked waiting for a full queue to drain.
+     *
+     * @internal
+     */
+    wakeDemuxThread() {
+        const resolve = this.drainResolver;
+        if (resolve) {
+            this.drainResolver = null;
+            resolve();
+        }
+    }
     /**
      * Interrupt a blocking read without closing the demuxer.
      *
      * Aborts any in-progress `av_read_frame()` (e.g. on a quiet RTSP/network source
-     * that is waiting for data) and signals end-of-stream to packet consumers, so
-     * an active pipeline can drain and finish. The demuxer is not freed and its
-     * streams stay valid - call {@link close} afterwards to release resources.
+     * or a stalled Readable/custom I/O source that is waiting for data) and signals
+     * end-of-stream to packet consumers, so an active pipeline can drain and finish.
+     * The demuxer is not freed and its streams stay valid - call {@link close}
+     * afterwards to release resources.
      *
      * Mainly used by pipeline teardown: a blocking read only unblocks on close, but
      * closing while the pipeline is still draining would free the context too early,
@@ -1561,8 +1663,11 @@ export class Demuxer {
         this.formatContext.interrupt();
         // Signal EOF to consumers and wake any generator parked on an empty queue.
         this.demuxEof = true;
-        for (const resolve of this.queueResolvers.values()) {
-            resolve();
+        this.wakeDemuxThread();
+        for (const resolvers of this.queueResolvers.values()) {
+            for (const resolve of resolvers) {
+                resolve();
+            }
         }
         this.queueResolvers.clear();
     }
@@ -1610,10 +1715,21 @@ export class Demuxer {
                             await new Promise((resolve) => setTimeout(resolve, 10));
                             continue;
                         }
-                        // Actual end of stream - notify all waiting consumers
+                        // Anything but a genuine end-of-file is a real read error (I/O
+                        // failure, dropped network source, ...). Store it so consumers throw
+                        // instead of seeing a clean EOF - matching FFmpeg CLI, where a read
+                        // error ends processing with a failure, not a normal finish.
+                        // AVERROR_EXIT is exempt: it is how interrupt() aborts a blocking
+                        // read on purpose (pipeline stop/teardown), not a source failure.
+                        if (!FFmpegError.is(ret, AVERROR_EOF) && !FFmpegError.is(ret, AVERROR_EXIT)) {
+                            this.lastError = new FFmpegError(ret);
+                        }
+                        // End of stream (or error) - notify all waiting consumers
                         this.demuxEof = true;
-                        for (const resolve of this.queueResolvers.values()) {
-                            resolve();
+                        for (const resolvers of this.queueResolvers.values()) {
+                            for (const resolve of resolvers) {
+                                resolve();
+                            }
                         }
                         this.queueResolvers.clear();
                         break;
@@ -1678,7 +1794,10 @@ export class Demuxer {
                         if (!queueFull) {
                             break;
                         }
-                        await new Promise(setImmediate);
+                        // Wait until a consumer frees a slot or the demuxer shuts down. Polling here would keep a CPU core busy.
+                        const { promise: drained, resolve: onDrain } = Promise.withResolvers();
+                        this.drainResolver = onDrain;
+                        await drained;
                     }
                     if (abandoned || !this.demuxThreadActive || this.isClosed) {
                         packet.unref();
@@ -1700,10 +1819,14 @@ export class Demuxer {
                             throw new Error('Failed to clone packet in demux thread (out of memory)');
                         }
                         target.queue.push(clone);
-                        const resolver = this.queueResolvers.get(target.key);
-                        if (resolver) {
-                            resolver();
+                        // Wake every consumer waiting on this key - only one gets the packet,
+                        // the others re-park, but a lost wakeup would deadlock them.
+                        const resolvers = this.queueResolvers.get(target.key);
+                        if (resolvers) {
                             this.queueResolvers.delete(target.key);
+                            for (const resolve of resolvers) {
+                                resolve();
+                            }
                         }
                     }
                     packet.unref();
@@ -1727,9 +1850,12 @@ export class Demuxer {
     async stopDemuxThread() {
         this.demuxThreadActive = false;
         this.demuxEof = true;
+        this.wakeDemuxThread();
         // Wake up any waiting generators
-        for (const resolve of this.queueResolvers.values()) {
-            resolve();
+        for (const resolvers of this.queueResolvers.values()) {
+            for (const resolve of resolvers) {
+                resolve();
+            }
         }
         this.queueResolvers.clear();
         // Wait for demux thread with timeout to avoid hanging on blocked reads
@@ -1993,6 +2119,8 @@ export class Demuxer {
      * Close demuxer and free resources.
      *
      * Releases format context and I/O context.
+     * A read waiting for a stalled Readable or custom I/O source is abandoned,
+     * so closing never waits for the source to deliver.
      * Safe to call multiple times.
      * Automatically called by Symbol.asyncDispose.
      *
@@ -2022,18 +2150,19 @@ export class Demuxer {
         this.demuxThreadActive = false;
         // Set EOF flag so generators know to exit
         this.demuxEof = true;
+        this.wakeDemuxThread();
         // Wake up all waiting generators BEFORE closing format context
         // This ensures generators can exit cleanly even if readFrame() is blocking
-        for (const resolve of this.queueResolvers.values()) {
-            resolve();
+        for (const resolvers of this.queueResolvers.values()) {
+            for (const resolve of resolvers) {
+                resolve();
+            }
         }
         this.queueResolvers.clear();
-        // Clear pb reference to prevent use-after-free
-        if (this.ioContext) {
-            this.formatContext.pb = null;
-        }
-        // Close FormatContext - this may interrupt blocking readFrame()
-        await this.formatContext.closeInput();
+        // Close FormatContext - this may interrupt blocking readFrame(). A custom
+        // pb is detached inside, after the reader thread stopped: nulling it from
+        // here would pull it out from under a running av_read_frame()
+        await this.formatContext.closeInput(!!this.ioContext);
         // Wait for demux thread with timeout to avoid hanging on blocked reads
         if (this.demuxThread) {
             const threadPromise = this.demuxThread;
@@ -2055,9 +2184,18 @@ export class Demuxer {
         }
         this.packetQueues.clear();
         this.packetQueueConsumers.clear();
-        // NOW we can safely free the IOContext
+        // NOW we can safely release the IOContext. Contexts we built ourselves are
+        // callback-backed and go through freeContext(), which IOStream hooks to
+        // detach its stream listeners. A caller-supplied context may instead own a
+        // protocol handle from open2(); dispose picks avio_closep() for those, as
+        // freeing them alone leaks the handle and keeps the file locked on Windows.
         if (this.ioContext) {
-            this.ioContext.freeContext();
+            if (this.externalIO) {
+                await this.ioContext[Symbol.asyncDispose]();
+            }
+            else {
+                this.ioContext.freeContext();
+            }
             this.ioContext = undefined;
         }
     }
@@ -2066,6 +2204,7 @@ export class Demuxer {
      * Synchronous version of close.
      *
      * Releases format context and I/O context.
+     * A read waiting for a stalled Readable or custom I/O source is abandoned.
      * Safe to call multiple times.
      * Automatically called by Symbol.dispose.
      *
@@ -2091,13 +2230,19 @@ export class Demuxer {
         // Clean up abort signal listener
         this.signalCleanup?.();
         this.signalCleanup = undefined;
-        // IMPORTANT: Clear pb reference FIRST to prevent use-after-free
-        if (this.ioContext) {
-            this.formatContext.pb = null;
-        }
-        // Close FormatContext
-        this.formatContext.closeInputSync();
+        // Stop the demux thread and wake generators parked on an empty queue: they
+        // resume once this returns and end, as in close()
         this.demuxThreadActive = false;
+        this.demuxEof = true;
+        this.wakeDemuxThread();
+        for (const resolvers of this.queueResolvers.values()) {
+            for (const resolve of resolvers) {
+                resolve();
+            }
+        }
+        this.queueResolvers.clear();
+        // Close FormatContext; a custom pb is detached inside so it is not closed with the input
+        this.formatContext.closeInputSync(!!this.ioContext);
         for (const queue of this.packetQueues.values()) {
             for (const packet of queue) {
                 packet.free();
@@ -2105,11 +2250,15 @@ export class Demuxer {
             queue.length = 0;
         }
         this.packetQueues.clear();
-        this.queueResolvers.clear();
-        this.demuxEof = false;
-        // NOW we can safely free the IOContext
+        this.packetQueueConsumers.clear();
+        // NOW we can safely release the IOContext (see close() for why dispose)
         if (this.ioContext) {
-            this.ioContext.freeContext();
+            if (this.externalIO) {
+                this.ioContext[Symbol.dispose]();
+            }
+            else {
+                this.ioContext.freeContext();
+            }
             this.ioContext = undefined;
         }
     }