node-av 6.0.0-beta.6 → 6.0.0-beta.8

package/dist/api/encoder-pool.d.ts

@@ -0,0 +1,220 @@
+import type { AVCodecFlag, AVCodecID, FFEncoderCodec } from '../constants/index.js';
+import type { Codec } from '../lib/codec.js';
+import type { Frame } from '../lib/frame.js';
+import type { EncoderOptions } from './encoder.js';
+/**
+ * Options for encoder pool creation.
+ *
+ * Extends {@link EncoderOptions} with the pool size limit.
+ */
+export type EncoderPoolOptions<C = unknown> = EncoderOptions<C> & {
+    /**
+     * Maximum number of encoders kept alive at once.
+     *
+     * When exceeded, the least-recently-used encoder is closed. In the worst case
+     * (every frame a unique size) the pool degrades to per-frame open/close, never leaking.
+     *
+     * @default 8
+     */
+    maxSize?: number;
+    /**
+     * Codec flags applied to every pooled encoder before its first frame.
+     *
+     * Needed for flags that change encode behaviour, e.g. `AV_CODEC_FLAG_QSCALE` so
+     * MJPEG honours per-frame `frame.quality`.
+     */
+    flags?: AVCodecFlag | AVCodecFlag[];
+};
+/**
+ * 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 declare class EncoderPool<const C extends FFEncoderCodec | AVCodecID | Codec> implements Disposable {
+    private readonly encoderCodec;
+    private readonly options;
+    private readonly maxSize;
+    private readonly flags;
+    private readonly encoders;
+    /**
+     * 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: C, options?: EncoderPoolOptions<C>);
+    /**
+     * Number of encoders currently held alive.
+     *
+     * @example
+     * ```typescript
+     * console.log(`Pool holds ${pool.size} encoders`);
+     * ```
+     */
+    get size(): number;
+    /**
+     * 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
+     */
+    encode(frame: Frame): Promise<Buffer>;
+    /**
+     * 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: Frame): Buffer;
+    /**
+     * 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(): void;
+    /**
+     * 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
+     */
+    private keyFor;
+    /**
+     * 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
+     */
+    private touch;
+    /**
+     * 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
+     */
+    private set;
+    /**
+     * 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
+     */
+    private extract;
+    /**
+     * 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](): void;
+}

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

@@ -304,6 +304,64 @@ export declare class Encoder implements Disposable {
      * @see {@link create} For async version
      */
     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.
      *