node-av 1.3.0 → 2.1.0

package/dist/api/encoder.js

@@ -1,5 +1,5 @@
-import { AVERROR_EAGAIN, AVERROR_EOF, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_VIDEO } from '../constants/constants.js';
-import { avGetPixFmtName, avGetSampleFmtName, Codec, CodecContext, FFmpegError, Packet, Rational } from '../lib/index.js';
+import { AVERROR_EAGAIN, AVERROR_EOF } from '../constants/constants.js';
+import { Codec, CodecContext, Dictionary, FFmpegError, Packet, Rational } from '../lib/index.js';
 import { parseBitrate } from './utils.js';
 /**
  * High-level encoder for audio and video streams.
@@ -37,17 +37,18 @@ import { parseBitrate } from './utils.js';
  *
  * @example
  * ```typescript
- * // Hardware-accelerated encoding
+ * // Hardware-accelerated encoding with lazy initialization
  * import { HardwareContext } from 'node-av/api';
- * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
+ * import { FF_ENCODER_H264_VIDEOTOOLBOX } from 'node-av/constants';
  *
- * const hw = HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
- * const encoder = await Encoder.create('h264_nvenc', streamInfo, {
- *   hardware: hw,
+ * const hw = HardwareContext.auto();
+ * const encoderCodec = hw?.getEncoderCodec('h264') ?? FF_ENCODER_H264_VIDEOTOOLBOX;
+ * const encoder = await Encoder.create(encoderCodec, {
+ *   timeBase: video.timeBase,
  *   bitrate: '10M'
  * });
  *
- * // Frames with hw_frames_ctx will be encoded on GPU
+ * // Hardware context will be detected from first frame's hw_frames_ctx
  * for await (const packet of encoder.packets(frames)) {
  *   await output.writePacket(packet);
  *   packet.free();
@@ -62,18 +63,22 @@ export class Encoder {
     codecContext;
     packet;
     codec;
-    isOpen = true;
-    hardware;
+    initialized = false;
+    isClosed = false;
+    opts;
     /**
      * @param codecContext - Configured codec context
+     *
      * @param codec - Encoder codec
-     * @param hardware - Optional hardware context
+     *
+     * @param opts - Encoder options as Dictionary
+     *
      * @internal
      */
