node-av 5.2.4-beta.1 → 6.0.0-beta.10

package/dist/api/encoder-pool.js

@@ -0,0 +1,285 @@
+import { Encoder } from './encoder.js';
+/**
+ * Bounded LRU pool of image encoders keyed by resolution and pixel format.
+ *
+ * A single encoder cannot change dimensions after opening, so encoding frames of
+ * varying sizes needs one encoder per resolution. This pool routes each frame to
+ * the encoder matching its `width x height x pixelFormat`, creating one on demand
+ * and reusing it afterwards. Each frame is given a monotonic PTS internally, so
+ * callers can feed independent snapshots without managing timestamps.
+ *
+ * Pooled encoders are never flushed between frames, so this only suits intra-only
+ * image codecs (MJPEG, PNG, WebP, ...). Hardware frames work as-is: the encoder
+ * adopts the frame's hardware context. For a single one-off conversion use
+ * {@link Encoder.encodeOne} instead.
+ *
+ * @example
+ * ```typescript
+ * import { EncoderPool } from 'node-av/api';
+ * import { FF_ENCODER_MJPEG } from 'node-av/constants';
+ *
+ * using pool = new EncoderPool(FF_ENCODER_MJPEG);
+ * const a = await pool.encode(frame1920); // opens + caches
+ * const b = await pool.encode(frame640);  // opens + caches
+ * const c = await pool.encode(frame1920); // reuses, no open
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // MJPEG quality: set the QSCALE flag on the pool, then carry the quality on
+ * // each frame (qscale 2 = best, 31 = worst). The `q` private option has no
+ * // effect on MJPEG.
+ * import { AV_CODEC_FLAG_QSCALE, FF_QP2LAMBDA } from 'node-av/constants';
+ *
+ * using pool = new EncoderPool(FF_ENCODER_MJPEG, { maxSize: 4, flags: AV_CODEC_FLAG_QSCALE });
+ * frame.quality = 3 * FF_QP2LAMBDA;
+ * const jpeg = await pool.encode(frame);
+ * ```
+ *
+ * @see {@link Encoder.encodeOne} For a one-shot, stateless single-frame encode
+ */
+export class EncoderPool {
+    encoderCodec;
+    options;
+    maxSize;
+    flags;
+    // Insertion order doubles as LRU order: touched entries move to the end,
+    // so the first key is always the least-recently-used.
+    encoders = new Map();
+    /**
+     * Create a new encoder pool.
+     *
+     * @param encoderCodec - Encoder codec applied to every pooled encoder
+     *
+     * @param options - Encoder options forwarded to each encoder, plus the optional `maxSize` limit
+     *
+     * @throws {Error} If maxSize is less than 1
+     *
+     * @example
+     * ```typescript
+     * using pool = new EncoderPool(FF_ENCODER_MJPEG, { maxSize: 4, flags: AV_CODEC_FLAG_QSCALE });
+     * ```
+     */
+    constructor(encoderCodec, options = {}) {
+        const { maxSize = 8, flags, ...encoderOptions } = options;
+        if (maxSize < 1) {
+            throw new Error(`EncoderPool maxSize must be at least 1, got ${maxSize}`);
+        }
+        this.encoderCodec = encoderCodec;
+        this.options = { threadCount: 1, ...encoderOptions };
+        this.maxSize = maxSize;
+        this.flags = flags === undefined ? [] : Array.isArray(flags) ? flags : [flags];
+    }
+    /**
+     * Number of encoders currently held alive.
+     *
+     * @example
+     * ```typescript
+     * console.log(`Pool holds ${pool.size} encoders`);
+     * ```
+     */
+    get size() {
+        return this.encoders.size;
+    }
+    /**
+     * Encode a frame into a self-contained image buffer.
+     *
+     * Routes the frame to the encoder matching its dimensions and pixel format,
+     * creating and caching one if necessary.
+     *
+     * @param frame - Frame to encode
+     *
+     * @returns Encoded image bytes
+     *
+     * @throws {FFmpegError} If the encoder is not found or encoding fails
+     *
+     * @throws {Error} If the encoder produced no output
+     *
+     * @example
+     * ```typescript
+     * const jpeg = await pool.encode(frame);
+     * ```
+     *
+     * @see {@link encodeSync} For synchronous version
+     */
+    async encode(frame) {
+        const key = this.keyFor(frame);
+        let pooled = this.touch(key);
+        if (!pooled) {
+            const encoder = await Encoder.create(this.encoderCodec, this.options);
+            pooled = this.touch(key);
+            if (pooled) {
+                encoder.close();
+            }
+            else {
+                pooled = this.set(key, encoder);
+            }
+        }
+        const savedPts = frame.pts;
+        frame.pts = pooled.nextPts++;
+        try {
+            return this.extract(await pooled.encoder.encodeAll(frame), pooled.encoder);
+        }
+        finally {
+            frame.pts = savedPts;
+        }
+    }
+    /**
+     * Encode a frame into a self-contained image buffer synchronously.
+     * Synchronous version of encode.
+     *
+     * @param frame - Frame to encode
+     *
+     * @returns Encoded image bytes
+     *
+     * @throws {FFmpegError} If the encoder is not found or encoding fails
+     *
+     * @throws {Error} If the encoder produced no output
+     *
+     * @example
+     * ```typescript
+     * const jpeg = pool.encodeSync(frame);
+     * ```
+     *
+     * @see {@link encode} For asynchronous version
+     */
+    encodeSync(frame) {
+        const key = this.keyFor(frame);
+        let pooled = this.touch(key);
+        pooled ??= this.set(key, Encoder.createSync(this.encoderCodec, this.options));
+        const savedPts = frame.pts;
+        frame.pts = pooled.nextPts++;
+        try {
+            return this.extract(pooled.encoder.encodeAllSync(frame), pooled.encoder);
+        }
+        finally {
+            frame.pts = savedPts;
+        }
+    }
+    /**
+     * Close all pooled encoders and clear the pool.
+     *
+     * Automatically called by Symbol.dispose.
+     *
+     * @example
+     * ```typescript
+     * pool.close();
+     * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
+     */
+    close() {
+        for (const { encoder } of this.encoders.values()) {
+            encoder.close();
+        }
+        this.encoders.clear();
+    }
+    /**
+     * Build the cache key from frame dimensions and pixel format.
+     *
+     * Pixel format is part of the key because the encoder is opened with the frame's
+     * format; a cached encoder for the same size but a different format would be invalid.
+     *
+     * @param frame - Frame to derive the key from
+     *
+     * @returns Cache key `width x height x pixelFormat`
+     *
+     * @internal
+     */
+    keyFor(frame) {
+        return `${frame.width}x${frame.height}x${frame.format}`;
+    }
+    /**
+     * Look up an encoder and mark it as most-recently-used.
+     *
+     * @param key - Cache key to look up
+     *
+     * @returns Pooled encoder, or undefined if not cached
+     *
+     * @internal
+     */
+    touch(key) {
+        const pooled = this.encoders.get(key);
+        if (pooled) {
+            this.encoders.delete(key);
+            this.encoders.set(key, pooled);
+        }
+        return pooled;
+    }
+    /**
+     * Insert a freshly created encoder, evicting the least-recently-used one if full.
+     *
+     * @param key - Cache key for the encoder
+     *
+     * @param encoder - Freshly created encoder to cache
+     *
+     * @returns The pooled encoder entry
+     *
+     * @internal
+     */
+    set(key, encoder) {
+        if (this.flags.length > 0) {
+            encoder.setCodecFlags(...this.flags);
+        }
+        const pooled = { encoder, nextPts: 0n };
+        this.encoders.set(key, pooled);
+        if (this.encoders.size > this.maxSize) {
+            const oldestKey = this.encoders.keys().next().value;
+            if (oldestKey !== undefined) {
+                const oldest = this.encoders.get(oldestKey);
+                this.encoders.delete(oldestKey);
+                oldest?.encoder.close();
+            }
+        }
+        return pooled;
+    }
+    /**
+     * Extract the encoded bytes from the produced packets and free them.
+     *
+     * packet.data returns a JS-owned copy, so the buffer stays valid after freeing.
+     *
+     * @param packets - Packets produced by the encoder
+     *
+     * @param encoder - Encoder that produced the packets (for error messages)
+     *
+     * @returns Encoded image bytes
+     *
+     * @throws {Error} If no packet was produced
+     *
+     * @internal
+     */
+    extract(packets, encoder) {
+        try {
+            const data = packets[0]?.data;
+            if (!data) {
+                throw new Error(`Encoder '${encoder.getCodec().name}' produced no output for frame`);
+            }
+            return data;
+        }
+        finally {
+            for (const packet of packets) {
+                packet.free();
+            }
+        }
+    }
+    /**
+     * Dispose of the pool.
+     *
+     * Implements Disposable interface for automatic cleanup.
+     * Equivalent to calling close().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using pool = new EncoderPool(FF_ENCODER_MJPEG, { maxSize: 4 });
+     *   // Encode frames...
+     * } // All encoders automatically closed
+     * ```
+     *
+     * @see {@link close} For manual cleanup
+     */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+//# sourceMappingURL=encoder-pool.js.map

package/dist/api/encoder-pool.js.map

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

package/dist/api/encoder.d.ts

@@ -3,7 +3,7 @@ import { Codec } from '../lib/codec.js';
 import { Frame } from '../lib/frame.js';
 import { Packet } from '../lib/packet.js';
 import { SchedulerControl } from './utilities/scheduler.js';
-import type { AVCodecFlag, AVCodecID, AVThreadType, EOFSignal, FFEncoderCodec } from '../constants/index.js';
+import type { AVCodecFlag, AVCodecID, AVThreadType, EncoderOptionsFor, EOFSignal, FFEncoderCodec } from '../constants/index.js';
 import type { Decoder } from './decoder.js';
 import type { FilterComplexAPI } from './filter-complex.js';
 import type { FilterAPI } from './filter.js';
@@ -11,7 +11,7 @@ import type { Muxer } from './muxer.js';
 /**
  * Options for encoder creation.
  */
-export interface EncoderOptions {
+export interface EncoderOptions<C = unknown> {
     /**
      * Target bitrate.
      *
@@ -90,13 +90,30 @@ export interface EncoderOptions {
      * @default FFmpeg default (both methods, codec chooses best)
      */
     threadType?: AVThreadType;
+    /**
+     * Automatically resample incoming audio to a format the codec supports.
+     *
+     * Audio encoders only accept specific sample rates, sample formats, and channel
+     * layouts (e.g. libmp3lame rejects 96 kHz; AAC needs planar `fltp`). When `true`,
+     * the encoder transparently converts each frame to the nearest supported
+     * sample rate / sample format / channel layout (like `ffmpeg`'s automatic
+     * `aresample`). When `false` (default), an unsupported input raises a descriptive
+     * error instead — keeping behaviour explicit and 1:1 with the codec.
+     *
+     * Has no effect on video.
+     *
+     * @default false
+     */
+    autoResample?: boolean;
     /**
      * Additional codec-specific options.
      *
-     * Key-value pairs of FFmpeg AVCodecContext options.
-     * These are passed directly to the encoder.
+     * Key-value pairs of FFmpeg private codec options, passed directly to the encoder.
+     * When the codec is created from a branded constant (e.g. `FF_ENCODER_LIBX264`),
+     * these are strongly typed to that codec's known options (autocomplete + validation);
+     * otherwise any string/number/boolean values are accepted.
      */
-    options?: Record<string, string | number | boolean | undefined | null>;
+    options?: EncoderOptionsFor<C>;
     /**
      * AbortSignal for cancellation.
      *
@@ -172,6 +189,10 @@ export declare class Encoder implements Disposable {
     private opts?;
     private options;
     private audioFrameBuffer?;
+    private autoResample;
+    private audioResampler?;
+    private resampledFrame?;
+    private audioInputLayout?;
     private inputQueue;
     private outputQueue;
     private workerPromise;
@@ -243,7 +264,7 @@ export declare class Encoder implements Disposable {
      * @see {@link EncoderOptions} For configuration options
      * @see {@link createSync} For synchronous version
      */
-    static create(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options?: EncoderOptions): Promise<Encoder>;
+    static create<const C extends FFEncoderCodec | AVCodecID | Codec>(encoderCodec: C, options?: EncoderOptions<C>): Promise<Encoder>;
     /**
      * Create an encoder with specified codec and options synchronously.
      * Synchronous version of create.
@@ -301,7 +322,65 @@ export declare class Encoder implements Disposable {
      * @see {@link EncoderOptions} For configuration options
      * @see {@link create} For async version
      */
-    static createSync(encoderCodec: FFEncoderCodec | AVCodecID | Codec, options?: EncoderOptions): Encoder;
+    static createSync<const C extends FFEncoderCodec | AVCodecID | Codec>(encoderCodec: C, options?: EncoderOptions<C>): Encoder;
+    /**
+     * Encode a single frame into a self-contained image buffer.
+     *
+     * One-shot, stateless helper for intra-only image codecs (MJPEG, PNG, WebP, ...).
+     * Creates a fresh encoder, encodes the frame, flushes and frees everything in one call.
+     * The encoder adopts dimensions, pixel format and hardware context from the frame,
+     * so any frame size works without reconfiguration.
+     *
+     * @param encoderCodec - Encoder codec (name, ID, branded constant, or Codec)
+     *
+     * @param frame - Frame to encode
+     *
+     * @param options - Optional encoder configuration (e.g. `{ options: { q: 3 } }` for MJPEG quality)
+     *
+     * @returns Encoded image bytes
+     *
+     * @throws {FFmpegError} If the encoder is not found or encoding fails
+     *
+     * @throws {Error} If the encoder produced no output
+     *
+     * @example
+     * ```typescript
+     * const jpeg = await Encoder.encodeOne(FF_ENCODER_MJPEG, frame, { options: { q: 3 } });
+     * ```
+     *
+     * @see {@link EncoderPool} For reusing encoders across recurring resolutions
+     */
+    static encodeOne<const C extends FFEncoderCodec | AVCodecID | Codec>(encoderCodec: C, frame: Frame, options?: EncoderOptions<C>): Promise<Buffer>;
+    /**
+     * Encode a single frame into a self-contained image buffer synchronously.
+     * Synchronous version of encodeOne.
+     *
+     * One-shot, stateless helper for intra-only image codecs (MJPEG, PNG, WebP, ...).
+     * Creates a fresh encoder, encodes the frame, flushes and frees everything in one call.
+     * The encoder adopts dimensions, pixel format and hardware context from the frame,
+     * so any frame size works without reconfiguration.
+     *
+     * @param encoderCodec - Encoder codec (name, ID, branded constant, or Codec)
+     *
+     * @param frame - Frame to encode
+     *
+     * @param options - Optional encoder configuration (e.g. `{ options: { q: 3 } }` for MJPEG quality)
+     *
+     * @returns Encoded image bytes
+     *
+     * @throws {FFmpegError} If the encoder is not found or encoding fails
+     *
+     * @throws {Error} If the encoder produced no output
+     *
+     * @example
+     * ```typescript
+     * const jpeg = Encoder.encodeOneSync(FF_ENCODER_MJPEG, frame, { options: { q: 3 } });
+     * ```
+     *
+     * @see {@link encodeOne} For async version
+     * @see {@link EncoderPool} For reusing encoders across recurring resolutions
+     */
+    static encodeOneSync<const C extends FFEncoderCodec | AVCodecID | Codec>(encoderCodec: C, frame: Frame, options?: EncoderOptions<C>): Buffer;
     /**
      * Check if encoder is open.
      *
@@ -1096,6 +1175,53 @@ export declare class Encoder implements Disposable {
      * @internal
      */
     private setupHardwareAcceleration;
+    /**
+     * Configure the codec context's audio parameters from the first frame.
+     *
+     * Audio encoders only accept specific sample rates / sample formats / channel
+     * layouts. This picks codec-supported targets; if they differ from the input it
+     * either sets up a resampler (when `autoResample`) or throws a descriptive error.
+     *
+     * @param frame - First audio frame
+     *
+     * @throws {Error} If the input is unsupported and `autoResample` is disabled
+     *
+     * @throws {FFmpegError} If the resampler fails to configure
+     *
+     * @internal
+     */
+    private setupAudioParams;
+    /**
+     * Lazily allocate the reused resampler output frame.
+     *
+     * @returns The allocated output frame
+     *
+     * @internal
+     */
+    private getResampleFrame;
+    /**
+     * Resample an incoming audio frame to the codec's target format.
+     *
+     * Reuses a single output frame; `swr_convert_frame` allocates/sizes its buffer.
+     * The (fixed-frame-size) audio FIFO copies the samples and re-stamps PTS, so the
+     * reused frame and its carried timing are only relevant on the non-FIFO path.
+     *
+     * @param frame - Source audio frame
+     *
+     * @returns The resampled frame (owned by the encoder, reused across calls)
+     *
+     * @internal
+     */
+    private resampleAudio;
+    /**
+     * Drain samples buffered inside the resampler (rate-conversion delay) into the
+     * encoder path. Returns the drained frame if any, else null.
+     *
+     * @returns The drained frame (reused), or null when the resampler is empty
+     *
+     * @internal
+     */
+    private drainResampler;
     /**
      * Prepare frame for encoding.
      *