node-av 6.2.0-beta.1 → 6.2.0-beta.11

package/README.md

@@ -129,11 +129,33 @@ while (true) {
       console.log(`Decoded frame ${frame.pts}, size: ${frame.width}x${frame.height}`);
 
       // Process frame data...
+
+      frame.unref();
     }
   }
 
   packet.unref();
 }
+
+// Flush the decoder - codecs buffer frames internally (B-frames, threading),
+// so the last frames only come out after signaling EOF with a null packet.
+ret = await decoderCtx.sendPacket(null);
+if (ret < 0 && ret !== AVERROR_EOF) {
+  FFmpegError.throwIfError(ret, 'Failed to flush decoder');
+}
+
+while (true) {
+  const ret = await decoderCtx.receiveFrame(frame);
+  if (ret === AVERROR_EOF || ret < 0) {
+    break;
+  }
+
+  console.log(`Decoded frame ${frame.pts}, size: ${frame.width}x${frame.height}`);
+
+  // Process frame data...
+
+  frame.unref();
+}
 ```
 
 ### High-Level API
@@ -505,6 +527,13 @@ The key difference: Async methods don't block the Node.js event loop, allowing o
 
 NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory pointers. The high-level API adds safety abstractions and automatic resource management, but incorrect usage can still cause crashes. Common issues include mismatched video dimensions, incompatible pixel formats, or improper frame buffer handling. The library validates parameters where possible, but can't guarantee complete memory safety without limiting functionality. When using the low-level API, pay attention to parameter consistency, resource cleanup, and format compatibility. Following the documented patterns helps avoid memory-related issues.
 
+## Worker Threads and the libuv Thread Pool
+
+NodeAV works inside `worker_threads`, with two caveats:
+
+- **Prefer graceful shutdown over `worker.terminate()`.** Terminating a worker while native calls are in flight is mitigated (pending completions are dropped safely instead of aborting), but a termination that lands exactly inside a running synchronous native call can still abort the process — a limitation of Node-API error handling during isolate teardown. Signal the worker to close its NodeAV resources and exit on its own. For test runners, process isolation (e.g. vitest `pool: 'forks'`) is the most robust choice.
+- **Async operations share the libuv thread pool** (default: 4 threads, process-wide across all workers). A custom IO read callback that never settles parks one pool thread until it resolves; enough of them stall every async NodeAV operation in the entire process. Make custom IO callbacks always settle (return `null` for EOF, throw on error), and raise `UV_THREADPOOL_SIZE` when running many parallel live inputs.
+
 ## Electron
 
 NodeAV fully supports Electron applications. The prebuilt binaries are ABI-compatible with Electron, so no native rebuild is required during packaging. Both the native bindings and the bundled FFmpeg CLI binaries work seamlessly within Electron's main process.

package/dist/api/audio-frame-buffer.d.ts

@@ -29,18 +29,25 @@ import type { ChannelLayout } from '../lib/types.js';
  *   }
  * }
  *
- * // Flush remaining samples
+ * // Flush remaining samples (final partial frame is padded with silence)
  * let outputFrame;
  * while ((outputFrame = await buffer.pull()) !== null) {
  *   await encoder.encode(outputFrame);
  *   outputFrame.free();
  * }
+ * const tail = await buffer.pullPartial();
+ * if (tail) {
+ *   await encoder.encode(tail);
+ *   tail.free();
+ * }
  * ```
  */
 export declare class AudioFrameBuffer implements Disposable {
     private fifo;
     private frame;
     private frameSize;
+    private sampleFormat;
+    private channels;
     private nextPts;
     private firstFramePts;
     /**
@@ -184,6 +191,71 @@ export declare class AudioFrameBuffer implements Disposable {
      * @see {@link pull} For async version
      */
     pullSync(): Frame | null;
+    /**
+     * Pull the final partial frame from the buffer asynchronously.
+     *
+     * Reads the remaining samples (fewer than frameSize) and pads the tail with
+     * silence so the returned frame still carries exactly frameSize samples.
+     * Intended for end-of-stream flushing only - without it the tail (up to
+     * frameSize - 1 samples) would be dropped. Returns null if the buffer is
+     * empty, or while a complete frame is still available (drain those with
+     * pull() first).
+     *
+     * @returns Silence-padded audio frame with frameSize samples, or null if nothing to drain
+     *
+     * @throws {Error} If frame cloning fails (out of memory)
+     *
+     * @example
+     * ```typescript
+     * // At end of stream, after pull() has returned null
+     * using tail = await buffer.pullPartial();
+     * if (tail) {
+     *   await encoder.encode(tail);
+     * }
+     * ```
+     *
+     * @see {@link pullPartialSync} For synchronous version
+     * @see {@link pull} For pulling complete frames
+     */
+    pullPartial(): Promise<Frame | null>;
+    /**
+     * Pull the final partial frame from the buffer synchronously.
+     * Synchronous version of pullPartial.
+     *
+     * Reads the remaining samples (fewer than frameSize) and pads the tail with
+     * silence so the returned frame still carries exactly frameSize samples.
+     * Intended for end-of-stream flushing only. Returns null if the buffer is
+     * empty, or while a complete frame is still available.
+     *
+     * @returns Silence-padded audio frame with frameSize samples, or null if nothing to drain
+     *
+     * @throws {Error} If frame cloning fails (out of memory)
+     *
+     * @example
+     * ```typescript
+     * // At end of stream, after pullSync() has returned null
+     * using tail = buffer.pullPartialSync();
+     * if (tail) {
+     *   encoder.encodeSync(tail);
+     * }
+     * ```
+     *
+     * @see {@link pullPartial} For async version
+     * @see {@link pullSync} For pulling complete frames
+     */
+    pullPartialSync(): Frame | null;
+    /**
+     * Fill the reusable frame's sample range [fromSample, frameSize) with silence.
+     *
+     * Follows av_samples_set_silence() semantics: unsigned 8-bit formats use 0x80
+     * as the silence value, every other format uses 0. Planar frames carry one
+     * channel per plane; packed frames interleave all channels in plane 0.
+     *
+     * @param fromSample - First sample index to silence
+     *
+     * @internal
+     */
+    private padWithSilence;
     /**
      * Reset the buffer, discarding all buffered samples.
      *

package/dist/api/audio-frame-buffer.js

@@ -1,5 +1,8 @@
+import { AV_SAMPLE_FMT_U8, AV_SAMPLE_FMT_U8P } from '../constants/constants.js';
 import { AudioFifo } from '../lib/audio-fifo.js';
 import { Frame } from '../lib/frame.js';
+import { Rational } from '../lib/rational.js';
+import { avGetBytesPerSample, avSampleFmtIsPlanar } from '../lib/utilities.js';
 /**
  * Audio frame buffering utility for encoders with fixed frame size requirements.
  *
@@ -28,18 +31,25 @@ import { Frame } from '../lib/frame.js';
  *   }
  * }
  *
- * // Flush remaining samples
+ * // Flush remaining samples (final partial frame is padded with silence)
  * let outputFrame;
  * while ((outputFrame = await buffer.pull()) !== null) {
  *   await encoder.encode(outputFrame);
  *   outputFrame.free();
  * }
+ * const tail = await buffer.pullPartial();
+ * if (tail) {
+ *   await encoder.encode(tail);
+ *   tail.free();
+ * }
  * ```
  */
 export class AudioFrameBuffer {
     fifo;
     frame;
     frameSize;
+    sampleFormat;
+    channels;
     nextPts = 0n;
     firstFramePts = null;
     /**
@@ -58,12 +68,17 @@ export class AudioFrameBuffer {
     constructor(fifo, frameSize, sampleFormat, sampleRate, channelLayout) {
         this.fifo = fifo;
         this.frameSize = frameSize;
+        this.sampleFormat = sampleFormat;
+        this.channels = channelLayout.nbChannels;
         this.frame = new Frame();
         this.frame.alloc();
         this.frame.nbSamples = frameSize;
         this.frame.format = sampleFormat;
         this.frame.sampleRate = sampleRate;
         this.frame.channelLayout = channelLayout;
+        // Output PTS is a running sample counter, so the matching timebase is
+        // 1/sample_rate; pulled frames go to the codec without further rescaling.
+        this.frame.timeBase = new Rational(1, sampleRate);
         this.frame.getBuffer(0); // Allocate buffer once
     }
     /**
@@ -258,6 +273,117 @@ export class AudioFrameBuffer {
         }
         return cloned;
     }
+    /**
+     * Pull the final partial frame from the buffer asynchronously.
+     *
+     * Reads the remaining samples (fewer than frameSize) and pads the tail with
+     * silence so the returned frame still carries exactly frameSize samples.
+     * Intended for end-of-stream flushing only - without it the tail (up to
+     * frameSize - 1 samples) would be dropped. Returns null if the buffer is
+     * empty, or while a complete frame is still available (drain those with
+     * pull() first).
+     *
+     * @returns Silence-padded audio frame with frameSize samples, or null if nothing to drain
+     *
+     * @throws {Error} If frame cloning fails (out of memory)
+     *
+     * @example
+     * ```typescript
+     * // At end of stream, after pull() has returned null
+     * using tail = await buffer.pullPartial();
+     * if (tail) {
+     *   await encoder.encode(tail);
+     * }
+     * ```
+     *
+     * @see {@link pullPartialSync} For synchronous version
+     * @see {@link pull} For pulling complete frames
+     */
+    async pullPartial() {
+        const remaining = this.fifo.size;
+        if (remaining <= 0 || remaining >= this.frameSize) {
+            return null;
+        }
+        // Update PTS
+        this.frame.pts = this.nextPts;
+        // Read the remaining samples into the head of the reusable frame
+        await this.fifo.read(this.frame.data, remaining);
+        // Pad the tail with silence up to frameSize
+        this.padWithSilence(remaining);
+        // Update PTS for next frame
+        this.nextPts += BigInt(this.frameSize);
+        // Clone frame for user (like Decoder does)
+        const cloned = this.frame.clone();
+        if (!cloned) {
+            throw new Error('Failed to clone frame (out of memory)');
+        }
+        return cloned;
+    }
+    /**
+     * Pull the final partial frame from the buffer synchronously.
+     * Synchronous version of pullPartial.
+     *
+     * Reads the remaining samples (fewer than frameSize) and pads the tail with
+     * silence so the returned frame still carries exactly frameSize samples.
+     * Intended for end-of-stream flushing only. Returns null if the buffer is
+     * empty, or while a complete frame is still available.
+     *
+     * @returns Silence-padded audio frame with frameSize samples, or null if nothing to drain
+     *
+     * @throws {Error} If frame cloning fails (out of memory)
+     *
+     * @example
+     * ```typescript
+     * // At end of stream, after pullSync() has returned null
+     * using tail = buffer.pullPartialSync();
+     * if (tail) {
+     *   encoder.encodeSync(tail);
+     * }
+     * ```
+     *
+     * @see {@link pullPartial} For async version
+     * @see {@link pullSync} For pulling complete frames
+     */
+    pullPartialSync() {
+        const remaining = this.fifo.size;
+        if (remaining <= 0 || remaining >= this.frameSize) {
+            return null;
+        }
+        // Update PTS
+        this.frame.pts = this.nextPts;
+        // Read the remaining samples into the head of the reusable frame
+        this.fifo.readSync(this.frame.data, remaining);
+        // Pad the tail with silence up to frameSize
+        this.padWithSilence(remaining);
+        // Update PTS for next frame
+        this.nextPts += BigInt(this.frameSize);
+        // Clone frame for user
+        const cloned = this.frame.clone();
+        if (!cloned) {
+            throw new Error('Failed to clone frame (out of memory)');
+        }
+        return cloned;
+    }
+    /**
+     * Fill the reusable frame's sample range [fromSample, frameSize) with silence.
+     *
+     * Follows av_samples_set_silence() semantics: unsigned 8-bit formats use 0x80
+     * as the silence value, every other format uses 0. Planar frames carry one
+     * channel per plane; packed frames interleave all channels in plane 0.
+     *
+     * @param fromSample - First sample index to silence
+     *
+     * @internal
+     */
+    padWithSilence(fromSample) {
+        const silence = this.sampleFormat === AV_SAMPLE_FMT_U8 || this.sampleFormat === AV_SAMPLE_FMT_U8P ? 0x80 : 0;
+        const bytesPerSample = avGetBytesPerSample(this.sampleFormat);
+        const stride = avSampleFmtIsPlanar(this.sampleFormat) ? bytesPerSample : bytesPerSample * this.channels;
+        const planes = this.frame.data ?? [];
+        for (const plane of planes) {
+            plane.fill(silence, fromSample * stride, this.frameSize * stride);
+        }
+    }
     /**
      * Reset the buffer, discarding all buffered samples.
      *

package/dist/api/audio-frame-buffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"audio-frame-buffer.js","sourceRoot":"","sources":["../../src/api/audio-frame-buffer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audio-frame-buffer.js","sourceRoot":"","sources":["../../src/api/audio-frame-buffer.ts"],"names":[],"mappings":"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"}

package/dist/api/bitstream-filter.d.ts

@@ -72,6 +72,7 @@ export declare class BitStreamFilterAPI implements Disposable {
     private source;
     private initialized;
     private packet;
+    private pendingOutput;
     private isClosed;
     private inputQueue;
     private outputQueue;
@@ -526,8 +527,9 @@ export declare class BitStreamFilterAPI implements Disposable {
      * Sends null packet to filter to signal end-of-stream.
      * Does nothing if filter is closed.
      * Must call receive() or flushPackets() to get remaining buffered packets.
+     * Does not reset filter state - use {@link reset} for that.
      *
-     * Direct mapping to av_bsf_send_packet(NULL) and av_bsf_flush().
+     * Direct mapping to av_bsf_send_packet(NULL).
      *
      * @throws {FFmpegError} If flush fails
      *
@@ -558,8 +560,9 @@ export declare class BitStreamFilterAPI implements Disposable {
      * Sends null packet to filter to signal end-of-stream.
      * Does nothing if filter is closed.
      * Must call receiveSync() or flushPacketsSync() to get remaining buffered packets.
+     * Does not reset filter state - use {@link reset} for that.
      *
-     * Direct mapping to av_bsf_send_packet(NULL) and av_bsf_flush().
+     * Direct mapping to av_bsf_send_packet(NULL).
      *
      * @throws {FFmpegError} If flush fails
      *
@@ -734,7 +737,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      * Synchronous version of flushPackets.
      *
      * Convenient sync iteration over remaining packets.
-     * Automatically retrieves buffered packets after flush.
+     * Automatically sends flush signal and retrieves buffered packets.
      * Useful for end-of-stream processing.
      *
      * @yields {Packet} Buffered packets
@@ -768,7 +771,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      * filter.reset();
      * ```
      *
-     * @see {@link flush} For reset with packet retrieval
+     * @see {@link flush} For end-of-stream signaling with packet retrieval
      */
     reset(): void;
     /**
@@ -808,6 +811,81 @@ export declare class BitStreamFilterAPI implements Disposable {
      * @internal
      */
     private ensureInitialized;
+    /**
+     * Send a packet to the filter context, retrying once on EAGAIN.
+     *
+     * av_bsf_send_packet() returning EAGAIN means the packet was NOT consumed:
+     * the filter holds output that must be received before it accepts more
+     * input. That output is drained into pendingOutput (delivered by subsequent
+     * receive() calls in FIFO order) and the send is retried, mirroring how the
+     * FFmpeg CLI interleaves send/receive.
+     *
+     * @param packet - Packet to send, or null to signal EOF
+     *
+     * @throws {FFmpegError} If sending fails
+     *
+     * @internal
+     */
+    private sendPacketWithRetry;
+    /**
+     * Send a packet to the filter context, retrying once on EAGAIN.
+     * Synchronous version of sendPacketWithRetry.
+     *
+     * @param packet - Packet to send, or null to signal EOF
+     *
+     * @throws {FFmpegError} If sending fails
+     *
+     * @internal
+     */
+    private sendPacketWithRetrySync;
+    /**
+     * Receive one packet directly from the filter context.
+     *
+     * Bypasses pendingOutput so an EAGAIN drain can buffer packets without
+     * re-reading them.
+     *
+     * @returns Cloned packet or null if no packets available
+     *
+     * @throws {FFmpegError} If receive fails
+     *
+     * @throws {Error} If packet cloning fails (out of memory)
+     *
+     * @internal
+     */
+    private receiveFromContext;
+    /**
+     * Receive one packet directly from the filter context.
+     * Synchronous version of receiveFromContext.
+     *
+     * @returns Cloned packet or null if no packets available
+     *
+     * @throws {FFmpegError} If receive fails
+     *
+     * @throws {Error} If packet cloning fails (out of memory)
+     *
+     * @internal
+     */
+    private receiveFromContextSync;
+    /**
+     * Convert a receive return code into a cloned output packet.
+     *
+     * @param recvRet - Return code of av_bsf_receive_packet()
+     *
+     * @returns Cloned packet, or null on EAGAIN/EOF
+     *
+     * @throws {FFmpegError} If the return code is any other error
+     *
+     * @throws {Error} If packet cloning fails (out of memory)
+     *
+     * @internal
+     */
+    private consumeReceived;
+    /**
+     * Free and clear any packets buffered by an EAGAIN drain.
+     *
+     * @internal
+     */
+    private clearPendingOutput;
     /**
      * Send packet to input queue or flush the pipeline.
      *