-    constructor(codecContext, codec, hardware) {
+    constructor(codecContext, codec, opts) {
         this.codecContext = codecContext;
         this.codec = codec;
-        this.hardware = hardware;
+        this.opts = opts;
         this.packet = new Packet();
         this.packet.alloc();
     }
@@ -81,25 +86,26 @@ export class Encoder {
      * Create an encoder with specified codec and options.
      *
      * Initializes an encoder with the appropriate codec and configuration.
-     * Automatically configures parameters based on input stream info.
-     * Handles hardware acceleration setup if provided.
+     * Uses lazy initialization - encoder is opened when first frame is received.
+     * Hardware context will be automatically detected from first frame if not provided.
      *
      * Direct mapping to avcodec_find_encoder_by_name() or avcodec_find_encoder().
      *
      * @param encoderCodec - Codec name, ID, or instance to use for encoding
-     * @param input - Stream information to configure encoder
-     * @param options - Encoder configuration options
+     *
+     * @param options - Encoder configuration options including required timeBase
+     *
      * @returns Configured encoder instance
      *
-     * @throws {Error} If encoder not found or unsupported format
+     * @throws {Error} If encoder not found or timeBase not provided
      *
-     * @throws {FFmpegError} If codec initialization fails
+     * @throws {FFmpegError} If codec allocation fails
      *
      * @example
      * ```typescript
      * // From decoder stream info
-     * const streamInfo = decoder.getOutputStreamInfo();
-     * const encoder = await Encoder.create(FF_ENCODER_LIBX264, streamInfo, {
+     * const encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+     *   timeBase: video.timeBase,
      *   bitrate: '5M',
      *   gopSize: 60,
      *   options: {
@@ -113,12 +119,7 @@ export class Encoder {
      * ```typescript
      * // With custom stream info
      * const encoder = await Encoder.create(FF_ENCODER_AAC, {
-     *   type: 'audio',
-     *   sampleRate: 48000,
-     *   sampleFormat: AV_SAMPLE_FMT_FLTP,
-     *   channelLayout: AV_CH_LAYOUT_STEREO,
-     *   timeBase: { num: 1, den: 48000 }
-     * }, {
+     *   timeBase: audio.timeBase,
      *   bitrate: '192k'
      * });
      * ```
@@ -127,16 +128,16 @@ export class Encoder {
      * ```typescript
      * // Hardware encoder
      * const hw = HardwareContext.auto();
-     * const encoder = await Encoder.create('hevc_videotoolbox', streamInfo, {
-     *   hardware: hw,
+     * const encoderCodec = hw?.getEncoderCodec('h264') ?? FF_ENCODER_H264_VIDEOTOOLBOX;
+     * const encoder = await Encoder.create(encoderCodec, {
+     *   timeBase: video.timeBase,
      *   bitrate: '8M'
      * });
      * ```
      *
-     * @see {@link Decoder.getOutputStreamInfo} For stream info source
      * @see {@link EncoderOptions} For configuration options
      */
-    static async create(encoderCodec, input, options = {}) {
+    static async create(encoderCodec, options) {
         let codec = null;
         let codecName = '';
         if (encoderCodec instanceof Codec) {
@@ -157,52 +158,6 @@ export class Encoder {
         // Allocate codec context
         const codecContext = new CodecContext();
         codecContext.allocContext3(codec);
-        // It's StreamInfo - apply manually
-        if (input.type === 'video' && codec.type === AVMEDIA_TYPE_VIDEO) {
-            const videoInfo = input;
-            const codecPixelformats = codec.pixelFormats;
-            if (codecPixelformats && !codecPixelformats.includes(videoInfo.pixelFormat)) {
-                codecContext.freeContext();
-                const pixelFormatName = avGetPixFmtName(videoInfo.pixelFormat) ?? 'unknown';
-                const codecPixFmtNames = codecPixelformats.map(avGetPixFmtName).filter(Boolean).join(', ');
-                throw new Error(`Unsupported pixel format for '${codecName}' encoder: ${pixelFormatName}! Supported formats: ${codecPixFmtNames}`);
-            }
-            codecContext.width = videoInfo.width;
-            codecContext.height = videoInfo.height;
-            codecContext.pixelFormat = videoInfo.pixelFormat;
-            // Set pkt_timebase and timeBase to input timebase
-            codecContext.pktTimebase = new Rational(videoInfo.timeBase.num, videoInfo.timeBase.den);
-            codecContext.timeBase = new Rational(videoInfo.timeBase.num, videoInfo.timeBase.den);
-            if (videoInfo.frameRate) {
-                codecContext.framerate = new Rational(videoInfo.frameRate.num, videoInfo.frameRate.den);
-            }
-            if (videoInfo.sampleAspectRatio) {
-                codecContext.sampleAspectRatio = new Rational(videoInfo.sampleAspectRatio.num, videoInfo.sampleAspectRatio.den);
-            }
-        }
-        else if (input.type === 'audio' && codec.type === AVMEDIA_TYPE_AUDIO) {
-            const audioInfo = input;
-            const codecSampleFormats = codec.sampleFormats;
-            if (codecSampleFormats && !codecSampleFormats.includes(audioInfo.sampleFormat)) {
-                codecContext.freeContext();
-                const sampleFormatName = avGetSampleFmtName(audioInfo.sampleFormat) ?? 'unknown';
-                const supportedFormats = codecSampleFormats.map(avGetSampleFmtName).filter(Boolean).join(', ');
-                throw new Error(`Unsupported sample format for '${codecName}' encoder: ${sampleFormatName}! Supported formats: ${supportedFormats}`);
-            }
-            codecContext.sampleRate = audioInfo.sampleRate;
-            codecContext.sampleFormat = audioInfo.sampleFormat;
-            codecContext.channelLayout = audioInfo.channelLayout;
-            // Set both pkt_timebase and timeBase for audio
-            codecContext.pktTimebase = new Rational(audioInfo.timeBase.num, audioInfo.timeBase.den);
-            codecContext.timeBase = new Rational(audioInfo.timeBase.num, audioInfo.timeBase.den);
-            if (audioInfo.frameSize) {
-                codecContext.frameSize = audioInfo.frameSize;
-            }
-        }
-        else {
-            codecContext.freeContext();
-            throw new Error(`Unsupported codec type for encoder! Input type: ${input.type}, Codec type: ${codec.type}`);
-        }
         // Apply encoder-specific options
         if (options.gopSize !== undefined) {
             codecContext.gopSize = options.gopSize;
@@ -215,32 +170,28 @@ export class Encoder {
             const bitrate = typeof options.bitrate === 'string' ? parseBitrate(options.bitrate) : BigInt(options.bitrate);
             codecContext.bitRate = bitrate;
         }
-        if (options.threads !== undefined) {
-            codecContext.threadCount = options.threads;
+        if (options.minRate !== undefined) {
+            const minRate = typeof options.minRate === 'string' ? parseBitrate(options.minRate) : BigInt(options.minRate);
+            codecContext.rcMinRate = minRate;
         }
-        // Override timeBase if explicitly specified in options
-        if (options.timeBase) {
-            codecContext.timeBase = new Rational(options.timeBase.num, options.timeBase.den);
+        if (options.maxRate !== undefined) {
+            const maxRate = typeof options.maxRate === 'string' ? parseBitrate(options.maxRate) : BigInt(options.maxRate);
+            codecContext.rcMaxRate = maxRate;
         }
-        // Apply codec-specific options via AVOptions
-        if (options.options) {
-            for (const [key, value] of Object.entries(options.options)) {
-                codecContext.setOption(key, value.toString());
-            }
+        if (options.bufSize !== undefined) {
+            const bufSize = typeof options.bufSize === 'string' ? parseBitrate(options.bufSize) : BigInt(options.bufSize);
+            codecContext.rcBufferSize = Number(bufSize);
         }
-        const isHWEncoder = codec.isHardwareAcceleratedEncoder();
-        if (isHWEncoder && !options.hardware) {
-            codecContext.freeContext();
-            throw new Error(`Hardware encoder '${codecName}' requires a hardware context`);
+        if (options.threads !== undefined) {
+            codecContext.threadCount = options.threads;
         }
-        // Open codec
-        const openRet = await codecContext.open2(codec, null);
-        if (openRet < 0) {
-            codecContext.freeContext();
-            FFmpegError.throwIfError(openRet, 'Failed to open encoder');
+        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 encoder = new Encoder(codecContext, codec, isHWEncoder ? options.hardware : undefined);
-        return encoder;
+        const opts = options.options ? Dictionary.fromObject(options.options) : undefined;
+        return new Encoder(codecContext, codec, opts);
     }
     /**
      * Check if encoder is open.
@@ -253,7 +204,25 @@ export class Encoder {
      * ```
      */
     get isEncoderOpen() {
-        return this.isOpen;
+        return !this.isClosed;
+    }
+    /**
+     * Check if encoder has been initialized.
+     *
+     * Returns true after first frame has been processed and encoder opened.
+     * Useful for checking if encoder has received frame properties.
+     *
+     * @returns true if encoder has been initialized with frame data
+     *
+     * @example
+     * ```typescript
+     * if (!encoder.isEncoderInitialized) {
+     *   console.log('Encoder will initialize on first frame');
+     * }
+     * ```
+     */
+    get isEncoderInitialized() {
+        return this.initialized;
     }
     /**
      * Check if encoder uses hardware acceleration.
@@ -270,18 +239,34 @@ export class Encoder {
      * @see {@link HardwareContext} For hardware setup
      */
     isHardware() {
-        return !!this.hardware;
+        return this.codec.isHardwareAcceleratedEncoder();
+    }
+    /**
+     * Check if encoder is ready for processing.
+     *
+     * @returns true if initialized and ready
+     *
+     * @example
+     * ```typescript
+     * if (encoder.isReady()) {
+     *   const packet = await encoder.encode(frame);
+     * }
+     * ```
+     */
+    isReady() {
+        return this.initialized && !this.isClosed;
     }
     /**
      * Encode a frame to a packet.
      *
      * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * On first frame, automatically initializes encoder with frame properties.
      * Handles internal buffering - may return null if more frames needed.
-     * Automatically manages encoder state and hardware context binding.
      *
      * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
      *
      * @param frame - Raw frame to encode (or null to flush)
+     *
      * @returns Encoded packet or null if more data needed
      *
      * @throws {Error} If encoder is closed
@@ -315,21 +300,96 @@ export class Encoder {
      * @see {@link flush} For end-of-stream handling
      */
     async encode(frame) {
-        if (!this.isOpen) {
+        if (this.isClosed) {
+            if (!frame) {
+                return null;
+            }
             throw new Error('Encoder is closed');
         }
-        // Late binding of hw_frames_ctx for hardware encoders
-        // Hardware encoders get hw_frames_ctx from the frames they receive
-        if (this.hardware && frame?.hwFramesCtx && !this.codecContext.hwFramesCtx) {
-            // Use the hw_frames_ctx from the frame
-            this.codecContext.hwFramesCtx = frame.hwFramesCtx;
-            this.codecContext.pixelFormat = this.hardware.devicePixelFormat;
+        // Open encoder if not already done
+        if (!this.initialized) {
+            if (!frame) {
+                return null;
+            }
+            await this.initialize(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
-            const packet = await this.receivePacket();
+            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');
+            }
+        }
+        // Try to receive packet
+        return await this.receive();
+    }
+    /**
+     * Encode a frame to a packet synchronously.
+     * Synchronous version of encode.
+     *
+     * Sends a frame to the encoder and attempts to receive an encoded packet.
+     * On first frame, automatically initializes encoder with frame properties.
+     * Handles internal buffering - may return null if more frames needed.
+     *
+     * Direct mapping to avcodec_send_frame() and avcodec_receive_packet().
+     *
+     * @param frame - Raw frame to encode (or null to flush)
+     *
+     * @returns Encoded packet or null if more data needed
+     *
+     * @throws {Error} If encoder is closed
+     *
+     * @throws {FFmpegError} If encoding fails
+     *
+     * @example
+     * ```typescript
+     * const packet = encoder.encodeSync(frame);
+     * if (packet) {
+     *   console.log(`Encoded packet with PTS: ${packet.pts}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Encode loop
+     * for (const frame of decoder.framesSync(packets)) {
+     *   const packet = encoder.encodeSync(frame);
+     *   if (packet) {
+     *     output.writePacketSync(packet);
+     *     packet.free();
+     *   }
+     *   frame.free();
+     * }
+     * ```
+     *
+     * @see {@link encode} For async version
+     */
+    encodeSync(frame) {
+        if (this.isClosed) {
+            if (!frame) {
+                return null;
+            }
+            throw new Error('Encoder is closed');
+        }
+        // Open encoder if not already done
+        if (!this.initialized) {
+            if (!frame) {
+                return null;
+            }
+            this.initializeSync(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
+            const packet = this.receiveSync();
             if (packet)
                 return packet;
             // If still failing, it's an error
@@ -338,7 +398,7 @@ export class Encoder {
             }
         }
         // Try to receive packet
-        return await this.receivePacket();
+        return this.receiveSync();
     }
     /**
      * Encode frame stream to packet stream.
@@ -349,7 +409,9 @@ export class Encoder {
      * Primary interface for stream-based encoding.
      *
      * @param frames - Async iterable of frames (freed automatically)
-     * @yields Encoded packets (caller must free)
+     *
+     * @yields {Packet} Encoded packets (caller must free)
+     *
      * @throws {Error} If encoder is closed
      *
      * @throws {FFmpegError} If encoding fails
@@ -368,11 +430,11 @@ export class Encoder {
      * // With frame filtering
      * async function* filteredFrames() {
      *   for await (const frame of decoder.frames(input.packets())) {
-     *     await filter.filterFrame(frame);
-     *     const filtered = await filter.getFrame();
+     *     const filtered = await filter.process(frame);
      *     if (filtered) {
      *       yield filtered;
      *     }
+     *     frame.free();
      *   }
      * }
      *
@@ -400,9 +462,6 @@ export class Encoder {
      * @see {@link Decoder.frames} For frame source
      */
     async *packets(frames) {
-        if (!this.isOpen) {
-            throw new Error('Encoder is closed');
-        }
         // Process frames
         for await (const frame of frames) {
             try {
@@ -417,29 +476,101 @@ export class Encoder {
             }
         }
         // Flush encoder after all frames
-        let packet;
-        while ((packet = await this.flush()) !== null) {
-            yield packet;
+        await this.flush();
+        while (true) {
+            const remaining = await this.receive();
+            if (!remaining)
+                break;
+            yield remaining;
         }
     }
     /**
-     * Flush encoder and get buffered packet.
+     * Encode frame stream to packet stream synchronously.
+     * Synchronous version of packets.
      *
-     * Signals end-of-stream and retrieves remaining packets.
-     * Call repeatedly until null to get all buffered packets.
-     * Essential for ensuring all frames are encoded.
+     * High-level sync generator for complete encoding pipeline.
+     * Automatically manages frame memory, encoder state,
+     * and flushes buffered packets at end.
+     * Primary interface for stream-based encoding.
      *
-     * Direct mapping to avcodec_send_frame(NULL).
+     * @param frames - Iterable of frames (freed automatically)
      *
-     * @returns Buffered packet or null if none remaining
+     * @yields {Packet} Encoded packets (caller must free)
      *
      * @throws {Error} If encoder is closed
      *
+     * @throws {FFmpegError} If encoding fails
+     *
+     * @example
+     * ```typescript
+     * // Basic encoding pipeline
+     * for (const packet of encoder.packetsSync(decoder.framesSync(packets))) {
+     *   output.writePacketSync(packet);
+     *   packet.free(); // Must free output packets
+     * }
+     * ```
+     *
+     * @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();
+     *   }
+     * }
+     *
+     * for (const packet of encoder.packetsSync(filteredFrames())) {
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link packets} For async version
+     */
+    *packetsSync(frames) {
+        // Process frames
+        for (const frame of frames) {
+            try {
+                const packet = this.encodeSync(frame);
+                if (packet) {
+                    yield packet;
+                }
+            }
+            finally {
+                // Free the input frame after encoding
+                frame.free();
+            }
+        }
+        // Flush encoder after all frames
+        this.flushSync();
+        while (true) {
+            const remaining = this.receiveSync();
+            if (!remaining)
+                break;
+            yield remaining;
+        }
+    }
+    /**
+     * Flush encoder and signal end-of-stream.
+     *
+     * Sends null frame to encoder to signal end-of-stream.
+     * Does nothing if encoder was never initialized or is closed.
+     * Must call receive() to get remaining buffered packets.
+     *
+     * Direct mapping to avcodec_send_frame(NULL).
+     *
      * @example
      * ```typescript
-     * // Flush remaining packets
+     * // Signal end of stream
+     * await encoder.flush();
+     *
+     * // Then get remaining packets
      * let packet;
-     * while ((packet = await encoder.flush()) !== null) {
+     * while ((packet = await encoder.receive()) !== null) {
      *   console.log('Got buffered packet');
      *   await output.writePacket(packet);
      *   packet.free();
@@ -447,26 +578,66 @@ export class Encoder {
      * ```
      *
      * @see {@link flushPackets} For async iteration
-     * @see {@link packets} For complete encoding pipeline
+     * @see {@link receive} For getting buffered packets
      */
     async flush() {
-        if (!this.isOpen) {
-            throw new Error('Encoder is closed');
+        if (this.isClosed || !this.initialized) {
+            return;
+        }
+        // Send flush frame (null)
+        const ret = await this.codecContext.sendFrame(null);
+        if (ret < 0 && ret !== AVERROR_EOF) {
+            if (ret !== AVERROR_EAGAIN) {
+                FFmpegError.throwIfError(ret, 'Failed to flush encoder');
+            }
+        }
+    }
+    /**
+     * Flush encoder and signal end-of-stream synchronously.
+     * Synchronous version of flush.
+     *
+     * Sends null frame to encoder to signal end-of-stream.
+     * Does nothing if encoder was never initialized or is closed.
+     * Must call receiveSync() to get remaining buffered packets.
+     *
+     * Direct mapping to avcodec_send_frame(NULL).
+     *
+     * @example
+     * ```typescript
+     * // Signal end of stream
+     * encoder.flushSync();
+     *
+     * // Then get remaining packets
+     * let packet;
+     * while ((packet = encoder.receiveSync()) !== null) {
+     *   console.log('Got buffered packet');
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link flush} For async version
+     */
+    flushSync() {
+        if (this.isClosed || !this.initialized) {
+            return;
         }
         // Send flush frame (null)
-        await this.codecContext.sendFrame(null);
-        // Receive packet
-        return await this.receivePacket();
+        const ret = this.codecContext.sendFrameSync(null);
+        if (ret < 0 && ret !== AVERROR_EOF) {
+            if (ret !== AVERROR_EAGAIN) {
+                FFmpegError.throwIfError(ret, 'Failed to flush encoder');
+            }
+        }
     }
     /**
      * Flush all buffered packets as async generator.
      *
      * Convenient async iteration over remaining packets.
-     * Automatically handles repeated flush calls.
-     * Useful for end-of-stream processing.
+     * Automatically handles flush and repeated receive calls.
+     * Returns immediately if encoder was never initialized or is closed.
      *
-     * @yields Buffered packets
-     * @throws {Error} If encoder is closed
+     * @yields {Packet} Buffered packets
      *
      * @example
      * ```typescript
@@ -478,96 +649,151 @@ export class Encoder {
      * }
      * ```
      *
-     * @see {@link flush} For single packet flush
+     * @see {@link flush} For signaling end-of-stream
      * @see {@link packets} For complete pipeline
      */
     async *flushPackets() {
-        if (!this.isOpen) {
-            throw new Error('Encoder is closed');
-        }
+        // Send flush signal
+        await this.flush();
         let packet;
-        while ((packet = await this.flush()) !== null) {
+        while ((packet = await this.receive()) !== null) {
             yield packet;
         }
     }
     /**
-     * Close encoder and free resources.
+     * Flush all buffered packets as generator synchronously.
+     * Synchronous version of flushPackets.
      *
-     * Releases codec context and internal packet buffer.
-     * Safe to call multiple times.
-     * Does NOT dispose hardware context - caller is responsible.
-     * Automatically called by Symbol.dispose.
+     * Convenient sync iteration over remaining packets.
+     * Automatically handles flush and repeated receive calls.
+     * Returns immediately if encoder was never initialized or is closed.
+     *
+     * @yields {Packet} Buffered packets
      *
      * @example
      * ```typescript
-     * const encoder = await Encoder.create(FF_ENCODER_LIBX264, streamInfo);
-     * try {
-     *   // Use encoder
-     * } finally {
-     *   encoder.close();
+     * // Flush at end of encoding
+     * for (const packet of encoder.flushPacketsSync()) {
+     *   console.log('Processing buffered packet');
+     *   output.writePacketSync(packet);
+     *   packet.free();
      * }
      * ```
      *
-     * @see {@link Symbol.dispose} For automatic cleanup
+     * @see {@link flushPackets} For async version
      */
-    close() {
-        if (!this.isOpen)
-            return;
-        this.packet.free();
-        this.codecContext.freeContext();
-        this.isOpen = false;
+    *flushPacketsSync() {
+        // Send flush signal
+        this.flushSync();
+        let packet;
+        while ((packet = this.receiveSync()) !== null) {
+            yield packet;
+        }
     }
     /**
-     * Get encoder codec.
+     * Receive packet from encoder.
      *
-     * Returns the codec used by this encoder.
-     * Useful for checking codec capabilities and properties.
+     * 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.
      *
-     * @returns Codec instance
+     * Direct mapping to avcodec_receive_packet().
+     *
+     * @returns Cloned packet or null if no packets available
+     *
+     * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
      * @example
      * ```typescript
-     * const codec = encoder.getCodec();
-     * console.log(`Using codec: ${codec.name}`);
-     * console.log(`Capabilities: ${codec.capabilities}`);
+     * const packet = await encoder.receive();
+     * if (packet) {
+     *   console.log(`Got packet with PTS: ${packet.pts}`);
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
      * ```
      *
-     * @see {@link Codec} For codec properties
-     */
-    getCodec() {
-        return this.codec;
-    }
-    /**
-     * Get underlying codec context.
-     *
-     * Returns the internal codec context for advanced operations.
-     * Returns null if encoder is closed.
-     *
-     * @returns Codec context or null
+     * @example
+     * ```typescript
+     * // Drain all buffered packets
+     * let packet;
+     * while ((packet = await encoder.receive()) !== null) {
+     *   console.log(`Packet size: ${packet.size}`);
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * ```
      *
-     * @internal
+     * @see {@link encode} For sending frames and receiving packets
+     * @see {@link flush} For signaling end-of-stream
      */
-    getCodecContext() {
-        return this.isOpen ? this.codecContext : null;
+    async receive() {
+        if (this.isClosed || !this.initialized) {
+            return null;
+        }
+        // Clear previous packet data
+        this.packet.unref();
+        const ret = await this.codecContext.receivePacket(this.packet);
+        if (ret === 0) {
+            // 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
+            return null;
+        }
+        else {
+            // Error
+            FFmpegError.throwIfError(ret, 'Failed to receive packet');
+            return null;
+        }
     }
     /**
-     * Receive packet from encoder.
+     * Receive packet from encoder synchronously.
+     * Synchronous version of receive.
      *
-     * Internal method to get encoded packets from codec.
+     * 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.
      *
      * Direct mapping to avcodec_receive_packet().
      *
-     * @returns Cloned packet or null
+     * @returns Cloned packet or null if no packets available
      *
      * @throws {FFmpegError} If receive fails with error other than AVERROR_EAGAIN or AVERROR_EOF
      *
-     * @internal
+     * @example
+     * ```typescript
+     * const packet = encoder.receiveSync();
+     * if (packet) {
+     *   console.log(`Got packet with PTS: ${packet.pts}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Drain all buffered packets
+     * let packet;
+     * while ((packet = encoder.receiveSync()) !== null) {
+     *   console.log(`Packet size: ${packet.size}`);
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
+     * @see {@link receive} For async version
      */
-    async receivePacket() {
+    receiveSync() {
+        if (this.isClosed || !this.initialized) {
+            return null;
+        }
         // Clear previous packet data
         this.packet.unref();
-        const ret = await this.codecContext.receivePacket(this.packet);
+        const ret = this.codecContext.receivePacketSync(this.packet);
         if (ret === 0) {
             // Got a packet, clone it for the user
             return this.packet.clone();
@@ -582,6 +808,138 @@ export class Encoder {
             return null;
         }
     }
+    /**
+     * Close encoder and free resources.
+     *
+     * Releases codec context and internal packet buffer.
+     * Safe to call multiple times.
+     * Automatically called by Symbol.dispose.
+     *
+     * @example
+     * ```typescript
+     * const encoder = await Encoder.create(FF_ENCODER_LIBX264, { ... });
+     * try {
+     *   // Use encoder
+     * } finally {
+     *   encoder.close();
+     * }
+     * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
+     */
+    close() {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+        this.packet.free();
+        this.codecContext.freeContext();
+        this.initialized = false;
+    }
+    /**
+     * Initialize encoder from first frame.
+     *
+     * Sets codec context parameters from frame properties.
+     * Configures hardware context if present in frame.
+     * Opens encoder with accumulated options.
+     *
+     * @param frame - First frame to encode
+     *
+     * @throws {FFmpegError} If encoder open fails
+     *
+     * @internal
+     */
+    async initialize(frame) {
+        if (frame.isVideo()) {
+            this.codecContext.width = frame.width;
+            this.codecContext.height = frame.height;
+            this.codecContext.pixelFormat = frame.format;
+            this.codecContext.sampleAspectRatio = frame.sampleAspectRatio;
+        }
+        else {
+            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;
+        // 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');
+        }
+        this.initialized = true;
+    }
+    /**
+     * Initialize encoder from first frame synchronously.
+     * Synchronous version of initialize.
+     *
+     * Sets codec context parameters from frame properties.
+     * Configures hardware context if present in frame.
+     * Opens encoder with accumulated options.
+     *
+     * @param frame - First frame to encode
+     *
+     * @throws {FFmpegError} If encoder open fails
+     *
+     * @internal
+     *
+     * @see {@link initialize} For async version
+     */
+    initializeSync(frame) {
+        if (frame.isVideo()) {
+            this.codecContext.width = frame.width;
+            this.codecContext.height = frame.height;
+            this.codecContext.pixelFormat = frame.format;
+            this.codecContext.sampleAspectRatio = frame.sampleAspectRatio;
+        }
+        else {
+            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;
+        // Open codec
+        const openRet = this.codecContext.open2Sync(this.codec, this.opts);
+        if (openRet < 0) {
+            this.codecContext.freeContext();
+            FFmpegError.throwIfError(openRet, 'Failed to open encoder');
+        }
+        this.initialized = true;
+    }
+    /**
+     * 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;
+    }
     /**
      * Dispose of encoder.
      *
@@ -591,7 +949,7 @@ export class Encoder {
      * @example
      * ```typescript
      * {
-     *   using encoder = await Encoder.create(FF_ENCODER_LIBX264, streamInfo);
+     *   using encoder = await Encoder.create(FF_ENCODER_LIBX264, { ... });
      *   // Encode frames...
      * } // Automatically closed
      * ```