node-av-light 0.0.0 → 7.1.0-beta.1

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

@@ -0,0 +1,636 @@
+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.
+ *
+ * Many audio encoders (Opus, AAC, MP3, etc.) require frames with a specific number
+ * 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
+ * ```typescript
+ * import { AudioFrameBuffer } from 'node-av/api';
+ *
+ * // Create buffer for 480-sample frames (e.g., Opus at 24kHz)
+ * using buffer = AudioFrameBuffer.create(480, AV_SAMPLE_FMT_FLT, 48000, 'mono', 1);
+ *
+ * // Push variable-sized frames from filter
+ * for await (const frame of filterOutput) {
+ *   await buffer.push(frame);
+ *
+ *   // Pull fixed-size frames for encoder
+ *   let outputFrame;
+ *   while ((outputFrame = await buffer.pull()) !== null) {
+ *     await encoder.encode(outputFrame);
+ *     outputFrame.free();
+ *   }
+ * }
+ *
+ * // 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 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
+     *
+     * @param frameSize - Number of samples per output frame
+     *
+     * @param sampleFormat - Audio sample format
+     *
+     * @param sampleRate - Sample rate in Hz
+     *
+     * @param channelLayout - Channel layout
+     *
+     * @param options - Timing options
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create an audio frame buffer.
+     *
+     * @param frameSize - Required frame size in samples
+     *
+     * @param sampleFormat - Audio sample format
+     *
+     * @param sampleRate - Sample rate in Hz
+     *
+     * @param channelLayout - Channel layout (e.g., 'mono', 'stereo')
+     *
+     * @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, options?: AudioFrameBufferOptions): AudioFrameBuffer;
+    /**
+     * Get number of samples currently in buffer.
+     *
+     * Includes silence inserted for gaps in the input.
+     *
+     * @returns Number of buffered samples
+     *
+     * @example
+     * ```typescript
+     * console.log(`Buffer contains ${buffer.size} samples`);
+     * ```
+     */
+    get size(): number;
+    /**
+     * Check if a complete frame is available.
+     *
+     * Returns true if the buffer holds at least frameSize samples.
+     *
+     * @returns True if a full frame can be pulled
+     *
+     * @example
+     * ```typescript
+     * while (buffer.hasFrame()) {
+     *   const frame = buffer.pull();
+     *   // Process frame...
+     * }
+     * ```
+     */
+    hasFrame(): boolean;
+    /**
+     * Push an audio frame into the buffer asynchronously.
+     *
+     * 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);
+     * ```
+     *
+     * @see {@link pushSync} For synchronous version
+     */
+    push(frame: Frame): Promise<void>;
+    /**
+     * Push an audio frame into the buffer synchronously.
+     * Synchronous version of push.
+     *
+     * 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);
+     * ```
+     *
+     * @see {@link push} For async version
+     */
+    pushSync(frame: Frame): void;
+    /**
+     * Pull a fixed-size audio frame from the buffer asynchronously.
+     *
+     * 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
+     * ```typescript
+     * using frame = await buffer.pull();
+     * if (frame) {
+     *   await encoder.encode(frame);
+     * }
+     * ```
+     *
+     * @see {@link pullSync} For synchronous version
+     */
+    pull(): Promise<Frame | null>;
+    /**
+     * 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
+     * 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
+     * ```typescript
+     * using frame = buffer.pullSync();
+     * if (frame) {
+     *   encoder.encodeSync(frame);
+     * }
+     * ```
+     *
+     * @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.
+     *
+     * @example
+     * ```typescript
+     * buffer.free();
+     * ```
+     */
+    [Symbol.dispose](): void;
+}