node-av 3.1.3 → 4.0.0

package/dist/api/encoder.js

@@ -1,5 +1,67 @@
-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_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 { 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 { 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 +118,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 +154,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 +168,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 +209,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 +259,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 +274,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 +316,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 +366,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 +400,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.
      *
@@ -382,6 +548,10 @@ export class Encoder {
      * 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 encodeAll} or {@link packets} instead.
+     *
      * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
      * @param frame - Raw frame to encode (or null to flush)
@@ -413,8 +583,10 @@ export class Encoder {
      * }
      * ```
      *
+     * @see {@link encodeAll} For multiple packet encoding
      * @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) {
@@ -425,20 +597,30 @@ export class Encoder {
             if (!frame) {
                 return null;
             }
-            await 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);
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            // Encoder might be full, try to receive first
+        // 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;
             }
-            // If still failing, it's an error
-            if (sendRet !== AVERROR_EAGAIN) {
-                FFmpegError.throwIfError(sendRet, 'Failed to send frame');
-            }
+            // If receive() returned null, this is unexpected - treat as error
+            throw new Error('Encoder returned EAGAIN but no packet available');
+        }
+        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+            FFmpegError.throwIfError(sendRet, 'Failed to send frame');
         }
         // Try to receive packet
         return await this.receive();
@@ -451,6 +633,10 @@ export class Encoder {
      * 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.
+     *
      * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
      * @param frame - Raw frame to encode (or null to flush)
@@ -482,6 +668,9 @@ export class Encoder {
      * }
      * ```
      *
+     * @see {@link encodeAllSync} For multiple packet encoding
+     * @see {@link packetsSync} For automatic frame iteration
+     * @see {@link flushSync} For end-of-stream handling
      * @see {@link encode} For async version
      */
     encodeSync(frame) {
@@ -495,21 +684,251 @@ export class Encoder {
             }
             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);
-        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
-            // Encoder might be full, try to receive first
+        // 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)
+            if (packet) {
                 return packet;
-            // If still failing, it's an error
-            if (sendRet !== AVERROR_EAGAIN) {
-                FFmpegError.throwIfError(sendRet, 'Failed to send frame');
             }
+            // If receive() returned null, this is unexpected - treat as error
+            throw new Error('Encoder returned EAGAIN but no packet available');
+        }
+        if (sendRet < 0 && sendRet !== AVERROR_EOF) {
+            FFmpegError.throwIfError(sendRet, 'Failed to send frame');
         }
         // Try to receive packet
         return this.receiveSync();
     }
+    /**
+     * 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 (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;
+        }
+        // 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 [];
+        }
+        // Receive all available packets
+        const packets = [];
+        while (true) {
+            const packet = await this.receive();
+            if (!packet)
+                break;
+            packets.push(packet);
+        }
+        return packets;
+    }
+    /**
+     * Encode a frame to packets synchronously.
+     * Synchronous version of encodeAll.
+     *
+     * 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 = encoder.encodeAllSync(frame);
+     * for (const packet of packets) {
+     *   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 packets = encoder.encodeAllSync(frame);
+     *   for (const packet of packets) {
+     *     output.writePacketSync(packet);
+     *     packet.free();
+     *   }
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @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
+     */
+    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);
+        }
+        // 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 [];
+        }
+        // Receive all available packets
+        const packets = [];
+        while (true) {
+            const packet = this.receiveSync();
+            if (!packet)
+                break;
+            packets.push(packet);
+        }
+        return packets;
+    }
     /**
      * Encode frame stream to packet stream.
      *
@@ -568,29 +987,106 @@ export class Encoder {
      *
      * @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) {
+        for await (const frame_1 of frames) {
+            const env_3 = { stack: [], error: void 0, hasError: false };
             try {
-                const packet = await this.encode(frame);
-                if (packet) {
-                    yield packet;
+                const frame = __addDisposableResource(env_3, frame_1, false);
+                // Handle EOF signal
+                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;
+                    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;
+                    }
+                }
+            }
+            catch (e_4) {
+                env_3.error = e_4;
+                env_3.hasError = true;
             }
             finally {
-                // Free the input frame after encoding
-                frame.free();
+                __disposeResources(env_3);
             }
         }
-        // Flush encoder after all frames
+        // Flush encoder after all frames (fallback if no null was sent)
         await this.flush();
-        while (!this.isClosed) {
+        while (true) {
             const remaining = await this.receive();
             if (!remaining)
                 break;
             yield remaining;
         }
+        // Signal EOF
+        yield null;
     }
     /**
      * Encode frame stream to packet stream synchronously.
@@ -635,30 +1131,107 @@ export class Encoder {
      * }
      * ```
      *
+     * @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) {
+        for (const frame_2 of frames) {
+            const env_5 = { stack: [], error: void 0, hasError: false };
             try {
-                const packet = this.encodeSync(frame);
-                if (packet) {
-                    yield packet;
+                const frame = __addDisposableResource(env_5, frame_2, false);
+                // Handle EOF signal
+                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;
+                    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;
+                    }
+                }
+            }
+            catch (e_6) {
+                env_5.error = e_6;
+                env_5.hasError = true;
             }
             finally {
-                // Free the input frame after encoding
-                frame.free();
+                __disposeResources(env_5);
             }
         }
-        // Flush encoder after all frames
+        // Flush encoder after all frames (fallback if no null was sent)
         this.flushSync();
-        while (!this.isClosed) {
+        while (true) {
             const remaining = this.receiveSync();
             if (!remaining)
                 break;
             yield remaining;
         }
+        // Signal EOF
+        yield null;
     }
     /**
      * Flush encoder and signal end-of-stream.
@@ -685,11 +1258,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_7 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const bufferedFrame = __addDisposableResource(env_7, _bufferedFrame, false);
+                    await this.codecContext.sendFrame(bufferedFrame);
+                }
+                catch (e_7) {
+                    env_7.error = e_7;
+                    env_7.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_7);
+                }
+            }
+        }
         // Send flush frame (null)
         const ret = await this.codecContext.sendFrame(null);
         if (ret < 0 && ret !== AVERROR_EOF) {
@@ -722,12 +1316,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_8 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const bufferedFrame = __addDisposableResource(env_8, _bufferedFrame, false);
+                    this.codecContext.sendFrameSync(bufferedFrame);
+                }
+                catch (e_8) {
+                    env_8.error = e_8;
+                    env_8.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_8);
+                }
+            }
+        }
         // Send flush frame (null)
         const ret = this.codecContext.sendFrameSync(null);
         if (ret < 0 && ret !== AVERROR_EOF) {
@@ -755,14 +1371,17 @@ 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) {
+        while (true) {
+            const packet = await this.receive();
+            if (!packet)
+                break;
             yield packet;
         }
     }
@@ -786,13 +1405,17 @@ 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) {
+        while (true) {
+            const packet = this.receiveSync();
+            if (!packet)
+                break;
             yield packet;
         }
     }
@@ -833,6 +1456,7 @@ 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
      */
     async receive() {
         if (this.isClosed || !this.initialized) {
@@ -842,6 +1466,10 @@ export class Encoder {
         this.packet.unref();
         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();
         }
@@ -891,6 +1519,8 @@ 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
      */
     receiveSync() {
@@ -901,6 +1531,10 @@ export class Encoder {
         this.packet.unref();
         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();
         }
@@ -914,6 +1548,35 @@ export class Encoder {
             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 +1601,184 @@ 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_9 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const frame = __addDisposableResource(env_9, 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);
+                    // 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);
+                        }
+                    }
+                }
+                catch (e_10) {
+                    env_9.error = e_10;
+                    env_9.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_9);
+                }
+            }
+            // Flush encoder at end
+            await this.flush();
+            while (!this.outputQueue.isClosed) {
+                const packet = await this.receive();
+                if (!packet)
+                    break;
+                await this.outputQueue.send(packet);
+            }
+        }
+        catch {
+            // Ignore error ?
+        }
+        finally {
+            // Close output queue when done
+            this.outputQueue?.close();
+        }
+    }
+    /**
+     * Send frame to input queue.
+     *
+     * @param frame - Frame to send
+     *
+     * @internal
+     */
+    async sendToQueue(frame) {
+        await this.inputQueue.send(frame);
+    }
+    /**
+     * Receive packet from output queue.
+     *
+     * @returns Packet from output queue
+     *
+     * @internal
+     */
+    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.
      *
@@ -956,25 +1793,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 +1886,225 @@ 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
-     *
-     * @internal
+     * Prepare frame for encoding.
      *
-     * @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) {
+        // 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.