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

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.
      *

package/dist/api/encoder.js

@@ -389,6 +389,114 @@ export class Encoder {
         }
         return 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 async encodeOne(encoderCodec, frame, options = {}) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const encoder = __addDisposableResource(env_1, await Encoder.create(encoderCodec, options), false);
+            const packets = [...(await encoder.encodeAll(frame)), ...(await encoder.encodeAll(null))];
+            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();
+                }
+            }
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    /**
+     * 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(encoderCodec, frame, options = {}) {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const encoder = __addDisposableResource(env_2, Encoder.createSync(encoderCodec, options), false);
+            const packets = [...encoder.encodeAllSync(frame), ...encoder.encodeAllSync(null)];
+            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();
+                }
+            }
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            __disposeResources(env_2);
+        }
+    }
     /**
      * Check if encoder is open.
      *
@@ -912,9 +1020,9 @@ export class Encoder {
             return;
         }
         for await (const frame_1 of frames) {
-            const env_1 = { stack: [], error: void 0, hasError: false };
+            const env_3 = { stack: [], error: void 0, hasError: false };
             try {
-                const frame = __addDisposableResource(env_1, frame_1, false);
+                const frame = __addDisposableResource(env_3, frame_1, false);
                 this.signal?.throwIfAborted();
                 if (frame === null) {
                     yield* finalize();
@@ -922,12 +1030,12 @@ export class Encoder {
                 }
                 yield* processFrame(frame);
             }
-            catch (e_1) {
-                env_1.error = e_1;
-                env_1.hasError = true;
+            catch (e_3) {
+                env_3.error = e_3;
+                env_3.hasError = true;
             }
             finally {
-                __disposeResources(env_1);
+                __disposeResources(env_3);
             }
         }
     }
@@ -1023,9 +1131,9 @@ export class Encoder {
         }
         // Case 3: Iterable of frames
         for (const frame_2 of frames) {
-            const env_2 = { stack: [], error: void 0, hasError: false };
+            const env_4 = { stack: [], error: void 0, hasError: false };
             try {
-                const frame = __addDisposableResource(env_2, frame_2, false);
+                const frame = __addDisposableResource(env_4, frame_2, false);
                 // Check for EOF signal from upstream
                 if (frame === null) {
                     yield* finalize();
@@ -1033,12 +1141,12 @@ export class Encoder {
                 }
                 yield* processFrame(frame);
             }
-            catch (e_2) {
-                env_2.error = e_2;
-                env_2.hasError = true;
+            catch (e_4) {
+                env_4.error = e_4;
+                env_4.hasError = true;
             }
             finally {
-                __disposeResources(env_2);
+                __disposeResources(env_4);
             }
         }
         // No fallback flush - only flush on explicit EOF
@@ -1081,17 +1189,17 @@ export class Encoder {
             // For the final frame, we pad or truncate as needed
             let _bufferedFrame;
             while (!this.isClosed && (_bufferedFrame = await this.audioFrameBuffer.pull()) !== null) {
-                const env_3 = { stack: [], error: void 0, hasError: false };
+                const env_5 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const bufferedFrame = __addDisposableResource(env_3, _bufferedFrame, false);
+                    const bufferedFrame = __addDisposableResource(env_5, _bufferedFrame, false);
                     await this.codecContext.sendFrame(bufferedFrame);
                 }
-                catch (e_3) {
-                    env_3.error = e_3;
-                    env_3.hasError = true;
+                catch (e_5) {
+                    env_5.error = e_5;
+                    env_5.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_3);
+                    __disposeResources(env_5);
                 }
             }
         }
@@ -1141,17 +1249,17 @@ export class Encoder {
             // For the final frame, we pad or truncate as needed
             let _bufferedFrame;
             while (!this.isClosed && (_bufferedFrame = this.audioFrameBuffer.pullSync()) !== null) {
-                const env_4 = { stack: [], error: void 0, hasError: false };
+                const env_6 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const bufferedFrame = __addDisposableResource(env_4, _bufferedFrame, false);
+                    const bufferedFrame = __addDisposableResource(env_6, _bufferedFrame, false);
                     this.codecContext.sendFrameSync(bufferedFrame);
                 }
-                catch (e_4) {
-                    env_4.error = e_4;
-                    env_4.hasError = true;
+                catch (e_6) {
+                    env_6.error = e_6;
+                    env_6.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_4);
+                    __disposeResources(env_6);
                 }
             }
         }
@@ -1294,19 +1402,19 @@ export class Encoder {
         // Clear previous packet data
         this.packet.unref();
         if (this.audioFrameBuffer?.hasFrame()) {
-            const env_5 = { stack: [], error: void 0, hasError: false };
+            const env_7 = { stack: [], error: void 0, hasError: false };
             try {
-                const bufferedFrame = __addDisposableResource(env_5, await this.audioFrameBuffer.pull(), false);
+                const bufferedFrame = __addDisposableResource(env_7, await this.audioFrameBuffer.pull(), false);
                 if (bufferedFrame) {
                     await this.codecContext.sendFrame(bufferedFrame);
                 }
             }
-            catch (e_5) {
-                env_5.error = e_5;
-                env_5.hasError = true;
+            catch (e_7) {
+                env_7.error = e_7;
+                env_7.hasError = true;
             }
             finally {
-                __disposeResources(env_5);
+                __disposeResources(env_7);
             }
         }
         const ret = await this.codecContext.receivePacket(this.packet);
@@ -1399,19 +1507,19 @@ export class Encoder {
         // Clear previous packet data
         this.packet.unref();
         if (this.audioFrameBuffer?.hasFrame()) {
-            const env_6 = { stack: [], error: void 0, hasError: false };
+            const env_8 = { stack: [], error: void 0, hasError: false };
             try {
-                const bufferedFrame = __addDisposableResource(env_6, this.audioFrameBuffer.pullSync(), false);
+                const bufferedFrame = __addDisposableResource(env_8, this.audioFrameBuffer.pullSync(), false);
                 if (bufferedFrame) {
                     this.codecContext.sendFrameSync(bufferedFrame);
                 }
             }
-            catch (e_6) {
-                env_6.error = e_6;
-                env_6.hasError = true;
+            catch (e_8) {
+                env_8.error = e_8;
+                env_8.hasError = true;
             }
             finally {
-                __disposeResources(env_6);
+                __disposeResources(env_8);
             }
         }
         const ret = this.codecContext.receivePacketSync(this.packet);
@@ -1541,9 +1649,9 @@ export class Encoder {
         try {
             // Outer loop - receive frames
             while (!this.inputQueue.isClosed) {
-                const env_7 = { stack: [], error: void 0, hasError: false };
+                const env_9 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const frame = __addDisposableResource(env_7, await this.inputQueue.receive(), false);
+                    const frame = __addDisposableResource(env_9, await this.inputQueue.receive(), false);
                     if (!frame)
                         break;
                     // Open encoder if not already done
@@ -1562,12 +1670,12 @@ export class Encoder {
                         await this.outputQueue.send(packet); // Only send actual packets
                     }
                 }
-                catch (e_7) {
-                    env_7.error = e_7;
-                    env_7.hasError = true;
+                catch (e_9) {
+                    env_9.error = e_9;
+                    env_9.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_7);
+                    __disposeResources(env_9);
                 }
             }
             // Flush encoder at end