node-av 3.1.3 → 5.0.0

package/dist/api/encoder.js

@@ -1,5 +1,68 @@
-import { AVERROR_EAGAIN, AVERROR_EOF, AVMEDIA_TYPE_AUDIO } from '../constants/constants.js';
-import { Codec, CodecContext, Dictionary, FFmpegError, Packet, Rational } from '../lib/index.js';
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    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_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';
+import { AudioFrameBuffer } from './audio-frame-buffer.js';
+import { FRAME_THREAD_QUEUE_SIZE, PACKET_THREAD_QUEUE_SIZE } from './constants.js';
+import { AsyncQueue } from './utilities/async-queue.js';
+import { SchedulerControl } from './utilities/scheduler.js';
 import { parseBitrate } from './utils.js';
 /**
  * High-level encoder for audio and video streams.
@@ -56,17 +119,24 @@ import { parseBitrate } from './utils.js';
  * ```
  *
  * @see {@link Decoder} For decoding packets to frames
- * @see {@link MediaOutput} For writing encoded packets
+ * @see {@link Muxer} For writing encoded packets
  * @see {@link HardwareContext} For GPU acceleration
  */
 export class Encoder {
     codecContext;
     packet;
     codec;
+    initializePromise = null;
     initialized = false;
     isClosed = false;
     opts;
     options;
+    audioFrameBuffer;
+    // Worker pattern for push-based processing
+    inputQueue;
+    outputQueue;
+    workerPromise = null;
+    pipeToPromise = null;
     /**
      * @param codecContext - Configured codec context
      *
@@ -85,6 +155,8 @@ export class Encoder {
         this.opts = opts;
         this.packet = new Packet();
         this.packet.alloc();
+        this.inputQueue = new AsyncQueue(FRAME_THREAD_QUEUE_SIZE);
+        this.outputQueue = new AsyncQueue(PACKET_THREAD_QUEUE_SIZE);
     }
     /**
      * Create an encoder with specified codec and options.
@@ -97,7 +169,7 @@ export class Encoder {
      *
      * @param encoderCodec - Codec name, ID, or instance to use for encoding
      *
-     * @param options - Encoder configuration options including required timeBase
+     * @param options - Optional encoder configuration options including required timeBase
      *
      * @returns Configured encoder instance
      *
@@ -138,8 +210,9 @@ export class Encoder {
      * ```
      *
      * @see {@link EncoderOptions} For configuration options
+     * @see {@link createSync} For synchronous version
      */
-    static async create(encoderCodec, options) {
+    static async create(encoderCodec, options = {}) {
         let codec = null;
         let codecName = '';
         if (encoderCodec instanceof Codec) {
@@ -187,14 +260,6 @@ export class Encoder {
             const bufSize = typeof options.bufSize === 'string' ? parseBitrate(options.bufSize) : BigInt(options.bufSize);
             codecContext.rcBufferSize = Number(bufSize);
         }
-        if (options.threads !== undefined) {
-            codecContext.threadCount = options.threads;
-        }
-        codecContext.timeBase = new Rational(options.timeBase.num, options.timeBase.den);
-        codecContext.pktTimebase = new Rational(options.timeBase.num, options.timeBase.den);
-        if (options.frameRate) {
-            codecContext.framerate = new Rational(options.frameRate.num, options.frameRate.den);
-        }
         const opts = options.options ? Dictionary.fromObject(options.options) : undefined;
         return new Encoder(codecContext, codec, options, opts);
     }
@@ -210,7 +275,7 @@ export class Encoder {
      *
      * @param encoderCodec - Codec name, ID, or instance to use for encoding
      *
-     * @param options - Encoder configuration options including required timeBase
+     * @param options - Optional encoder configuration options including required timeBase
      *
      * @returns Configured encoder instance
      *
@@ -252,9 +317,10 @@ export class Encoder {
      * });
      * ```
      *
+     * @see {@link EncoderOptions} For configuration options
      * @see {@link create} For async version
      */
-    static createSync(encoderCodec, options) {
+    static createSync(encoderCodec, options = {}) {
         let codec = null;
         let codecName = '';
         if (encoderCodec instanceof Codec) {
@@ -301,14 +367,6 @@ export class Encoder {
             const bufSize = typeof options.bufSize === 'string' ? parseBitrate(options.bufSize) : BigInt(options.bufSize);
             codecContext.rcBufferSize = Number(bufSize);
         }
-        if (options.threads !== undefined) {
-            codecContext.threadCount = options.threads;
-        }
-        if (options.frameRate) {
-            codecContext.framerate = new Rational(options.frameRate.num, options.frameRate.den);
-        }
-        codecContext.timeBase = new Rational(options.timeBase.num, options.timeBase.den);
-        codecContext.pktTimebase = new Rational(options.timeBase.num, options.timeBase.den);
         const opts = options.options ? Dictionary.fromObject(options.options) : undefined;
         return new Encoder(codecContext, codec, options, opts);
     }
@@ -343,6 +401,115 @@ export class Encoder {
     get isEncoderInitialized() {
         return this.initialized;
     }
+    /**
+     * Codec flags.
+     *
+     * @returns Current codec flags
+     *
+     * @throws {Error} If encoder is closed
+     *
+     * @example
+     * ```typescript
+     * const flags = encoder.codecFlags;
+     * console.log('Current flags:', flags);
+     * ```
+     *
+     * @see {@link setCodecFlags} To set flags
+     * @see {@link clearCodecFlags} To clear flags
+     * @see {@link hasCodecFlags} To check flags
+     */
+    get codecFlags() {
+        if (this.isClosed) {
+            throw new Error('Cannot get flags on closed encoder');
+        }
+        return this.codecContext.flags;
+    }
+    /**
+     * Set codec flags.
+     *
+     * @param flags - One or more flag values to set
+     *
+     * @throws {Error} If encoder is already initialized or closed
+     *
+     * @example
+     * ```typescript
+     * import { AV_CODEC_FLAG_GLOBAL_HEADER, AV_CODEC_FLAG_QSCALE } from 'node-av/constants';
+     *
+     * // Set multiple flags before initialization
+     * encoder.setCodecFlags(AV_CODEC_FLAG_GLOBAL_HEADER, AV_CODEC_FLAG_QSCALE);
+     * ```
+     *
+     * @see {@link clearCodecFlags} To clear flags
+     * @see {@link hasCodecFlags} To check flags
+     * @see {@link codecFlags} For direct flag access
+     */
+    setCodecFlags(...flags) {
+        if (this.isClosed) {
+            throw new Error('Cannot set flags on closed encoder');
+        }
+        if (this.initialized) {
+            throw new Error('Cannot set flags on already initialized encoder');
+        }
+        this.codecContext.setFlags(...flags);
+    }
+    /**
+     * Clear codec flags.
+     *
+     * @param flags - One or more flag values to clear
+     *
+     * @throws {Error} If encoder is already initialized or closed
+     *
+     * @example
+     * ```typescript
+     * import { AV_CODEC_FLAG_QSCALE } from 'node-av/constants';
+     *
+     * // Clear specific flag before initialization
+     * encoder.clearCodecFlags(AV_CODEC_FLAG_QSCALE);
+     * ```
+     *
+     * @see {@link setCodecFlags} To set flags
+     * @see {@link hasCodecFlags} To check flags
+     * @see {@link codecFlags} For direct flag access
+     */
+    clearCodecFlags(...flags) {
+        if (this.isClosed) {
+            throw new Error('Cannot clear flags on closed encoder');
+        }
+        if (this.initialized) {
+            throw new Error('Cannot clear flags on already initialized encoder');
+        }
+        this.codecContext.clearFlags(...flags);
+    }
+    /**
+     * Check if codec has specific flags.
+     *
+     * Tests whether all specified codec flags are set using bitwise AND.
+     *
+     * @param flags - One or more flag values to check
+     *
+     * @returns true if all specified flags are set, false otherwise
+     *
+     * @throws {Error} If encoder is closed
+     *
+     * @example
+     * ```typescript
+     * import { AV_CODEC_FLAG_GLOBAL_HEADER } from 'node-av/constants';
+     *
+     * if (encoder.hasCodecFlags(AV_CODEC_FLAG_GLOBAL_HEADER)) {
+     *   console.log('Global header flag is set');
+     * }
+     * ```
+     *
+     * @see {@link setCodecFlags} To set flags
+     * @see {@link clearCodecFlags} To clear flags
+     * @see {@link codecFlags} For direct flag access
+     */
+    hasCodecFlags(...flags) {
+        if (this.isClosed) {
+            throw new Error('Cannot check flags on closed encoder');
+        }
+        return this.codecContext.hasFlags(...flags);
+    }
     /**
      * Check if encoder uses hardware acceleration.
      *
@@ -376,24 +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.
      *
-     * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
+     * **Important**: This method only SENDS the frame to the encoder.
+     * You must call {@link receive} 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 = 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();
@@ -402,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();
      *   }
@@ -413,56 +590,181 @@ export class Encoder {
      * }
      * ```
      *
+     * @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
+        this.initializePromise ??= this.initialize(frame);
+        await this.initializePromise;
+        // Prepare frame for encoding (set quality, validate channel count)
+        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 (this.audioFrameBuffer) {
+            // Push frame into buffer - actual sending happens in receive()
+            await this.audioFrameBuffer.push(frame);
+        }
+        else {
+            await encode(frame);
+        }
+    }
+    /**
+     * Send a frame to the encoder synchronously.
+     * Synchronous version of encode.
+     *
+     * 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.
+     * A single frame can produce zero, one, or multiple packets depending on codec buffering.
+     *
+     * **Important**: This method only SENDS the frame to the encoder.
+     * You must call {@link receiveSync} separately (potentially multiple times) to get encoded packets.
+     *
+     * Direct mapping to avcodec_send_frame().
+     *
+     * @param frame - Raw frame to send to encoder
+     *
+     * @throws {FFmpegError} If sending frame fails
+     *
+     * @example
+     * ```typescript
+     * // 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();
+     * }
+     * ```
+     *
+     * @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;
         }
         // 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)
+        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;
             }
-            await this.initialize(frame);
+        };
+        if (this.audioFrameBuffer) {
+            // Push frame into buffer - actual sending happens in receiveSync()
+            this.audioFrameBuffer.pushSync(frame);
+        }
+        else {
+            encode(frame);
+        }
+    }
+    /**
+     * Encode a frame to packets.
+     *
+     * Sends a frame to the encoder and receives all available encoded packets.
+     * Returns array of packets - may be empty if encoder needs more data.
+     * On first frame, automatically initializes encoder with frame properties.
+     * One frame can produce zero, one, or multiple packets depending on codec.
+     *
+     * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
+     *
+     * @param frame - Raw frame to encode (or null to flush)
+     *
+     * @returns Array of encoded packets (empty if more data needed or encoder is closed)
+     *
+     * @throws {FFmpegError} If encoding fails
+     *
+     * @example
+     * ```typescript
+     * const packets = await encoder.encodeAll(frame);
+     * for (const packet of packets) {
+     *   console.log(`Encoded packet with PTS: ${packet.pts}`);
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Encode loop
+     * for await (const frame of decoder.frames(input.packets())) {
+     *   const packets = await encoder.encodeAll(frame);
+     *   for (const packet of packets) {
+     *     await output.writePacket(packet);
+     *     packet.free();
+     *   }
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link encode} For single packet encoding
+     * @see {@link packets} For automatic frame iteration
+     * @see {@link flush} For end-of-stream handling
+     * @see {@link encodeAllSync} For synchronous version
+     */
+    async encodeAll(frame) {
+        if (frame) {
+            await this.encode(frame);
         }
-        // Send frame to encoder
-        const sendRet = await this.codecContext.sendFrame(frame);
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            // Encoder might be full, try to receive first
+        else {
+            await this.flush();
+        }
+        // Receive all available packets
+        const packets = [];
+        while (true) {
             const packet = await this.receive();
-            if (packet) {
-                return packet;
-            }
-            // If still failing, it's an error
-            if (sendRet !== AVERROR_EAGAIN) {
-                FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-            }
+            if (!packet)
+                break; // Stop on EAGAIN or EOF
+            packets.push(packet); // Only push actual packets
         }
-        // Try to receive packet
-        return await this.receive();
+        return packets;
     }
     /**
-     * Encode a frame to a packet synchronously.
-     * Synchronous version of encode.
+     * Encode a frame to packets synchronously.
+     * Synchronous version of encodeAll.
      *
-     * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * Sends a frame to the encoder and receives all available encoded packets.
+     * Returns array of packets - may be empty if encoder needs more data.
      * On first frame, automatically initializes encoder with frame properties.
-     * Handles internal buffering - may return null if more frames needed.
+     * One frame can produce zero, one, or multiple packets depending on codec.
      *
      * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
      * @param frame - Raw frame to encode (or null to flush)
      *
-     * @returns Encoded packet, null if more data needed, or null if encoder is closed
+     * @returns Array of encoded packets (empty if more data needed or encoder is closed)
      *
      * @throws {FFmpegError} If encoding fails
      *
      * @example
      * ```typescript
-     * const packet = encoder.encodeSync(frame);
-     * if (packet) {
+     * const packets = encoder.encodeAllSync(frame);
+     * for (const packet of packets) {
      *   console.log(`Encoded packet with PTS: ${packet.pts}`);
      *   output.writePacketSync(packet);
      *   packet.free();
@@ -473,8 +775,8 @@ export class Encoder {
      * ```typescript
      * // Encode loop
      * for (const frame of decoder.framesSync(packets)) {
-     *   const packet = encoder.encodeSync(frame);
-     *   if (packet) {
+     *   const packets = encoder.encodeAllSync(frame);
+     *   for (const packet of packets) {
      *     output.writePacketSync(packet);
      *     packet.free();
      *   }
@@ -482,52 +784,54 @@ export class Encoder {
      * }
      * ```
      *
-     * @see {@link encode} For async version
+     * @see {@link encodeSync} For single packet encoding
+     * @see {@link packetsSync} For automatic frame iteration
+     * @see {@link flushSync} For end-of-stream handling
+     * @see {@link encodeAll} For async version
      */
-    encodeSync(frame) {
-        if (this.isClosed) {
-            return null;
+    encodeAllSync(frame) {
+        if (frame) {
+            this.encodeSync(frame);
         }
-        // Open encoder if not already done
-        if (!this.initialized) {
-            if (!frame) {
-                return null;
-            }
-            this.initializeSync(frame);
+        else {
+            this.flushSync();
         }
-        // Send frame to encoder
-        const sendRet = this.codecContext.sendFrameSync(frame);
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            // Encoder might be full, try to receive first
+        // Receive all available packets
+        const packets = [];
+        while (true) {
             const packet = this.receiveSync();
-            if (packet)
-                return packet;
-            // If still failing, it's an error
-            if (sendRet !== AVERROR_EAGAIN) {
-                FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-            }
+            if (!packet)
+                break; // Stop on EAGAIN or EOF
+            packets.push(packet); // Only push actual packets
         }
-        // Try to receive packet
-        return this.receiveSync();
+        return packets;
     }
     /**
      * 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
      * }
@@ -535,82 +839,103 @@ 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
      * @see {@link Decoder.frames} For frame source
+     * @see {@link packetsSync} For sync version
      */
     async *packets(frames) {
-        // Process frames
-        for await (const frame of 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_1 = { stack: [], error: void 0, hasError: false };
             try {
-                const packet = await this.encode(frame);
-                if (packet) {
-                    yield packet;
+                const frame = __addDisposableResource(env_1, frame_1, false);
+                if (frame === null) {
+                    yield* finalize();
+                    return;
                 }
+                yield* processFrame(frame);
+            }
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
             }
             finally {
-                // Free the input frame after encoding
-                frame.free();
+                __disposeResources(env_1);
             }
         }
-        // Flush encoder after all frames
-        await this.flush();
-        while (!this.isClosed) {
-            const remaining = await this.receive();
-            if (!remaining)
-                break;
-            yield remaining;
-        }
     }
     /**
      * 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()
+     *
+     * @param frames - 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 (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
      * }
@@ -618,47 +943,83 @@ 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();
      * }
      * ```
      *
+     * @see {@link encodeSync} For single frame encoding
+     * @see {@link Decoder.framesSync} For frame source
      * @see {@link packets} For async version
      */
     *packetsSync(frames) {
-        // Process frames
-        for (const frame of 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_2 = { stack: [], error: void 0, hasError: false };
             try {
-                const packet = this.encodeSync(frame);
-                if (packet) {
-                    yield packet;
+                const frame = __addDisposableResource(env_2, frame_2, false);
+                // Check for EOF signal from upstream
+                if (frame === null) {
+                    yield* finalize();
+                    return;
                 }
+                yield* processFrame(frame);
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
             }
             finally {
-                // Free the input frame after encoding
-                frame.free();
+                __disposeResources(env_2);
             }
         }
-        // Flush encoder after all frames
-        this.flushSync();
-        while (!this.isClosed) {
-            const remaining = this.receiveSync();
-            if (!remaining)
-                break;
-            yield remaining;
-        }
+        // No fallback flush - only flush on explicit EOF
     }
     /**
      * Flush encoder and signal end-of-stream.
@@ -685,11 +1046,32 @@ export class Encoder {
      *
      * @see {@link flushPackets} For async iteration
      * @see {@link receive} For getting buffered packets
+     * @see {@link flushSync} For synchronous version
      */
     async flush() {
         if (this.isClosed || !this.initialized) {
             return;
         }
+        // If using AudioFrameBuffer, flush remaining buffered samples first
+        if (this.audioFrameBuffer && this.audioFrameBuffer.size > 0) {
+            // Pull any remaining partial frame (may be less than frameSize)
+            // 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 };
+                try {
+                    const bufferedFrame = __addDisposableResource(env_3, _bufferedFrame, false);
+                    await this.codecContext.sendFrame(bufferedFrame);
+                }
+                catch (e_3) {
+                    env_3.error = e_3;
+                    env_3.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_3);
+                }
+            }
+        }
         // Send flush frame (null)
         const ret = await this.codecContext.sendFrame(null);
         if (ret < 0 && ret !== AVERROR_EOF) {
@@ -722,12 +1104,34 @@ export class Encoder {
      * }
      * ```
      *
+     * @see {@link flushPacketsSync} For sync iteration
+     * @see {@link receiveSync} For getting buffered packets
      * @see {@link flush} For async version
      */
     flushSync() {
         if (this.isClosed || !this.initialized) {
             return;
         }
+        // If using AudioFrameBuffer, flush remaining buffered samples first
+        if (this.audioFrameBuffer && this.audioFrameBuffer.size > 0) {
+            // Pull any remaining partial frame (may be less than frameSize)
+            // 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 };
+                try {
+                    const bufferedFrame = __addDisposableResource(env_4, _bufferedFrame, false);
+                    this.codecContext.sendFrameSync(bufferedFrame);
+                }
+                catch (e_4) {
+                    env_4.error = e_4;
+                    env_4.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_4);
+                }
+            }
+        }
         // Send flush frame (null)
         const ret = this.codecContext.sendFrameSync(null);
         if (ret < 0 && ret !== AVERROR_EOF) {
@@ -755,15 +1159,19 @@ export class Encoder {
      * }
      * ```
      *
+     * @see {@link encode} For sending frames and receiving packets
      * @see {@link flush} For signaling end-of-stream
-     * @see {@link packets} For complete pipeline
+     * @see {@link flushPacketsSync} For synchronous version
      */
     async *flushPackets() {
         // Send flush signal
         await this.flush();
-        let packet;
-        while ((packet = await this.receive()) !== null) {
-            yield packet;
+        // Yield all remaining packets (filter out null/EAGAIN and EOF)
+        while (true) {
+            const packet = await this.receive();
+            if (!packet)
+                break; // Stop on EAGAIN or EOF
+            yield packet; // Only yield actual packets
         }
     }
     /**
@@ -786,14 +1194,19 @@ export class Encoder {
      * }
      * ```
      *
+     * @see {@link encodeSync} For sending frames and receiving packets
+     * @see {@link flushSync} For signaling end-of-stream
      * @see {@link flushPackets} For async version
      */
     *flushPacketsSync() {
         // Send flush signal
         this.flushSync();
-        let packet;
-        while ((packet = this.receiveSync()) !== null) {
-            yield packet;
+        // Yield all remaining packets (filter out null/EAGAIN and EOF)
+        while (true) {
+            const packet = this.receiveSync();
+            if (!packet)
+                break; // Stop on EAGAIN or EOF
+            yield packet; // Only yield actual packets
         }
     }
     /**
@@ -801,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();
@@ -822,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();
      * }
@@ -833,22 +1256,51 @@ 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
+            this.packet.timeBase = this.codecContext.timeBase;
+            // Mark packet as trusted (from encoder)
+            this.packet.setFlags(AV_PKT_FLAG_TRUSTED);
             // 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');
@@ -861,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();
@@ -882,38 +1340,101 @@ 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();
      * }
      * ```
      *
+     * @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
+            this.packet.timeBase = this.codecContext.timeBase;
+            // Mark packet as trusted (from encoder)
+            this.packet.setFlags(AV_PKT_FLAG_TRUSTED);
             // 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');
             return null;
         }
     }
+    /**
+     * Pipe encoded packets to muxer.
+     *
+     * @param target - Media output component to write packets to
+     *
+     * @param streamIndex - Stream index to write packets to
+     *
+     * @returns Scheduler for continued chaining
+     *
+     * @example
+     * ```typescript
+     * decoder.pipeTo(filter).pipeTo(encoder)
+     * ```
+     */
+    pipeTo(target, streamIndex) {
+        // Start worker if not already running
+        this.workerPromise ??= this.runWorker();
+        // Start pipe task: encoder.outputQueue -> output
+        this.pipeToPromise = (async () => {
+            while (true) {
+                const packet = await this.receiveFromQueue();
+                if (!packet)
+                    break;
+                await target.writePacket(packet, streamIndex);
+            }
+        })();
+        // Return control without pipeTo (terminal stage)
+        return new SchedulerControl(this);
+    }
     /**
      * Close encoder and free resources.
      *
@@ -938,10 +1459,150 @@ export class Encoder {
             return;
         }
         this.isClosed = true;
+        // Close queues
+        this.inputQueue.close();
+        this.outputQueue.close();
         this.packet.free();
         this.codecContext.freeContext();
         this.initialized = false;
     }
+    /**
+     * Get encoder codec.
+     *
+     * Returns the codec used by this encoder.
+     * Useful for checking codec capabilities and properties.
+     *
+     * @returns Codec instance
+     *
+     * @internal
+     *
+     * @see {@link Codec} For codec details
+     */
+    getCodec() {
+        return this.codec;
+    }
+    /**
+     * Get underlying codec context.
+     *
+     * Returns the codec context for advanced operations.
+     * Useful for accessing low-level codec properties and settings.
+     * Returns null if encoder is closed or not initialized.
+     *
+     * @returns Codec context or null if closed/not initialized
+     *
+     * @internal
+     *
+     * @see {@link CodecContext} For context details
+     */
+    getCodecContext() {
+        return !this.isClosed && this.initialized ? this.codecContext : null;
+    }
+    /**
+     * Worker loop for push-based processing.
+     *
+     * @internal
+     */
+    async runWorker() {
+        try {
+            // Outer loop - receive frames
+            while (!this.inputQueue.isClosed) {
+                const env_7 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const frame = __addDisposableResource(env_7, await this.inputQueue.receive(), false);
+                    if (!frame)
+                        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)
+                    this.prepareFrameForEncoding(frame);
+                    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_7) {
+                    env_7.error = e_7;
+                    env_7.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_7);
+                }
+            }
+            // Flush encoder at end
+            await this.flush();
+            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 {
+            // Ignore error ?
+        }
+        finally {
+            // Close output queue when done
+            this.outputQueue?.close();
+        }
+    }
+    /**
+     * 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, or null to flush
+     *
+     * @internal
+     */
+    async sendToQueue(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.
+     *
+     * @returns Packet from output queue
+     *
+     * @internal
+     */
+    async receiveFromQueue() {
+        return await this.outputQueue.receive();
+    }
     /**
      * Initialize encoder from first frame.
      *
@@ -956,25 +1617,80 @@ export class Encoder {
      * @internal
      */
     async initialize(frame) {
+        // Get bits_per_raw_sample from decoder if available
+        if (this.options.decoder) {
+            const decoderCtx = this.options.decoder.getCodecContext();
+            if (decoderCtx && decoderCtx.bitsPerRawSample > 0) {
+                this.codecContext.bitsPerRawSample = decoderCtx.bitsPerRawSample;
+            }
+        }
+        // Get framerate from filter if available, otherwise from decoder
+        // This matches FFmpeg CLI behavior where encoder gets frame_rate_filter from FrameData
+        if (this.options.filter && frame.isVideo()) {
+            const filterFrameRate = this.options.filter.frameRate;
+            if (filterFrameRate) {
+                this.codecContext.framerate = new Rational(filterFrameRate.num, filterFrameRate.den);
+            }
+        }
+        // If no filter framerate, try to get from decoder stream
+        if ((!this.codecContext.framerate || this.codecContext.framerate.num === 0) && this.options.decoder && frame.isVideo()) {
+            const decoderCtx = this.options.decoder.getCodecContext();
+            if (decoderCtx?.framerate && decoderCtx.framerate.num > 0) {
+                this.codecContext.framerate = decoderCtx.framerate;
+            }
+        }
         if (frame.isVideo()) {
+            // FFmpeg CLI sets encoder time_base to 1/framerate (inverse of framerate)
+            // This allows encoder to produce sequential PTS (0, 1, 2, 3...) which enables
+            // proper B-frame DTS generation (negative DTS values)
+            if (this.codecContext.framerate && this.codecContext.framerate.num > 0) {
+                // Use inverse of framerate (e.g., framerate=30/1 → timebase=1/30)
+                this.codecContext.timeBase = new Rational(this.codecContext.framerate.den, this.codecContext.framerate.num);
+            }
+            else {
+                // Fallback: use frame timebase if framerate not available
+                this.codecContext.timeBase = frame.timeBase;
+            }
             this.codecContext.width = frame.width;
             this.codecContext.height = frame.height;
             this.codecContext.pixelFormat = frame.format;
             this.codecContext.sampleAspectRatio = frame.sampleAspectRatio;
+            this.codecContext.colorRange = frame.colorRange;
+            this.codecContext.colorPrimaries = frame.colorPrimaries;
+            this.codecContext.colorTrc = frame.colorTrc;
+            this.codecContext.colorSpace = frame.colorSpace;
+            // Only set chroma location if unspecified
+            if (this.codecContext.chromaLocation === AVCHROMA_LOC_UNSPECIFIED) {
+                this.codecContext.chromaLocation = frame.chromaLocation;
+            }
         }
         else {
+            // Audio: Always use frame timebase (which is typically 1/sample_rate)
+            // This ensures correct PTS progression for audio frames
+            this.codecContext.timeBase = frame.timeBase;
             this.codecContext.sampleRate = frame.sampleRate;
             this.codecContext.sampleFormat = frame.format;
             this.codecContext.channelLayout = frame.channelLayout;
         }
-        this.codecContext.hwDeviceCtx = frame.hwFramesCtx?.deviceRef ?? null;
-        this.codecContext.hwFramesCtx = frame.hwFramesCtx;
+        // Setup hardware acceleration with validation
+        this.setupHardwareAcceleration(frame);
+        // AV_CODEC_FLAG_COPY_OPAQUE: Copy opaque data from frames to packets if supported
+        if (this.codec.hasCapabilities(AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE)) {
+            this.codecContext.setFlags(AV_CODEC_FLAG_COPY_OPAQUE);
+        }
+        // AV_CODEC_FLAG_FRAME_DURATION: Signal that frame duration matters for timestamps
+        this.codecContext.setFlags(AV_CODEC_FLAG_FRAME_DURATION);
         // Open codec
         const openRet = await this.codecContext.open2(this.codec, this.opts);
         if (openRet < 0) {
             this.codecContext.freeContext();
             FFmpegError.throwIfError(openRet, 'Failed to open encoder');
         }
+        // Check if encoder requires fixed frame size (e.g., Opus, AAC, MP3)
+        // If so, create AudioFrameBuffer to automatically chunk frames
+        if (frame.isAudio() && this.codecContext.frameSize > 0) {
+            this.audioFrameBuffer = AudioFrameBuffer.create(this.codecContext.frameSize, this.codecContext.sampleFormat, this.codecContext.sampleRate, this.codecContext.channelLayout, this.codecContext.channels);
+        }
         this.initialized = true;
     }
     /**
@@ -994,95 +1710,228 @@ export class Encoder {
      * @see {@link initialize} For async version
      */
     initializeSync(frame) {
+        // Get bits_per_raw_sample from decoder if available
+        if (this.options.decoder) {
+            const decoderCtx = this.options.decoder.getCodecContext();
+            if (decoderCtx && decoderCtx.bitsPerRawSample > 0) {
+                this.codecContext.bitsPerRawSample = decoderCtx.bitsPerRawSample;
+            }
+        }
+        // Get framerate from filter if available, otherwise from decoder
+        // This matches FFmpeg CLI behavior where encoder gets frame_rate_filter from FrameData
+        if (this.options.filter && frame.isVideo()) {
+            const filterFrameRate = this.options.filter.frameRate;
+            if (filterFrameRate) {
+                this.codecContext.framerate = new Rational(filterFrameRate.num, filterFrameRate.den);
+            }
+        }
+        // If no filter framerate, try to get from decoder stream
+        if ((!this.codecContext.framerate || this.codecContext.framerate.num === 0) && this.options.decoder && frame.isVideo()) {
+            const decoderCtx = this.options.decoder.getCodecContext();
+            if (decoderCtx?.framerate && decoderCtx.framerate.num > 0) {
+                this.codecContext.framerate = decoderCtx.framerate;
+            }
+        }
         if (frame.isVideo()) {
+            // FFmpeg CLI sets encoder time_base to 1/framerate (inverse of framerate)
+            // This allows encoder to produce sequential PTS (0, 1, 2, 3...) which enables
+            // proper B-frame DTS generation (negative DTS values)
+            if (this.codecContext.framerate && this.codecContext.framerate.num > 0) {
+                // Use inverse of framerate (e.g., framerate=30/1 → timebase=1/30)
+                this.codecContext.timeBase = new Rational(this.codecContext.framerate.den, this.codecContext.framerate.num);
+            }
+            else {
+                // Fallback: use frame timebase if framerate not available
+                this.codecContext.timeBase = frame.timeBase;
+            }
             this.codecContext.width = frame.width;
             this.codecContext.height = frame.height;
             this.codecContext.pixelFormat = frame.format;
             this.codecContext.sampleAspectRatio = frame.sampleAspectRatio;
+            this.codecContext.colorRange = frame.colorRange;
+            this.codecContext.colorPrimaries = frame.colorPrimaries;
+            this.codecContext.colorTrc = frame.colorTrc;
+            this.codecContext.colorSpace = frame.colorSpace;
+            // Only set chroma location if unspecified
+            if (this.codecContext.chromaLocation === AVCHROMA_LOC_UNSPECIFIED) {
+                this.codecContext.chromaLocation = frame.chromaLocation;
+            }
         }
         else {
+            // Audio: Always use frame timebase (which is typically 1/sample_rate)
+            // This ensures correct PTS progression for audio frames
+            this.codecContext.timeBase = frame.timeBase;
             this.codecContext.sampleRate = frame.sampleRate;
             this.codecContext.sampleFormat = frame.format;
             this.codecContext.channelLayout = frame.channelLayout;
         }
-        this.codecContext.hwDeviceCtx = frame.hwFramesCtx?.deviceRef ?? null;
-        this.codecContext.hwFramesCtx = frame.hwFramesCtx;
+        // Setup hardware acceleration with validation
+        this.setupHardwareAcceleration(frame);
+        // Set codec flags
+        // AV_CODEC_FLAG_COPY_OPAQUE: Copy opaque data from frames to packets if supported
+        if (this.codec.hasCapabilities(AV_CODEC_CAP_ENCODER_REORDERED_OPAQUE)) {
+            this.codecContext.setFlags(AV_CODEC_FLAG_COPY_OPAQUE);
+        }
+        // AV_CODEC_FLAG_FRAME_DURATION: Signal that frame duration matters for timestamps
+        this.codecContext.setFlags(AV_CODEC_FLAG_FRAME_DURATION);
         // Open codec
         const openRet = this.codecContext.open2Sync(this.codec, this.opts);
         if (openRet < 0) {
             this.codecContext.freeContext();
             FFmpegError.throwIfError(openRet, 'Failed to open encoder');
         }
+        // Check if encoder requires fixed frame size (e.g., Opus, AAC, MP3)
+        // If so, create AudioFrameBuffer to automatically chunk frames
+        if (frame.isAudio() && this.codecContext.frameSize > 0) {
+            this.audioFrameBuffer = AudioFrameBuffer.create(this.codecContext.frameSize, this.codecContext.sampleFormat, this.codecContext.sampleRate, this.codecContext.channelLayout, this.codecContext.channels);
+        }
         this.initialized = true;
     }
     /**
-     * Get encoder codec.
+     * Setup hardware acceleration for encoder.
      *
-     * Returns the codec used by this encoder.
-     * Useful for checking codec capabilities and properties.
+     * Implements FFmpeg's hw_device_setup_for_encode logic.
+     * Validates hardware frames context format and codec support.
+     * Falls back to device context if frames context is incompatible.
      *
-     * @returns Codec instance
+     * @param frame - Frame to get hardware context from
      *
      * @internal
-     *
-     * @see {@link Codec} For codec details
      */
-    getCodec() {
-        return this.codec;
+    setupHardwareAcceleration(frame) {
+        if (!frame.hwFramesCtx) {
+            // Software encoding
+            return;
+        }
+        const hwFramesCtx = frame.hwFramesCtx;
+        const framesFormat = hwFramesCtx.format;
+        const encoderFormat = this.codecContext.pixelFormat;
+        // Check 1: Format validation
+        if (framesFormat !== encoderFormat) {
+            this.codecContext.hwDeviceCtx = hwFramesCtx.deviceRef;
+            this.codecContext.hwFramesCtx = null;
+            return;
+        }
+        // Check 2: Codec supports HW_FRAMES_CTX?
+        let supportsFramesCtx = false;
+        for (let i = 0;; i++) {
+            const config = this.codec.getHwConfig(i);
+            if (!config)
+                break;
+            // Check if codec supports HW_FRAMES_CTX method
+            if (config.methods & AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX) {
+                // Check if pixel format matches or is unspecified
+                if (config.pixFmt === AV_PIX_FMT_NONE || config.pixFmt === encoderFormat) {
+                    supportsFramesCtx = true;
+                    break;
+                }
+            }
+        }
+        if (supportsFramesCtx) {
+            // Use hw_frames_ctx (best performance - zero copy)
+            this.codecContext.hwFramesCtx = hwFramesCtx;
+            this.codecContext.hwDeviceCtx = hwFramesCtx.deviceRef;
+        }
+        else {
+            // Fallback to hw_device_ctx (still uses HW, but may copy)
+            // Check if codec supports HW_DEVICE_CTX as fallback
+            let supportsDeviceCtx = false;
+            for (let i = 0;; i++) {
+                const config = this.codec.getHwConfig(i);
+                if (!config)
+                    break;
+                if (config.methods & AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX) {
+                    supportsDeviceCtx = true;
+                    break;
+                }
+            }
+            if (supportsDeviceCtx) {
+                this.codecContext.hwDeviceCtx = hwFramesCtx.deviceRef;
+                this.codecContext.hwFramesCtx = null;
+            }
+            else {
+                // No hardware support at all - software encoding
+                this.codecContext.hwDeviceCtx = null;
+                this.codecContext.hwFramesCtx = null;
+            }
+        }
     }
     /**
-     * Get underlying codec context.
-     *
-     * Returns the codec context for advanced operations.
-     * Useful for accessing low-level codec properties and settings.
-     * Returns null if encoder is closed or not initialized.
-     *
-     * @returns Codec context or null if closed/not initialized
+     * Prepare frame for encoding.
      *
-     * @internal
-     *
-     * @see {@link CodecContext} For context details
-     */
-    getCodecContext() {
-        return !this.isClosed && this.initialized ? this.codecContext : null;
-    }
-    /**
-     * Get codec flags even before encoder initialization.
+     * Implements FFmpeg's frame_encode() pre-encoding logic:
+     * 1. Video: Sets frame.quality from encoder's globalQuality (like -qscale)
+     * 2. Audio: Validates channel count consistency for encoders without PARAM_CHANGE capability
      *
-     * Unlike getCodecContext(), this works before initialization.
+     * This matches FFmpeg CLI behavior where these properties are automatically managed.
      *
-     * @returns Current codec flags
+     * @param frame - Frame to prepare for encoding
      *
-     * @throws {Error} If encoder is closed
+     * @throws {Error} If audio channel count changed and encoder doesn't support parameter changes
      *
      * @internal
      */
-    getCodecFlags() {
-        if (this.isClosed) {
-            throw new Error('Cannot get flags on closed encoder');
+    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)
+        // 2. Sets frame->time_base = tb_dst (so encoder gets correct timebase)
+        // Note: prepareFrameForEncoding is always called AFTER initialize(),
+        // so codecContext.timeBase is already set correctly:
+        // - Video: 1/framerate (if available)
+        // - Audio: frame.timeBase from first frame (typically 1/sample_rate)
+        const encoderTimebase = this.codecContext.timeBase;
+        const oldTimebase = frame.timeBase;
+        // IMPORTANT: Calculate duration BEFORE converting frame timebase
+        // This matches FFmpeg's video_sync_process() which calculates:
+        //   duration = frame->duration * av_q2d(frame->time_base) / av_q2d(ofp->tb_out)
+        // We need the OLD timebase to convert duration properly
+        let frameDuration;
+        if (frame.duration && frame.duration > 0n) {
+            // Convert duration from frame timebase to encoder timebase
+            // This ensures encoder gets correct frame duration for timestamps
+            frameDuration = avRescaleQ(frame.duration, oldTimebase, encoderTimebase);
         }
-        return this.codecContext.flags;
-    }
-    /**
-     * Set codec flags before encoder initialization.
-     *
-     * This allows setting flags on the codec context before the encoder is opened,
-     * which is necessary for flags that affect initialization behavior (like GLOBAL_HEADER).
-     *
-     * @param flags - The flags to set
-     *
-     * @throws {Error} If encoder is already initialized or closed
-     *
-     * @internal
-     */
-    setCodecFlags(flags) {
-        if (this.isClosed) {
-            throw new Error('Cannot set flags on closed encoder');
+        else {
+            // Default to 1 (constant frame rate behavior)
+            // Matches FFmpeg's CFR mode: frame->duration = 1
+            frameDuration = 1n;
         }
-        if (this.initialized) {
-            throw new Error('Cannot set flags on already initialized encoder');
+        if (frame.pts !== null && frame.pts !== undefined) {
+            // Convert PTS to encoder timebase
+            frame.pts = avRescaleQ(frame.pts, oldTimebase, encoderTimebase);
+            // IMPORTANT: Set frame timebase to encoder timebase
+            // FFmpeg does this in adjust_frame_pts_to_encoder_tb(): frame->time_base = tb_dst
+            // This ensures encoder gets frames with correct timebase (1/framerate for video, 1/sample_rate for audio)
+            frame.timeBase = encoderTimebase;
+        }
+        // Set frame duration in encoder timebase
+        // This matches FFmpeg's video_sync_process() which sets frame->duration
+        // based on vsync_method (CFR: 1, VFR: calculated, PASSTHROUGH: calculated)
+        // Since we don't have automatic filter like FFmpeg, we always set it here
+        frame.duration = frameDuration;
+        if (this.codecContext.codecType === AVMEDIA_TYPE_VIDEO) {
+            // Video: Set frame quality from encoder's global quality
+            // Only set if encoder has globalQuality configured and frame doesn't already have quality set
+            if (this.codecContext.globalQuality > 0 && frame.quality <= 0) {
+                frame.quality = this.codecContext.globalQuality;
+            }
+        }
+        else if (this.codecContext.codecType === AVMEDIA_TYPE_AUDIO) {
+            // Audio: Validate channel count consistency
+            // If encoder doesn't support AV_CODEC_CAP_PARAM_CHANGE, channel count must remain constant
+            const supportsParamChange = this.codec.hasCapabilities(AV_CODEC_CAP_PARAM_CHANGE);
+            if (!supportsParamChange) {
+                const encoderChannels = this.codecContext.channelLayout.nbChannels;
+                const frameChannels = frame.channelLayout?.nbChannels ?? 0;
+                if (encoderChannels !== frameChannels) {
+                    throw new Error(`Audio channel count changed (${encoderChannels} -> ${frameChannels}) and encoder '${this.codec.name}' does not support parameter changes`);
+                }
+            }
         }
-        this.codecContext.flags = flags;
     }
     /**
      * Dispose of encoder.