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

package/README.md

@@ -10,7 +10,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![FFmpeg](https://img.shields.io/badge/FFmpeg-8.1.1-green.svg)](https://ffmpeg.org)
-[![Platform](https://img.shields.io/badge/platform-Windows%20(MSVC%20%7C%20MinGW)%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/seydx/node-av)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/seydx/node-av)
 
 Native Node.js bindings for FFmpeg with full TypeScript support - including type-safe options (autocomplete + validation) for every codec, format, filter, and bitstream filter, generated from FFmpeg's own metadata. Provides direct access to FFmpeg's C APIs through N-API. Includes both raw FFmpeg bindings for full control and higher-level abstractions. Automatic resource management via Disposable pattern, hardware acceleration support and prebuilt binaries for Windows, Linux, and macOS.
 
@@ -527,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 or its input is closed or interrupted (a closing `Demuxer` or an exiting process or worker fails it with `AVERROR_EXIT`); 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.
@@ -555,7 +562,7 @@ Prebuilt binaries are available for multiple platforms:
 
 - **macOS**: x64, ARM64
 - **Linux**: x64, ARM64
-- **Windows**: x64, ARM64 (automatic MSVC/MinGW selection)
+- **Windows**: x64, ARM64
 
 ### Cross-Platform Packaging (CI/CD)
 
@@ -569,9 +576,7 @@ npm install --os=win32 --cpu=x64
 ```
 
 npm filters the platform-specific `optionalDependencies` by these flags, and the
-postinstall hook honors them for the bundled FFmpeg binary as well. Cross-compiled
-Windows installs default to the MSVC build; pass `--libc=mingw` to select the MinGW
-(jellyfin) build instead.
+postinstall hook honors them for the bundled FFmpeg binary as well.
 
 ## Troubleshooting
 
@@ -635,17 +640,17 @@ For issues and questions, please use the GitHub issue tracker.
   <source
     media="(prefers-color-scheme: dark)"
     srcset="
-      https://api.star-history.com/svg?repos=seydx/node-av&type=Date&theme=dark
+      https://star-history.dera.page/svg?repos=seydx/node-av&type=Date&theme=dark
     "
   />
   <source
     media="(prefers-color-scheme: light)"
     srcset="
-      https://api.star-history.com/svg?repos=seydx/node-av&type=Date
+https://star-history.dera.page/svg?repos=seydx/node-av&type=Date
     "
   />
   <img
     alt="Star History Chart"
-    src="https://api.star-history.com/svg?repos=seydx/node-av&type=Date"
+    src="https://star-history.dera.page/svg?repos=seydx/node-av&type=Date"
   />
 </picture>

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

@@ -1,6 +1,47 @@
 import { Frame } from '../lib/frame.js';
 import type { AVSampleFormat } from '../constants/index.js';
 import type { ChannelLayout } from '../lib/types.js';
+/**
+ * Options for {@link AudioFrameBuffer.create}.
+ */
+export interface AudioFrameBufferOptions {
+    /**
+     * Where the timestamps of the output frames come from.
+     *
+     * With `'input'` the output keeps the timing of the pushed frames, as described
+     * for {@link AudioFrameBuffer}. With `'samples'` input timestamps are ignored and
+     * the output is counted from 0 by its samples, in the time base of the pushed
+     * frames; use it for input whose timestamps are unusable.
+     *
+     * @default 'input'
+     */
+    timestamps?: 'input' | 'samples';
+    /**
+     * Largest gap in seconds that is filled with silence.
+     *
+     * A larger gap restarts the output timeline at the new timestamp, so it shows up
+     * as a timestamp jump instead. Real-time outputs such as RTP are better served by
+     * `0`: a filled gap is only written once the input resumes and then goes out as a
+     * burst of late packets, while receivers handle a timestamp gap like packet loss.
+     * Gaps of up to one output frame are filled either way, because a restart pads the
+     * current output frame with silence to its end. The silence is generated while
+     * pulling and takes no memory, but a long fill comes out in one go once the input
+     * resumes.
+     *
+     * @default 1
+     */
+    maxGapFill?: number;
+}
+/**
+ * Check the options of an audio frame buffer.
+ *
+ * @param options - Options to check
+ *
+ * @throws {RangeError} If an option is out of range
+ *
+ * @internal
+ */
+export declare function assertAudioFrameBufferOptions(options: AudioFrameBufferOptions): void;
 /**
  * Audio frame buffering utility for encoders with fixed frame size requirements.
  *
@@ -8,6 +49,16 @@ import type { ChannelLayout } from '../lib/types.js';
  * of samples (frame_size). This class buffers incoming frames and outputs frames
  * with exactly the required size.
  *
+ * Output frames keep the input timing: each carries the timestamp of its first
+ * sample, in the time base of the pushed frames, and counts on by samples while the
+ * input is continuous. Deviations of up to 20 ms count as continuous, and larger ones
+ * only once they persist over 0.2 s of input, so jitter and single frames with a wrong
+ * timestamp leave the audio untouched. A persistent gap of up to a second is then
+ * filled with silence and an overlap of up to a second is dropped, which keeps the
+ * audio contiguous and in sync; a larger jump restarts the timeline at the new
+ * timestamp on the next frame boundary. Frames without a timestamp or time base
+ * continue the previous one.
+ *
  * Uses FFmpeg's AVAudioFifo internally for efficient sample buffering.
  *
  * @example
@@ -29,20 +80,49 @@ 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();
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Real-time output: input gaps become timestamp jumps instead of silence
+ * using buffer = AudioFrameBuffer.create(960, AV_SAMPLE_FMT_FLT, 48000, 'mono', 1, { maxGapFill: 0 });
  * ```
  */
 export declare class AudioFrameBuffer implements Disposable {
     private fifo;
     private frame;
     private frameSize;
-    private nextPts;
-    private firstFramePts;
+    private channels;
+    private sampleStride;
+    private staging;
+    private stagingPlanes;
+    private silenceValue;
+    private sampleTimeBase;
+    private timeBase;
+    private countsInSamples;
+    private followInput;
+    private tolerance;
+    private confirmSamples;
+    private maxFill;
+    private maxTrim;
+    private headIndex;
+    private tailIndex;
+    private segments;
+    private silence;
+    private timed;
+    private trimPending;
+    private deviation;
     /**
      * @param fifo - Underlying AudioFifo instance
      *
@@ -54,6 +134,8 @@ export declare class AudioFrameBuffer implements Disposable {
      *
      * @param channelLayout - Channel layout
      *
+     * @param options - Timing options
+     *
      * @internal
      */
     private constructor();
@@ -70,18 +152,24 @@ export declare class AudioFrameBuffer implements Disposable {
      *
      * @param channels - Number of audio channels
      *
+     * @param options - Timing options
+     *
      * @returns Configured audio frame buffer
      *
+     * @throws {RangeError} If an option is out of range
+     *
      * @example
      * ```typescript
      * // For Opus encoder at 48kHz with 20ms frames
      * const buffer = AudioFrameBuffer.create(960, AV_SAMPLE_FMT_FLT, 48000, 'mono', 1);
      * ```
      */
-    static create(frameSize: number, sampleFormat: AVSampleFormat, sampleRate: number, channelLayout: ChannelLayout, channels: number): AudioFrameBuffer;
+    static create(frameSize: number, sampleFormat: AVSampleFormat, sampleRate: number, channelLayout: ChannelLayout, channels: number, options?: AudioFrameBufferOptions): AudioFrameBuffer;
     /**
      * Get number of samples currently in buffer.
      *
+     * Includes silence inserted for gaps in the input.
+     *
      * @returns Number of buffered samples
      *
      * @example
@@ -93,7 +181,7 @@ export declare class AudioFrameBuffer implements Disposable {
     /**
      * Check if a complete frame is available.
      *
-     * Returns true if the FIFO contains at least frameSize samples.
+     * Returns true if the buffer holds at least frameSize samples.
      *
      * @returns True if a full frame can be pulled
      *
@@ -112,8 +200,23 @@ export declare class AudioFrameBuffer implements Disposable {
      * The frame's samples are added to the internal FIFO.
      * Call hasFrame() and pull() to retrieve fixed-size output frames.
      *
+     * The first frame with a valid time base fixes the time base of the output frames.
+     * When the frame timestamps deviate from the buffered samples by more than 20 ms
+     * over at least 0.2 s of input (and 3 frames), a gap is filled with silence (up to
+     * `maxGapFill`) and an overlap of up to 1 s is dropped from the input; a larger jump
+     * restarts the timeline at the new timestamp after padding the current output frame
+     * with silence. The frames that arrive until then still continue the previous
+     * timeline. Each such correction is a short dropout or cut in the audio: input whose
+     * timestamps drift against its sample count, such as a capture device stamped from
+     * the system clock, gets one per 20 ms of drift, which keeps it within about 20 ms
+     * of its timestamps.
+     *
      * @param frame - Audio frame to buffer
      *
+     * @throws {Error} If the frame is not an audio frame
+     *
+     * @throws {FFmpegError} If the samples cannot be written to the FIFO
+     *
      * @example
      * ```typescript
      * await buffer.push(filterFrame);
@@ -128,9 +231,14 @@ export declare class AudioFrameBuffer implements Disposable {
      *
      * The frame's samples are added to the internal FIFO.
      * Call hasFrame() and pullSync() to retrieve fixed-size output frames.
+     * Timestamps are handled as in push().
      *
      * @param frame - Audio frame to buffer
      *
+     * @throws {Error} If the frame is not an audio frame
+     *
+     * @throws {FFmpegError} If the samples cannot be written to the FIFO
+     *
      * @example
      * ```typescript
      * buffer.pushSync(filterFrame);
@@ -142,12 +250,15 @@ export declare class AudioFrameBuffer implements Disposable {
     /**
      * Pull a fixed-size audio frame from the buffer asynchronously.
      *
-     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame.
+     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame
+     * stamped with the timestamp of its first sample.
      * Returns null if not enough samples are available.
      * Reuses internal frame buffer for efficiency (like Decoder does).
      *
      * @returns Audio frame with exactly frameSize samples, or null if insufficient samples
      *
+     * @throws {FFmpegError} If the FIFO cannot be read or the frame cannot be filled
+     *
      * @throws {Error} If frame cloning fails (out of memory)
      *
      * @example
@@ -165,12 +276,15 @@ export declare class AudioFrameBuffer implements Disposable {
      * Pull a fixed-size audio frame from the buffer synchronously.
      * Synchronous version of pull.
      *
-     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame.
+     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame
+     * stamped with the timestamp of its first sample.
      * Returns null if not enough samples are available.
      * Reuses internal frame buffer for efficiency (like Decoder does).
      *
      * @returns Audio frame with exactly frameSize samples, or null if insufficient samples
      *
+     * @throws {FFmpegError} If the FIFO cannot be read or the frame cannot be filled
+     *
      * @throws {Error} If frame cloning fails (out of memory)
      *
      * @example
@@ -184,15 +298,332 @@ 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). The padding counts as audio, so frames pushed afterwards are
+     * timed after it.
+     *
+     * @returns Silence-padded audio frame with frameSize samples, or null if nothing to drain
+     *
+     * @throws {FFmpegError} If the FIFO cannot be read or the frame cannot be filled
+     *
+     * @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 {FFmpegError} If the FIFO cannot be read or the frame cannot be filled
+     *
+     * @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;
     /**
      * Reset the buffer, discarding all buffered samples.
      *
+     * The next pushed frame starts a new timeline, and its time base becomes
+     * the output time base.
+     *
      * @example
      * ```typescript
      * buffer.reset();
      * ```
      */
     reset(): void;
+    /**
+     * Decide how a pushed frame continues the buffered samples.
+     *
+     * The only place that moves the write position: it records the silence before the
+     * frame and accounts for the samples the caller then writes, so the position always
+     * runs ahead of the buffered samples by exactly the writes still in flight.
+     *
+     * @param frame - Audio frame about to be written
+     *
+     * @param nbSamples - Number of samples in the frame
+     *
+     * @returns Samples to drop from the head of the frame
+     *
+     * @internal
+     */
+    private planPush;
+    /**
+     * Append silence at the write position.
+     *
+     * Silence only exists as a run of sample indices and is generated while pulling, so
+     * a long gap costs neither a buffer of its size nor a FIFO grown to hold it (an
+     * AVAudioFifo never shrinks again).
+     *
+     * @param samples - Number of silent samples
+     *
+     * @internal
+     */
+    private addSilence;
+    /**
+     * Anchor the timeline at the first frame that carries a timestamp.
+     *
+     * @param pts - Timestamp of the frame in the output time base
+     *
+     * @returns Silence to write before the frame
+     *
+     * @internal
+     */
+    private anchorInput;
+    /**
+     * Compare a frame's timestamp with the buffered samples and compensate a persistent deviation.
+     *
+     * Within the tolerance the frame counts on by samples. A larger deviation is only
+     * acted on once it has lasted over enough input in the same direction: jitter and
+     * frames with a wrong timestamp come and go, while gaps, overlaps and clock steps
+     * persist. The correction is the median deviation of that run, so jitter on top of
+     * a real step does not leak into it.
+     *
+     * @param pts - Timestamp of the frame in the output time base
+     *
+     * @param nbSamples - Number of samples in the frame
+     *
+     * @returns Silence to write before the frame
+     *
+     * @internal
+     */
+    private trackInput;
+    /**
+     * Apply a confirmed deviation to the timeline.
+     *
+     * A gap is filled with silence and an overlap is dropped from the input, which keeps
+     * the output contiguous and on its frame grid. Beyond their limits the timeline
+     * restarts at the frame's timestamp instead.
+     *
+     * @param offset - Deviation of the frame in the output time base
+     *
+     * @param expected - Timestamp the frame would have without the deviation
+     *
+     * @returns Silence to write before the frame
+     *
+     * @internal
+     */
+    private compensate;
+    /**
+     * Start a new segment at the next output frame boundary.
+     *
+     * Every output frame then lies within one segment, so its timestamp stays well
+     * defined; the current partial frame is padded with silence to get there.
+     *
+     * @param pts - Timestamp of the frame about to be written
+     *
+     * @returns Silence to write before the frame
+     *
+     * @internal
+     */
+    private restart;
+    /**
+     * Fix the output time base from the first pushed frame.
+     *
+     * Frames without a valid time base leave the output counting samples (1/sample_rate).
+     *
+     * @param frame - First pushed frame
+     *
+     * @returns Output time base
+     *
+     * @internal
+     */
+    private lockTimeBase;
+    /**
+     * Read a frame's timestamp in the output time base.
+     *
+     * @param frame - Pushed frame
+     *
+     * @returns Timestamp, or AV_NOPTS_VALUE if the frame has no timestamp or time base
+     *
+     * @internal
+     */
+    private inputPts;
+    /**
+     * Timestamp of the next sample to pull.
+     *
+     * Drops segments the head has reached the end of first, so the head lies in the first one.
+     *
+     * @returns Timestamp in the output time base
+     *
+     * @internal
+     */
+    private headPts;
+    /**
+     * Timestamp right after the last buffered sample.
+     *
+     * @returns Timestamp in the output time base
+     *
+     * @internal
+     */
+    private tailPts;
+    /**
+     * Treat the silence padding of a partial frame as written audio.
+     *
+     * @internal
+     */
+    private advanceTailToHead;
+    /**
+     * Realign the write position with the FIFO after a failed write.
+     *
+     * @internal
+     */
+    private resyncTail;
+    /**
+     * Number of samples that can be pulled: buffered samples plus the silence between them.
+     *
+     * Stops at the first silence run that lies behind a write still in flight.
+     *
+     * @returns Number of samples available from the read position
+     *
+     * @internal
+     */
+    private available;
+    /**
+     * Split the next samples to pull into FIFO reads and silence.
+     *
+     * @param count - Number of samples to pull
+     *
+     * @returns Parts in pull order
+     *
+     * @internal
+     */
+    private readRuns;
+    /**
+     * Read the next samples into the head of the staging buffer.
+     *
+     * @param count - Number of samples to read
+     *
+     * @throws {FFmpegError} If the FIFO cannot be read
+     *
+     * @internal
+     */
+    private readStaging;
+    /**
+     * Read the next samples into the head of the staging buffer synchronously.
+     * Synchronous version of readStaging.
+     *
+     * @param count - Number of samples to read
+     *
+     * @throws {FFmpegError} If the FIFO cannot be read
+     *
+     * @internal
+     */
+    private readStagingSync;
+    /**
+     * Staging planes starting at a sample offset.
+     *
+     * @param offset - First sample to write to
+     *
+     * @returns Plane buffers for a FIFO read
+     *
+     * @internal
+     */
+    private stagingAt;
+    /**
+     * Convert a sample count to output time base ticks.
+     *
+     * @param samples - Number of samples
+     *
+     * @returns Duration in the output time base
+     *
+     * @internal
+     */
+    private ticks;
+    /**
+     * Convert output time base ticks to a sample count.
+     *
+     * @param ticks - Duration in the output time base
+     *
+     * @returns Number of samples (rounded)
+     *
+     * @internal
+     */
+    private samples;
+    /**
+     * Plane buffers of a pushed frame, starting at a sample offset.
+     *
+     * @param frame - Pushed frame
+     *
+     * @param skip - Samples to leave out at the head
+     *
+     * @returns Plane buffers to write to the FIFO
+     *
+     * @internal
+     */
+    private inputPlanes;
+    /**
+     * Stamp the reusable frame, advance the read position by one frame and hand out a clone.
+     *
+     * @param pts - Timestamp of the frame's first sample
+     *
+     * @returns Cloned output frame
+     *
+     * @throws {Error} If frame cloning fails (out of memory)
+     *
+     * @internal
+     */
+    private emitFrame;
+    /**
+     * Fill the staged sample range [fromSample, toSample) with silence.
+     *
+     * Planar frames carry one channel per plane; packed frames interleave all
+     * channels in plane 0.
+     *
+     * @param fromSample - First sample index to silence
+     *
+     * @param toSample - Sample index after the last one to silence
+     *
+     * @internal
+     */
+    private fillSilence;
+    /**
+     * Copy the staged samples into the reusable frame.
+     *
+     * A frame pulled earlier may still share the frame's buffer, so the buffer is
+     * made writable first instead of overwriting the samples under that frame.
+     *
+     * @throws {FFmpegError} If the frame buffer cannot be made writable or filled
+     *
+     * @internal
+     */
+    private commitStaging;
     /**
      * Free the buffer and all resources.
      *