node-av 3.1.3 → 4.0.0

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

@@ -0,0 +1,275 @@
+import { AudioFifo } from '../lib/audio-fifo.js';
+import { Frame } from '../lib/frame.js';
+/**
+ * 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.
+ *
+ * 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
+ * let outputFrame;
+ * while ((outputFrame = await buffer.pull()) !== null) {
+ *   await encoder.encode(outputFrame);
+ *   outputFrame.free();
+ * }
+ * ```
+ */
+export class AudioFrameBuffer {
+    fifo;
+    frame;
+    frameSize;
+    nextPts = 0n;
+    firstFramePts = null;
+    /**
+     * @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
+     *
+     * @internal
+     */
+    constructor(fifo, frameSize, sampleFormat, sampleRate, channelLayout) {
+        this.fifo = fifo;
+        this.frameSize = frameSize;
+        this.frame = new Frame();
+        this.frame.alloc();
+        this.frame.nbSamples = frameSize;
+        this.frame.format = sampleFormat;
+        this.frame.sampleRate = sampleRate;
+        this.frame.channelLayout = channelLayout;
+        this.frame.getBuffer(0); // Allocate buffer once
+    }
+    /**
+     * 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
+     *
+     * @returns Configured audio frame buffer
+     *
+     * @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, sampleFormat, sampleRate, channelLayout, channels) {
+        const fifo = new AudioFifo();
+        // Allocate FIFO with capacity for multiple frames
+        fifo.alloc(sampleFormat, channels, frameSize * 4);
+        return new AudioFrameBuffer(fifo, frameSize, sampleFormat, sampleRate, channelLayout);
+    }
+    /**
+     * Get number of samples currently in buffer.
+     *
+     * @returns Number of buffered samples
+     *
+     * @example
+     * ```typescript
+     * console.log(`Buffer contains ${buffer.size} samples`);
+     * ```
+     */
+    get size() {
+        return this.fifo.size;
+    }
+    /**
+     * Check if a complete frame is available.
+     *
+     * Returns true if the FIFO contains 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() {
+        return this.fifo.size >= this.frameSize;
+    }
+    /**
+     * 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.
+     *
+     * @param frame - Audio frame to buffer
+     *
+     * @example
+     * ```typescript
+     * await buffer.push(filterFrame);
+     * ```
+     *
+     * @see {@link pushSync} For synchronous version
+     */
+    async push(frame) {
+        if (!frame.isAudio()) {
+            throw new Error('AudioFrameBuffer.push() requires an audio frame');
+        }
+        if (this.firstFramePts === null) {
+            // Always start PTS from 0 for encoder frames
+            // Input frames may be in different timebase than encoder expects
+            this.firstFramePts = 0n;
+            this.nextPts = 0n;
+        }
+        // Write frame data to FIFO
+        await this.fifo.write(frame.data, frame.nbSamples);
+    }
+    /**
+     * 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.
+     *
+     * @param frame - Audio frame to buffer
+     *
+     * @example
+     * ```typescript
+     * buffer.pushSync(filterFrame);
+     * ```
+     *
+     * @see {@link push} For async version
+     */
+    pushSync(frame) {
+        if (!frame.isAudio()) {
+            throw new Error('AudioFrameBuffer.pushSync() requires an audio frame');
+        }
+        if (this.firstFramePts === null) {
+            // Always start PTS from 0 for encoder frames
+            // Input frames may be in different timebase than encoder expects
+            this.firstFramePts = 0n;
+            this.nextPts = 0n;
+        }
+        // Write frame data to FIFO
+        this.fifo.writeSync(frame.data, frame.nbSamples);
+    }
+    /**
+     * Pull a fixed-size audio frame from the buffer asynchronously.
+     *
+     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame.
+     * 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
+     *
+     * @example
+     * ```typescript
+     * using frame = await buffer.pull();
+     * if (frame) {
+     *   await encoder.encode(frame);
+     * }
+     * ```
+     *
+     * @see {@link pullSync} For synchronous version
+     */
+    async pull() {
+        if (!this.hasFrame()) {
+            return null;
+        }
+        // Update PTS
+        this.frame.pts = this.nextPts;
+        // Read samples from FIFO into reusable frame
+        await this.fifo.read(this.frame.data, this.frameSize);
+        // Update PTS for next frame
+        this.nextPts += BigInt(this.frameSize);
+        // Clone frame for user (like Decoder does)
+        return this.frame.clone();
+    }
+    /**
+     * 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.
+     * 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
+     *
+     * @example
+     * ```typescript
+     * using frame = buffer.pullSync();
+     * if (frame) {
+     *   encoder.encodeSync(frame);
+     * }
+     * ```
+     *
+     * @see {@link pull} For async version
+     */
+    pullSync() {
+        if (!this.hasFrame()) {
+            return null;
+        }
+        // Update PTS
+        this.frame.pts = this.nextPts;
+        // Read samples from FIFO into reusable frame
+        this.fifo.readSync(this.frame.data, this.frameSize);
+        // Update PTS for next frame
+        this.nextPts += BigInt(this.frameSize);
+        // Clone frame for user (like Decoder does)
+        return this.frame.clone();
+    }
+    /**
+     * Reset the buffer, discarding all buffered samples.
+     *
+     * @example
+     * ```typescript
+     * buffer.reset();
+     * ```
+     */
+    reset() {
+        this.fifo.reset();
+        this.nextPts = 0n;
+        this.firstFramePts = null;
+    }
+    /**
+     * Free the buffer and all resources.
+     *
+     * @example
+     * ```typescript
+     * buffer.free();
+     * ```
+     */
+    [Symbol.dispose]() {
+        this.frame.free();
+        this.fifo[Symbol.dispose]();
+    }
+}
+//# sourceMappingURL=audio-frame-buffer.js.map

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

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