node-av 6.2.0-beta.25 → 6.2.0-beta.26

package/README.md

@@ -532,7 +532,7 @@ NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory p
 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.
+- **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
 

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
@@ -41,17 +92,37 @@ import type { ChannelLayout } from '../lib/types.js';
  *   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 sampleFormat;
     private channels;
+    private sampleStride;
     private staging;
     private stagingPlanes;
-    private nextPts;
-    private firstFramePts;
+    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
      *
@@ -63,6 +134,8 @@ export declare class AudioFrameBuffer implements Disposable {
      *
      * @param channelLayout - Channel layout
      *
+     * @param options - Timing options
+     *
      * @internal
      */
     private constructor();
@@ -79,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
@@ -102,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
      *
@@ -121,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);
@@ -137,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);
@@ -151,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
@@ -174,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
@@ -201,10 +306,13 @@ export declare class AudioFrameBuffer implements Disposable {
      * 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).
+     * 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
@@ -231,6 +339,8 @@ export declare class AudioFrameBuffer implements Disposable {
      *
      * @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
@@ -247,17 +357,262 @@ export declare class AudioFrameBuffer implements Disposable {
      */
     pullPartialSync(): Frame | null;
     /**
-     * Fill the staged sample range [fromSample, frameSize) with silence.
+     * 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.
      *
-     * 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 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 padWithSilence;
+    private fillSilence;
     /**
      * Copy the staged samples into the reusable frame.
      *
@@ -269,15 +624,6 @@ export declare class AudioFrameBuffer implements Disposable {
      * @internal
      */
     private commitStaging;
-    /**
-     * Reset the buffer, discarding all buffered samples.
-     *
-     * @example
-     * ```typescript
-     * buffer.reset();
-     * ```
-     */
-    reset(): void;
     /**
      * Free the buffer and all resources.
      *