node-av 4.0.0 → 5.0.0

package/dist/api/encoder.js

@@ -50,11 +50,12 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE, AV_CODEC_CAP_PARAM_CHANGE, AV_CODEC_FLAG_COPY_OPAQUE, AV_CODEC_FLAG_FRAME_DURATION, AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX, AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, AV_PIX_FMT_NONE, AV_PKT_FLAG_TRUSTED, AVCHROMA_LOC_UNSPECIFIED, AVERROR_EAGAIN, AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, } from '../constants/constants.js';
+import { AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE, AV_CODEC_CAP_PARAM_CHANGE, AV_CODEC_FLAG_COPY_OPAQUE, AV_CODEC_FLAG_FRAME_DURATION, AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX, AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, AV_PICTURE_TYPE_NONE, AV_PIX_FMT_NONE, AV_PKT_FLAG_TRUSTED, AVCHROMA_LOC_UNSPECIFIED, AVERROR_EAGAIN, AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO, EOF, } from '../constants/constants.js';
 import { CodecContext } from '../lib/codec-context.js';
 import { Codec } from '../lib/codec.js';
 import { Dictionary } from '../lib/dictionary.js';
 import { FFmpegError } from '../lib/error.js';
+import { Frame } from '../lib/frame.js';
 import { Packet } from '../lib/packet.js';
 import { Rational } from '../lib/rational.js';
 import { avRescaleQ } from '../lib/utilities.js';
@@ -542,28 +543,31 @@ export class Encoder {
         return this.initialized && !this.isClosed;
     }
     /**
-     * Encode a frame to a packet.
+     * Send a frame to the encoder.
      *
-     * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * Sends a raw frame to the encoder for encoding.
+     * Does not return encoded packets - use {@link receive} to retrieve packets.
      * On first frame, automatically initializes encoder with frame properties.
-     * Handles internal buffering - may return null if more frames needed.
+     * A single frame can produce zero, one, or multiple packets depending on codec buffering.
      *
-     * **Note**: This method receives only ONE packet per call.
-     * A single frame can produce multiple packets (e.g., B-frames, codec buffering).
-     * To receive all packets from a frame, use {@link encodeAll} or {@link packets} instead.
+     * **Important**: This method only SENDS the frame to the encoder.
+     * You must call {@link receive} separately (potentially multiple times) to get encoded packets.
      *
-     * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
-     *
-     * @param frame - Raw frame to encode (or null to flush)
+     * Direct mapping to avcodec_send_frame().
      *
-     * @returns Encoded packet, null if more data needed, or null if encoder is closed
+     * @param frame - Raw frame to send to encoder
      *
-     * @throws {FFmpegError} If encoding fails
+     * @throws {FFmpegError} If sending frame fails
      *
      * @example
      * ```typescript
-     * const packet = await encoder.encode(frame);
-     * if (packet) {
+     * // Send frame and receive packets
+     * await encoder.encode(frame);
+     *
+     * // Receive all available packets
+     * while (true) {
+     *   const packet = await encoder.receive();
+     *   if (!packet) break;
      *   console.log(`Encoded packet with PTS: ${packet.pts}`);
      *   await output.writePacket(packet);
      *   packet.free();
@@ -572,10 +576,13 @@ export class Encoder {
      *
      * @example
      * ```typescript
-     * // Encode loop
      * for await (const frame of decoder.frames(input.packets())) {
-     *   const packet = await encoder.encode(frame);
-     *   if (packet) {
+     *   // Send frame
+     *   await encoder.encode(frame);
+     *
+     *   // Receive available packets
+     *   let packet;
+     *   while ((packet = await encoder.receive())) {
      *     await output.writePacket(packet);
      *     packet.free();
      *   }
@@ -583,131 +590,98 @@ export class Encoder {
      * }
      * ```
      *
-     * @see {@link encodeAll} For multiple packet encoding
+     * @see {@link receive} For receiving encoded packets
+     * @see {@link encodeAll} For combined send+receive operation
      * @see {@link packets} For automatic frame iteration
      * @see {@link flush} For end-of-stream handling
      * @see {@link encodeSync} For synchronous version
      */
     async encode(frame) {
         if (this.isClosed) {
-            return null;
+            return;
         }
         // Open encoder if not already done
-        if (!this.initialized) {
-            if (!frame) {
-                return null;
-            }
-            this.initializePromise ??= this.initialize(frame);
-        }
+        this.initializePromise ??= this.initialize(frame);
         await this.initializePromise;
         // Prepare frame for encoding (set quality, validate channel count)
-        if (frame) {
-            this.prepareFrameForEncoding(frame);
-        }
-        // Send frame to encoder
-        const sendRet = await this.codecContext.sendFrame(frame);
-        // Handle EAGAIN: encoder buffer is full, need to read packets first
-        // Unlike FFmpeg CLI which reads ALL packets in a loop, our encode() returns
-        // only one packet at a time. This means the encoder can still have packets
-        // from previous frames when we try to send a new frame.
-        if (sendRet === AVERROR_EAGAIN) {
-            // Encoder is full, receive a packet first
-            const packet = await this.receive();
-            if (packet) {
-                return packet;
+        this.prepareFrameForEncoding(frame);
+        const encode = async (newFrame) => {
+            const sendRet = await this.codecContext.sendFrame(newFrame);
+            if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+                FFmpegError.throwIfError(sendRet, 'Failed to send frame to encoder');
+                return;
             }
-            // If receive() returned null, this is unexpected - treat as error
-            throw new Error('Encoder returned EAGAIN but no packet available');
+        };
+        if (this.audioFrameBuffer) {
+            // Push frame into buffer - actual sending happens in receive()
+            await this.audioFrameBuffer.push(frame);
         }
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            FFmpegError.throwIfError(sendRet, 'Failed to send frame');
+        else {
+            await encode(frame);
         }
-        // Try to receive packet
-        return await this.receive();
     }
     /**
-     * Encode a frame to a packet synchronously.
+     * Send a frame to the encoder synchronously.
      * Synchronous version of encode.
      *
-     * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * Sends a raw frame to the encoder for encoding.
+     * Does not return encoded packets - use {@link receiveSync} to retrieve packets.
      * On first frame, automatically initializes encoder with frame properties.
-     * Handles internal buffering - may return null if more frames needed.
-     *
-     * **Note**: This method receives only ONE packet per call.
-     * A single frame can produce multiple packets (e.g., B-frames, codec buffering).
-     * To receive all packets from a frame, use {@link encodeAllSync} or {@link packetsSync} instead.
+     * A single frame can produce zero, one, or multiple packets depending on codec buffering.
      *
-     * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
+     * **Important**: This method only SENDS the frame to the encoder.
+     * You must call {@link receiveSync} separately (potentially multiple times) to get encoded packets.
      *
-     * @param frame - Raw frame to encode (or null to flush)
+     * Direct mapping to avcodec_send_frame().
      *
-     * @returns Encoded packet, null if more data needed, or null if encoder is closed
+     * @param frame - Raw frame to send to encoder
      *
-     * @throws {FFmpegError} If encoding fails
+     * @throws {FFmpegError} If sending frame fails
      *
      * @example
      * ```typescript
-     * const packet = encoder.encodeSync(frame);
-     * if (packet) {
+     * // Send frame and receive packets
+     * encoder.encodeSync(frame);
+     *
+     * // Receive all available packets
+     * let packet;
+     * while ((packet = encoder.receiveSync())) {
      *   console.log(`Encoded packet with PTS: ${packet.pts}`);
      *   output.writePacketSync(packet);
      *   packet.free();
      * }
      * ```
      *
-     * @example
-     * ```typescript
-     * // Encode loop
-     * for (const frame of decoder.framesSync(packets)) {
-     *   const packet = encoder.encodeSync(frame);
-     *   if (packet) {
-     *     output.writePacketSync(packet);
-     *     packet.free();
-     *   }
-     *   frame.free();
-     * }
-     * ```
-     *
-     * @see {@link encodeAllSync} For multiple packet encoding
+     * @see {@link receiveSync} For receiving encoded packets
+     * @see {@link encodeAllSync} For combined send+receive operation
      * @see {@link packetsSync} For automatic frame iteration
      * @see {@link flushSync} For end-of-stream handling
      * @see {@link encode} For async version
      */
     encodeSync(frame) {
         if (this.isClosed) {
-            return null;
+            return;
         }
         // Open encoder if not already done
         if (!this.initialized) {
-            if (!frame) {
-                return null;
-            }
             this.initializeSync(frame);
         }
         // Prepare frame for encoding (set quality, validate channel count)
-        if (frame) {
-            this.prepareFrameForEncoding(frame);
-        }
-        // Send frame to encoder
-        const sendRet = this.codecContext.sendFrameSync(frame);
-        // Handle EAGAIN: encoder buffer is full, need to read packets first
-        // Unlike FFmpeg CLI which reads ALL packets in a loop, our encode() returns
-        // only one packet at a time. This means the encoder can still have packets
-        // from previous frames when we try to send a new frame.
-        if (sendRet === AVERROR_EAGAIN) {
-            // Encoder is full, receive a packet first
-            const packet = this.receiveSync();
-            if (packet) {
-                return packet;
+        this.prepareFrameForEncoding(frame);
+        const encode = (newFrame) => {
+            const sendRet = this.codecContext.sendFrameSync(newFrame);
+            if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+                FFmpegError.throwIfError(sendRet, 'Failed to send frame to encoder');
+                return;
             }
-            // If receive() returned null, this is unexpected - treat as error
-            throw new Error('Encoder returned EAGAIN but no packet available');
+        };
+        if (this.audioFrameBuffer) {
+            // Push frame into buffer - actual sending happens in receiveSync()
+            this.audioFrameBuffer.pushSync(frame);
         }
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            FFmpegError.throwIfError(sendRet, 'Failed to send frame');
+        else {
+            encode(frame);
         }
-        // Try to receive packet
-        return this.receiveSync();
     }
     /**
      * Encode a frame to packets.
@@ -754,68 +728,19 @@ export class Encoder {
      * @see {@link encodeAllSync} For synchronous version
      */
     async encodeAll(frame) {
-        if (this.isClosed) {
-            return [];
-        }
-        // Open encoder if not already done
-        if (!this.initialized) {
-            if (!frame) {
-                return [];
-            }
-            this.initializePromise ??= this.initialize(frame);
-        }
-        await this.initializePromise;
-        // Prepare frame for encoding (set quality, validate channel count)
         if (frame) {
-            this.prepareFrameForEncoding(frame);
-        }
-        // If audio encoder with fixed frame size, use AudioFrameBuffer
-        if (this.audioFrameBuffer && frame) {
-            // Push frame into buffer
-            await this.audioFrameBuffer.push(frame);
-            // Pull and encode all available fixed-size frames
-            const packets = [];
-            let _bufferedFrame;
-            while (!this.isClosed && (_bufferedFrame = await this.audioFrameBuffer.pull()) !== null) {
-                const env_1 = { stack: [], error: void 0, hasError: false };
-                try {
-                    const bufferedFrame = __addDisposableResource(env_1, _bufferedFrame, false);
-                    // Send buffered frame to encoder
-                    const sendRet = await this.codecContext.sendFrame(bufferedFrame);
-                    if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
-                        FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-                    }
-                    // Receive packets
-                    while (true) {
-                        const packet = await this.receive();
-                        if (!packet)
-                            break;
-                        packets.push(packet);
-                    }
-                }
-                catch (e_1) {
-                    env_1.error = e_1;
-                    env_1.hasError = true;
-                }
-                finally {
-                    __disposeResources(env_1);
-                }
-            }
-            return packets;
+            await this.encode(frame);
         }
-        // Send frame first, error immediately if send fails
-        const sendRet = await this.codecContext.sendFrame(frame);
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            FFmpegError.throwIfError(sendRet, 'Failed to send frame to encoder');
-            return [];
+        else {
+            await this.flush();
         }
         // Receive all available packets
         const packets = [];
         while (true) {
             const packet = await this.receive();
             if (!packet)
-                break;
-            packets.push(packet);
+                break; // Stop on EAGAIN or EOF
+            packets.push(packet); // Only push actual packets
         }
         return packets;
     }
@@ -865,67 +790,19 @@ export class Encoder {
      * @see {@link encodeAll} For async version
      */
     encodeAllSync(frame) {
-        if (this.isClosed) {
-            return [];
-        }
-        // Open encoder if not already done
-        if (!this.initialized) {
-            if (!frame) {
-                return [];
-            }
-            this.initializeSync(frame);
-        }
-        // Prepare frame for encoding (set quality, validate channel count)
         if (frame) {
-            this.prepareFrameForEncoding(frame);
+            this.encodeSync(frame);
         }
-        // If audio encoder with fixed frame size, use AudioFrameBuffer
-        if (this.audioFrameBuffer && frame) {
-            // Push frame into buffer
-            this.audioFrameBuffer.pushSync(frame);
-            // Pull and encode all available fixed-size frames
-            const packets = [];
-            let _bufferedFrame;
-            while (!this.isClosed && (_bufferedFrame = this.audioFrameBuffer.pullSync()) !== null) {
-                const env_2 = { stack: [], error: void 0, hasError: false };
-                try {
-                    const bufferedFrame = __addDisposableResource(env_2, _bufferedFrame, false);
-                    // Send buffered frame to encoder
-                    const sendRet = this.codecContext.sendFrameSync(bufferedFrame);
-                    if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
-                        FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-                    }
-                    // Receive packets
-                    while (true) {
-                        const packet = this.receiveSync();
-                        if (!packet)
-                            break;
-                        packets.push(packet);
-                    }
-                }
-                catch (e_2) {
-                    env_2.error = e_2;
-                    env_2.hasError = true;
-                }
-                finally {
-                    __disposeResources(env_2);
-                }
-            }
-            return packets;
-        }
-        // Send frame first, error immediately if send fails
-        const sendRet = this.codecContext.sendFrameSync(frame);
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            FFmpegError.throwIfError(sendRet, 'Failed to send frame to encoder');
-            return [];
+        else {
+            this.flushSync();
         }
         // Receive all available packets
         const packets = [];
         while (true) {
             const packet = this.receiveSync();
             if (!packet)
-                break;
-            packets.push(packet);
+                break; // Stop on EAGAIN or EOF
+            packets.push(packet); // Only push actual packets
         }
         return packets;
     }
@@ -933,20 +810,28 @@ export class Encoder {
      * Encode frame stream to packet stream.
      *
      * High-level async generator for complete encoding pipeline.
-     * Automatically manages frame memory, encoder state,
-     * and flushes buffered packets at end.
+     * Encoder is only flushed when EOF (null) signal is explicitly received.
      * Primary interface for stream-based encoding.
      *
-     * @param frames - Async iterable of frames (freed automatically)
+     * **EOF Handling:**
+     * - Send null to flush encoder and get remaining buffered packets
+     * - Generator yields null after flushing when null is received
+     * - No automatic flushing - encoder stays open until EOF or close()
+     *
+     * @param frames - Async iterable of frames, single frame, or null to flush
      *
-     * @yields {Packet} Encoded packets (caller must free)
+     * @yields {Packet | null} Encoded packets, followed by null when explicitly flushed
      *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
      * ```typescript
-     * // Basic encoding pipeline
+     * // Stream of frames with automatic EOF propagation
      * for await (const packet of encoder.packets(decoder.frames(input.packets()))) {
+     *   if (packet === null) {
+     *     console.log('Encoder flushed');
+     *     break;
+     *   }
      *   await output.writePacket(packet);
      *   packet.free(); // Must free output packets
      * }
@@ -954,35 +839,26 @@ export class Encoder {
      *
      * @example
      * ```typescript
-     * // With frame filtering
-     * async function* filteredFrames() {
-     *   for await (const frame of decoder.frames(input.packets())) {
-     *     const filtered = await filter.process(frame);
-     *     if (filtered) {
-     *       yield filtered;
-     *     }
-     *     frame.free();
-     *   }
-     * }
-     *
-     * for await (const packet of encoder.packets(filteredFrames())) {
+     * // Single frame - no automatic flush
+     * for await (const packet of encoder.packets(singleFrame)) {
      *   await output.writePacket(packet);
      *   packet.free();
      * }
+     * // Encoder remains open, buffered packets not flushed
      * ```
      *
      * @example
      * ```typescript
-     * // Pipeline integration
-     * import { pipeline } from 'node-av/api';
-     *
-     * const control = pipeline(
-     *   input,
-     *   decoder,
-     *   encoder,
-     *   output
-     * );
-     * await control.completion;
+     * // Explicit flush with EOF
+     * for await (const packet of encoder.packets(null)) {
+     *   if (packet === null) {
+     *     console.log('All buffered packets flushed');
+     *     break;
+     *   }
+     *   console.log('Buffered packet:', packet.pts);
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
      * ```
      *
      * @see {@link encode} For single frame encoding
@@ -990,123 +866,76 @@ export class Encoder {
      * @see {@link packetsSync} For sync version
      */
     async *packets(frames) {
-        // Process frames
+        const self = this;
+        const processFrame = async function* (frame) {
+            await self.encode(frame);
+            while (true) {
+                const packet = await self.receive();
+                if (!packet)
+                    break;
+                yield packet;
+            }
+        }.bind(this);
+        const finalize = async function* () {
+            for await (const remaining of self.flushPackets()) {
+                yield remaining;
+            }
+            yield null;
+        }.bind(this);
+        if (frames === null) {
+            yield* finalize();
+            return;
+        }
+        if (frames instanceof Frame) {
+            yield* processFrame(frames);
+            return;
+        }
         for await (const frame_1 of frames) {
-            const env_3 = { stack: [], error: void 0, hasError: false };
+            const env_1 = { stack: [], error: void 0, hasError: false };
             try {
-                const frame = __addDisposableResource(env_3, frame_1, false);
-                // Handle EOF signal
+                const frame = __addDisposableResource(env_1, frame_1, false);
                 if (frame === null) {
-                    // Flush encoder (audio frame buffer doesn't need explicit flush)
-                    await this.flush();
-                    while (true) {
-                        const remaining = await this.receive();
-                        if (!remaining)
-                            break;
-                        yield remaining;
-                    }
-                    // Signal EOF and stop processing
-                    yield null;
+                    yield* finalize();
                     return;
                 }
-                if (this.isClosed) {
-                    break;
-                }
-                // Open encoder if not already done
-                if (!this.initialized) {
-                    this.initializePromise ??= this.initialize(frame);
-                }
-                await this.initializePromise;
-                // Prepare frame for encoding (set quality, validate channel count)
-                if (frame) {
-                    this.prepareFrameForEncoding(frame);
-                }
-                // If audio encoder with fixed frame size, use AudioFrameBuffer
-                if (this.audioFrameBuffer) {
-                    // Push frame into buffer
-                    await this.audioFrameBuffer.push(frame);
-                    // Pull and encode all available fixed-size frames
-                    let _bufferedFrame;
-                    while (!this.isClosed && (_bufferedFrame = await this.audioFrameBuffer.pull()) !== null) {
-                        const env_4 = { stack: [], error: void 0, hasError: false };
-                        try {
-                            const bufferedFrame = __addDisposableResource(env_4, _bufferedFrame, false);
-                            // Send buffered frame to encoder
-                            const sendRet = await this.codecContext.sendFrame(bufferedFrame);
-                            if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
-                                FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-                            }
-                            // Receive packets
-                            while (true) {
-                                const packet = await this.receive();
-                                if (!packet)
-                                    break;
-                                yield packet;
-                            }
-                        }
-                        catch (e_3) {
-                            env_4.error = e_3;
-                            env_4.hasError = true;
-                        }
-                        finally {
-                            __disposeResources(env_4);
-                        }
-                    }
-                }
-                else {
-                    // Send frame to encoder
-                    const sendRet = await this.codecContext.sendFrame(frame);
-                    if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
-                        FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-                    }
-                    // Receive ALL packets
-                    // A single frame can produce multiple packets (e.g., B-frames, lookahead)
-                    while (true) {
-                        const packet = await this.receive();
-                        if (!packet)
-                            break;
-                        yield packet;
-                    }
-                }
+                yield* processFrame(frame);
             }
-            catch (e_4) {
-                env_3.error = e_4;
-                env_3.hasError = true;
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
             }
             finally {
-                __disposeResources(env_3);
+                __disposeResources(env_1);
             }
         }
-        // Flush encoder after all frames (fallback if no null was sent)
-        await this.flush();
-        while (true) {
-            const remaining = await this.receive();
-            if (!remaining)
-                break;
-            yield remaining;
-        }
-        // Signal EOF
-        yield null;
     }
     /**
      * Encode frame stream to packet stream synchronously.
      * Synchronous version of packets.
      *
      * High-level sync generator for complete encoding pipeline.
-     * Automatically manages frame memory, encoder state,
-     * and flushes buffered packets at end.
+     * Encoder is only flushed when EOF (null) signal is explicitly received.
      * Primary interface for stream-based encoding.
      *
-     * @param frames - Iterable of frames (freed automatically)
+     * **EOF Handling:**
+     * - Send null to flush encoder and get remaining buffered packets
+     * - Generator yields null after flushing when null is received
+     * - No automatic flushing - encoder stays open until EOF or close()
      *
-     * @yields {Packet} Encoded packets (caller must free)
+     * @param frames - Iterable of frames, single frame, or null to flush
+     *
+     * @yields {Packet | null} Encoded packets, followed by null when explicitly flushed
      *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
      * ```typescript
-     * // Basic encoding pipeline
+     * // Stream of frames with automatic EOF propagation
      * for (const packet of encoder.packetsSync(decoder.framesSync(packets))) {
+     *   if (packet === null) {
+     *     console.log('Encoder flushed');
+     *     break;
+     *   }
      *   output.writePacketSync(packet);
      *   packet.free(); // Must free output packets
      * }
@@ -1114,18 +943,23 @@ export class Encoder {
      *
      * @example
      * ```typescript
-     * // With frame filtering
-     * function* filteredFrames() {
-     *   for (const frame of decoder.framesSync(packets)) {
-     *     const filtered = filter.processSync(frame);
-     *     if (filtered) {
-     *       yield filtered;
-     *     }
-     *     frame.free();
-     *   }
+     * // Single frame - no automatic flush
+     * for (const packet of encoder.packetsSync(singleFrame)) {
+     *   output.writePacketSync(packet);
+     *   packet.free();
      * }
+     * // Encoder remains open, buffered packets not flushed
+     * ```
      *
-     * for (const packet of encoder.packetsSync(filteredFrames())) {
+     * @example
+     * ```typescript
+     * // Explicit flush with EOF
+     * for (const packet of encoder.packetsSync(null)) {
+     *   if (packet === null) {
+     *     console.log('All buffered packets flushed');
+     *     break;
+     *   }
+     *   console.log('Buffered packet:', packet.pts);
      *   output.writePacketSync(packet);
      *   packet.free();
      * }
@@ -1136,102 +970,56 @@ export class Encoder {
      * @see {@link packets} For async version
      */
     *packetsSync(frames) {
-        // Process frames
+        const self = this;
+        // Helper: Encode frame and yield all available packets (filters out EAGAIN nulls and EOF)
+        const processFrame = function* (frame) {
+            self.encodeSync(frame);
+            // Receive ALL packets (filter out null/EAGAIN and EOF)
+            while (true) {
+                const packet = self.receiveSync();
+                if (!packet)
+                    break; // EAGAIN or EOF - no more packets available
+                yield packet; // Only yield actual packets
+            }
+        }.bind(this);
+        // Helper: Flush encoder and signal EOF
+        const finalize = function* () {
+            for (const remaining of self.flushPacketsSync()) {
+                yield remaining; // Only yield actual packets
+            }
+            yield null; // Signal end-of-stream
+        }.bind(this);
+        // Case 1: EOF input -> flush only
+        if (frames === null) {
+            yield* finalize();
+            return;
+        }
+        // Case 2: Single frame - NO AUTOMATIC FLUSH
+        if (frames instanceof Frame) {
+            yield* processFrame(frames);
+            return; // No finalize() call!
+        }
+        // Case 3: Iterable of frames
         for (const frame_2 of frames) {
-            const env_5 = { stack: [], error: void 0, hasError: false };
+            const env_2 = { stack: [], error: void 0, hasError: false };
             try {
-                const frame = __addDisposableResource(env_5, frame_2, false);
-                // Handle EOF signal
+                const frame = __addDisposableResource(env_2, frame_2, false);
+                // Check for EOF signal from upstream
                 if (frame === null) {
-                    // Flush encoder (audio frame buffer doesn't need explicit flush)
-                    this.flushSync();
-                    while (true) {
-                        const remaining = this.receiveSync();
-                        if (!remaining)
-                            break;
-                        yield remaining;
-                    }
-                    // Signal EOF and stop processing
-                    yield null;
+                    yield* finalize();
                     return;
                 }
-                if (this.isClosed) {
-                    break;
-                }
-                // Open encoder if not already done
-                if (!this.initialized) {
-                    this.initializeSync(frame);
-                }
-                // Prepare frame for encoding (set quality, validate channel count)
-                if (frame) {
-                    this.prepareFrameForEncoding(frame);
-                }
-                // If audio encoder with fixed frame size, use AudioFrameBuffer
-                if (this.audioFrameBuffer) {
-                    // Push frame into buffer
-                    this.audioFrameBuffer.pushSync(frame);
-                    // Pull and encode all available fixed-size frames
-                    let _bufferedFrame;
-                    while (!this.isClosed && (_bufferedFrame = this.audioFrameBuffer.pullSync()) !== null) {
-                        const env_6 = { stack: [], error: void 0, hasError: false };
-                        try {
-                            const bufferedFrame = __addDisposableResource(env_6, _bufferedFrame, false);
-                            // Send buffered frame to encoder
-                            const sendRet = this.codecContext.sendFrameSync(bufferedFrame);
-                            if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
-                                FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-                            }
-                            // Receive packets
-                            while (true) {
-                                const packet = this.receiveSync();
-                                if (!packet)
-                                    break;
-                                yield packet;
-                            }
-                        }
-                        catch (e_5) {
-                            env_6.error = e_5;
-                            env_6.hasError = true;
-                        }
-                        finally {
-                            __disposeResources(env_6);
-                        }
-                    }
-                }
-                else {
-                    // Send frame to encoder
-                    const sendRet = this.codecContext.sendFrameSync(frame);
-                    if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
-                        FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-                    }
-                    // Receive ALL packets
-                    // A single frame can produce multiple packets (e.g., B-frames, lookahead)
-                    while (true) {
-                        const packet = this.receiveSync();
-                        if (!packet)
-                            break;
-                        yield packet;
-                    }
-                }
+                yield* processFrame(frame);
             }
-            catch (e_6) {
-                env_5.error = e_6;
-                env_5.hasError = true;
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
             }
             finally {
-                __disposeResources(env_5);
+                __disposeResources(env_2);
             }
         }
-        // Flush encoder after all frames (fallback if no null was sent)
-        this.flushSync();
-        while (true) {
-            const remaining = this.receiveSync();
-            if (!remaining)
-                break;
-            yield remaining;
-        }
-        // Signal EOF
-        yield null;
+        // No fallback flush - only flush on explicit EOF
     }
     /**
      * Flush encoder and signal end-of-stream.
@@ -1270,17 +1058,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_7 = { stack: [], error: void 0, hasError: false };
+                const env_3 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const bufferedFrame = __addDisposableResource(env_7, _bufferedFrame, false);
+                    const bufferedFrame = __addDisposableResource(env_3, _bufferedFrame, false);
                     await this.codecContext.sendFrame(bufferedFrame);
                 }
-                catch (e_7) {
-                    env_7.error = e_7;
-                    env_7.hasError = true;
+                catch (e_3) {
+                    env_3.error = e_3;
+                    env_3.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_7);
+                    __disposeResources(env_3);
                 }
             }
         }
@@ -1330,17 +1118,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_8 = { stack: [], error: void 0, hasError: false };
+                const env_4 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const bufferedFrame = __addDisposableResource(env_8, _bufferedFrame, false);
+                    const bufferedFrame = __addDisposableResource(env_4, _bufferedFrame, false);
                     this.codecContext.sendFrameSync(bufferedFrame);
                 }
-                catch (e_8) {
-                    env_8.error = e_8;
-                    env_8.hasError = true;
+                catch (e_4) {
+                    env_4.error = e_4;
+                    env_4.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_8);
+                    __disposeResources(env_4);
                 }
             }
         }
@@ -1378,11 +1166,12 @@ export class Encoder {
     async *flushPackets() {
         // Send flush signal
         await this.flush();
+        // Yield all remaining packets (filter out null/EAGAIN and EOF)
         while (true) {
             const packet = await this.receive();
             if (!packet)
-                break;
-            yield packet;
+                break; // Stop on EAGAIN or EOF
+            yield packet; // Only yield actual packets
         }
     }
     /**
@@ -1412,11 +1201,12 @@ export class Encoder {
     *flushPacketsSync() {
         // Send flush signal
         this.flushSync();
+        // Yield all remaining packets (filter out null/EAGAIN and EOF)
         while (true) {
             const packet = this.receiveSync();
             if (!packet)
-                break;
-            yield packet;
+                break; // Stop on EAGAIN or EOF
+            yield packet; // Only yield actual packets
         }
     }
     /**
@@ -1424,19 +1214,25 @@ export class Encoder {
      *
      * Gets encoded packets from the codec's internal buffer.
      * Handles packet cloning and error checking.
-     * Returns null if encoder is closed, not initialized, or no packets available.
-     * Call repeatedly until null to drain all buffered packets.
+     * Implements FFmpeg's send/receive pattern.
+     *
+     * **Return Values:**
+     * - `Packet` - Successfully encoded packet (AVERROR >= 0)
+     * - `null` - Need more input frames (AVERROR_EAGAIN), or encoder not initialized
+     * - `undefined` - End of stream reached (AVERROR_EOF), or encoder is closed
      *
      * Direct mapping to avcodec_receive_packet().
      *
-     * @returns Cloned packet or null if no packets available
+     * @returns Cloned packet, null if need more data, or undefined if stream ended
      *
      * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
      * @example
      * ```typescript
-     * const packet = await encoder.receive();
-     * if (packet) {
+     * // Process all buffered packets
+     * while (true) {
+     *   const packet = await encoder.receive();
+     *   if (!packet) break; // Stop on EAGAIN or EOF
      *   console.log(`Got packet with PTS: ${packet.pts}`);
      *   await output.writePacket(packet);
      *   packet.free();
@@ -1445,10 +1241,14 @@ export class Encoder {
      *
      * @example
      * ```typescript
-     * // Drain all buffered packets
-     * let packet;
-     * while ((packet = await encoder.receive()) !== null) {
-     *   console.log(`Packet size: ${packet.size}`);
+     * // Handle each return value explicitly
+     * const packet = await encoder.receive();
+     * if (packet === EOF) {
+     *   console.log('Encoder stream ended');
+     * } else if (packet === null) {
+     *   console.log('Need more input frames');
+     * } else {
+     *   console.log(`Got packet: pts=${packet.pts}`);
      *   await output.writePacket(packet);
      *   packet.free();
      * }
@@ -1457,13 +1257,33 @@ export class Encoder {
      * @see {@link encode} For sending frames and receiving packets
      * @see {@link flush} For signaling end-of-stream
      * @see {@link receiveSync} For synchronous version
+     * @see {@link EOF} For end-of-stream signal
      */
     async receive() {
-        if (this.isClosed || !this.initialized) {
+        if (this.isClosed) {
+            return EOF;
+        }
+        if (!this.initialized) {
             return null;
         }
         // Clear previous packet data
         this.packet.unref();
+        if (this.audioFrameBuffer?.hasFrame()) {
+            const env_5 = { stack: [], error: void 0, hasError: false };
+            try {
+                const bufferedFrame = __addDisposableResource(env_5, await this.audioFrameBuffer.pull(), false);
+                if (bufferedFrame) {
+                    await this.codecContext.sendFrame(bufferedFrame);
+                }
+            }
+            catch (e_5) {
+                env_5.error = e_5;
+                env_5.hasError = true;
+            }
+            finally {
+                __disposeResources(env_5);
+            }
+        }
         const ret = await this.codecContext.receivePacket(this.packet);
         if (ret === 0) {
             // Set packet timebase to codec timebase
@@ -1473,10 +1293,14 @@ export class Encoder {
             // Got a packet, clone it for the user
             return this.packet.clone();
         }
-        else if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
-            // Need more data or end of stream
+        else if (ret === AVERROR_EAGAIN) {
+            // Need more data
             return null;
         }
+        else if (ret === AVERROR_EOF) {
+            // End of stream
+            return EOF;
+        }
         else {
             // Error
             FFmpegError.throwIfError(ret, 'Failed to receive packet');
@@ -1489,19 +1313,25 @@ export class Encoder {
      *
      * Gets encoded packets from the codec's internal buffer.
      * Handles packet cloning and error checking.
-     * Returns null if encoder is closed, not initialized, or no packets available.
-     * Call repeatedly until null to drain all buffered packets.
+     * Implements FFmpeg's send/receive pattern.
+     *
+     * **Return Values:**
+     * - `Packet` - Successfully encoded packet (AVERROR >= 0)
+     * - `null` - Need more input frames (AVERROR_EAGAIN), or encoder not initialized
+     * - `undefined` - End of stream reached (AVERROR_EOF), or encoder is closed
      *
      * Direct mapping to avcodec_receive_packet().
      *
-     * @returns Cloned packet or null if no packets available
+     * @returns Cloned packet, null if need more data, or undefined if stream ended
      *
      * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
      * @example
      * ```typescript
-     * const packet = encoder.receiveSync();
-     * if (packet) {
+     * // Process all buffered packets
+     * while (true) {
+     *   const packet = encoder.receiveSync();
+     *   if (!packet) break; // Stop on EAGAIN or EOF
      *   console.log(`Got packet with PTS: ${packet.pts}`);
      *   output.writePacketSync(packet);
      *   packet.free();
@@ -1510,10 +1340,14 @@ export class Encoder {
      *
      * @example
      * ```typescript
-     * // Drain all buffered packets
-     * let packet;
-     * while ((packet = encoder.receiveSync()) !== null) {
-     *   console.log(`Packet size: ${packet.size}`);
+     * // Handle each return value explicitly
+     * const packet = encoder.receiveSync();
+     * if (packet === EOF) {
+     *   console.log('Encoder stream ended');
+     * } else if (packet === null) {
+     *   console.log('Need more input frames');
+     * } else {
+     *   console.log(`Got packet: pts=${packet.pts}`);
      *   output.writePacketSync(packet);
      *   packet.free();
      * }
@@ -1522,13 +1356,33 @@ export class Encoder {
      * @see {@link encodeSync} For sending frames and receiving packets
      * @see {@link flushSync} For signaling end-of-stream
      * @see {@link receive} For async version
+     * @see {@link EOF} For end-of-stream signal
      */
     receiveSync() {
-        if (this.isClosed || !this.initialized) {
+        if (this.isClosed) {
+            return EOF;
+        }
+        if (!this.initialized) {
             return null;
         }
         // Clear previous packet data
         this.packet.unref();
+        if (this.audioFrameBuffer?.hasFrame()) {
+            const env_6 = { stack: [], error: void 0, hasError: false };
+            try {
+                const bufferedFrame = __addDisposableResource(env_6, this.audioFrameBuffer.pullSync(), false);
+                if (bufferedFrame) {
+                    this.codecContext.sendFrameSync(bufferedFrame);
+                }
+            }
+            catch (e_6) {
+                env_6.error = e_6;
+                env_6.hasError = true;
+            }
+            finally {
+                __disposeResources(env_6);
+            }
+        }
         const ret = this.codecContext.receivePacketSync(this.packet);
         if (ret === 0) {
             // Set packet timebase to codec timebase
@@ -1538,10 +1392,14 @@ export class Encoder {
             // Got a packet, clone it for the user
             return this.packet.clone();
         }
-        else if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
-            // Need more data or end of stream
+        else if (ret === AVERROR_EAGAIN) {
+            // Need more data
             return null;
         }
+        else if (ret === AVERROR_EOF) {
+            // End of stream
+            return EOF;
+        }
         else {
             // Error
             FFmpegError.throwIfError(ret, 'Failed to receive packet');
@@ -1648,9 +1506,9 @@ export class Encoder {
         try {
             // Outer loop - receive frames
             while (!this.inputQueue.isClosed) {
-                const env_9 = { stack: [], error: void 0, hasError: false };
+                const env_7 = { stack: [], error: void 0, hasError: false };
                 try {
-                    const frame = __addDisposableResource(env_9, await this.inputQueue.receive(), false);
+                    const frame = __addDisposableResource(env_7, await this.inputQueue.receive(), false);
                     if (!frame)
                         break;
                     // Open encoder if not already done
@@ -1660,60 +1518,21 @@ export class Encoder {
                     await this.initializePromise;
                     // Prepare frame for encoding (set quality, validate channel count)
                     this.prepareFrameForEncoding(frame);
-                    // If audio encoder with fixed frame size, use AudioFrameBuffer
-                    if (this.audioFrameBuffer) {
-                        // Push frame into buffer
-                        await this.audioFrameBuffer.push(frame);
-                        // Pull and encode all available fixed-size frames
-                        let _bufferedFrame;
-                        while ((_bufferedFrame = await this.audioFrameBuffer.pull()) !== null) {
-                            const env_10 = { stack: [], error: void 0, hasError: false };
-                            try {
-                                const bufferedFrame = __addDisposableResource(env_10, _bufferedFrame, false);
-                                // Send buffered frame to encoder
-                                const sendRet = await this.codecContext.sendFrame(bufferedFrame);
-                                if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
-                                    FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-                                }
-                                // Receive packets
-                                while (true) {
-                                    const packet = await this.receive();
-                                    if (!packet)
-                                        break;
-                                    await this.outputQueue.send(packet);
-                                }
-                            }
-                            catch (e_9) {
-                                env_10.error = e_9;
-                                env_10.hasError = true;
-                            }
-                            finally {
-                                __disposeResources(env_10);
-                            }
-                        }
-                    }
-                    else {
-                        // Send frame to encoder
-                        const sendRet = await this.codecContext.sendFrame(frame);
-                        if (sendRet < 0 && sendRet !== AVERROR_EOF && sendRet !== AVERROR_EAGAIN) {
-                            FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-                        }
-                        // Receive ALL packets
-                        // A single frame can produce multiple packets (e.g., B-frames, lookahead)
-                        while (!this.outputQueue.isClosed) {
-                            const packet = await this.receive();
-                            if (!packet)
-                                break;
-                            await this.outputQueue.send(packet);
-                        }
+                    await this.encode(frame);
+                    // Receive packets
+                    while (!this.outputQueue.isClosed) {
+                        const packet = await this.receive();
+                        if (!packet)
+                            break; // Stop on EAGAIN or EOF
+                        await this.outputQueue.send(packet); // Only send actual packets
                     }
                 }
-                catch (e_10) {
-                    env_9.error = e_10;
-                    env_9.hasError = true;
+                catch (e_7) {
+                    env_7.error = e_7;
+                    env_7.hasError = true;
                 }
                 finally {
-                    __disposeResources(env_9);
+                    __disposeResources(env_7);
                 }
             }
             // Flush encoder at end
@@ -1721,8 +1540,8 @@ export class Encoder {
             while (!this.outputQueue.isClosed) {
                 const packet = await this.receive();
                 if (!packet)
-                    break;
-                await this.outputQueue.send(packet);
+                    break; // Stop on EAGAIN or EOF
+                await this.outputQueue.send(packet); // Only send actual packets
             }
         }
         catch {
@@ -1734,14 +1553,45 @@ export class Encoder {
         }
     }
     /**
-     * Send frame to input queue.
+     * Send frame to input queue or flush the pipeline.
+     *
+     * When frame is provided, queues it for encoding.
+     * When null is provided, triggers flush sequence:
+     * - Closes input queue
+     * - Waits for worker completion
+     * - Flushes encoder and sends remaining packets to output queue
+     * - Closes output queue
+     * - Waits for pipeTo task completion (writes to muxer)
+     *
+     * Used by scheduler system for pipeline control.
      *
-     * @param frame - Frame to send
+     * @param frame - Frame to send, or null to flush
      *
      * @internal
      */
     async sendToQueue(frame) {
-        await this.inputQueue.send(frame);
+        if (frame) {
+            await this.inputQueue.send(frame);
+        }
+        else {
+            // Close input queue to signal end of stream to worker
+            this.inputQueue.close();
+            // Wait for worker to finish processing all frames (if exists)
+            if (this.workerPromise) {
+                await this.workerPromise;
+            }
+            // Flush encoder at end
+            await this.flush();
+            while (true) {
+                const packet = await this.receive();
+                if (!packet)
+                    break; // Stop on EAGAIN or EOF
+                await this.outputQueue.send(packet); // Only send actual packets
+            }
+            if (this.pipeToPromise) {
+                await this.pipeToPromise;
+            }
+        }
     }
     /**
      * Receive packet from output queue.
@@ -1753,32 +1603,6 @@ export class Encoder {
     async receiveFromQueue() {
         return await this.outputQueue.receive();
     }
-    /**
-     * Flush the entire filter pipeline.
-     *
-     * Propagates flush through worker, output queue, and next component.
-     *
-     * @internal
-     */
-    async flushPipeline() {
-        // Close input queue to signal end of stream to worker
-        this.inputQueue.close();
-        // Wait for worker to finish processing all frames (if exists)
-        if (this.workerPromise) {
-            await this.workerPromise;
-        }
-        // Flush encoder at end
-        await this.flush();
-        while (true) {
-            const packet = await this.receive();
-            if (!packet)
-                break;
-            await this.outputQueue.send(packet);
-        }
-        if (this.pipeToPromise) {
-            await this.pipeToPromise;
-        }
-    }
     /**
      * Initialize encoder from first frame.
      *
@@ -2048,6 +1872,9 @@ export class Encoder {
      * @internal
      */
     prepareFrameForEncoding(frame) {
+        // Clear pict_type - encoder will determine frame types based on its own settings
+        // Input stream's frame type hints are irrelevant when re-encoding
+        frame.pictType = AV_PICTURE_TYPE_NONE;
         // Adjust frame PTS and timebase to encoder timebase
         // This matches FFmpeg's adjust_frame_pts_to_encoder_tb() behavior which:
         // 1. Converts PTS from frame's timebase to encoder's timebase (av_rescale_q)